Results and Billing

Result Fields

One file can hold several documents, for example two passports scanned on one page. So every 200 answer of POST /v1/extract describes the file, and lists the documents found in it.

The file:

Field	Type	Description
`success`	boolean	`true` when at least one document was read and all three of its check digits matched
`documents`	array of objects	Every document found, in page order and from top to bottom. It can be empty (`[]`)
`document_count`	integer	The number of entries in `documents`
`verified_document_count`	integer	How many of them have `"success": true`
`processing_complete`	boolean	`false` when a limit stopped the work before every part of the file was read, see Several Documents in One File
`truncation_reason`	string or null	`null` when `processing_complete` is `true`. Otherwise `document_limit`, `page_limit` or `time_budget`
`failure_reason`	string or null	`null` when `success` is `true`. Otherwise one of the ten fixed texts in Failure Reasons
`notes`	array of strings	Short technical remarks about the file, for example which reading methods were tried. Notes never contain document data
`duration_ms`	integer	The processing time in milliseconds
`service_version`	string	The version of the processing service

Each entry of documents:

Field	Type	Description
`success`	boolean	`true` only when the MRZ (machine readable zone, the lines of letters, digits and `<` signs at the bottom of the document) of this document was read and all three check digits matched
`document_type`	string or null	The MRZ format that was found: `TD3` (passport), `TD1` or `TD2` (ID card), `MRV-A` or `MRV-B` (visa). `null` when no format was recognised
`fields`	object	The extracted data, see the next table. It can be empty (`{}`)
`check_digits_valid`	object	The result of each check digit, see Check Digits. It can be empty (`{}`)
`checksum_protected`	object	For each of the eight fields, whether a check digit covers it at all. It is the same for every document
`failure_reason`	string or null	`null` on a success. Otherwise one of the fixed texts in Failure Reasons
`notes`	array of strings	Short technical remarks about this reading, for example `birth date century inferred`. Notes never contain document data
`page`	integer	The page of the file, counted from 1. An image file has one page
`region`	object or null	Where the MRZ was found, as fractions of the page: `x`, `y`, `width` and `height`, each from 0 to 1. `null` when the position is not known

The fields object:

Field	Format	Protected by a Check Digit
`surname`	Text in capital letters	No
`given_names`	Text in capital letters, names separated by a space	No
`birth_date`	`YYYY-MM-DD`	Yes
`sex`	`M`, `F`, `X` or `null`. The MRZ filler `<` is returned as `X` (unspecified)	No
`nationality`	Country code from the MRZ. The `<` filler is removed, so the code can be shorter than three letters, for example `D`	No
`document_number`	Text	Yes
`expiry_date`	`YYYY-MM-DD`	Yes
`issuing_country`	Country code from the MRZ. The `<` filler is removed, so the code can be shorter than three letters, for example `D`	No

In a document with "success": true, all eight keys are present. The three protected fields always hold a value. The five fields without a check digit (surname, given_names, sex, nationality, issuing_country) can be null when they could not be read.

Note

The MRZ stores a year with two digits only. The engine chooses the century and tells you so in the document's notes, for example birth date century inferred.

Several Documents in One File

A file can hold several documents: for example the passports of two people on one scanned page, or one passport on each page of a PDF. IDParse returns every document it finds, up to five per file.

Check success of each document. The file's success only tells you that at least one document was verified.
A file can contain a verified document and a document that could not be verified. Both are listed, and the file counts as a success.
The same document number on two different pages is listed twice. IDParse cannot know whether it is the same physical document.
A PDF page that cannot be opened is skipped, and the file's notes say so, for example page 2 could not be rendered. The other pages are still read. In the rare PDF whose page count cannot be read, such a page ends the reading instead, and the later pages are not searched.
After a document was verified, the later pages of a PDF get a quicker reading. A second document there that is very hard to read can then be missed, even when processing_complete is true. For such files, send each document on its own.

When processing_complete is false, a limit stopped the work early. The documents found until then are still returned and are correct. truncation_reason names the limit:

`truncation_reason`	Meaning
`document_limit`	The file holds more documents than the limit of five per file
`page_limit`	The PDF has more pages than the page limit
`time_budget`	The processing time ran out before every part of the file was read

Note

For the best results, send one document per file. Several documents in one file work, but each one gets less of the processing time.

Check Digits

A check digit is a control number that is printed inside the MRZ. It is calculated from the characters of one field. After reading, the engine calculates the number again and compares it with the printed one. Check digits detect many reading errors but do not guarantee that the extracted values are correct.

Check digits protect only three fields: document_number, birth_date and expiry_date. The check_digits_valid object holds a flag (true or false) for each of them. A flag is true only when the field holds a usable value, its own check digit passes, and no combined check digit that covers the same line fails. In a partial result a flag is also false when two readings of the same page gave different verified values for the field.

What check digits do:

They detect many reading errors in the three protected fields, for example a 0 that was read as an O.

What check digits do not do:

