API v1 documentation

Getting started

Upload a PDF, wait for processing, and read normalized extraction fields.

Base URL

All examples in these docs use the documented API base URL.

Base URL
https://www.exdata.app/api/v1

Create a token

Start in the exdata app and create an account API token before you call the API.

  1. Open the exdata app and go to API Tokens.
  2. Create a test mode token while building the integration.
  3. Select the abilities your integration needs: documents:write for uploads and documents:read for polling, previews, and extraction fields.
  4. Copy the token when it is shown. The full token is shown once; after that, only the prefix is visible.
  5. Store it as an environment variable such as EXDATA_API_TOKEN.
Set your token
export EXDATA_API_TOKEN="your-test-token"

Upload, poll, read

Use a test-mode token and a real PDF on your machine. This example uses the default extraction processing mode: upload the document, poll until processing is terminal, then read the normalized extraction fields.

Upload, poll, read with cURL
export EXDATA_API_TOKEN="your-test-token"

UPLOAD_RESPONSE=$(curl -sS -X POST "https://www.exdata.app/api/v1/documents" \
  -H "Authorization: Bearer $EXDATA_API_TOKEN" \
  -H "Idempotency-Key: invoice-$(date +%s)" \
  -F "file=@./invoice.pdf" \
  -F "locale=en" \
  -F "custom_types[]=invoice")

DOCUMENT_ID=$(printf '%s' "$UPLOAD_RESPONSE" | jq -r '.data.id')

curl -sS "https://www.exdata.app/api/v1/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $EXDATA_API_TOKEN"

curl -sS "https://www.exdata.app/api/v1/documents/$DOCUMENT_ID/extractions" \
  -H "Authorization: Bearer $EXDATA_API_TOKEN"

Processing lifecycle

Treat document processing as asynchronous in both processing modes. Keep polling or wait for a webhook until the document reaches one of the terminal states. Use processing_mode to decide which result to read after completion.

Status Meaning Client behavior
pending Work is awaiting processing or running. Poll again or wait for a webhook.
completed Processing finished successfully. Read extraction fields for extraction mode, analysis fields for analysis mode, latest_extraction_run.quality.structured for validation mode, or download the JPEG thumbnail for thumbnail mode.
error Processing failed. Live credits are returned only when neither a usable result nor retrievable extracted fields remain. Inspect processing_error and latest_extraction_run.credits_charged, then show a retry/support path.
blocked Processing stopped because an account condition was not satisfied. This can happen asynchronously after 201 if analysis discovers an additional page band that available credits cannot cover. Inspect blocked_reason and resolve the account condition.
Live credit usage

A live extraction applies the profile rate to one initial band. After analysis determines the page count, exdata calculates usage as credit_cost × started 10-page bands and keeps that total when a usable result or retrievable extracted fields remain. Generic extraction has a rate of one. Terminal and preprocessing errors return credits only when neither remains. A page_band_insufficient_credits block also returns the initial credits, so the net charge is zero.

Thumbnail lifecycle

Thumbnail-only documents move through queued, thumbnailing, and completed, or reach failed with document status: "error". They can also report waiting_for_capacity, because thumbnail rendering uses standard processing capacity. They use the normal document webhooks but do not create an extraction run and have zero credit usage.

Test mode

Use test mode for development, QA, sample files, and webhook receiver testing. Test-mode tokens use the same endpoints, validation, idempotency behavior, processing states, request IDs, and webhook payload shape as live tokens.

Step What to do What to check
Create token Create a token with the test mode environment in the app. The token is clearly marked as test mode in the API Tokens list.
Upload samples Use the same upload endpoint and parameters as production. Responses include mode as test.
Map fields Poll the document or wait for webhooks, then read extraction fields. Your integration handles pending, completed, error, and blocked.
Switch to live Create a live token only after field mapping and webhook handling are working. Live extraction uploads use result-based page-band credits and should be connected to production automation.
Sandbox limits

Test uploads have zero live credit usage, but they are limited per user, account, and token each day. Extraction runs report credits_charged: 0. Limit responses use 429 with code test_mode_limit_exceeded.