Endpoint reference | exdata API Docs

OpenAPI coverage

The operation list below is read from the published OpenAPI contract. Use it as a compact index when comparing generated clients, request methods, operation IDs, and documented response codes.

Method	Path	Operation	Responses
GET	`/api/v1/ping`	Check API authentication ping	`200`
GET	`/api/v1/documents`	List documents listDocuments	`200` `429`
POST	`/api/v1/documents`	Upload a document uploadDocument	`201` `422` `409` `429` `402`
POST	`/api/v1/x402/extractions`	Upload a document with x402 payment createAnonymousX402Extraction	`200` `201` `400` `402` `409` `422` `429` `503`
GET	`/api/v1/x402/extractions/{document}`	Retrieve an anonymous x402 extraction getAnonymousX402Extraction	`200` `403` `404` `429`
GET	`/api/v1/documents/{document}`	Retrieve a document getDocument	`200` `403` `404`
DELETE	`/api/v1/documents/{document}`	Delete a document deleteDocument	`204` `403` `404`
GET	`/api/v1/documents/{document}/thumbnail`	Download document thumbnail getDocumentThumbnail	`200` `403` `404`
GET	`/api/v1/documents/{document}/previews`	List document previews listDocumentPreviews	`200` `403` `404`
GET	`/api/v1/documents/{document}/extractions`	List document extractions listDocumentExtractions	`200` `403` `404`
GET	`/api/v1/previews/{preview}`	Download a preview file getPreview	`200` `403` `404`

Common headers

Each request is scoped to the account behind the API token. Upload retries should include an idempotency key so a network retry does not create another document.

Header	Required	Value	Description
`Authorization`	Yes	`Bearer <token>`	Account-scoped API token created in the exdata app. The token must have the ability required by the endpoint.
`Idempotency-Key`	Uploads only	String, max 255 characters	Unique key for one logical upload. Reusing the same key and same payload returns the stored response.
`X-Request-ID`	No	String, max 128 characters	Optional caller request ID. exdata echoes this value, or a generated request ID, in error responses.

GET /api/v1/ping

Ping

Use this endpoint for a lightweight token check during integration setup, deploy checks, or uptime probes that should not upload files.

Parameter	Location	Required	Description
None	-	No	Only the bearer token is required.

Status	Response	Description
`200`	JSON object	Authentication succeeded.
`401`	Error envelope	Bearer token is missing, invalid, or revoked.
`429`	Error envelope	Read rate limit exceeded.

Request

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

200 response

{
  "status": true
}

GET /api/v1/documents

List documents

Returns paginated documents for the token's account. Use this endpoint for status dashboards, reconciliation, support tooling, and scheduled backfills.

Parameter	Location	Required	Type	Description
`sort`	Query	No	`created_at` or `-created_at`	Sort by creation time. Use `-created_at` for newest first.
`per_page`	Query	No	Integer, 1-100	Number of documents per page. Defaults to `100`.

Status	Response	Description
`200`	Paginated document list	`data` contains document objects. `links` and `meta` contain Laravel pagination data.
`403`	Error envelope	The token does not have `documents:read`.
`422`	Validation error	A query parameter is not valid.
`429`	Error envelope	Read rate limit exceeded.

Request

curl -sS "https://www.exdata.app/api/v1/documents?sort=-created_at&per_page=25" \
  -H "Authorization: Bearer $EXDATA_API_TOKEN"

200 response

{
  "data": [
    {
      "id": 123,
      "mode": "live",
      "status": "completed",
      "processing_stage": "completed",
      "processing_error": null,
      "blocked_reason": null,
      "scanner_status": "clean",
      "scanner_provider": "local_noop",
      "scanner_message": null,
      "filename": "invoice-re-2026-1048.pdf",
      "file_format": "pdf",
      "file_size": 240123,
      "locale": "en",
      "custom_types": ["invoice"],
      "requester": "accounts-payable",
      "origin": "api",
      "ai_processing": true,
      "is_e_invoice": false,
      "thumbnail": "https://www.exdata.app/api/v1/documents/123/thumbnail",
      "previews": [
        {
          "id": 987,
          "filename": "page-1.png",
          "file_format": "png",
          "file_size": 94812,
          "preview": "https://www.exdata.app/api/v1/previews/987"
        }
      ],
      "latest_extraction_run": {
        "id": 456,
        "mode": "live",
        "source": "api",
        "status": "completed",
        "blocked_reason": null,
        "error_code": null,
        "error_message": null,
        "extraction_schema_version": "2026-05-17",
        "extractor_version": "document:2026-05-17",
        "ai_prompt_version": "document-ai:2026-05-17",
        "normalization_version": "base:2026-05-10",
        "started_at": "2026-05-10T01:00:04.000000Z",
        "completed_at": "2026-05-10T01:00:18.000000Z",
        "created_at": "2026-05-10T01:00:03.000000Z"
      },
      "created_at": "2026-05-10T01:00:00.000000Z",
      "updated_at": "2026-05-10T01:00:18.000000Z"
    }
  ],
  "links": {
    "first": "https://www.exdata.app/api/v1/documents?page=1",
    "last": "https://www.exdata.app/api/v1/documents?page=4",
    "prev": null,
    "next": "https://www.exdata.app/api/v1/documents?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 4,
    "per_page": 25,
    "to": 25,
    "total": 82
  }
}

