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.
| Variable | Purpose |
|---|---|
MRZ_BASE_URL | Your activated base URL |
MRZ_API_KEY | Your secret API key |
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.
#!/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
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.
{
"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
}| Check | Handling |
|---|---|
timed_out | If true, the result is incomplete. Do not import automatically. |
documents | Empty: no candidate found. Multiple entries: review separately and identify the intended document unambiguously. |
status | recognized: continue validation. uncertain or no_mrz: review manually or request a better image. |
checks, errors, corrections | Evaluate 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.
Handle errors
Check the HTTP status before using the response as a result. HTTP 200 alone does not mean recognition succeeded.
| HTTP | Next step |
|---|---|
| 401 | Check the API key. Do not retry unchanged. |
| 404 | Check the base URL and activation; the website address is not an active Enterprise access point. |
| 400 / 405 / 408 / 413 / 422 | Correct the method, input format, image size or upload connection. |
| 503 | Honour Retry-After and retry only a limited number of times with a delay. |
| 500 / 502 / 504 | The 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.