Copy page

ALK API

Best Practices

Follow these guidelines to keep your Alk integration reliable, secure, and maintainable.

Workflows and extractions

Know your workflow structure

• Fetch workflow metadata before integrating so column IDs, collection layout, and stages match your expectations.
• Treat the workflow ID as stable configuration — store it securely alongside your API key, not in public client bundles.

Uploading documents

• Prefer signed URL uploads for large files or when the upload originates from an end-user device; keep the API key on your backend when generating URLs.
• Use direct multipart upload for trusted server-side batch jobs with smaller payloads.
• When targeting a collection, pass collection_id or collection_name consistently so documents land in the correct group.

Running extractions

• Confirm documents finished uploading (and signed uploads were confirmed) before triggering extraction.
• Use column_ids or document_ids filters when you only need partial re-runs instead of re-processing the entire workflow.
• Set force: true only when you intentionally want to overwrite existing extraction results.
• Paginate through GET /workflows/{id}/extractions rather than assuming all results fit in one response.

Error handling

• Give value or downstream automation only on definitive success responses — not on ambiguous or partial states.
• Map Alk error payloads to user-friendly messages; log full responses server-side for debugging.
• Retry idempotent reads (GET) on transient failures; use caution with retries on uploads and extractions to avoid duplicate work.

Security

API key management

• Never hardcode API credentials in source repositories.
• Initiate authenticated API calls from your backend only — not from browsers or mobile apps exposed to users.
• Store keys in environment variables or a secrets manager; rotate keys when team members leave or credentials may be exposed.
• Use alk_test_… keys in non-production environments and alk_live_… only where appropriate.

Authentication

• Send the bearer token on every request: Authorization: Bearer <api_key>.
• Request only the scopes your integration needs; avoid over-provisioned keys.
• Enforce TLS for all traffic to https://api.alk.work/.

Handling sensitive data

• Minimize logging of document contents and extraction values; prefer opaque IDs in logs.
• Restrict access to workflow IDs and API keys on a need-to-know basis inside your organization.
• Align retention and deletion policies with your compliance requirements for extracted data.

Operations

Rate limits

• Respect rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining).
• Back off exponentially when you receive throttling responses instead of hammering the API.
• Contact your Alk account team if you need higher limits for batch or peak workloads.

Observability

• Log request IDs, workflow ID, document ID, and HTTP status for each integration step.
• Track extraction lifecycle: upload → confirm (if applicable) → extract → results fetched.
• Alert on sustained 404 (misconfigured workflow ID) or auth failures (invalid or revoked keys).

Going to production

• Re-run your Integration Journey checklist against live credentials.
• Verify column prompts and collection structure in production match what you tested.
• Document rollback steps (disable integration flag, revoke key) before launch.

API reference

For request bodies, response schemas, and try-it-now examples, use the interactive API reference.