Use case · Passports
Passport OCR API
Passport OCR with Mahad OCR reads the data page of a passport from a photo or PDF and returns the holder’s fields as JSON. The document number, date of birth and expiry date are proven by the machine-readable zone’s own ICAO 9303 check digits where the MRZ is readable, and every other field is either confirmed by two independent readers or marked ⚠ for a person to check.
Fields returned
| Key | What it holds |
|---|---|
| surname, given_names, full_name | Holder name as printed |
| document_number | Passport number — MRZ check digit where readable (also returned as passport_number) |
| nationality, issuing_country | As printed / as in the MRZ |
| date_of_birth, expiry_date | ISO dates (YYYY-MM-DD) — MRZ check digits where readable |
| sex, place_of_birth | As printed |
| issue_date, place_of_issue | From the visual zone (the MRZ does not carry them) |
| father_name | Only where the passport prints it (for example Indian passports); otherwise not_present |
document_number, date_of_birth, expiry_date, full_name and nationality must all be settled before a passport can be verified.
How ✓ and ⚠ work here
- ✓ “Proven by the document’s own check digits (MRZ)” — document number, date of birth and expiry date, when the MRZ check digits pass (evidence mrz_checksum).
- ✓ “Two independent readers read the same value” — for fields the MRZ does not protect (evidence reader_agree).
- ⚠ A field read by only one reader, or where the readers disagree, is marked check / missing. A disputed value is never put in values; it is listed in disputed_fields and the document goes to review.
- ⚠ An expired passport goes to review with the reason “Document expired”, even when every field is proven.
Example request and response
Fictional data, real response shape (trimmed to the keys that matter here). Full field list in the API reference.
curl -X POST https://api.mahadocr.com/v1/documents/upload \
-H "X-MahadDoc-API-Key: mk_live_YOUR_KEY" \
-F "[email protected]" \
-F "doc_type=passport"
# 202 Accepted
# { "id": "DOC_3f9a1c7e2b40", "status": "processing", ... }
curl https://api.mahadocr.com/v1/documents/DOC_3f9a1c7e2b40 \
-H "X-MahadDoc-API-Key: mk_live_YOUR_KEY"{
"id": "DOC_3f9a1c7e2b40",
"status": "verified",
"result": {
"status": "verified",
"decision": "verified",
"document_type": "passport",
"values": {
"surname": "TESTKUMAR", "given_names": "RAVI SPECIMEN",
"full_name": "RAVI SPECIMEN TESTKUMAR",
"document_number": "T7654321", "passport_number": "T7654321",
"nationality": "INDIAN", "issuing_country": "IND",
"date_of_birth": "1990-04-15", "expiry_date": "2032-08-22",
"sex": "Male", "issue_date": "2022-08-23", "place_of_issue": "DOHA"
},
"field_status": { "father_name": "not_present", "surname": "read" },
"field_evidence": { "document_number": "deterministic", "date_of_birth": "deterministic",
"expiry_date": "deterministic", "full_name": "corroborated" },
"disputed_fields": [],
"review_reasons": [],
"fields": {
"document_number": { "value": "T7654321", "status": "passed",
"evidence": ["mrz_checksum"], "reason": null, "region": null }
}
}
}Limits
- Only the data page is read. Visas and stamps inside the passport are separate documents.
- Mahad OCR does not check a passport against any government database, reads no NFC chip and performs no face match.
- The MRZ proof covers the fields the check digits protect (number, birth date, expiry). Names, place of birth and issue details rest on two readers agreeing.
- Files: PNG, JPG, PDF or Word, up to 10 MB; a PDF is read up to its first 5 pages — later pages are reported as not processed and the document goes to review.
- A photo with strong glare, heavy blur or a cut-off edge is sent back as “retake” (rescan) rather than guessed.
How to do it
- 1Create an account at app.mahadocr.com, verify your email and phone, and create an API key.
- 2POST the passport photo or PDF to /v1/documents/upload with the X-MahadDoc-API-Key header (doc_type=passport is optional).
- 3Poll GET /v1/documents/{id} until result.status is no longer processing.
- 4Use result.values for the fields; show every field in result.field_review with state check or missing to a person.
Frequently asked questions
Does Mahad OCR check the passport MRZ check digits?
Yes. The ICAO 9303 check digits (weights 7-3-1) for the document number, date of birth and expiry date — and the composite digit on passports — are computed on the server. A value proven this way carries the evidence mrz_checksum; a failed digit sends the field to review.
What happens if the MRZ is not readable?
The fields are still read from the visual zone by two independent readers. Values both readers agree on are marked ✓; anything else is ⚠ for a person to check. Nothing is marked proven without a passing check digit.
Does Mahad OCR tell me whether a passport is genuine?
No. It reports evidence — check digits that pass, readers that agree — and never a verdict that a document is real. It does not read the chip or contact any issuing authority.
Which passports can it read?
Passports with an ICAO TD3 machine-readable zone get the check-digit proof. The visual zone is read by the AI readers; fields are copied in the script printed. Test your own passports in the live demo before you integrate.
Can I upload a PDF?
Yes — PNG, JPG, PDF or Word, up to 10 MB. A PDF is read up to its first 5 pages.
What does an expired passport return?
The document goes to review with the reason “Document expired”, so an expired passport is never silently accepted. A reviewer can still approve it.