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.

Field	Type	Nullable	Description
schema_version	string	no	The version of this body, always `1.0`. A consumer that pins this value checks that the body is the one it was written against.
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 the scan met the billing rule. On a live key, `true` means one credit was charged. On a sandbox key nothing is ever charged, and the flag only shows whether the same scan would have been.
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, which state issued it, its number and dates, and whether it has expired. 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, as its three-letter code. 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, the three-letter code the document writes – the same reading as `country`, under the name the machine-readable zone gives it.
issuing_state_detail	object	yes	The issuing state's code resolved: as written, as ISO 3166-1 alpha-3 and alpha-2, and its category. Null when no code was read.
issuing_state_detail.code	string	no	The code as the document writes it, without the zone's `<` filler: `D` for Germany, `GBD` for a British Overseas Territories citizen.
issuing_state_detail.alpha3	string	yes	The ISO 3166-1 alpha-3 code of the state the code stands for, or null when ISO has none (Kosovo, organisations, stateless persons, refugees, specimens, unknown codes).
issuing_state_detail.alpha2	string	yes	The ISO 3166-1 alpha-2 code of the same state, or null with `alpha3`.
issuing_state_detail.category	enum	no	What a document's country code is. `iso`: an ISO 3166-1 alpha-3 code. `icao_variant`: an ICAO spelling of an ISO state (`D` for Germany). `british_nationality`: a British nationality class (`GBD`, `GBN`, `GBO`, `GBP`, `GBS`). `kosovo`: `RKS`, which ISO does not list. `united_nations`: `UNO`, `UNA`, `UNK`. `organization`: an issuing authority that is not a state (`EUE`, `XPO`, `IAO` and the other `X..` codes of ICAO Doc 9303). `stateless`: `XXA`. `refugee`: `XXB`, `XXC`. `unspecified`: `XXX`. `deprecated`: a code ISO has withdrawn (`ANT`, `NTZ`). `specimen`: `UTO`, the fictional state of specimen documents. `unknown`: a code in none of these lists.
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.
number	string	yes	The document number, as printed. Null when none was read. A series the document prints separately is in `series`, never folded into this value.
series	string	yes	The document series, for a document that prints one as a field of its own. Null when the document carries none or none was read; it is never split out of `number`.
issue_date	date	yes	The date the document was issued, ISO-8601 (`YYYY-MM-DD`). Null when none was read.
expiry_date	date	yes	The date the document expires, ISO-8601 (`YYYY-MM-DD`). Null when none was read; `is_expired` and `days_remaining` are computed from it.
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, the three-letter code the document writes. Null when none was read; it is not assumed from the issuing state.
nationality_detail	object	yes	The nationality code resolved: as written, as ISO 3166-1 alpha-3 and alpha-2, and its category – `stateless` or `refugee` for a holder without a nationality. Null when no code was read.
nationality_detail.code	string	no	The code as the document writes it, without the zone's `<` filler: `D` for Germany, `GBD` for a British Overseas Territories citizen.
nationality_detail.alpha3	string	yes	The ISO 3166-1 alpha-3 code of the state the code stands for, or null when ISO has none (Kosovo, organisations, stateless persons, refugees, specimens, unknown codes).
nationality_detail.alpha2	string	yes	The ISO 3166-1 alpha-2 code of the same state, or null with `alpha3`.
nationality_detail.category	enum	no	What a document's country code is. `iso`: an ISO 3166-1 alpha-3 code. `icao_variant`: an ICAO spelling of an ISO state (`D` for Germany). `british_nationality`: a British nationality class (`GBD`, `GBN`, `GBO`, `GBP`, `GBS`). `kosovo`: `RKS`, which ISO does not list. `united_nations`: `UNO`, `UNA`, `UNK`. `organization`: an issuing authority that is not a state (`EUE`, `XPO`, `IAO` and the other `X..` codes of ICAO Doc 9303). `stateless`: `XXA`. `refugee`: `XXB`, `XXC`. `unspecified`: `XXX`. `deprecated`: a code ISO has withdrawn (`ANT`, `NTZ`). `specimen`: `UTO`, the fictional state of specimen documents. `unknown`: a code in none of these lists.

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 on a national-script reading, the transliterated Latin value on the default reading (the one whose `id` carries the identifier `0`). Null when the field is empty.
language	string	yes	The language this reading was made in, e.g. `Greek`. The default Latin-script reading – the document's own Latin page and the machine-readable zone, `id` suffix `@0` – is `English`. Null only on `days_to_expire`, a number computed from the expiry date rather than text read in any language.
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.