POST /v1/extract
Uploads a single document and returns the extracted, structured receipt.
POST https://api.receipts.oligontech.com/v1/extract
Content-Type: multipart/form-data
X-API-Key: sk_live_...Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
file | form-data | file | yes | Image (JPG, PNG, HEIC, WEBP, TIFF) or PDF, up to 15 MB. |
accuracy | form-data | string | no | standard (default, Haiku 4.5) or high (Sonnet 4.6). High mode bills 5 credits per receipt instead of 1; pick it for crumpled, low-light, or handwritten documents. |
type | form-data | string | no | Hint: receipt, invoice, nfe, nfce, nfse, cupom_fiscal. |
metadata | form-data | JSON | no | Arbitrary tags (≤16 keys, ≤256 chars per value). |
webhook_url | form-data | URL | no | Per-request callback override. Falls back to org default. |
Idempotency-Key | header | string | no | UUID-like value. Replays return the original receipt for 24 h. |
Accuracy modes
| Mode | Model | Latency (typ.) | Billing | When to use |
|---|---|---|---|---|
standard | Claude Haiku 4.5 Vision | ~2–4 s | 1 credit | Default. Clean printed receipts, NF-e/NFC-e PDFs, modern POS prints. |
high | Claude Sonnet 4.6 Vision | ~5–8 s | 5 credits | Crumpled, faded, photographed at angle, handwritten, low-light, or multi-language receipts where standard returns low confidence. |
Most production traffic should run on standard. Use high selectively (e.g. after standard returned confidence < 0.85).
Examples
curl https://api.receipts.oligontech.com/v1/extract \
-H "X-API-Key: $OLIGON_API_KEY" \
-H "Idempotency-Key: 5ddef0..." \
-F "file=@receipt.jpg" \
-F "type=nfe" \
-F "accuracy=standard" \
-F 'metadata={"order_id":"ord_42","tenant_id":"tnt_x"}'Response — 200 OK
{
"id": "rcp_01HQX...",
"org_id": "org_01HQX...",
"status": "completed",
"type": "nfe",
"merchant_name": "Padaria Bom Pão Ltda",
"merchant_tax_id": "12.345.678/0001-90",
"issued_at": "2026-06-08T14:32:11-03:00",
"total": "47.50",
"subtotal": "44.00",
"tax": "3.50",
"currency": "BRL",
"document_number": "000.012.345",
"document_key": "352606123456780...",
"line_items": [
{ "name": "Pão francês", "qty": "10", "unit_price": "1.20", "total": "12.00" }
],
"confidence": 0.97,
"created_at": "2026-06-08T14:32:14Z",
"updated_at": "2026-06-08T14:32:16Z"
}Errors
| Status | Code | Cause |
|---|---|---|
| 400 | unsupported_format | File MIME type not in the allow-list. |
| 400 | file_too_large | File >15 MB. |
| 401 | unauthorized | Missing/invalid/expired API key. |
| 403 | insufficient_scope | Key lacks write. |
| 422 | low_confidence | Document unreadable; consider re-uploading at higher resolution. |
| 429 | rate_limit_exceeded | See Rate limits. |
| 5xx | server_error | Transient — retried automatically by the SDKs. |
extract is idempotent on the SHA-256 of the file body within a 24 h
window. Resending the same file (with or without Idempotency-Key)
returns the cached receipt and is not billed twice.