Create Job

Create an asynchronous document extraction job with POST /v1/jobs: pass a schema_id and optional document_ids, then poll the returned job ID for results.

POST /v1/jobs creates an asynchronous Job (formerly called a structuring run): it runs the 4-phase extraction pipeline over a set of documents and fills your schema's fields into a structured grid. The job immediately enters pending status and processes in the background; the response returns a job ID you poll for progress and a results link for the extracted rows.

If document_ids is omitted or empty, the job runs over ALL documents with completed status in your organization. Pass explicit document_ids unless you really want a full-corpus run.

POST/v1/jobs

Body parameters

schema_id*stringSchema to extract against. Must be a valid UUID.

document_idsstring[]Specific document UUIDs to process. Omit to use all completed documents for your organization.

namestringOptional human-readable job name (max 200 characters).

Request

Response

Response fields (201 Created)

idstringJob UUID.

statusstringAlways "pending" immediately after creation.

messagestringHuman-readable confirmation message.

links.selfstringURL to poll for job status.

links.resultsstringURL to retrieve result rows once complete.

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "message": "Job created and queued for processing.",
  "links": {
    "self": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "results": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/results"
  }
}

Most integrations call POST /v1/jobs immediately after defining or updating a schema via the schemas API. Once created, poll GET /v1/jobs/:id every 2-5 seconds and watch for status transitioning to complete. Pair with GET /v1/jobs/:id/results to retrieve the structured output rows as soon as the job finishes.

Errors

Error responses

400bad_requestNo completed documents found for your organization, or request body is invalid.

401unauthorizedMissing or invalid API key.

403forbiddenThe API key lacks the write scope required by this endpoint.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Create Job

Response

Errors

Related