Copy page

ALK API

Integration Journey

Understand the integration path before you build. This guide mirrors a typical rollout from sandbox credentials to live extraction workflows.

Step 1. Obtain API access

Create your ALK credentials via ALK Platform:

• A workflow ID for the workflow you are integrating against. This is available in the workflow page. Click copy ID
• A bearer token in the form alk_live_… or alk_test_…. Available in settings via API Manager
• The scopes your key needs (for example workflows:read, document upload, extraction)

In the test environment you can validate authentication, list workflow structure, upload documents, and run extractions without affecting production data.

Step 2. Understand your workflow

Before writing integration code, confirm how your workflow is configured:

1. Columns — the fields Alk extracts (text, numbers, dates, tables, and more). Each column has a prompt that drives extraction.
2. Collections — optional groupings of related documents (for example, a deal room or loan file).
3. Stages — optional pipeline states that organize documents inside the workflow.

Retrieve the full picture with a single call:

Code
curl -X GET "https://api.alk.work/api/v1/workflows/<workflow_id>" \
  -H "Authorization: Bearer <api_key>" \
  -H "Accept: application/json"

See Workflows for a deeper explanation of these concepts.

Step 3. Choose an integration pattern

Alk supports two primary ways to get documents into a workflow:

Pattern	Best for	Summary
Direct upload	Smaller files, server-side scripts	POST /workflows/{id}/documents with multipart file bodies
Signed URL upload	Large files, browser or mobile clients	Request signed PUT URLs, upload to storage, then confirm

After documents are present, trigger extraction:

• Bulk — POST /workflows/{id}/extract for many documents or a collection
• Per document — POST /workflows/{id}/documents/{document_id}/extract

Poll extraction status via GET /workflows/{id}/documents or inspect extraction_status on the workflow response.

Optional: Merge documents in a collection (collections only)

If you group documents into a collection, you can optionally generate a single merged PDF that contains only the PDFs in that collection.

This capability works only for collections (it does not merge arbitrary workflow documents outside a collection).

Use:

• POST /api/v1/workflows/{workflow_id}/collections/{collection_id}/merged-document

You can control merge order by providing label_order in the request body (otherwise Alk uses the collection order).

Step 4. Build and test end-to-end

Work through this checklist in test mode:

1. Authenticate and fetch workflow metadata.
2. Upload at least one document (direct or signed URL flow).
3. Run extraction and confirm results appear for the expected columns.
4. Handle error responses (400, 404, 422) with retries only where appropriate.
5. Review Best Practices for security and reliability guidance.

Use the interactive reference at /api to explore request and response schemas.

Step 5. Go live

When you are ready for production:

1. Switch credentials — replace alk_test_… with alk_live_… and update the base URL if your account team provides a production host.
2. Lock down secrets — store keys in environment variables or a secrets manager; never embed them in client-side code.
3. Monitor rate limits — watch X-RateLimit-Limit and X-RateLimit-Remaining response headers.
4. Align workflow configuration — ensure production columns, collections, and prompts match what you validated in test.

You are live when uploads, extractions, and result retrieval behave consistently under production load and error handling matches your operational runbooks.