Document extract structured

POST /api/document-extract-structured6 quota units per call · cache hits free

Extract structured fields from a scanned document or receipt: emails, phone numbers, dates, currency amounts, URLs, and IBANs. Pure regex over OCR — no LLM.

Convenience layer over `document-ocr` that runs a fixed set of regular-expression extractors over the recognised text. Returns every match plus the full OCR text so callers can post-process further. Extractors (all enabled by default; opt out via the boolean knobs): - `emails`: RFC-5322-ish address matcher. - `phones`: international numbers (+CC, parens optional, hyphens or spaces). Won't catch every locale — tuned for the common Western patterns. - `urls`: http(s)://… plus bare `www.` URLs. - `dates`: ISO 8601 (`YYYY-MM-DD`), DMY/MDY with `-`, `/`, `.`, and `D Mon YYYY` (English month names). - `amounts`: currency-prefixed numbers (`$`, `£`, `€`, `¥`, `A$`, `NZ$`, `CHF`) plus three-letter ISO codes (`USD 12.34`). - `ibans`: 15-34 char IBAN with country prefix + checksum digits. **Honest scope:** This is regex-on-OCR. Misspellings, table layout, and locale-specific number formats can all confuse the matchers. For invoice/receipt-grade extraction with line-item fields and per-currency totals you want an LLM or a trained extraction model — out of scope here.

Inputs

Name	Type	Default	Description
image*	file	—	Document image bytes (PNG/JPEG/WebP/AVIF).
emails	boolean	true	Extract email addresses.
phones	boolean	true	Extract phone numbers.
urls	boolean	true	Extract URLs (http(s) and bare www.).
dates	boolean	true	Extract dates (ISO, DMY/MDY, D Mon YYYY).
amounts	boolean	true	Extract currency amounts.
ibans	boolean	true	Extract IBAN account numbers.
includeText	boolean	true	Include the full OCR text in the response (set false for a smaller payload).

Response

Modes: json. Cache: yes (24h TTL).

Every response carries x-cache (HIT / MISS / BYPASS), x-cache-signature (stable across identical inputs), and the rate-limit headers listed below.

Quota & limits

Cost per call	6 units against the 10,000-unit monthly quota. Cache hits are free — only cache misses decrement.
Burst limit	200 requests per rolling minute, shared across all tools.
Max request size	`25 MiB` (base64 inflates file payloads ~33% — the limit applies to the decoded bytes).
Max response size	`5 MiB`
Timeout	60s wall clock.
Rate-limit headers	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Burst-Limit` on every response; `X-Quota-Warning` once 80% of the monthly quota is spent; `Retry-After` on 429s.

Errors

Errors are JSON with an error string; schema failures add a details object (Zod's flattened field errors).

Status	When	Body
400	Input fails the tool's schema (wrong type, missing required field, malformed base64) or the file bytes can't be parsed as the expected format.	{ "error": "invalid inputs", "details": { "fieldErrors": { … } } }
401	Missing or invalid X-Api-Key / X-Account-Id headers (or no session when called from the browser).	{ "error": "unauthorized" }
404	Unknown tool id, or calling /api/* on the website hostname instead of api.xtract.bot.	{ "error": "not found" }
413	Request body over the tool's max request size, or an image header declaring more megapixels than the tool's pixel budget.	{ "error": "…exceeds maxRequestBytes…" }
415	Content-Type isn't application/json on the json-body transport.	{ "error": "unsupported content-type; expected application/json" }
429	Monthly quota or the 200/min burst limit exhausted. Check Retry-After and the X-RateLimit-* headers.	{ "error": "monthly quota exceeded", "monthRemaining": 0, … }
5xx	Conversion engine failure. Safe to retry; if it persists, the input is hitting a bug — please report it.	{ "error": "…" }

Code samples

Built from the invoice example.

# Download or substitute the example input:
#   curl -O https://xtract.bot/examples/ocr-fixtures/document-small.png
IMAGE=$(base64 -w0 < document-small.png)

curl -X POST https://api.xtract.bot/api/document-extract-structured \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Account-Id: $XTRACT_ACCOUNT_ID" \
  -H "X-Api-Key: $XTRACT_API_KEY" \
  -d '{
  "image": "'"$IMAGE"'"
}'