Offline Aadhaar KYC

What is it?

Offline Aadhaar KYC performs a synchronous, no-redirect Aadhaar identity verification — your users never leave your app and there is no browser handoff. /init accepts either typed demographic fields, a photo of the Aadhaar card front, or both — if a field wasn't typed, OCR fills it in from the photo before verification runs. For most users with an existing linked account, the verified identity (and signed identity document, where available) comes back in the same call. A smaller share of users complete one additional one-time-password step via /verify-otp.

OCR is never itself the verification. Whatever ends up populated — typed or OCR-filled — is exactly what gets checked against Aadhaar by this same call, so a bad OCR read simply surfaces as a 422, never a false positive.

Quick Start

Option A: typed fields

POST /api/v1/aadhaar/offline-kyc/init

{
  "aadhaarNumber": "999999999999",
  "name": "RAM KUMAR",
  "dob": "03071990",
  "gender": "M",
  "mobile": "9999999999"
}

Option B: photo instead of typing

POST /api/v1/aadhaar/offline-kyc/init

{
  "mobile": "9999999999",
  "aadhaarImage": "<base64 photo of the Aadhaar card front>"
}

Mix and match freely — type what you have, attach the photo for the rest; a typed field always wins over an OCR-read one for that same field.

aadhaarImage must be JPEG or PNG. A PDF (including a downloaded eAadhaar) or a HEIC photo straight from an iPhone is rejected with a 400 naming the format — the OCR engine's synchronous API reads only those two. Convert first, or type the details instead.

Field formats: dob is DDMMYYYY, day first — 03071990 is 3 July 1990, not 7 March. gender is a single character, M or F — no other value is accepted. aadhaarNumber is 12 digits; mobile is 10 digits. Both dob and gender are validated before the verification call, so a wrong format returns a 400 naming the problem rather than an ambiguous "did not match Aadhaar records".

Response (either option): transactionId, otpRequired, and — when otpRequired is false — the verified result inline, as 200 OK. When otpRequired is true instead, the call still succeeded but verification isn't finished — that comes back as 202 Accepted (not 200), with no result yet and message naming the mobile the OTP was sent to.

Step 2 (only if otpRequired is true): Verify the OTP

POST /api/v1/aadhaar/offline-kyc/verify-otp

{
  "transactionId": "<from init>",
  "otp": "123456"
}

Response: the verified result.

Result shape

{
  "verifiedId": "stable pseudonymous identifier",
  "name": "RAM KUMAR",
  "dob": "03071990",
  "gender": "M",
  "mobile": "9999999999",
  "verifiedAtUtc": "2026-08-21T10:18:30Z",
  "document": { "data": "<UIDAI-signed eAadhaar XML>", "mime": "application/xml" },
  "details": {
    "name": "RAM KUMAR",
    "dob": "03-07-1990",
    "gender": "M",
    "address": "12, MG Road, Near Park",
    "village": "Pune",
    "district": "Pune",
    "state": "Maharashtra",
    "pinCode": "411001",
    "aadhaarNumber": "XXXXXXXX1234",
    "photo": "<base64 JPEG>",
    "kycDateTime": "25-08-2026/13:33:52"
  },
  "fieldsFilledFromImage": ["dob", "gender"]
}

details carries the demographic data that exists only inside the signed document — full address, photo, KYC timestamp. Its aadhaarNumber is masked to the last four digits; the unmasked number remains inside document.data only because UIDAI's signature covers it and stripping it would make the document unverifiable. details is null when the account has no eAadhaar on file — the identity is still verified.

verifiedId is a stable identifier for the verified individual — use it as your identity key. Never persist the Aadhaar number or photo you submitted; neither is echoed back and neither should be stored on your side. fieldsFilledFromImage lists which fields, if any, came from OCR rather than typing — empty when no photo was attached or nothing needed filling.

The document field is present only when a signed identity document is available for that account.

Error Codes

• 400 — Missing/invalid input, OCR couldn't read a required field from the photo (retype it and resubmit), or the verification session expired (restart from /init)
• 401 — Unauthorized: check X-API-KEY and X-API-APP-ID headers
• 404 — Signed identity document not available for this account (identity is still verified)
• 422 — Submitted (typed or OCR-filled) name/DOB/gender did not match Aadhaar records
• 429 — Too many requests

Benefits

• No redirect — your users stay on your screen throughout
• Often zero OTP — accounts with an existing link verify in a single call
• One consolidated result — identity and signed document in one response
• Type it or photograph it — one endpoint, either input, no separate OCR round trip
• Full UX ownership — your branding, your copy, your error handling