Copy page

ALK API

Workflows

A workflow is the central unit in Alk. It defines what documents you process, what data you extract, and how results are organized. Every API call in this reference is scoped to a workflow_id.

What a workflow contains

Concept	Role
Columns	Extraction fields — each has a name, type (text, number, date, singleSelect, multiSelect, url, table), and a natural-language prompt that tells Alk what to pull from documents.
Documents	Files uploaded into the workflow (PDFs, images, and other supported types).
Collections	Optional folders that group related documents (for example, one loan package or one deal).
Stages	Optional pipeline states for organizing work inside the workflow.
Extractions	Structured values produced when Alk runs columns against your documents.

At a high level:

Code
Workflow
├── Columns (what to extract)
├── Documents (what you upload)
│   └── Collections (optional grouping)
├── Stages (optional workflow states)
└── Extractions (results)

Workflow lifecycle

1. Configure — columns and prompts are defined for the workflow (typically in the Alk dashboard; your account team provisions the workflow ID).
2. Ingest — upload documents via direct multipart upload or the signed URL flow.
3. Extract — run bulk or per-document extraction so Alk populates column values.
4. Retrieve — list extractions, read workflow status (extraction_status, is_extracting), and integrate results into your product.

Workflow status fields you will see in API responses include:

• status — workflow state (for example draft)
• extraction_status — overall extraction progress (not_started, pending, complete, has_failures)
• is_extracting — whether an extraction job is currently running

Setting up a workflow

Most teams receive a workflow ID from Alk after onboarding. You can also create your workflows yourself. That ID is all you need to call the API.

If you are configuring a new use case with your account team, align on:

1. Column schema — field names, types, and prompts for each data point you need.
2. Collection strategy — whether documents should be flat in the workflow or grouped (and default collection names, if any).
3. Extraction triggers — manual via API after upload, batch on a schedule, or event-driven from your backend.
4. Environments — separate test and live workflows or keys as needed.

Verify setup via API

Confirm the workflow is ready before building upload logic:

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

A successful response includes columns, and optionally documents and stages, so you can validate IDs used in later calls.

List columns separately

When you only need schema metadata:

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

Use returned column id values when filtering extractions or passing column_ids to bulk extract.

Working with documents and collections

Documents are the files Alk processes. Upload them with:

• POST /api/v1/workflows/{workflow_id}/documents — multipart upload from your server
• POST .../documents/upload-url then POST .../documents/confirm — signed URL flow for larger or client-origin files

Collections group documents. When uploading, you can:

• Pass collection_id to add files to an existing collection
• Pass collection_name to create a new collection and add files in one step

Collections are useful when extraction should consider multiple files together or when your product UI mirrors folder-style organization.

Running extraction

After documents are in the workflow:

Code
curl -X POST "https://api.alk.work/api/v1/workflows/<workflow_id>/extract" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"collection_id": "<optional_collection_id>"}'

Filter by document_ids, collection_id, or column_ids when you do not need a full workflow re-run. See Integration Journey for the full upload-to-results path.

Next steps

• Integration Journey — end-to-end rollout from credentials to production
• Best Practices — security and operational guidance
• API Reference — all workflow, document, upload, and extraction endpoints