Feel free to reach techsupport@surepass.io for any technical support or guidance.
Legal Bulk Download Initialize
Production
https://kyc-api.surepass.app
Production
https://kyc-api.surepass.app
POST
https://kyc-api.surepass.app
CKYC Legal Bulk Download Initialize
Description
client_id to poll for results. Records are fetched from CERSAI asynchronously via SFTP.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 JWT token (Bearer <JWT>) |
| Content-Type | Yes | application/json |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| data | Object | Yes | Main request payload |
| data.legal_entities | Array | Yes | Array of legal entity download requests |
| data.legal_entities[].ckyc_id | String | Yes | CKYC Number or Reference ID (from Search API) |
| data.legal_entities[].dob | String | Conditional | Date of incorporation (DD-MM-YYYY). Required if pincode not provided. |
| data.legal_entities[].pincode | String | Conditional | Registered pincode. Required if dob not provided. |
Example Request
{
"data": {
"legal_entities": [
{
"ckyc_id": "80024980223909",
"dob": "10-05-2019",
"pincode": ""
},
{
"ckyc_id": "80024980224567",
"dob": "",
"pincode": "110001"
}
]
}
}Process Response
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| data | Object | Response payload |
| data.client_id | String | Unique identifier for tracking this bulk download |
| data.message | String | Status message |
| data.state | String | Initial state (pending) |
| data.error | Array | Validation errors, if any |
| status_code | Integer | HTTP status code |
| success | Boolean | Whether the request was successful |
| message | String | Human-readable status message |
| message_code | String | Machine-readable status code |
Example Successful Response
{
"data": {
"client_id": "ckyc_legal_bulk_download_AbCdEfGhIjKlMnOp",
"message": "CKYC bulk Download has been initiated",
"state": "pending",
"error": []
},
"status_code": 200,
"success": true,
"message": "Success",
"message_code": "success"
}Possible Error Responses
Authentication Failed
Validation Error
{
"data": null,
"status_code": 401,
"success": false,
"message": "Unauthorized",
"message_code": "auth_failed"
}dob (date of incorporation) or pincode (registered pincode), not both. This differs from individuals which use DOB or mobile number.ckyc_id values come from the CKYC Search API.:::
Code Samples
cURL
Python
Node.js
Next 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-upload/legal/download/initialize' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"legal_entities": [
{
"ckyc_id": "80024980223909",
"dob": "10-05-2019",
"pincode": ""
},
{
"ckyc_id": "80024980224567",
"dob": "",
"pincode": "110001"
}
]
}
}'Response Response Example
{
"data": {
"client_id": "ckyc_legal_bulk_download_AbCdEfGhIjKlMnOp",
"message": "CKYC bulk Download has been initiated",
"state": "pending",
"error": []
},
"status_code": 200,
"success": true,
"message": "Success",
"message_code": "success"
}