API v1 documentation
Authentication
Create account tokens, send bearer auth, and keep retries idempotent.
Send bearer auth
Create an account API token in the exdata app, then send it in the Authorization header on every request.
Authorization: Bearer <your-exdata-token>Full token values are shown only at creation. After that, exdata stores the token hash and displays only the prefix.
Test and live tokens
Tokens are scoped to the account where they were created. They can only access documents, previews, extraction fields, and webhook configuration for that account.
| Token type | Use for | Credit behavior |
|---|---|---|
| Test mode | Development, QA, webhook receiver testing, and sample files. | Zero live credit usage. Extraction runs report credits_charged: 0. |
| Live mode | Production document processing. | Extraction applies the profile rate to the first band, calculates final usage as credit_cost × started 10-page bands after analysis, and keeps that total when a usable result or retrievable extracted fields remain. Generic extraction has a rate of one. |
Live-token uploads with processing_mode=thumbnail have zero credit usage and no extraction run. Credit usage applies to extraction, analysis, and validation mode, including when allow_ai_processing=false. A selected profile can use a different per-band rate; read the rate returned in the extraction-run metadata. Terminal processing errors return credits only when neither a usable result nor retrievable extracted fields remain. A completed validation assessment is usable unless its technical status is unavailable. If processing discovers an additional page band that available credits cannot cover, the document is asynchronously blocked and the initial credits are returned.
Token abilities
Choose the narrowest abilities your integration needs. Abilities are enforced together with account scope.
| Ability | Allows |
|---|---|
documents:read | List and retrieve documents, previews, generic fields, and complete profile extraction results. |
documents:write | Upload and delete documents. |
extractions:review | Confirm, correct, or reject profile extraction results. This ability does not grant document read access by itself. |
Safe retries
Send an Idempotency-Key header for uploads. If the network drops and you retry with the same key, file, and caller-supplied form fields—including processing mode, lane, and extraction profile—exdata returns the original response without uploading a duplicate document, applying another charge, or starting duplicate processing. Later changes to profile settings or prices do not change that replay. If an interrupted attempt created a document but could not finish the upload response, the identical retry returns 409 idempotency_conflict with conflict_reason=document_created and a cleanup-only document.id. Delete that document before deciding whether to submit a new upload; a deletion response of 404 means it was already removed.
curl -sS -X POST "https://www.exdata.app/api/v1/documents" \
-H "Authorization: Bearer $EXDATA_API_TOKEN" \
-H "Idempotency-Key: invoice-2026-1048" \
-F "file=@./invoice.pdf"Reusing the same key with a different upload payload returns 409. This includes changing processing_mode among extraction, analysis, validation, and thumbnail, or changing processing_lane between standard and batch. Use one unique key per logical upload.
Sector review decisions also require Idempotency-Key. They additionally use If-Match with the extraction-result ETag so two reviewers cannot silently overwrite each other.