Documents

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 extraction, send analysis for the same lifecycle without AI and structured extraction, send validation to assess a PDF or XML e-invoice without general extraction, or send thumbnail when you only need a JPEG thumbnail. Omit processing_lane for standard priority; the delayed batch lane is available to eligible accounts. Review supported files and capabilities before sending a new format.

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.

Processing modes

The mode determines which results are produced after upload. All modes use the same asynchronous document statuses, polling endpoint, and lifecycle webhooks.

Credit usage

Live extraction-lifecycle runs apply the applicable profile rate per started 10-page band. A specialized profile can use a different credit_cost, expressed as credits per started 10-page band. Because the final page count can become available only after processing begins, latest_extraction_run.credits_charged can update as processing progresses. Generic extraction, analysis, and validation have a one-credit rate. Read latest_extraction_run.credits_charged for the current total attributed to the run.

Processing lanes

The lane controls processing priority, not extraction semantics. Choose a lane independently from processing_mode; extraction, analysis, validation, and thumbnail work support standard and batch processing. Batch is available to eligible accounts and is typically used for archive backfills. If batch is unavailable for the account, the upload returns 422 with code=validation_failed and a processing_lane validation error.

Extraction profiles

A profile adds a versioned document schema, validation policy, review rules, evidence contract, and optional export projections while preserving the regular document and extraction endpoints. Every active account can explicitly select a registered profile by sending its key in extraction_profile. The selected profile records the profile, schema, processing settings, and applicable per-band rate for each extraction run. These values are returned as run metadata rather than upload fields.

Omitting extraction_profile always selects generic. New German energy uploads use profile version 2.0.1 with schema version 2.0.0. Profile setting changes apply to new uploads; reprocessing an existing document preserves the version, processing settings, and credit rate recorded for that document.

Profile results are returned by GET /api/v1/documents/{document}/extractions under the sector_extraction key; there is no separate profile-result endpoint. The response envelope is shared across profiles, while machine_payload, effective_payload, validation details, review behavior, and projections come from the selected profile. See German energy invoices for the currently available profile's canonical data model and review workflow.

Document object

Document responses include the selected processing mode, lane, extraction profile, status, processing details, and file metadata. Extraction, analysis, and validation documents can include extraction-run metadata; thumbnail-only documents always return latest_extraction_run: null. When a specialized profile result exists, the sector_extraction_summary key provides its compact review and handoff state, a link to the extractions endpoint, and available export descriptors.

{
  "data": {
    "id": 123,
    "mode": "live",
    "processing_mode": "extraction",
    "processing_lane": "batch",
    "pages": null,
    "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,
    "extraction_profile": "generic",
    "latest_extraction_run": {
      "id": 456,
      "mode": "live",
      "processing_lane": "batch",
      "source": "api",
      "status": "pending",
      "blocked_reason": null,
      "credits_charged": 1,
      "extraction_schema_version": "2026-08-28.1",
      "extractor_version": "document:2026-08-28.1",
      "ai_prompt_version": "document-ai:2026-07-28.1",
      "normalization_version": "base:2026-08-28.1",
      "extraction_profile": "generic",
      "profile_version": "1.0.0",
      "ai_model": "gpt-5.4-mini-2026-03-17",
      "ai_reasoning_effort": "low",
      "strategies_used": null,
      "provenance_summary": null,
      "billing_mode": "credits",
      "credit_cost": 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.