Skip to main content

​
Document contract

Trade Document accepts one remote document per request and supports invoices and receipts. The public operation is POST /v1/documents/extract.

​
Request

Send a JSON object with these fields: The request object is strict. Unknown properties are rejected. Omitting expectedType or language sends no corresponding hint; it does not select a document type or language guarantee. Required headers:
The optional Idempotency-Key header accepts one nonblank value of at most 255 characters. See idempotent requests.

​
Sources and limits

The source URL must use http or https. The retrieved response must have one of these media types: The runtime enforces a finite maximum content size configured per deployment. The numeric value is not a stable public contract and may differ by deployment; oversized content returns 413 document_too_large. The runtime does not define a page-count limit. A multi-page PDF is subject to the configured content-size limit and extraction support, not a documented maximum page count. Direct file upload, multipart form data, and inline/base64 document content are not supported by this URL-only API.

​
Successful response

The endpoint returns 201 Created and this response envelope:
id identifies the stored extraction. status is currently completed. documentType is the resulting detected type, either invoice or receipt. createdAt is an ISO 8601 timestamp. Optional extracted properties are omitted when unavailable; they are not serialized as null.

​
Invoice fields

An invoice’s extracted object always includes supplier and items. It can also include documentNumber, issuedAt, buyer, subtotal, tax, and total. Party objects can contain name and taxIdentifier. Each item has a description and may include quantity, unitPrice, and lineTotal.

​
Receipt fields

A receipt’s extracted object always includes merchant and items. It can also include purchasedAt, subtotal, tax, and total. Merchant party and item fields use the same shape as invoice party and item fields. Example receipt response:

​
Money

Monetary values use integer minorUnits and an uppercase three-letter ISO currency code in currency. For a currency with two fractional decimal places, { "minorUnits": 4990, "currency": "USD" } represents USD 49.90. Currency fractional digits vary, so do not assume every currency uses two decimal places.

​
Expected and detected type

expectedType is an optional request hint. documentType in a successful response is the type detected and returned by extraction. If the detected type does not match the hint, the completed response reports the detected documentType and includes document_type_mismatch in riskFlags; the hint does not force the returned type.

​
Missing fields, review flags, and confidence

missingFields contains controlled identifiers for values the extraction schema expects but did not produce at usable reliability. It does not prove the source document omits the value. Possible identifiers are: document_number, issued_at, supplier_name, supplier_tax_identifier, buyer_name, buyer_tax_identifier, merchant_name, merchant_tax_identifier, purchased_at, subtotal, tax, total, and line_items. riskFlags contains review prompts, not findings of fraud or legal defects. Current values are document_type_mismatch, low_confidence_critical_field, inconsistent_totals, unreadable_section, and incomplete_line_items. confidence is a number from 0 to 1 representing extraction confidence. It is not a probability that the document is authentic or that every field is true. Use missing fields and review flags to route results for human review where appropriate.