POST /api/v1/documents

Upload document

Upload a file with multipart form data. The response is a document resource you can poll until processing is complete.

Parameter	Location	Required	Type	Description
`file`	Form data	Yes	File, max 500 MB	Document file. Supported file types are listed under Files and versioning.
`text`	Form data	No	String or null	Additional context you already know, such as the mailbox, source workflow, or customer note.
`custom_types[]`	Form data	No	Array of strings	Optional type extensions for your workflow. Standard types are `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`	Form data	No	String or null	Integration name, user reference, workflow ID, or source system.
`locale`	Form data	No	String or null	Supported locale such as `en` or `de`.
`allow_ai_processing`	Form data	No	Boolean	Legacy processing flag. Most integrations omit this field.

Status	Response	Description
`201`	Document resource	The document was accepted. A pending extraction run is included when processing is queued.
`402`	Insufficient credits error	The document was created, then blocked because the account does not have enough credits.
`403`	Error envelope	The token does not have `documents:write`, or the account is suspended.
`409`	Error envelope	The idempotency key is still processing or was reused with a different upload payload.
`422`	Validation error	The file or form field failed validation.
`429`	Error envelope	Upload rate limit exceeded, including sandbox daily upload limits for test-mode tokens.

Upload request with cURL

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-re-2026-1048.pdf" \
  -F "locale=en" \
  -F "custom_types[]=invoice" \
  -F "requester=accounts-payable"

Upload request with Node.js

import fs from "node:fs";

const form = new FormData();
form.set("file", new Blob([fs.readFileSync("./invoice-re-2026-1048.pdf")]), "invoice-re-2026-1048.pdf");
form.set("locale", "en");
form.append("custom_types[]", "invoice");
form.set("requester", "accounts-payable");

const response = await fetch("https://www.exdata.app/api/v1/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EXDATA_API_TOKEN}`,
    "Idempotency-Key": "invoice-2026-1048",
  },
  body: form,
});

console.log(await response.json());

Upload request with Python

import os
import requests

with open("./invoice-re-2026-1048.pdf", "rb") as file:
    response = requests.post(
        "https://www.exdata.app/api/v1/documents",
        headers={
            "Authorization": f"Bearer {os.environ['EXDATA_API_TOKEN']}",
            "Idempotency-Key": "invoice-2026-1048",
        },
        files={"file": ("invoice-re-2026-1048.pdf", file, "application/pdf")},
        data={
            "locale": "en",
            "custom_types[]": "invoice",
            "requester": "accounts-payable",
        },
        timeout=60,
    )

print(response.json())

Upload request with PHP

<?php

$client = new GuzzleHttp\Client(['base_uri' => 'https://www.exdata.app/api/v1']);

$response = $client->post('/documents', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('EXDATA_API_TOKEN'),
        'Idempotency-Key' => 'invoice-2026-1048',
    ],
    'multipart' => [
        ['name' => 'file', 'contents' => fopen('./invoice-re-2026-1048.pdf', 'r'), 'filename' => 'invoice-re-2026-1048.pdf'],
        ['name' => 'locale', 'contents' => 'en'],
        ['name' => 'custom_types[]', 'contents' => 'invoice'],
        ['name' => 'requester', 'contents' => 'accounts-payable'],
    ],
]);

print_r(json_decode((string) $response->getBody(), true));

201 response

