Document Extraction API Reference

Authentication

All API requests authenticate with an API key in the X-API-Key header — not a Bearer token. Generate a key from the Developer page in your account; keys are prefixed dex_, scoped to your account, can have descriptive names (e.g. production-erp-sync or staging-tests), and can be revoked at any time without affecting other keys.

Send it on every request, for example: curl -X POST https://api.dataextractor.io/api/v1/extract/YOUR_WORKFLOW_SLUG -H "X-API-Key: dex_your_api_key_here" -F "file=@invoice.pdf"

Keys are long-lived. Never expose a key in client-side code or commit it to a public repository. If a key is compromised, revoke it from the Developer page and issue a replacement. A missing or invalid key returns 401 with the error code INVALID_API_KEY.

Extract from a document (synchronous)

POST /api/v1/extract/{workflow_slug} — upload a document and get the extracted fields back in the same response. Send the file as multipart/form-data under the form field named file. The workflow_slug selects which saved workflow (schema + prompts) to run; find it on the Developer or Workflows page.

The response is a JSON object with success, data, and meta. data contains: execution_id (the run's unique ID); extracted_fields, a flat array where each item has path (a dot-path like invoice_number or line_items[0].quantity), value (a scalar, a list of row objects, or null), and confidence (0.0–1.0 or null); structured, the same values grouped into headers and line-item arrays; metadata such as processing_time_ms, model, and credits_remaining; and documents, an array with one entry per logical document detected in the upload (always at least one). The top-level extracted_fields and structured mirror documents[0] for convenience.

Asynchronous extraction & polling

For large documents, submit the job and poll rather than blocking on a single request.

POST /api/v1/extract/{workflow_slug}/async takes the same multipart upload and returns immediately with data.execution_id, data.status ("processing"), and data.poll_url.

GET /api/v1/extract/jobs/{execution_id} returns the job's current state. status moves through pending → extracting → extracted, or failed. When status is extracted, the body carries the same extracted_fields / structured / documents shape as the synchronous endpoint; when status is failed, an error string explains why. Poll every few seconds — there is no webhook callback today, so polling is the supported way to collect async results.

Get a workflow's schema

GET /api/v1/extract/{workflow_slug}/schema returns the field schema a workflow extracts, so you can validate your downstream mapping before sending documents. data includes workflow_slug, workflow_name, header_fields (top-level values), and line_item_fields (the columns within each row of a line-item table). Each field has a path, a human-readable label, and a type.

Rate limits & quotas

Rate limits are enforced per API key. Each key has a requests-per-minute limit (set per key on the Developer page); exceeding it returns 429 Too Many Requests with a Retry-After header telling you how many seconds to wait.

Extraction also consumes credits from your plan's monthly allowance. A multi-document upload costs one credit per detected document. Each extract response reports metadata.credits_remaining; when you run out, the API returns 402 with the error code CREDITS_EXHAUSTED. The Free plan includes a fixed number of documents per month; paid plans include more.

For batch pipelines, spread requests over time rather than bursting, and prefer the async endpoint for large documents so one slow extraction doesn't hold a connection open.

Error codes reference

The API uses standard HTTP status codes. Error bodies are { code, message } (FastAPI validation errors use { detail }).

401 Unauthorized — the X-API-Key header is missing, invalid, or revoked (code INVALID_API_KEY).

402 Payment Required — no extraction credits remain for the current period (code CREDITS_EXHAUSTED).

404 Not Found — no workflow matches the given workflow_slug in your account.

422 Unprocessable Entity — the uploaded file is missing, an unsupported format, or corrupted.

429 Too Many Requests — per-key rate limit exceeded; honor the Retry-After header.

500 Internal Server Error — an unexpected server-side error; retry with exponential backoff and contact support@dataextractor.io if it persists.