Document field explorer

Every successful scan returns the same structured object. Here is each field, its type and whether it can be null — a known-but-absent value is null, never a missing key.

meta

What this scan is and how it went: its id, its status, whether it drew a credit, and where the time went.

Field	Type	Nullable	Description
schema_version	string	no	The revision of this body, always `1.0`. A key removed or renamed moves the major segment, so a consumer that pins this value stops loudly rather than reading a key that no longer means what it did.
id	string	no	Scan identifier: a UUID version 7 (RFC 9562), canonical lower-case `8-4-4-4-12`. Its leading 48 bits are the millisecond the scan was made, so ids sort in the order the scans happened — but treat the value as opaque: nothing else about it is part of the contract.
status	enum	no	Outcome of a scan. Exactly these five string values; there are no numeric codes.
billed	boolean	no	Whether this scan was charged to the balance.
confidence	enum	no	How strongly the recognition backs this reading as a whole. Each entry of `fields` carries its own band as well, and they can differ from this one.
timing	object	yes	The split of the request's time. Null on a scan made before the split existed and read back out of storage: only the engine call was timed then, and the two halves cannot be recovered from it.
timing.upload_ms	integer	no	From the request's headers reaching the server to its body being received and validated, with your key resolved and its rate limit checked. The allowance, idempotency and credit gates are claimed after this number is taken, so they are not in it. Dominated by your own connection and by how large the image is — this is the half you can shrink, by sending a smaller picture from closer by.
timing.processing_ms	integer	no	The recognition itself — the server-side engine call.
timing.total_ms	integer	no	From the request arriving to the result being complete. At least `upload_ms + processing_ms`; the remainder is the gates that run after `upload_ms` is taken — the allowance, the idempotency check and the credit hold — plus preparing the result images and mapping the engine's output into this body. It stops there: writing the history row and serializing the response happen after the number is fixed, so the same figure is stored and returned.
created_at	date-time	no	Timestamp, ISO-8601 in UTC (`YYYY-MM-DDTHH:MM:SSZ`).
reference	string	yes	The request's `reference`, echoed back.

document

What kind of document was recognised and which state issued it. Null when nothing was recognised.

Field	Type	Nullable	Description
kind	string	no	Document type, e.g. `passport`.
country	string	yes	The state that issued the document, ISO 3166-1 alpha-3. The same reading as `issuing_state` under the name most callers filter on; null when nothing was read.
country_name	string	yes	The issuing state's name, as read from the document.
issuing_state	string	yes	The issuing state, ISO 3166-1 alpha-3 — the same reading as `country`, under the name the machine-readable zone gives it.
type_name	string	yes	The document type under its full name. Null on a scan read back from storage, which keeps no engine output.
type_confidence	enum	no	How strongly the document-type match is backed.
is_expired	boolean	yes	Whether the document had already expired when the scan was made. Null when no expiry date was read, which is a different answer from `false`.
days_remaining	integer	yes	Days until expiry at the time of the scan; negative once expired.

holder

The person the document identifies. Null when nothing was recognised.

Field	Type	Nullable	Description
given_names	string	yes	The holder's given names, as printed. Null when none was read.
surname	string	yes	The holder's surname, as printed. Null when none was read.
full_name	string	yes	The holder's name as the document prints it in one combined field. Null when the document carries no such field — it is not composed from the two above.
birth_date	date	yes	The holder's date of birth, ISO-8601 (`YYYY-MM-DD`). Null when none was read.
sex	enum	yes	The sex the document states: `M`, `F`, or `X` for unspecified. Null when none was read.
nationality	string	yes	The holder's nationality, ISO 3166-1 alpha-3. Null when none was read; it is not assumed from the issuing state.

fields[]

Every field read off the printed page, re-keyed to a stable name. One entry per reading, each with its own language and confidence band.

Field	Type	Nullable	Description
id	string	no	Identity of this entry, unique across `fields`: the key and the language identifier the value was read as, plus an occurrence counter when the same pair is reported twice. `name` is the semantic key and repeats — a document that carries a field in two scripts yields one entry per language — so use `id`, not `name`, to address or key a single entry.
name	string	no	Our stable snake_case key.
label	string	no	Our human label.
category	enum	no	Which group of the report a field belongs to.
value	string	yes	The value of this reading: the national-script spelling when `language` names one, the transliterated Latin value otherwise. Null when the field is empty.
language	string	yes	The language this reading was made in, e.g. `Greek`; null for the neutral, transliterated Latin reading.
confidence	enum	no	How strongly the recognition backs this value: `high`, `medium` or `low`. An unknown or missing probability reads as `low`.

mrz

The machine-readable zone: a verdict on whether it checks out, the reason when it does not, and the lines themselves exactly as read.

Field	Type	Nullable	Description
status	enum	no	Verdict on the machine-readable zone: `passed` (present, every check digit valid and nothing contradicting the printed page), `failed` (present but something did not check out) or `absent` (the document carries none).
reason	string	yes	One plain sentence naming what did not check out, for `failed`; null otherwise.
lines	string[]	yes	The zone's lines in order, exactly as read — two for a TD3 passport, three for a TD1 card. The zone's alphabet is `A-Z`, `0-9` and the filler `<`, so a line carries no whitespace. Null when the document carries none.
text	string	yes	The same lines run together with nothing between them: one unbroken string, with no newlines and no spaces. Null when there are none.

images

Crops taken from the picture you sent, each one a data URL.

Field	Type	Nullable	Description
document_crop	string	yes	The document itself, cropped out of the uploaded picture and deskewed — the front side of a card, the data page of a booklet.
rear	string	yes	The reverse side of the document, when the picture carried one and a crop of it was produced.
main_photo	string	yes	The holder's photograph as printed on the document.
signature	string	yes	The holder's signature as printed on the document.
watermark_face	string	yes	The faint second copy of the holder's face printed into the page as a security feature — a different image from `main_photo`, and the one a verifier compares against it. Null when the document carries none.
barcode	string	yes	The barcode area of the document, when it carries one.
chip	string	yes	The chip area of the document, when it carries one.

quality

Whether the picture you sent was good enough to recognise from.

Field	Type	Nullable	Description
overall	enum	no	Whether the uploaded picture was good enough to recognize from. `not_checked` when nothing measured it — a scan read back from storage, which keeps no engine output.

authenticity

Authenticity verification. It does not run under the recognition-only call, which reports it as not checked.

Field	Type	Nullable	Description
overall	enum	no	`not_checked` under the recognition-only scenario; populated by authenticity verification later.
checks	object[]	no	One entry per authenticity check that ran. Always present; empty under the recognition-only scenario, where nothing ran.
checks.name	string	no	Our stable snake_case key for this check.
checks.label	string	no	Our human label for this check.
checks.result	enum	no	Outcome of a single check.
checks.detail	string	yes	One plain sentence about what this check saw, or null when it has nothing to add.

Try it on a real document in the live demo, or see per-country structure under passport OCR.