Base URL: https://ocr.onegovai.app. All endpoints return JSON.
Documents are processed in memory and never stored.
Send your key in the X-API-Key header on every request except
/health. Create keys yourself in the
developer portal — sign up with an email, create up to
3 keys, and watch per-key usage. The browser demo on the home page needs no key
(5 extractions/IP/day).
Multipart upload. JPEG/PNG/WEBP/BMP/TIFF or PDF, max 15MB.
| Param | In | Values | Default |
|---|---|---|---|
file | form-data | the document | required |
documentType | query | AUTO, NATIONAL_ID, PASSPORT, PROOF_OF_RESIDENCE |
AUTO |
curl -H "X-API-Key: $KEY" \
-F "file=@id.jpg" \
"https://ocr.onegovai.app/extract?documentType=NATIONAL_ID"{
"fields": {
"documentType": "NATIONAL_ID",
"idNumber": "63-123456A70",
"surname": "MOYO",
"firstName": "TENDAI",
"dateOfBirth": "1990-05-14",
"placeOfBirth": "HARARE",
"villageOfOrigin": "GUTU",
"dateOfIssue": "2015-02-10"
},
"fieldConfidences": { "idNumber": 0.99, "surname": 0.97 },
"warnings": [],
"ocrConfidence": 0.96,
"rawText": ["..."]
}passportNumber, issuingCountry,
nationality, surname, givenNames,
dateOfBirth, sex, dateOfExpiry,
personalNumber, plus MRZ checks (check-digit results).documentClass, issuer
(ZETDC, councils, TelOne, ZINWA, …), customerName, address,
accountNumber, amount, documentDate,
ageInDays — enforce your own recency rule (e.g. ≤ 90 days).Warning codes: PASSPORT_EXPIRED, CHECK_DIGIT_FAILED,
DOCUMENT_TOO_OLD, NO_DOCUMENT_DATE, MISSING_FIELDS,
LOW_OCR_CONFIDENCE, UNRECOGNISED_ISSUER.
| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 413 | File over 15MB |
| 415 | Unsupported file type |
| 422 | POOR_QUALITY (blurry / low resolution / too dark — ask the
customer to retake) or no text detected |
| 429 | Demo limit reached (keyless demo endpoint only) |
Cross-document KYC check. Send the fields objects from 2–5
/extract responses. Names match on tokens (initials match full
names), ID numbers are zero-padding tolerant (passport
personalNumber vs national idNumber).
curl -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"documents":[{ "...fields A..." : "" },{ "...fields B..." : "" }]}' \
https://ocr.onegovai.app/matchReturns per-attribute scores (name, dateOfBirth,
idNumber) and an overall matched boolean.
Your metered usage: {"client": "...", "today": 12, "total": 340}.
Liveness: {"status": "UP"}. No key required.