Feel free to reach techsupport@surepass.io for any technical support or guidance.
API Flow
CKYC API Flow
Overview
/api/v1/ckyc/v3| Environment | Base URL |
|---|---|
| Sandbox | https://sandbox.surepass.app |
| Production | https://kyc-api.surepass.app |
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/jsonEndpoints
| Flow | Endpoint | Purpose |
|---|---|---|
| Individual search | POST /api/v1/ckyc/v3/search/individual | Search for individual CKYC records by an identifier. |
| Individual download initiate | POST /api/v1/ckyc/v3/download/individual/initiate | Validate the CKYC identifier and mobile number, then trigger OTP. |
| Individual download | POST /api/v1/ckyc/v3/download/individual | Submit OTP or request OTP resend using request_id. |
| Legal search | POST /api/v1/ckyc/v3/search/legal | Search for legal entity CKYC records by an identifier. |
| Legal download | POST /api/v1/ckyc/v3/download/legal | Download legal entity CKYC data using an auth factor. |
Individual Workflow
1.
id_type and id_number.2.
data.records.3.
record.ckyc_identifier in the initiate call. This is usually the CKYC reference ID when CERSAI returns one.4.
ckyc_identifier and the registered mobile_number.5.
data.request_id from the initiate response.6.
request_id to download ckyc_download_data.client_id is a SurePass transaction identifier. The OTP continuation endpoint uses request_id, not client_id.Legal Entity Workflow
1.
id_type and id_number.2.
data.records.3.
record.ckyc_identifier in the legal download call.4.
date_of_incorporation, mobile_number, email, or pincode.5.
ckyc_download_data in the same call. Legal download does not use OTP.Supported Individual Search id_type Values
| Document Type | id_type value | Format / Example |
|---|---|---|
| Passport | passport | Passport number |
| Voter ID | voter_id | EPIC / voter ID number |
| PAN | pan | ABCDE1234F |
| Driving License | driving_license | State-specific driving licence number |
| Proof of Possession of Aadhaar | aadhaar_proof | Aadhaar composite / proof value |
| NREGA Job Card | nrega_job_card | NREGA job card number |
| NPR Letter | npr_letter | NPR letter number |
| CKYC Number | ckyc_number | 14-digit CKYC number |
| CKYC Reference ID | ckyc_reference_id | Usually starts with IN for individuals |
| Mobile Number | mobile_number | 10-digit registered mobile number |
Supported Legal Search id_type Values
| Document Type | id_type value | Format / Example |
|---|---|---|
| PAN | pan | Entity PAN |
| CKYC Number | ckyc_number | 14-digit CKYC number |
| Certificate of Incorporation | certificate_of_incorporation | Incorporation certificate number |
| Registration Certificate | registration_certificate | Registration certificate number |
| CKYC Reference ID | ckyc_reference_id | Usually starts with LE for legal entities |
| Mobile Number | mobile_number | Registered mobile number |
Legal Download Auth Factors
| Auth Factor | auth_factor_type value | auth_factor format |
|---|---|---|
| Date of Incorporation | date_of_incorporation | Date value accepted by CKYC, commonly DD-MM-YYYY or YYYY-MM-DD |
| Mobile Number | mobile_number | Registered mobile number |
email | Registered email address | |
| Pincode | pincode | Registered or local pincode |
Response Field Shapes
| Shape | Meaning | Example | How to use it |
|---|---|---|---|
| Label directly in the field | The field already contains the display label. | "gender": "MALE" | Display the field directly. |
| Short code plus label companion | The original field contains a raw code and <field>_value contains the label. | "doc_sub": "01", "doc_sub_value": "Certified Copies" | Display _value; use the original code when another API expects the CKYC code. |
| Identity enum plus raw code plus label | Identity fields expose app value, raw CERSAI code, and display label. | "identity_type": "PAN", "identity_type_code": "C", "identity_type_value": "PAN" | Use the enum for app logic, _code for raw integrations, and _value for display. |
| Integer flag | A flag returns 0 or 1 without a companion label. | "dis_flag": 1 | Render 0 as No and 1 as Yes in your UI. |
Identity Documents
id_list:{
"type": "PAN",
"type_code": "C",
"type_value": "PAN",
"status": "03",
"status_value": "Verified"
}identity_details.identity:{
"identity_number": "ABCDE1234F",
"identity_type": "PAN",
"identity_type_code": "C",
"identity_type_value": "PAN",
"id_verification_status": "YES"
}Common Error Handling
{
"data": null,
"status_code": 422,
"success": false,
"message": "Auth factor does not match.",
"message_code": "auth_factor_mismatch"
}message_code. Common codes include:| Message Code | When it can occur |
|---|---|
incorrect_id_number_format | Search identifier format is invalid. |
no_records_found | CERSAI did not return a matching record. |
too_many_mobile_matches | Mobile number search matched more than the allowed CKYC records. |
auth_factor_mismatch | Mobile, pincode, DOB, or date of incorporation did not match the CKYC record. |
mobile_not_registered | The individual CKYC record does not have the submitted mobile number registered. |
invalid_otp | OTP validation failed. |
otp_expired | OTP expired before validation. |
otp_resend_throttled | OTP resend was requested too soon. |
daily_limit_exceeded | CERSAI download or OTP limits were reached. |
downstream_service_unavailable | CKYC realtime service was unavailable. |
downstream_request_timeout | CKYC realtime service timed out. |
Data Handling Notes
data.records.ckyc_identifier for download calls. Do not assume ckyc_no is always usable; CERSAI may mask it on non-CKYC-number searches.client_id, request_id when present, and final message_code.