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;
a trusted server environment where the key can remain secret.

See Product access for the current catalog state and Authentication 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.

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.

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 for all request and source rules.

Read the result

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

{
  "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.

Handle errors

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

{
  "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 for the public error catalog and retry guidance.

Next steps

Review Authentication.
Read the full Document contract.
Understand Usage and quotas.
Follow the TypeScript example.
Open the API Reference.
Look up public failures in Errors.

Overview

Getting started

Product guides

Examples

Quickstart

Quickstart

Before you start

Configure your environment

Send an extraction request

Read the result

Handle errors

Next steps

​Quickstart

​Before you start

​Configure your environment

​Send an extraction request

​Read the result

​Handle errors

​Next steps

Quickstart

Before you start

Configure your environment

Send an extraction request

Read the result

Handle errors

Next steps