Extract structured FIELDS from a document (PDF or image) with a vision model.
USE THIS WHEN you need specific values OUT of a document — a payslip's gross/net, an invoice's
total/ABN, a form's checkboxes, a table's cells — rather than a yes/no about the document. (For
"is this genuine?" use verify_document; for "what kind of document is this?" classify_document.)
Say WHAT to pull, four ways:
- `fields`: an ad-hoc list — names like ["gross_pay","abn"], or objects
{"name":..., "type":"text|amount|date|boolean", "description":...}. THE general case: ask
for exactly the fields your task needs. Use type "boolean" for a checkbox/tickbox.
- `template`: a named preset — "payslip", "tax_invoice", "bank_statement", "receipt".
- NEITHER: AUTO — the document is classified and that type's fields are used.
- auto on an unrecognised type: schema-free — every labelled field is returned.
Provide the document ONE way: `url` (a public http(s) link — fetched server-side, the cheapest
call) OR `bytes_b64` (inline base64, plus `filename` for PDF-vs-image routing). `country` is an
optional hint; `max_pages` caps how many pages are read (default a few; hard ceiling 10).
Returns `{mode, document_type, fields{name:{value,confidence,page}}, not_found, pages_read,
page_limit}`. EXTRACTION, not verification — values are what the document SHOWS, not proof it is
genuine. A field that isn't clearly present comes back in `not_found` (it abstains rather than
guessing). The document is never stored.