Skip to main content

Create Job

Create and run an extraction job with a schema and optional document set. Returns a job ID for polling progress and retrieving results.

Create a new extraction job targeting a specific schema. The job immediately enters pending status and begins processing asynchronously. If document_ids is omitted, the job processes all completed documents in your organization. Poll the job status endpoint to track progress.

Jobs are limited to 2,000 documents per run. If you need to process more, split your document set across multiple jobs.
POST/v1/jobs

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.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

List Jobs
Get Job