API documentation

Documents

Upload, process, inspect, and download document thumbnails, previews, and extraction results.

Upload a document

POST /api/v1/documents accepts multipart form data and returns a document resource you can poll until processing is complete. Omit processing_mode for the existing extraction workflow, or send thumbnail when you only need a JPEG thumbnail.

POST /documents 
curl -sS -X POST "https://www.exdata.app/api/v1/documents" \
  -H "Authorization: Bearer $EXDATA_API_TOKEN" \
  -H "Idempotency-Key: invoice-upload-001" \
  -F "file=@./invoice.pdf" \
  -F "locale=en" \
  -F "custom_types[]=invoice"

Upload fields

Send the file and any context your workflow already knows. Keep hints short and factual; they help classification without replacing extraction from the document itself.

Field Required Type Description
file Yes File Document file, up to 500 MB. XML files are limited to 5 MiB.
text No String Additional source text or business context to treat as document evidence, not extraction instructions, up to 256 KiB (262,144 UTF-8 bytes).
custom_types[] No Array Up to 50 optional type extensions, each up to 100 characters. exdata already supports standard types: invoice, credit-note, reminder, salary-statement, bank-statement, contract, balance-sheet, tax-assessment-note, timesheet, letter, and other. Add custom values only when your integration needs extra document categories.
requester No String Your integration name, user reference, workflow ID, or request source, up to 255 characters.
locale No String Supported locale such as en or de.
processing_mode No extraction or thumbnail Defaults to extraction. Use thumbnail to generate only a JPEG thumbnail without extraction work or an extraction credit.
allow_ai_processing No Boolean Optional extraction flag. Multipart clients may send true, false, 1, or 0; letter case does not matter for the words. In extraction mode, false disables AI only; OCR, previews, non-AI structured extraction, thumbnail generation, and the extraction credit still apply. Thumbnail mode takes precedence over either value.

Processing modes

The mode controls the work scheduled after upload. Both modes use the same asynchronous document statuses, polling endpoint, and lifecycle webhooks.

Mode Work performed Extraction credit Completed results
extraction Existing OCR, preview, structured extraction, thumbnail, and optional AI workflow. One live credit. Test-mode uploads do not spend live credits. Thumbnail, previews, extraction fields, and extraction-run metadata when available.
thumbnail JPEG thumbnail only. Videos use a representative decoded frame. No OCR, AI, structured extraction, or persisted preview generation runs. None. A zero-credit account can use this mode. Thumbnail URL, empty preview and extraction endpoint results, and latest_extraction_run: null.
Field precedence

processing_mode=thumbnail always wins over allow_ai_processing and returns ai_processing: false. If processing_mode is omitted or set to extraction, allow_ai_processing keeps its existing AI-only meaning.

Document object

Document responses include the selected processing mode, status, processing details, and file metadata. Extraction-mode documents can include extraction-run metadata; thumbnail-only documents always return latest_extraction_run: null.

Document response 
{
  "data": {
    "id": 123,
    "mode": "live",
    "processing_mode": "extraction",
    "status": "pending",
    "processing_stage": "queued",
    "processing_error": null,
    "blocked_reason": null,
    "filename": "invoice.pdf",
    "file_format": "pdf",
    "file_size": 240123,
    "locale": "en",
    "custom_types": ["invoice"],
    "ai_processing": true,
    "latest_extraction_run": {
      "id": 456,
      "mode": "live",
      "source": "api",
      "status": "pending",
      "blocked_reason": null,
      "extraction_schema_version": "2026-07-28.1",
      "extractor_version": "document:2026-07-28.1",
      "ai_prompt_version": "document-ai:2026-07-28.1",
      "normalization_version": "base:2026-07-28.1",
      "quality": null
    },
    "created_at": "2026-05-10T01:00:00.000000Z"
  }
}

Endpoint reference

The document endpoints cover upload, status polling, generated previews, deletion, and reading extraction fields after processing completes. See the endpoint reference for parameters, response behavior, and copyable examples for every endpoint.

Method Path Purpose
GET /api/v1/documents List account documents with pagination.
POST /api/v1/documents Upload a document.
GET /api/v1/documents/{document} Fetch current document status and metadata.
DELETE /api/v1/documents/{document} Delete a document.
GET /api/v1/documents/{document}/thumbnail Download a generated thumbnail.
GET /api/v1/documents/{document}/previews List generated preview files.
GET /api/v1/previews/{preview} Download a preview file.
GET /api/v1/documents/{document}/extractions Read extraction fields after completion.