{
  "data": {
    "id": 123,
    "mode": "live",
    "status": "pending",
    "processing_stage": "queued",
    "processing_error": null,
    "blocked_reason": null,
    "filename": "invoice-re-2026-1048.pdf",
    "file_format": "pdf",
    "file_size": 240123,
    "additional_text": null,
    "additional_text_plain": null,
    "custom_types": ["invoice"],
    "requester": "accounts-payable",
    "locale": "en",
    "number_of_pages": null,
    "origin": "api",
    "ai_processing": true,
    "is_e_invoice": false,
    "thumbnail": null,
    "previews": null,
    "extractions": null,
    "latest_extraction_run": {
      "id": 456,
      "mode": "live",
      "source": "api",
      "status": "pending",
      "blocked_reason": null,
      "error_code": null,
      "error_message": null,
      "extraction_schema_version": "2026-05-17",
      "extractor_version": "document:2026-05-17",
      "ai_prompt_version": "document-ai:2026-05-17",
      "normalization_version": "base:2026-05-10",
      "started_at": null,
      "completed_at": null,
      "created_at": "2026-05-10T01:00:03.000000Z"
    },
    "created_at": "2026-05-10T01:00:00.000000Z",
    "updated_at": "2026-05-10T01:00:03.000000Z"
  }
}

GET /api/v1/documents/{document}

Retrieve document

Fetch the current document status, file metadata, preview links, completed extraction fields, and the latest extraction run metadata.

Parameter	Location	Required	Type	Description
`document`	Path	Yes	Integer	Document ID returned by create or list.

Status	Response	Description
`200`	Document resource	Current document state. Completed documents can include previews and extraction fields.
`403`	Error envelope	The token cannot access this document or lacks `documents:read`.
`404`	Error envelope	No document exists for this account and ID.

Request

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

200 response

{
  "data": {
    "id": 123,
    "mode": "live",
    "status": "completed",
    "processing_stage": "completed",
    "processing_error": null,
    "blocked_reason": null,
    "filename": "invoice-re-2026-1048.pdf",
    "file_format": "pdf",
    "file_size": 240123,
    "number_of_pages": 1,
    "origin": "api",
    "ai_processing": true,
    "is_e_invoice": false,
    "thumbnail": "https://www.exdata.app/api/v1/documents/123/thumbnail",
    "previews": [
      {
        "id": 987,
        "filename": "page-1.png",
        "file_format": "png",
        "file_size": 94812,
        "preview": "https://www.exdata.app/api/v1/previews/987"
      }
    ],
    "extractions": {
      "document_number": {
        "value": "RE-2026-1048",
        "candidates": ["RE-2026-1048"]
      },
      "gross_amount": {
        "value": "1079.50",
        "candidates": ["Total due EUR 1,079.50"]
      }
    },
    "latest_extraction_run": {
      "id": 456,
      "mode": "live",
      "source": "api",
      "status": "completed",
      "blocked_reason": null,
      "error_code": null,
      "error_message": null,
      "extraction_schema_version": "2026-05-17",
      "extractor_version": "document:2026-05-17",
      "ai_prompt_version": "document-ai:2026-05-17",
      "normalization_version": "base:2026-05-10",
      "started_at": "2026-05-10T01:00:04.000000Z",
      "completed_at": "2026-05-10T01:00:18.000000Z",
      "created_at": "2026-05-10T01:00:03.000000Z"
    },
    "created_at": "2026-05-10T01:00:00.000000Z",
    "updated_at": "2026-05-10T01:00:18.000000Z"
  }
}

DELETE /api/v1/documents/{document}

Delete document

Deletes the document resource for the account. Use this when your retention policy or customer request requires removal.

Parameter	Location	Required	Type	Description
`document`	Path	Yes	Integer	Document ID to delete.

Status	Response	Description
`204 No Content`	No body	Document deleted.
`403`	Error envelope	The token cannot delete this document or lacks `documents:write`.
`404`	Error envelope	No document exists for this account and ID.

Request

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

GET /api/v1/documents/{document}/thumbnail

Thumbnail

Downloads the generated thumbnail binary for a document when one is available.

Parameter	Location	Required	Type	Description
`document`	Path	Yes	Integer	Document ID.

Status	Response	Description
`200`	Binary stream	Thumbnail file. The content type depends on the generated image.
`403`	Error envelope	The token cannot access this document or lacks `documents:read`.
`404`	Error envelope	No document or thumbnail exists for this account and ID.

Request

curl -L "https://www.exdata.app/api/v1/documents/123/thumbnail" \
  -H "Authorization: Bearer $EXDATA_API_TOKEN" \
  -o document-123-thumbnail.png

GET /api/v1/documents/{document}/previews

List previews

Returns preview metadata for generated page or file previews. Use the returned preview ID with the preview download endpoint.

Parameter	Location	Required	Type	Description
`document`	Path	Yes	Integer	Document ID.

Status	Response	Description
`200`	Preview list	`data` contains preview objects for this document.
`403`	Error envelope	The token cannot access this document or lacks `documents:read`.
`404`	Error envelope	No document exists for this account and ID.

Request

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

200 response

