Extract fields from documents

A page costs 13 credits when the schema counts up to 50 leaf fields, and 19.5 credits when it counts 51 to 100. That is two and three times the OCR rate of 6.5. The reading is included. A page is one PDF page or one image file. The page count is read from the document and the leaf count from the schema, both before the charge. The cost is known before any reading starts. Evidence and the reading change no charge.

The leaf count is every leaf field once, plus every leaf inside an array once per element the array is sized for. A schema with fifteen header fields and three fields per line item over ten items counts 45 leaves. The same schema over twenty items counts 75. The response reports the count in usage.leaves beside usage.pages and usage.credits.

The charge is reported only in the body's usage.credits. This endpoint sends no x-credits-charged header. When extraction fails after the charge, the refund is automatic and the response is 502 provider_error. A document that carries none of the fields is a delivery, with the fields null, and is charged.

schema is an object with one key, fields, mapping each field name to its definition. A definition carries a type, an optional required flag, an optional description of up to 200 characters, and the keys its type offers. The description is the one piece of your prose the model reads. It is where a field's meaning goes, for example "Seller name as printed at the top". Names are 1 to 64 characters of letters, digits, and underscores.

Two containers nest fields. An object carries its own fields. An array carries items, a leaf or an object, and a required max_items of 1 to 200. At most 3 containers sit below the root. items[].tax.rate is allowed and a fourth level is refused. An array holds leaves or objects. An array inside an array is refused.

Constraints#

A constraint says what the field is. A printed value that fails one is delivered null with the reason, and the span stays in evidence when you asked for it. Bound a number with min, max, and decimals. Shape a string with pattern, a regular expression of up to 200 characters matched against the whole value, and with min_length and max_length. Bound a date with min and max as ISO dates and with not_future, judged against today in Thailand. An id takes digits as a count or a [min, max] pair from 1 to 64, and check as none, thai_mod11, or luhn. A check detects a wrong digit and never corrects it.

year says how a date reads a two-digit year. The default, recent, takes whichever era puts the date in the recent past. A bare 69 on a receipt is then BE 2569. strict delivers a year only when one era fits. be and ce name the era you know. Whichever rule applies, every two-digit year read is listed in the response's assumed with the digits as printed.

Enums and built-in sets#

An enum lists its values and may carry aliases, a map from a value to up to 20 other spellings, for example "bangkok" to กรุงเทพมหานคร, กทม., and BKK. The printed span is resolved against the set. An exact match, case folded, wins first. Then a span containing exactly one value's spellings of four characters or more. Then a span one edit from exactly one value, with no other value within two edits. A tie resolves to nothing and the field is null with ambiguous_match. Set strict to true for exact matches only. An enum is also the one field that may be a judgment: a classification nothing prints, such as the kind of document, is chosen from the listed values.

The closed-set types, province, bank, insurer, postal_code, card_scheme, payment_method, legal_form, currency, and unit, are enums whose tables the service ships, including the abbreviations documents print. A former bank name resolves to its successor. A bare currency sign such as $ names several currencies and is delivered as the sign. format picks the delivered form, always a lossless one:

Schema refusals#

A schema outside the dialect answers 400 schema_invalid before the document is read, uncharged. The problem body carries two fields beyond the minimum shape. path names the offending field in dot form, empty for the root. reason is one of the values below. A schema over 128 KB as JSON answers the same code with reason too_large.

fields is your schema's tree with plain values, null wherever nothing was read. status is "complete" when every required field carries a value and "incomplete" otherwise. It is computed from the fields alone. A file that is not what the schema describes comes back incomplete with most required fields in missing, which is how to detect the wrong document. There is no confidence score. A faithful copy of a misread digit is invisible to any score, and the types that carry a check digit are how such a misread is caught.

• missing lists every required field delivered as null, for any reason.
• unverified lists every field whose span could not be read as the field's type, or whose value the reading did not carry, each with a reason from the table below. Those fields are null.
• truncated lists every array whose document carried more elements than it was sized for. The first max_items elements are in fields, in reading order. Raise max_items to read the rest.
• assumed lists every date whose year was printed with two digits, with printed and read_as. It is always present and empty when nothing was assumed.
• evidence, when include_evidence is true, maps each field path to the printed span its value was read from, whether or not a value could be read from it.
• pages, when include_pages is true, is the text read from each page as Markdown, the same reading POST /v1/ocr returns. The fields were extracted from it.

Paths are in dot form with array elements indexed, for example "items[2].amount". The unverified reasons:

One request reads at most 20 pages, and a longer document answers 400 too_many_pages. The decoded file may be at most 10 MiB, and a larger one answers 413 document_too_large. A schema counts at most 100 leaves and is at most 128 KB as JSON. The document rules of the OCR guide apply unchanged: the format is detected from the bytes, an image is one page, and an unreadable or password-protected file is refused before the charge. One document per request. A file holding several documents gets one set of fields.

The response is one buffered JSON body. A multi-page document can take minutes. Set the client timeout generously. The samples above allow 300 seconds.

A request that runs long enough writes its response headers before the outcome is known. Intermediate proxies abandon a connection that has been silent too long, and the early headers prevent that. Such a response always has status 200. It reports a failure in the body, as the same problem document a failed request returns: a title and a status where fields would be. Treat a body carrying title as the error it describes.

Retries are safe with an Idempotency-Key. A replay of a delivered request serves the same fields again without a second charge. When extraction fails, the charge is refunded and a fresh request needs a new key. The model id is the contract version. The dialect, the response shape, and the leaf-counting rule are fixed under paxa-doc-extract-v1, and a change ships as a new id served beside it.