Feel free to reach techsupport@surepass.io for any technical support or guidance.
CKYC Download Legal
Production
https://kyc-api.surepass.app
Production
https://kyc-api.surepass.app
POST
https://kyc-api.surepass.app
CKYC Download Legal API
Description
Key Benefits
Technical Implementation
Authentication
All API requests require authentication using a JWT Bearer token:Obtain API Credentials: Register with Surepass to receive your API key. Generate JWT Token: Use your API key to generate a JWT token. Include in Requests: Add the token to the Environment URLs: Sandbox: Production:
1.
2.
3.
Authorization header as Bearer TOKEN.https://sandbox.surepass.iohttps://kyc-api.surepass.ioRequest Parameters
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token for API authentication (format: Bearer YOUR_JWT_TOKEN) |
| Content-Type | Yes | Must be set to application/json |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_id | string | Yes | client_id from the Search step |
| dob | string | Conditional | Date of incorporation in YYYY-MM-DD or DD-MM-YYYY format. Required if pincode is not provided. |
| pincode | string | Conditional | Entity's registered 6-digit pincode. Required if dob is not provided. |
Example Requests
{
"client_id": "ckyc_YWECGljIfgTrlCaijVKf",
"dob": "2006-05-24"
}{
"client_id": "ckyc_YWECGljIfgTrlCaijVKf",
"pincode": "110001"
}Process Response
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| record_counts | object | Contains update and download count statistics |
| record_counts.update_count | integer | Number of updates made to the record |
| record_counts.download_count | integer | Number of times the record has been downloaded |
| image_details | object | Contains image/document related information |
| image_details.image_data | string | Base64 encoded image data |
| image_details.image_code | integer | Numeric code identifying the image type |
| image_details.sequence_no | integer | Sequential number for the image |
| image_details.image_type | string | Type of image encoded |
| related_persons | array | List of persons related to the legal entity |
| identity_details | array | List of identity documents and verification status |
| personal_details | object | Complete details of the legal entity |
Related Persons Object Structure
| Parameter | Type | Description |
|---|---|---|
| full_name | string | Complete name of the related person |
| father_full_name | string | Father's full name |
| mother_full_name | string | Mother's full name |
| maiden_full_name | string | Maiden name if applicable |
| residence_status | string | Residential status of the person |
| address_line_1 | string | First line of permanent address |
| address_line_2 | string | Second line of permanent address |
| address_line_3 | string | Third line of permanent address |
| address_district | string | District of permanent address |
| address_city | string | City of permanent address |
| address_state | string | State of permanent address |
| address_pin | integer | PIN code of permanent address |
| address_country | string | Country of permanent address |
| same_as_permanent_address_flag | string | Flag indicating if correspondence address is same |
| relationship_type | integer | Numeric code for relationship type |
| din | integer | Director Identification Number |
| pan | string | PAN number |
| dob | string | Date of birth |
| gender | string | Gender (M/F/O) |
| mob_num | string | Mobile number |
| string | Email address | |
| photo_data | string | Base64 encoded photo data |
| photo_type | string | Format of photo (jpg, png, etc.) |
| sequence_no | integer | Sequence number of the record |
Identity Details Object Structure
| Parameter | Type | Description |
|---|---|---|
| identity_number | string | Identity document number |
| identity_type | string | Type of identity document |
| id_verification_status | string | Verification status (YES/NO) |
| sequence_no | integer | Sequence number of the identity record |
Personal Details Object Structure
| Parameter | Type | Description |
|---|---|---|
| fullname | string | Full name of the legal entity |
| dob | string | Date of incorporation |
| pan | string | PAN number of the entity |
| constitution_type | string | Type of legal constitution |
| country_of_incorporation | string | Country where entity is incorporated |
| place_of_incorporation | string | Place of incorporation |
| date_comm_bus | string | Date of commencement of business |
| tin_gst | string | TIN/GST number |
| permanent_address_line_1 | string | First line of registered address |
| permanent_address_city | string | City of registered address |
| permanent_address_state | string | State of registered address |
| permanent_address_pin | integer | PIN code of registered address |
| permanent_address_country | string | Country of registered address |
| correspondence_address_line_1 | string | First line of correspondence address |
| correspondence_address_city | string | City of correspondence address |
| correspondence_address_state | string | State of correspondence address |
| correspondence_address_pin | integer | PIN code of correspondence address |
| string | Primary email address | |
| mobile_number | string | Primary mobile number |
| total_identity_records | integer | Total number of identity records |
| total_image_records | integer | Total number of image records |
| total_related_persons | integer | Total number of related persons |
| ckyc_number | string | Central KYC number |
| ckyc_reference_id | string | CKYC reference ID |
Example Successful Response
{
"record_counts": {
"update_count": 1,
"download_count": 7
},
"image_details": {
"image_data": "aGVsbG8=",
"image_code": 19,
"sequence_no": 1,
"image_type": "aGVsbG8="
},
"related_persons": [
{
"full_name": "VINEET KAPOOR",
"father_full_name": "MOHAN KAPOOR",
"mother_full_name": "MEENA",
"prefix": "MR",
"din": 1234567,
"pan": "ABCDE1234F",
"dob": "29-02-1996",
"gender": "M",
"mob_num": "9876543210",
"email": "user@example.com",
"relationship_type": 4,
"address_line_1": "Sample Address",
"address_city": "New Delhi",
"address_state": "DL",
"address_pin": 110001,
"address_country": "IN",
"same_as_permanent_address_flag": "Y",
"sequence_no": 1,
"photo_type": "jpg",
"photo_data": "/9j/4AAQSkZJRgABAQEAlgCWAAD/..."
}
],
"identity_details": [
{
"identity_number": "U72900DL2019PTC349962",
"identity_type": "Certificate of Incorporation/Formation",
"id_verification_status": "NO",
"sequence_no": 1
}
],
"personal_details": {
"fullname": "ABC PRIVATE LIMITED",
"dob": "10-05-2019",
"pan": "ABCDE1234F",
"constitution_type": "Private Limited Company",
"country_of_incorporation": "IN",
"place_of_incorporation": "NORTH DELHI",
"date_comm_bus": "10-05-2019",
"tin_gst": "SAMPLE",
"permanent_address_line_1": "Sample Address",
"permanent_address_city": "Sample City",
"permanent_address_state": "DL",
"permanent_address_pin": 110001,
"permanent_address_country": "IN",
"email": "company@example.com",
"mobile_number": "9876543210",
"total_identity_records": 1,
"total_image_records": 1,
"total_related_persons": 4,
"ckyc_number": "80024980223909",
"ckyc_reference_id": "LEFILB20063639"
}
}Possible Error Responses
Date Does Not Match
Verification Failed
Daily Limit Exceeded
Invalid Client ID
Authentication Failed
Server Error
{
"data": null,
"status_code": 422,
"success": false,
"message": "Date of incorporation does not match CKYC records.",
"message_code": "date_does_not_match"
}Heads Up
dob or pincode, not both.Code Samples
cURL
Python
Node.js
Previous Steps
client_idRequest
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ckyc-v2/download-legal' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "ckyc_YWFCGlkIedJflCaijVKf",
"dob": "2006-05-24"
}'Response Response Example
200 - Success Example
{
"data": {
"client_id": "ckyc_download_legal_LdyuJkgjsuS",
"ckyc_search_client_id": null,
"dob": "2006-05-24",
"pincode": 110001,
"ckyc_download_data": {
"record_counts": {
"update_count": 1,
"download_count": 8
},
"image_details": "aGVsbG8=",
"related_persons": [
{
"full_name": "Rahul Kumar",
"father_full_name": "Mahesh Kumar",
"mother_full_name": "Anita",
"maiden_full_name": "",
"residence_status": "",
"residential_std_code": "",
"residential_telephone": "",
"address_line_1": "Sample Address",
"address_line_2": "Sample Address",
"address_line_3": "Sample Address",
"address_district": "Sample Address",
"address_city": "Sample Address",
"address_state": "Sample Address",
"address_pin": 110001,
"address_country": "IN",
"same_as_permanent_address_flag": "Sample Address",
"relationship_type": 4,
"relationship_type_others": "",
"declaration_date": "10-08-2022",
"organization_code": "********",
"kyc_employee_code": "********",
"declaration_place": "New Delhi",
"permanent_proof_of_identity_type": "10",
"permanent_proof_of_identity_image_type": "aGVsbG8=",
"permanent_proof_of_identity_data": "/9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDABALDA4",
"correspondence_address_line_1": "Sample Address",
"correspondence_address_line_2": "Sample Address",
"correspondence_address_line_3": "Sample Address",
"correspondence_address_city": "Sample Address",
"correspondence_address_state": "Sample Address",
"correspondence_address_district": "Sample Address",
"correspondence_address_pin": 110001,
"correspondence_address_country": "IN",
"Correspondence_proof_of_identity_type": 10,
"Correspondence_proof_of_identity_data": null,
"disability_type": "",
"disability_percent": "",
"disability_flag": "",
"disability_udid_number": "",
"kyc_designation": "********",
"prefix": "MR",
"din": 8036863,
"offline_verification_aadhaar": "XXXXXXXX1234",
"off_std_code": "",
"father_prefix": "MR",
"fatherspouse_flag": 1,
"mob_code": 91,
"photo_type": "jpg",
"kyc_name": "********",
"off_tel_num": "",
"pan": "ABCDE1234F",
"mother_prefix": "MR",
"photo_data": "/9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDABALDA",
"kyc_date": "********",
"nationality": "IN",
"dob": "29-02-1996",
"doc_sub": 1,
"gender": "M",
"mob_num": "9876543210",
"add_del_flag": 1,
"kyc_branch": "********",
"ckyc_no": "",
"org_name": "********",
"email": "user@example.com",
"form_sixty": "",
"sequence_no": 1,
"remarks": ""
},
{
"full_name": "Viren Singh",
"father_full_name": "Deepak Kumar",
"mother_full_name": "Pooja",
"maiden_full_name": "",
"residence_status": "",
"residential_std_code": "",
"residential_telephone": "",
"address_line_1": "Sample Address",
"address_line_2": "Sample Address",
"address_line_3": "Sample Address",
"address_district": "Sample Address",
"address_city": "Sample Address",
"address_state": "Sample Address",
"address_pin": 110001,
"address_country": "IN",
"same_as_permanent_address_flag": "Sample Address",
"relationship_type": 4,
"relationship_type_others": "",
"declaration_date": "10-08-2022",
"organization_code": "********",
"kyc_employee_code": "********",
"declaration_place": "New Delhi",
"permanent_proof_of_identity_type": "10",
"permanent_proof_of_identity_image_type": "aGVsbG8=",
"permanent_proof_of_identity_data": "/9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDABALDA4M",
"correspondence_address_line_1": "Sample Address",
"correspondence_address_line_2": "Sample Address",
"correspondence_address_line_3": "Sample Address",
"correspondence_address_city": "Sample Address",
"correspondence_address_state": "Sample Address",
"correspondence_address_district": "Sample Address",
"correspondence_address_pin": 110001,
"correspondence_address_country": "IN",
"Correspondence_proof_of_identity_type": 10,
"Correspondence_proof_of_identity_data": null,
"disability_type": "",
"disability_percent": "",
"disability_flag": "",
"disability_udid_number": "",
"kyc_designation": "********",
"prefix": "MR",
"din": 8272605,
"offline_verification_aadhaar": "XXXXXXXX1234",
"off_std_code": "",
"father_prefix": "MR",
"fatherspouse_flag": 1,
"mob_code": 91,
"photo_type": "jpg",
"kyc_name": "********",
"off_tel_num": "",
"pan": "ABCDE1234F",
"mother_prefix": "MR",
"photo_data": "/9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDABALDA4M",
"kyc_date": "********",
"nationality": "IN",
"dob": "23-11-1996",
"doc_sub": 1,
"gender": "M",
"mob_num": "9876543210",
"add_del_flag": 1,
"kyc_branch": "********",
"ckyc_no": "",
"org_name": "********",
"email": "user@example.com",
"form_sixty": "",
"sequence_no": 2,
"remarks": ""
},
{
"full_name": "Viren Singh",
"father_full_name": "Deepak Kumar",
"mother_full_name": "Pooja",
"maiden_full_name": "",
"residence_status": "",
"residential_std_code": "",
"residential_telephone": "",
"address_line_1": "Sample Address",
"address_line_2": "Sample Address",
"address_line_3": "Sample Address",
"address_district": "Sample Address",
"address_city": "Sample Address",
"address_state": "Sample Address",
"address_pin": 110001,
"address_country": "IN",
"same_as_permanent_address_flag": "Sample Address",
"relationship_type": 4,
"relationship_type_others": "",
"declaration_date": "16-08-2023",
"organization_code": "********",
"kyc_employee_code": "********",
"declaration_place": "Kamla Nagar Branch New Delhi",
"permanent_proof_of_identity_type": "1",
"permanent_proof_of_identity_image_type": "aGVsbG8=",
"permanent_proof_of_identity_data": "SUkqAOgxAQD/2P/BAAsIBtoE2Q",
"correspondence_address_line_1": "Sample Address",
"correspondence_address_line_2": "Sample Address",
"correspondence_address_line_3": "Sample Address",
"correspondence_address_city": "Sample Address",
"correspondence_address_state": "Sample Address",
"correspondence_address_district": "Sample Address",
"correspondence_address_pin": 110001,
"correspondence_address_country": "IN",
"Correspondence_proof_of_identity_type": 1,
"Correspondence_proof_of_identity_data": null,
"disability_type": "",
"disability_percent": "",
"disability_flag": "",
"disability_udid_number": "",
"kyc_designation": "********",
"prefix": "Mr.",
"din": 8272605,
"off_std_code": "",
"father_prefix": "Mr.",
"fatherspouse_flag": 1,
"mob_code": 91,
"photo_type": "jpg",
"kyc_name": "********",
"off_tel_num": "",
"pan": "ABCDE1234F",
"mother_prefix": "Mrs.",
"photo_data": "/9j/4AAQSkZJRgABAQEAyADIAAD/2wCEAB",
"kyc_date": "********",
"nationality": "IN",
"dob": "23-11-1996",
"doc_sub": 1,
"gender": "M",
"mob_num": "9876543210",
"add_del_flag": 1,
"proof_of_possession_of_aadhaar": "XXXXXXXX1234",
"kyc_branch": "********",
"ckyc_no": "",
"org_name": "********",
"email": "user@example.com",
"form_sixty": "",
"sequence_no": 3,
"remarks": ""
},
{
"full_name": "Rahul Kumar",
"father_full_name": "Mahesh Kumar",
"mother_full_name": "Anita",
"maiden_full_name": "",
"residence_status": "",
"residential_std_code": "",
"residential_telephone": "",
"address_line_1": "Sample Address",
"address_line_2": "Sample Address",
"address_line_3": "Sample Address",
"address_district": "Sample Address",
"address_city": "Sample Address",
"address_state": "Sample Address",
"address_pin": 110001,
"address_country": "IN",
"same_as_permanent_address_flag": "Sample Address",
"relationship_type": 4,
"relationship_type_others": "",
"declaration_date": "16-08-2023",
"organization_code": "********",
"kyc_employee_code": "********",
"declaration_place": "Kamla Nagar Branch New Delhi",
"permanent_proof_of_identity_type": "1",
"permanent_proof_of_identity_image_type": "aGVsbG8=",
"permanent_proof_of_identity_data": "SUkqAGrJAAD/2P/BAAsI",
"correspondence_address_line_1": "Sample Address",
"correspondence_address_line_2": "Sample Address",
"correspondence_address_line_3": "Sample Address",
"correspondence_address_city": "Sample Address",
"correspondence_address_state": "Sample Address",
"correspondence_address_district": "Sample Address",
"correspondence_address_pin": 110001,
"correspondence_address_country": "IN",
"Correspondence_proof_of_identity_type": 1,
"Correspondence_proof_of_identity_data": null,
"disability_type": "",
"disability_percent": "",
"disability_flag": "",
"disability_udid_number": "",
"kyc_designation": "********",
"prefix": "Mr.",
"din": 8986863,
"off_std_code": "",
"father_prefix": "Mr.",
"fatherspouse_flag": 1,
"mob_code": 91,
"photo_type": "jpg",
"kyc_name": "********",
"off_tel_num": "",
"pan": "ABCDE1234F",
"mother_prefix": "Mrs.",
"photo_data": "/9j/4AAQSkZJRgABAQEAyADIAAD",
"kyc_date": "********",
"nationality": "IN",
"dob": "29-02-1996",
"doc_sub": 1,
"gender": "M",
"mob_num": "9876543210",
"add_del_flag": 1,
"proof_of_possession_of_aadhaar": "XXXXXXXX1234",
"kyc_branch": "********",
"ckyc_no": "",
"org_name": "********",
"email": "user@example.com",
"form_sixty": "",
"sequence_no": 4,
"remarks": ""
}
],
"identity_details": [
{
"identity_number": "U72900DL2019PTC349962",
"identity_type": "Certificate of Incorporation/Formation",
"ident_type": 2,
"sequence_no": 1
}
],
"personal_details": {
"fullname": "ABC PRIVATE LIMITED",
"dob": "10-05-2019",
"pan": "ABCDE1234F",
"ipv_flag": 1,
"remarks": "",
"permanent_address_line_1": "Sample Address",
"permanent_address_line_2": "Sample Address",
"permanent_address_line_3": "Sample Address",
"permanent_address_district": "Sample Address",
"permanent_address_city": "Sample Address",
"permanent_address_state": "Sample Address",
"permanent_address_pin": 110001,
"permanent_address_country": "IN",
"correspondence_address_line_1": "Sample Address",
"correspondence_address_line_2": "Sample Address",
"correspondence_address_line_3": "Sample Address",
"correspondence_address_district": "Sample Address",
"correspondence_address_city": "Sample Address",
"correspondence_address_state": "Sample Address",
"correspondence_address_pin": 110001,
"correspondence_address_country": "IN",
"same_as_permanent_address": "Sample Address",
"email": "user@example.com",
"email_secondary": "user@example.com",
"mobile_number": "9876543210",
"mobile_number_secondary": "",
"mobile_code": 91,
"mobile_code_secondary": "",
"fax_code": "",
"fax_number": "",
"office_std_code": "",
"office_phone_number": "",
"declaration_date": "16-08-2023",
"declaration_place": "Kamla Nagar Branch New Delhi",
"organization_name": "********",
"organization_code": "********",
"kyc_employee_code": "********",
"kyc_branch": "********",
"kyc_name": "********",
"kyc_date": "********",
"constitution_type": "Private Limited Company",
"constitution_type_others": "",
"proof_of_address": "Sample Address",
"permanent_proof_of_address": "Sample Address",
"permanent_proof_of_address_others": "Sample Address",
"correspondence_proof_of_address": "Sample Address",
"total_identity_records": 1,
"total_image_records": "aGVsbG8=",
"total_related_persons": 4,
"ckyc_number": "80024980223909",
"ckyc_reference_id": "LEFILB20063639",
"gst_country": "",
"country_of_incorporation": "IN",
"place_of_incorporation": "NORTH DELHI",
"kyc_designation": "********",
"date_comm_bus": "10-05-2019",
"consti_type": "D",
"doc_sub": 1,
"tin_gst": ""
}
}
},
"status_code": 200,
"success": true,
"message": "Success",
"message_code": "success"
}