They do not prove that a document is genuine. A forged document can carry correct check digits.
They do not prove that the document belongs to the person who presents it.
They do not protect the names, the sex, the nationality or the issuing country. These fields can contain a reading error even when success is true.

A second, independent reader can check the name. The document notes then say readers agree on the name (both readers read the same name) or name not checked by a second reader (no second reading was possible). Both are hints, not check digits. When the two readers read different names, the document is not verified: its failure_reason is mrz check digits passed but two readers read different names, the names are withheld, and the protected fields stay as a partial result.

Important

IDParse is a data extraction service. It reads what is printed in the MRZ. Decisions about a person or about the validity of a document stay with you.

Failure Reasons

When the file's success is false, its failure_reason holds exactly one of these ten texts. A document that could not be verified carries one of them in its own failure_reason too. The texts are fixed, so you can compare them in your code. A file without any verified document is free of charge.

`failure_reason`	Meaning	What You Can Do
`no machine readable zone found`	No MRZ was found in the file	Make sure the whole MRZ is visible, sharp and well lit. Check that the document has an MRZ at all
`mrz found but check digits failed`	An MRZ was found, but at least one check digit did not match. The reading is not reliable	Send a better image: higher resolution, no glare, no blur, no fingers over the MRZ. A partial result is possible
`mrz check digits passed but the name zone could not be read`	The protected fields were read, but the name part of the MRZ was not readable	Send a sharper image of the whole MRZ. A partial result is possible
`mrz check digits passed but two readers read different names`	The protected fields passed their check digits, but two independent readers read the name differently, so the names are withheld	Send a sharper image of the whole MRZ, or let a person read the name. A partial result is possible
`ambiguous mrz candidates`	Two different readings of the same MRZ were found, and the engine could not decide between them	Send a sharper image of that document
`unrecognised file type`	The file is not one of the supported file types	Send a JPEG, PNG, PDF, TIFF, BMP, WebP or HEIF/HEIC file
`image could not be decoded`	The image file is damaged or incomplete	Export or save the image again and send the new file
`image exceeds the pixel limit`	The image has too many pixels	Scale the image down and send it again
`pdf could not be rendered`	The PDF file could not be opened, for example because it is damaged or protected by a password	Export the PDF again without protection, or send the page as an image
`no ocr engine available`	The text reading software (OCR, optical character recognition) is not ready on our side. This is a temporary fault of the service, not of your file	Send the same file again later. If it happens again, contact support

Partial Results

A partial result is a document with "success": false in which some fields are filled. It can happen with failure reasons such as mrz found but check digits failed, mrz check digits passed but the name zone could not be read or mrz check digits passed but two readers read different names. A partial document can stand alone in the file, or next to verified documents.

You recognise a partial document by its notes array. It holds the exact text partial read: trust only fields whose check digit passed. A protected field that is not trusted is returned as null. A reading in which no field could be verified is not returned at all.

Rules for a partial document:

Trust a protected field (document_number, birth_date, expiry_date) only when its entry in check_digits_valid is true.
Treat every other filled field as a hint only. Show it to a person for review, or ask for a better image.
A missing key in check_digits_valid means "not verified". Treat it like false.

A file with partial documents only is free of charge. An example is shown in Endpoints.

What Is Charged

Only a validated success is charged: HTTP 200 with "success": true. One file uses one of your included scans, whatever number of documents it holds.

Answer	Charged
`200` with `"success": true`, one or more documents	Yes, one scan
`200` with `"success": true` and `"processing_complete": false`	Yes, one scan
`200` with `"success": false` (unreadable or partial)	No
Every `4xx` error (for example `401`, `413`, `422`, `429`)	No
Every `5xx` error (for example `502`, `503`, `504`)	No
`GET /v1/quota`	No, never

Important

There is no duplicate protection. If you send the same file twice and both answers are a success, two scans are charged. Store the result of a success on your side instead of sending the file again.

When to Retry

Retry after 503 (engine_busy, engine_unavailable, service_unavailable), 504 (engine_timeout) and 502 (bad_engine_result). These requests were not charged. If the answer has a Retry-After header, wait at least that number of seconds.
Retry after 429 rate_limited. Wait the number of seconds in Retry-After first.
Do not retry quickly after 429 quota_exhausted. Here Retry-After is the time until the next calendar month.
Send the same file again later after 200 with "success": false and the failure reason no ocr engine available. This is a temporary fault of the service, not a problem of your file.
Do not retry the same file after any other 200 with "success": false. These answers need a better image, not a retry.
Do not send the whole file again after 200 with "processing_complete": false. Keep the documents you received, and send the pages or documents that were not read as separate files.
Do not retry after 401, 403, 413 and 422. Fix the key, the account or the file first.
Limit the number of retries, and make the waiting time longer after each failed attempt.

Note

If your connection breaks before you receive an answer, you cannot know whether the scan was charged. The used value of GET /v1/quota can give you a hint, but no proof. The usage count can include scans that are still being processed. It cannot confirm whether one interrupted request was charged.