> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thewo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Document contract

> Request fields, source limits, response fields, and extraction semantics.

# 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:

| Field | Required | Contract |
| - | - | - |
| `documentUrl` | Yes | Non-empty absolute HTTP or HTTPS URL. Surrounding whitespace is trimmed. The source must be reachable by The Wo. |
| `expectedType` | No | `invoice` or `receipt`. A hint about the expected source type. |
| `language` | No | `en`, `pt`, or `es`. A supported source-language hint supplied to extraction. |

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:

```http theme={"theme":"github-dark-default"}
content-type: application/json
x-api-key: <your-api-key>
```

The optional `Idempotency-Key` header accepts one nonblank value of at most 255
characters. See [idempotent requests](https://docs.thewo.io/trade-document/guides/usage-and-quotas.md#idempotency).

## Sources and limits

The source URL must use `http` or `https`. The retrieved response must have one
of these media types:

| MIME type | Format |
| - | - |
| `application/pdf` | PDF |
| `image/jpeg` | JPEG |
| `image/png` | PNG |
| `image/webp` | WebP |

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:

```json theme={"theme":"github-dark-default"}
{
  "id": "trade_document_example_01",
  "status": "completed",
  "documentType": "invoice",
  "extracted": {
    "documentNumber": "INV-2026-104",
    "issuedAt": "2026-10-19",
    "supplier": { "name": "Example Paper Goods", "taxIdentifier": "SUP-104" },
    "buyer": { "name": "Northstar Workshop" },
    "total": { "minorUnits": 245000, "currency": "USD" },
    "items": [
      {
        "description": "Workshop materials",
        "quantity": 2,
        "unitPrice": { "minorUnits": 1000, "currency": "USD" },
        "lineTotal": { "minorUnits": 2000, "currency": "USD" }
      }
    ]
  },
  "missingFields": ["buyer_tax_identifier"],
  "riskFlags": ["inconsistent_totals"],
  "confidence": 0.93,
  "usage": { "operation": "document_extraction", "units": 1 },
  "createdAt": "2026-10-20T12:00:00.000Z"
}
```

`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:

```json theme={"theme":"github-dark-default"}
{
  "id": "trade_document_example_02",
  "status": "completed",
  "documentType": "receipt",
  "extracted": {
    "merchant": { "name": "Example Market", "taxIdentifier": "MER-204" },
    "purchasedAt": "2026-10-19",
    "subtotal": { "minorUnits": 5000, "currency": "BRL" },
    "total": { "minorUnits": 5000, "currency": "BRL" },
    "items": [{ "description": "Coffee", "quantity": 1.5 }]
  },
  "missingFields": ["tax"],
  "riskFlags": ["low_confidence_critical_field"],
  "confidence": 0.72,
  "usage": { "operation": "document_extraction", "units": 1 },
  "createdAt": "2026-10-20T12:05:00.000Z"
}
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.