Feel free to reach techsupport@surepass.io for any technical support or guidance.
CKYC Legal Entity Search
Production
https://kyc-api.surepass.app
Production
https://kyc-api.surepass.app
POST
https://kyc-api.surepass.app
Description
client_id, a records array, and record_count.ckyc_identifier to POST /api/v1/ckyc/v3/download/legal with a matching auth factor.Authentication
| Environment | Base URL |
|---|---|
| Sandbox | https://sandbox.surepass.app |
| Production | https://kyc-api.surepass.app |
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer token. Format: Bearer YOUR_JWT_TOKEN |
Content-Type | Yes | Must be application/json |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
id_type | String | Yes | Legal entity identifier type. The API normalizes case, spaces, and hyphens to lowercase snake_case. |
id_number | String | Yes | Identifier value to search in CKYC. |
Supported id_type Values
id_type value | Description | Format / Example |
|---|---|---|
pan | Entity PAN | ABCAA1234A |
ckyc_number | CKYC number | 14-digit 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 |
mobile_number | Registered mobile number | 10 digits |
Certificate of Incorporation, CERTIFICATE-OF-INCORPORATION, and certificate_of_incorporation are normalized to the same value. Prefer sending the canonical lowercase value.Example Request
{
"id_type": "pan",
"id_number": "ABCAA1234A"
}Response
| Parameter | Type | Description |
|---|---|---|
data.client_id | String | SurePass transaction ID for this search. |
data.records | Array | Matching legal entity CKYC records. |
data.record_count | Integer | Number of records returned. |
status_code | Integer | HTTP status code. |
success | Boolean | Whether the operation succeeded. |
message | String | Human-readable status. |
message_code | String | Machine-readable status. |
Common Record Fields
| Field | Type | Description |
|---|---|---|
ckyc_identifier | String | Canonical value to use in legal download calls. This resolves to ckyc_reference_id when available, otherwise ckyc_no. |
ckyc_no | String | CKYC number when available. |
ckyc_reference_id | String | CKYC reference ID, usually starting with LE. |
name | String | Legal entity name as returned in search. |
constitution_type | String | Entity constitution type with any CERSAI prefix stripped. |
place_of_incorporation | String | Place of incorporation or registration. |
age | String | Age field when returned by CERSAI. For legal entities this may be blank. |
mob_code | Integer or null | ISD calling-code prefix, for example 91. |
mob_num | String | Registered mobile number when returned. |
image_type | String | Type of search photo/image, for example jpg. |
photo | String | Base64-encoded image when returned. |
kyc_date | String | KYC date normalized to YYYY-MM-DD when parseable. |
updated_date | String | Last update date normalized to YYYY-MM-DD when parseable. |
id_list | Array | Identity documents attached to the entity record. |
remarks | String | Registry remarks when returned. |
The id_list Field
| Field | Type | Description |
|---|---|---|
type | String | App-facing enum-like identity type, for example PAN, CERTIFICATE_OF_INCORPORATION, or REGISTRATION_CERTIFICATE. |
type_code | String | Raw CERSAI identity-type code, for example C, 02, or 03. |
type_value | String | Human-readable document label. |
status | String | Raw verification status code. |
status_value | String | Human-readable verification status. |
Example Successful Response
{
"data": {
"client_id": "ckyc_realtime_search_JaopYqLdVbTf",
"records": [
{
"ckyc_identifier": "LEFILB20063639",
"ckyc_no": "22345678901234",
"ckyc_reference_id": "LEFILB20063639",
"name": "ACME TECHNOLOGIES PRIVATE LIMITED",
"constitution_type": "Private Limited Company",
"place_of_incorporation": "MUMBAI",
"age": "",
"mob_code": 91,
"mob_num": "9876543210",
"image_type": "jpg",
"photo": "BASE64_IMAGE_DATA",
"kyc_date": "2021-02-18",
"updated_date": "2024-03-06",
"id_list": [
{
"type": "PAN",
"type_code": "C",
"type_value": "PAN",
"status": "03",
"status_value": "Verified"
},
{
"type": "CERTIFICATE_OF_INCORPORATION",
"type_code": "02",
"type_value": "Certificate of Incorporation/Formation",
"status": "03",
"status_value": "Verified"
}
],
"remarks": ""
}
],
"record_count": 1
},
"status_code": 200,
"success": true,
"message": "Success",
"message_code": "success"
}Code Samples
cURL
Python
Next Step
ckyc_identifier with POST /api/v1/ckyc/v3/download/legal. Legal download needs a matching auth_factor_type and auth_factor; it does not use OTP.Request
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://kyc-api.surepass.app/api/v1/ckyc/v3/search/legal' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"id_type": "pan",
"id_number": "ABCAA1234A"
}'Response Response Example
{
"data": {
"client_id": "ckyc_realtime_search_JaopYqLdVbTf",
"records": [
{
"ckyc_identifier": "LEFILB20063639",
"ckyc_no": "22345678901234",
"ckyc_reference_id": "LEFILB20063639",
"name": "ACME TECHNOLOGIES PRIVATE LIMITED",
"constitution_type": "Private Limited Company",
"place_of_incorporation": "MUMBAI",
"age": "",
"mob_code": 91,
"mob_num": "9876543210",
"image_type": "jpg",
"photo": "BASE64_IMAGE_DATA",
"kyc_date": "2021-02-18",
"updated_date": "2024-03-06",
"id_list": [
{
"type": "PAN",
"type_code": "C",
"type_value": "PAN",
"status": "03",
"status_value": "Verified"
},
{
"type": "CERTIFICATE_OF_INCORPORATION",
"type_code": "02",
"type_value": "Certificate of Incorporation/Formation",
"status": "03",
"status_value": "Verified"
}
],
"remarks": ""
}
],
"record_count": 1
},
"status_code": 200,
"success": true,
"message": "Success",
"message_code": "success"
}