Recognise a passport or ID document
scan_documentExtract printed fields and MRZ from passports, ID cards, or driver's licences in a photo or scan, returning structured JSON for identity checks.
Instructions
Recognise a passport, national ID card or driver's licence from a photo or scan and return what is printed on it as structured JSON. Inputs: the image as image_base64 (always available), image_path (a local file, and only inside the directory DOC_CHEAP_IMAGE_ROOT names) or image_url (https, on a public address); plus the optional expect_country, return_portrait, retain_hours, reference and idempotency_key. Output: a Scan object – meta (id, status, billed, confidence, timing), document (kind, issuing country, number, series, date of issue, date of expiry, whether it has expired and how many days are left), holder (given names, surname, date of birth, sex, nationality), fields (every field read off the printed page, each with its own confidence), mrz (whether the machine-readable zone checks out, why not when it does not, and its lines exactly as read), images, quality and authenticity – plus a one-line summary of the same result. Calls POST /v1/scans. Cost: it bills one credit ($0.01) only when a document is recognised; an unreadable image, an empty frame or an unsupported type costs nothing, and meta.billed says which happened. Without a key, the public sandbox key is used. It gives 10 free recognised documents per address in all, and at most 10 requests per address an hour, whatever their answer. Registering gives 100 free documents every month. Use it whenever someone hands over an identity document and wants it read, transcribed, or checked against what they claim – a name, a document number, a date of birth or an expiry date.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image_url | No | https: URL of an image on a public internet address, which the server fetches (25 MB maximum). | |
| reference | No | Your own correlation string, echoed back in the result. | |
| image_path | No | Path to a local image file, inside the directory named by DOC_CHEAP_IMAGE_ROOT. Disabled unless that variable is set; send image_base64 instead. | |
| image_base64 | No | The document image as base64 (a data: URL is also accepted). | |
| retain_hours | No | Hours the result stays readable via GET /v1/scans/{id} (0 = store nothing). Omit it to use the account's own history-retention setting. | |
| expect_country | No | ISO 3166-1 alpha-3 country you expect, or omit for any. | |
| idempotency_key | No | Makes a retried scan return the first result instead of charging again. | |
| return_portrait | No | Whether to include the holder photograph crop, images.main_photo (default true). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mrz | Yes | ||
| meta | Yes | ||
| fields | Yes | Every field the engine extracted off the printed document, re-keyed to our vocabulary – the open set. Always present; empty when nothing was extracted. A field read in more than one language appears once per language, so `name` repeats and only `id` is unique. | |
| holder | Yes | ||
| images | Yes | ||
| quality | Yes | ||
| document | Yes | ||
| authenticity | Yes |