MRZ API

Send a document image. Receive structured data as JSON.

POST/v1/mrz

Your base URL and key are provided after activation. The customer API is not enabled on this website.

Full reference ↗

Access

We provide your base URL and API key. Store both as environment variables on your server. Keep the key out of browser code, client apps and public repositories.

VariablePurpose
MRZ_BASE_URLYour activated base URL
MRZ_API_KEYYour secret API key

Request access · Authentication details

Send a request

Send POST /v1/mrz with Authorization: Bearer … and Content-Type: application/json. The JSON contains exactly image_base64 with your image bytes encoded as Base64, without a data-URI prefix.

The examples use include_crop=false to return data first. For an available document crop, set include_crop=true or omit the parameter. Its image bytes are returned in crop_jpeg_base64; if no crop is available, the value remains null.

Bash 3.2+, cURL and Python 3.

mrz.sh
#!/usr/bin/env bash
set -euo pipefail
: "${MRZ_BASE_URL:?Set MRZ_BASE_URL}"
: "${MRZ_API_KEY:?Set MRZ_API_KEY}"
timeout="${MRZ_TIMEOUT_SECONDS:-95}"
if ! python3 -c 'import math, sys; n = float(sys.argv[1]); assert math.isfinite(n) and n > 0' "$timeout" 2>/dev/null; then
  printf '%s\n' 'Set a positive MRZ_TIMEOUT_SECONDS.' >&2
  exit 1
fi

# Keep the request and response in memory, not in temporary document files.
if ! wire="$(python3 -c '
import base64, json
from pathlib import Path
print(json.dumps({"image_base64": base64.b64encode(Path("document.jpg").read_bytes()).decode("ascii")}))
' 2>/dev/null | curl --disable --silent \
  --max-time "$timeout" --proto '=http,https' \
  --request POST "${MRZ_BASE_URL%/}/v1/mrz?include_crop=false" \
  --header "Authorization: Bearer ${MRZ_API_KEY}" \
  --header 'Content-Type: application/json' --header 'Accept: application/json' \
  --data-binary @- --write-out '\n%{http_code}')"; then
  printf '%s\n' 'MRZ request failed.' >&2
  exit 1
fi
status="${wire##*$'\n'}"
body="${wire%$'\n'*}"
case "$status" in
  2??) ;;
  *) printf 'MRZ HTTP %s.\n' "$status" >&2; exit 1 ;;
esac
printf '%s' "$body" | python3 -c '
import json, sys
try:
    result = json.load(sys.stdin, parse_constant=lambda _: (_ for _ in ()).throw(ValueError()))
except (ValueError, UnicodeError):
    sys.exit("Invalid JSON response.")
# Use result in your application; do not print document data.
print("MRZ response received.")
'

Run: bash mrz.sh

Download example ↓

Input formats, Base64 rules and size limits ↗

Read the result

The response contains a documents list. Each document has its own fields and checks. This is an abridged example; the full response contains additional fields.

Abridged response · HTTP 200
{
  "documents": [
    {
      "status": "recognized",
      "format": "TD3",
      "mrz": [
        "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "L898902C36UTO7408122F1204159ZE184226B<<<<<10"
      ],
      "fields": {
        "surname": "ERIKSSON",
        "given_names": "ANNA MARIA",
        "document_number": "L898902C3"
      },
      "errors": [],
      "corrections": [],
      "crop_jpeg_base64": null
    }
  ],
  "timed_out": false
}
CheckHandling
timed_outIf true, the result is incomplete. Do not import automatically.
documentsEmpty: no candidate found. Multiple entries: review separately and identify the intended document unambiguously.
statusrecognized: continue validation. uncertain or no_mrz: review manually or request a better image.
checks, errors, correctionsEvaluate even when a MRZ is recognised. Do not import failed applicable check digits, corrections or uncertain data without review.

Dates retain MRZ format YYMMDD; no century is inferred. Check digits do not establish document authenticity or identity.

All response fields and result states ↗

Handle errors

Check the HTTP status before using the response as a result. HTTP 200 alone does not mean recognition succeeded.

HTTPNext step
401Check the API key. Do not retry unchanged.
404Check the base URL and activation; the website address is not an active Enterprise access point.
400 / 405 / 408 / 413 / 422Correct the method, input format, image size or upload connection.
503Honour Retry-After and retry only a limited number of times with a delay.
500 / 502 / 504The service may have a temporary failure. Retry a limited number of times; contact us if it persists.

Errors may contain an error or detail field. Also handle network failures and non-JSON responses. Keep document data and API keys out of error logs.

All error codes and retry guidance ↗