API reference / Documents

post/v1/documents/mrz

Read a passport page's machine-readable zone

Operation
readPassportMrz
Authentication
API key

The caller sends the image as the request body (`image/jpeg`, `image/png` or `image/webp`) and gets back what the document says. A second opinion on the browser's own reading: `passporteye` validates every check digit in the line, including the composite one, so a misread character cannot quietly become a different valid value. `valid_score` is its confidence, passed through rather than hidden. A photograph with no readable zone answers 422 with a sentence for the traveller; an unconfigured or unreachable reader answers 503.

Request

Body

Free-form JSON object.

Responses

200The zone was read.
validbooleanrequired
valid_scorenumbernullrequired
passport_numberstringnullrequired
issuing_statestringnullrequired
surnamestringnullrequired
given_namesstringnullrequired
birth_datestringnullrequired
expiry_datestringnullrequired
sexstringnullrequired
personal_numberstringnullrequired
400The request body or query failed validation.
errorobjectrequired
401No key, an unknown key, a revoked key, or a key whose tenant is not active. All four return an identical body on purpose: distinguishing them would let a caller discover which partners we have.
errorobjectrequired
403The key is valid but does not hold the scope this route requires.
errorobjectrequired
404Not found, or not yours. A resource belonging to another tenant answers 404 rather than 403, because 403 would confirm the record exists.
errorobjectrequired
422The photograph has no readable machine-readable zone.
errorobjectrequired
503The passport reader is not configured, or could not be reached.
errorobjectrequired

Example

curl
curl -X POST https://api.haavisa.com/v1/documents/mrz \
  -H "Authorization: Bearer $HAAVISA_API_KEY"

More in Documents

Something unclear? The eligibility guide explains the model behind the answers; the errors guide covers the envelope.