{
  "data": [
    {
      "id": 987,
      "filename": "page-1.png",
      "file_format": "png",
      "file_size": 94812,
      "preview": "https://www.exdata.app/api/v1/previews/987"
    },
    {
      "id": 988,
      "filename": "page-2.png",
      "file_format": "png",
      "file_size": 88204,
      "preview": "https://www.exdata.app/api/v1/previews/988"
    }
  ]
}

GET /api/v1/previews/{preview}

Download preview

Downloads the binary preview file. Preview IDs are returned by the document previews endpoint and are account-scoped.

Parameter	Location	Required	Type	Description
`preview`	Path	Yes	Integer	Preview ID returned by `/documents/{document}/previews`.

Status	Response	Description
`200`	Binary stream	Preview file. The content type depends on the generated preview.
`403`	Error envelope	The token cannot access this preview or lacks `documents:read`.
`404`	Error envelope	No preview exists for this account and ID.

Request

curl -L "https://www.exdata.app/api/v1/previews/987" \
  -H "Authorization: Bearer $EXDATA_API_TOKEN" \
  -o document-123-page-1.png

GET /api/v1/documents/{document}/extractions

Read extractions

Returns extracted fields keyed by field name. Call this after the document reaches completed or after receiving a document.completed webhook.

Parameter	Location	Required	Type	Description
`document`	Path	Yes	Integer	Completed document ID.

Status	Response	Description
`200`	Extraction object	`data` is an object keyed by normalized field name.
`403`	Error envelope	The token cannot access this document or lacks `documents:read`.
`404`	Error envelope	No document exists for this account and ID.

Read extractions with cURL

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

Read extractions with Node.js

const response = await fetch("https://www.exdata.app/api/v1/documents/123/extractions", {
  headers: { Authorization: `Bearer ${process.env.EXDATA_API_TOKEN}` },
});

const extractions = await response.json();
console.log(extractions.data);

Read extractions with Python

import os
import requests

response = requests.get(
    "https://www.exdata.app/api/v1/documents/123/extractions",
    headers={"Authorization": f"Bearer {os.environ['EXDATA_API_TOKEN']}"},
    timeout=30,
)

print(response.json()["data"])

Read extractions with PHP

<?php

$client = new GuzzleHttp\Client(['base_uri' => 'https://www.exdata.app/api/v1']);

$response = $client->get('/documents/123/extractions', [
    'headers' => ['Authorization' => 'Bearer '.getenv('EXDATA_API_TOKEN')],
]);

print_r(json_decode((string) $response->getBody(), true)['data']);

200 response

{
  "data": {
    "type": {
      "value": "invoice",
      "candidates": ["Invoice"]
    },
    "document_number": {
      "value": "RE-2026-1048",
      "candidates": ["RE-2026-1048"]
    },
    "issue_date": {
      "value": "2026-05-10",
      "candidates": ["10 May 2026"]
    },
    "payment_due_date": {
      "value": "2026-06-09",
      "candidates": ["Due 09/06/2026"]
    },
    "sender_name": {
      "value": "Meyer Supply GmbH",
      "candidates": ["Meyer Supply GmbH"]
    },
    "recipient_name": {
      "value": "Northwind Operations Ltd.",
      "candidates": ["Northwind Operations Ltd."]
    },
    "currency": {
      "value": "EUR",
      "candidates": ["EUR"]
    },
    "net_amount": {
      "value": "1079.50",
      "candidates": ["Net amount EUR 1,079.50"]
    },
    "gross_amount": {
      "value": "1079.50",
      "candidates": ["Amount due EUR 1,079.50"]
    },
    "tax_breakdowns": {
      "value": [
        {
          "taxable_amount": "1079.50",
          "tax_amount": "0.00",
          "tax_rate": "0.00",
          "taxability": "taxable",
          "tax_collection_mechanism": "reverse_charge",
          "tax_exemption_reason": "Intra-EU B2B reverse charge"
        }
      ],
      "candidates": ["Reverse charge applies under Article 196 VAT Directive"]
    },
    "payment_reference": {
      "value": "RE-2026-1048",
      "candidates": ["Payment reference RE-2026-1048"]
    }
  }
}

Response objects

The tables below define the fields used by endpoint responses. The extraction field reference lists every normalized extraction key separately.

Document object

