Use case · Saudi residency permit
Saudi Iqama OCR API
Saudi Iqama OCR with Mahad OCR reads the Saudi residency permit (and the Saudi national ID) and returns the 10-digit ID number, name, nationality and dates as JSON. The number’s leading digit and its Luhn check digit are verified on the server, and when a date is returned in both Hijri and Gregorian form the two are checked to be the same day.
Fields returned
| Key | What it holds |
|---|---|
| id_number | The 10-digit number — starts with 2 (resident / Iqama) or 1 (citizen) |
| full_name, name_arabic | English name, with the Arabic name beside it where printed |
| nationality, occupation, employer | As printed |
| date_of_birth, expiry_date, issue_date | Gregorian ISO dates where printed |
id_number, full_name, date_of_birth and expiry_date must be settled before a card can be verified.
How ✓ and ⚠ work here
- Check digit: the 10-digit number is checked with the Luhn algorithm (saudi_id_check_digit).
- Hijri ↔ Gregorian: when both forms of a date are returned, they must describe the same day (within 2 days, because the tabular Hijri calendar can differ from Umm al-Qura). A mismatch is shown as a review reason.
- ⚠ A date that is not in the Gregorian calendar is not converted silently — it goes to review (DATE_NEEDS_REVIEW).
- ⚠ Single-reader or disputed values are marked for a person to check.
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]"
# 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": "review",
"result": {
"status": "review",
"decision": "review",
"document_type": "residence_permit",
"values": {
"id_number": "2123456786", "full_name": "RAVI SPECIMEN TESTKUMAR",
"nationality": "India", "occupation": "Pipe Welder"
},
"field_status": { "expiry_date": "unreadable" },
"disputed_fields": [],
"review_reasons": ["Expiry Date: could not be read"],
"verification": {
"evidence": [
{ "level": "L1", "rule": "saudi_id_check_digit", "result": "passed", "fields": ["id_number"] }
]
}
}
}Limits
- The check digit and date cross-check are evidence on what is printed. There is no Absher, Muqeem or other government lookup.
- The Hijri cross-check runs only when both date forms are present in the result.
- The check-digit rule runs when the card is identified as Saudi (issuing country) or the number is returned as an Iqama number.
- Files: PNG, JPG, PDF or Word, up to 10 MB.
Frequently asked questions
What does the first digit of an Iqama number mean?
2 for a resident (Iqama) and 1 for a Saudi citizen’s national ID. The full 10-digit number ends with a check digit.
Does Mahad OCR validate the Iqama check digit?
Yes. The Luhn check digit is computed on the server and reported as saudi_id_check_digit, passed or failed. A failure sends the card to review.
How are Hijri dates handled?
When a date is returned in both Hijri and Gregorian form, the two are compared and must be the same day within a 2-day tolerance. A date only in a non-Gregorian calendar goes to review rather than being converted silently.
Is the Iqama checked with Saudi government systems?
No. Mahad OCR checks what is printed on the card only.
Does it read the Arabic text on the card?
Yes. Arabic is read in the script printed; the Arabic name is returned as name_arabic beside the English name where printed.