API v1 documentation

Production checklist

Before going live, verify authentication, webhooks, retries, credits, and observability.

Credentials

Create live credentials only after your test-mode integration has passed uploads, polling or webhooks, and error handling.

Live token is stored in your secret manager, not in source control.
Token abilities are limited to the integration's needs.
Token rotation has an owner and a documented procedure.
Environment variables are separated for test and live deployments.

Uploads

Upload code should be retry-safe and should preserve enough context for your team when processing takes time.

Each logical upload sends a stable Idempotency-Key.
Your database stores the exdata document ID and local source ID together.
Your UI or application state supports pending, completed, error, and blocked.
Your integration keeps polling or receiving webhooks after 201, including for an asynchronous page_band_insufficient_credits block.
Your usage review reads latest_extraction_run.credits_charged after terminal states.
Your integration validates file size and type before upload where possible.
If you select processing_lane=batch, confirm that it is available for the account, allow for lower-priority processing, and handle 422 with code=validation_failed and a processing_lane validation error.

Webhooks

Webhook receivers should be small, deterministic, and idempotent. Do the minimum required work before returning a 2xx response.

Receiver verifies X-Signature over X-Timestamp, X-Delivery, X-Event, and the exact raw request body.
Receiver rejects missing or stale X-Timestamp values using a short tolerance such as five minutes.
Receiver stores X-Delivery under a unique constraint before starting downstream work.
Receiver handles duplicate delivery IDs without repeating automation.

Errors

Build explicit paths for validation errors, rate limits, blocked documents, and failed extraction runs.

Condition	Signal	Production behavior
Validation failed	`422`, `errors`	Show field-level diagnostics to your development team.
Rate limited	`429`, `retry_after`	Back off and retry according to your retry policy.
Initial credits unavailable	`402`, `insufficient_credits`	Alert the account owner and stop automatic retry loops. No credit was charged.
Later page band unavailable	`status: "blocked"`, `page_band_insufficient_credits`	Handle this asynchronous outcome after `201`. The initial credits are returned, so net usage is zero.
Processing error	`status: "error"`	Route to support or manual review with the request ID. A terminal error returns all applied credits only when neither a usable result nor retrievable extracted fields remain.

Observability

Keep exdata identifiers next to your local identifiers so your team can investigate and compare usage quickly.

Log local source ID, exdata document ID, and X-Request-ID.
Record webhook event type, delivery ID, processing result, and final credits_charged.
Alert when documents stay pending beyond your expected window.
Expose candidates in your review workflows when a field affects money, tax, or vendor identity.

Go-live

Before sending production volume, run one live document through the complete workflow and inspect the final JSON, webhook logs, and downstream mapping.

Recommended first live run

Upload one real invoice, verify the extraction response, verify the webhook delivery, and confirm that your system creates the expected draft or review item before enabling automation for a larger source.