Field	Type	When present	Description
`id`	Integer	Always	Document ID.
`mode`	`live` or `test`	Always	Whether the document was created by a live or test-mode token.
`status`	`pending`, `completed`, `error`, or `blocked`	Always	Current document processing status.
`processing_stage`	String or null	Always	Current stage such as `queued`, `extracting`, or `completed`.
`processing_error`	String or null	Always	Human-readable processing failure message when `status` is `error`.
`blocked_reason`	String or null	Always	Machine-readable reason when `status` is `blocked`, for example `insufficient_credits`.
`scanner_status`	`clean`, `rejected`, or null	Always	Upload scanner decision when available.
`scanner_provider`	String or null	Always	Scanner provider or configured scanning backend.
`scanner_message`	String or null	Always	Scanner explanation when available.
`scanned_at`	Date-time or null	Always	When file scanning completed.
`processing_started_at`	Date-time or null	Always	When processing work started.
`processed_at`	Date-time or null	Always	When processing reached a terminal state.
`filename`	String	Always	Original uploaded filename.
`file_format`	String	Always	Detected or stored file extension, for example `pdf`.
`file_size`	Integer	Always	File size in bytes.
`additional_text`	String or null	Always	Optional upload context supplied through the `text` form field.
`additional_text_plain`	String or null	Always	Plain-text version of `additional_text`.
`custom_types`	Array of strings or null	Always	Type extensions supplied at upload time.
`requester`	String or null	Always	Caller reference supplied at upload time.
`locale`	String or null	Always	Locale hint supplied at upload time.
`number_of_pages`	Integer or null	Always	Detected page count when available.
`extracted_text`	String or null	Always	Extracted document text when OCR/text extraction is available.
`extracted_text_plain`	String or null	Always	Plain-text version of `extracted_text`.
`origin`	`api`, `app`, or null	Always	Where the document was created.
`ai_processing`	Boolean	Always	Whether extraction processing is enabled for this document.
`is_e_invoice`	Boolean	Always	Whether the document was recognized as an e-invoice.
`thumbnail`	URL or null	Always	Download URL for the generated thumbnail.
`previews`	Array or null	Always	Preview objects for completed documents when previews are loaded.
`extractions`	Object or null	Always	Extraction fields for completed documents when extractions are loaded.
`latest_extraction_run`	Extraction run or null	Always	Latest extraction attempt metadata.
`created_at`	Date-time	Always	Document creation timestamp.
`updated_at`	Date-time	Always	Last document update timestamp.

Extraction run object

Field	Type	Description
`id`	Integer	Extraction run ID.
`mode`	`live` or `test`	Billing/reporting mode for the run.
`source`	`api`, `app`, or null	Where the run was started.
`status`	`pending`, `processing`, `completed`, `blocked`, or `error`	Run status.
`blocked_reason`	String or null	Machine-readable block reason.
`error_code`	String or null	Machine-readable failure code.
`error_message`	String or null	Failure message for operators or support tooling.
`extraction_schema_version`	String or null	Extraction schema version used by this run.
`extractor_version`	String or null	Extractor implementation version.
`ai_prompt_version`	String or null	AI prompt version used by this run.
`normalization_version`	String or null	Normalization version used after extraction.
`started_at`	Date-time or null	When extraction processing started.
`completed_at`	Date-time or null	When extraction processing completed.
`created_at`	Date-time or null	When the run record was created.

Preview object

Field	Type	Description
`id`	Integer	Preview ID used by the preview download endpoint.
`filename`	String	Generated preview filename.
`file_format`	String	Preview file extension, for example `png`.
`file_size`	Integer	Preview file size in bytes.
`preview`	URL	Download URL for the preview binary.

Extraction field object

Field	Type	Description
`value`	String, array, object, or null	Normalized value for system mapping. Amounts are dot-decimal strings, dates use `YYYY-MM-DD`, currency uses ISO 4217, and `tax_breakdowns` uses an array of tax rows.
`candidates`	Array or null	Raw or derived candidate values considered for the field. Use these in review UIs, support tools, and debugging.

Error envelope

Field	Type	Description
`message`	String	Human-readable error message.
`code`	String	Machine-readable error code such as `validation_failed` or `insufficient_credits`.
`request_id`	String	Request identifier for support and log correlation.
`errors`	Object	Validation field errors. Present on `422` responses.
`retry_after`	Integer or null	Retry delay in seconds. Present on some rate-limit responses.
`available_credits`	Integer	Available credits. Present on insufficient-credit upload responses.
`required_credits`	Integer	Credits required for the upload. Present on insufficient-credit upload responses.
`document`	Document object	Blocked document created before credit reservation failed. Present on insufficient-credit upload responses.
`account_daily_document_limit`	Integer	Sandbox account daily upload limit. Present on test-mode limit responses.
`user_daily_document_limit`	Integer	Sandbox user daily upload limit. Present on test-mode limit responses.
`token_daily_document_limit`	Integer	Sandbox token daily upload limit. Present on test-mode limit responses.