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

# Quickstart

> Extract your first invoice or receipt with The Wo Trade Document API.

# Quickstart

Send one remotely accessible invoice or receipt URL and receive its structured
extraction.

## Before you start

Trade Document is currently **Coming Soon**. There is no public plan or
self-service activation path, and publishing these docs does not grant access.
To prepare for access, you need:

* a The Wo account and Workspace;
* Trade Document entitlement when it becomes available;
* a Developer API key created in the [Developer Console API Keys page](https://thewo.io/app/api-keys);
* a trusted server environment where the key can remain secret.

See [Product access](https://docs.thewo.io/trade-document/guides/product-access.md) for the current
catalog state and [Authentication](https://docs.thewo.io/platform/authentication.md) for API-key
handling. Never commit the key, put it in a URL, log it, or embed it in browser
or mobile code.

## Configure your environment

Use the canonical production API origin for customer integrations. The Staging
API is reserved for internal The Wo release validation and is not a normal
customer integration target.

```bash theme={"theme":"github-dark-default"}
export THE_WO_API_BASE_URL="https://api.thewo.io"
export THE_WO_API_KEY="<your-api-key>"
```

## Send an extraction request

The example URL below is fictional. Replace it with an absolute HTTP or HTTPS
URL that The Wo can retrieve and that points to an invoice or receipt your
application is authorized to share.

```bash theme={"theme":"github-dark-default"}
curl \
  --request POST \
  --url "$THE_WO_API_BASE_URL/v1/documents/extract" \
  --header "content-type: application/json" \
  --header "x-api-key: $THE_WO_API_KEY" \
  --data '{
    "documentUrl": "https://example.com/documents/sample-invoice.pdf",
    "expectedType": "invoice",
    "language": "en"
  }'
```

`documentUrl` is required. `expectedType` and `language` are optional hints;
`expectedType` does not force the detected result. Accepted values are
`invoice` or `receipt`, and `en`, `pt`, or `es`. The request body is strict, so
unknown fields are rejected.

The URL must resolve to PDF, JPEG, PNG, or WebP content. The maximum content
size is configured per deployment; the public contract defines no page-count
limit. Direct upload, multipart form data, and inline/base64 content are not
supported. See the [document contract](https://docs.thewo.io/trade-document/guides/document-contract.md)
for all request and source rules.

## Read the result

A successful request returns `201 Created`. This illustrative invoice response
shows the public response shape:

```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",
      "taxIdentifier": "BUY-104"
    },
    "subtotal": { "minorUnits": 2000, "currency": "USD" },
    "tax": { "minorUnits": 0, "currency": "USD" },
    "total": { "minorUnits": 2000, "currency": "USD" },
    "items": [
      {
        "description": "Workshop materials",
        "quantity": 2,
        "unitPrice": { "minorUnits": 1000, "currency": "USD" },
        "lineTotal": { "minorUnits": 2000, "currency": "USD" }
      }
    ]
  },
  "missingFields": [],
  "riskFlags": [],
  "confidence": 0.93,
  "usage": { "operation": "document_extraction", "units": 1 },
  "createdAt": "2026-10-20T12:00:00.000Z"
}
```

`documentType` is the type detected by extraction. Monetary values use integer
`minorUnits` and an ISO currency code; currency precision varies. Confidence is
extraction confidence only. Review results against the source before relying on
them for consequential decisions.

One successful extraction records one `document_extraction` usage unit. For
quota and retry behavior, see [Usage and quotas](https://docs.thewo.io/trade-document/guides/usage-and-quotas.md).

## Handle errors

Errors use The Wo's shared JSON envelope. For example:

```json theme={"theme":"github-dark-default"}
{
  "error": {
    "code": "invalid_request_payload",
    "message": "Request body does not match the document extraction contract.",
    "requestId": "req_123"
  }
}
```

Use `error.code` to handle an error and keep `requestId` when reporting a
problem. See [Errors](https://docs.thewo.io/trade-document/guides/errors.md) for the public error
catalog and retry guidance.

## Next steps

* Review [Authentication](https://docs.thewo.io/platform/authentication.md).
* Read the full [Document contract](https://docs.thewo.io/trade-document/guides/document-contract.md).
* Understand [Usage and quotas](https://docs.thewo.io/trade-document/guides/usage-and-quotas.md).
* Follow the [TypeScript example](https://docs.thewo.io/trade-document/examples/typescript.md).
* Open the [API Reference](https://docs.thewo.io/trade-document/api-reference/overview.md).
* Look up public failures in [Errors](https://docs.thewo.io/trade-document/guides/errors.md).


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