FAQ
Common questions and integration guidance for Core API endpoints, grouped by API.
This page collects practical, integration-time questions that don't fit neatly inside an endpoint's reference. Sections are grouped by API — jump to the one you need.
eSign API Suite
Aadhaar name verification — how verifyInvitee, verifyName and smartNameVerify interact
Aadhaar names are often stored in a different order or with extra tokens (e.g. father's name appended). This frequently causes "name mismatch" errors even when the signer is the correct person. The three flags in userInfo[].aadhaarInfo control name validation behaviour after the signer completes Aadhaar OTP:
verifyInvitee | smartNameVerify | verifyName | Name validation behaviour |
|---|---|---|---|
false | (any) | (any) | No invitee-side validation at all — name, last-4-digit, pincode, state, gender, year are all skipped. |
true | true | (any) | Fuzzy similarity match against the Aadhaar name. Threshold is configurable per company (default 60%). Takes precedence over verifyName. |
true | false | true | Exact case-insensitive match against the Aadhaar name. |
true | false | false | Name is not verified, but last4Digit, pincode, state, gender, year are still validated (whichever you sent). |
The Smart Verify similarity threshold is configurable per company. Lower it (e.g. to 40–50) if your Aadhaar records routinely carry extra surname/father's-name tokens that your application-side name does not. Contact support to adjust the value for your tenant.
Why Smart Verify can still fail on a legitimate signer
The matcher scores token overlap between the name you pass and the name on the Aadhaar record. Extra tokens on the Aadhaar side reduce the score. Example:
- Name passed in
userInfo:Rohan Pansara - Name on Aadhaar:
PANSARA ROHAN PANKAJBHAI - Result: similarity drops below the 60% default threshold because
PANKAJBHAI(father's name) is not present in the application-supplied name.
Recommended approach
In order of preference:
- Source the name from Aadhaar / KYC before invoking eSign, so what you send already matches the Aadhaar record. Most reliable; eliminates fuzzy-match guesswork.
- If you cannot get the exact Aadhaar name upfront, set
smartNameVerify = true,verifyName = false, and pass the fullest name available (first + middle + last + father's name if known). Token order does not matter to the matcher, but missing tokens reduce the score. - For known-good cases where Aadhaar carries extra tokens your system genuinely cannot supply, set
verifyInvitee = truewith bothsmartNameVerify = falseandverifyName = false, and rely onlast4Digitpluspincode/statefor identity binding. - Only use
verifyInvitee = falsewhen the invitation link itself is your sole identity guarantee — every invitee-side check is bypassed.
Quick reference
// Strict: name must match Aadhaar exactly
"aadhaarInfo": {
"verifyInvitee": true,
"verifyName": true,
"smartNameVerify": false,
"lastFourDigitOfAadhaar": "1234",
"birthYear": "1990",
"gender": "M"
}
// Lenient: fuzzy match (recommended for most integrations)
"aadhaarInfo": {
"verifyInvitee": true,
"verifyName": false,
"smartNameVerify": true,
"lastFourDigitOfAadhaar": "1234",
"birthYear": "1990",
"gender": "M"
}
// Skip name only, still validate other fields
"aadhaarInfo": {
"verifyInvitee": true,
"verifyName": false,
"smartNameVerify": false,
"lastFourDigitOfAadhaar": "1234",
"pincode": "560001",
"state": "Karnataka"
}