CKYC Legal Bulk Download Status

Endpoint Overview

POST /api/v1/ckyc-upload/legal/download/status

Description

Polls the status and retrieves results of a legal entity bulk CKYC download request. Returns the current processing state and, once complete, the full CKYC record data for each legal entity including entity details, related persons, identity documents, and images.

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 Authorization header as Bearer TOKEN.

Environment URLs:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer JWT token (`Bearer <JWT>`)
Content-Type	Yes	`application/json`

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Client identifier from the Initialize step

Example Request

{
    "client_id": "ckyc_legal_bulk_download_AbCdEfGhIjKlMnOp"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Response payload
data.client_id	String	Client identifier
data.state	String	Current processing state
data.response	Object	Batch response (populated after processing)
data.response.batch_number	String	Unique batch file identifier
data.response.approved_by_checker	Boolean	Whether the batch was approved by CERSAI checker
data.response.individual_file_response	Array	Per-entity CKYC records
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

Per-Entity Record (`individual_file_response[]`)

Parameter	Type	Description
ckyc_id	String	CKYC number of the legal entity
data	Object	Full CKYC record data (see below)

Entity Personal Details (`data.personal_details`)

Parameter	Type	Description
fullname	String	Full legal name of the entity
dob	String	Date of incorporation
pan	String	PAN number
constitution_type	String	Legal constitution type
country_of_incorporation	String	Country of incorporation
place_of_incorporation	String	Place of incorporation
date_comm_bus	String	Date of commencement of business
tin_gst	String	TIN/GST registration number
permanent_address_line_1	String	Registered address line 1
permanent_address_city	String	City
permanent_address_state	String	State
permanent_address_pin	Integer	Postal code
permanent_address_country	String	Country
correspondence_address_line_1	String	Correspondence address line 1
correspondence_address_city	String	City
correspondence_address_state	String	State
correspondence_address_pin	Integer	Postal code
correspondence_address_country	String	Country
email	String	Primary email
mobile_number	String	Primary mobile number
total_identity_records	Integer	Number of identity records
total_image_records	Integer	Number of image records
total_related_persons	Integer	Number of related persons
ckyc_number	String	Central KYC number
ckyc_reference_id	String	CKYC reference ID

Related Persons (`data.related_persons[]`)

Each legal entity can have multiple related persons (directors, signatories, beneficial owners).

Parameter	Type	Description
full_name	String	Full name of the related person
father_full_name	String	Father's full name
mother_full_name	String	Mother's full name
prefix	String	Name prefix (MR, MRS, etc.)
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
email	String	Email address
relationship_type	Integer	Numeric code for relationship type
address_line_1	String	Address line 1
address_city	String	City
address_state	String	State
address_pin	Integer	Postal code
address_country	String	Country
same_as_permanent_address_flag	String	`Y` if correspondence address same as permanent
photo_type	String	Photo format (jpg, png, etc.)
photo_data	String	Base64-encoded photo data
sequence_no	Integer	Sequence number

Identity Details (`data.identity_details[]`)

Parameter	Type	Description
identity_number	String	Document number
identity_type	String	Document type (e.g., Certificate of Incorporation)
id_verification_status	String	Verification status (`YES`/`NO`)
sequence_no	Integer	Sequence number

Image Details (`data.image_details`)

Parameter	Type	Description
image_data	String	Base64-encoded image data
image_code	Integer	Image type code
sequence_no	Integer	Sequence number
image_type	String	Image format

Example Successful Response (Completed)

{
    "data": {
        "client_id": "ckyc_legal_bulk_download_AbCdEfGhIjKlMnOp",
        "state": "uploaded",
        "response": {
            "batch_number": "IN7196_LE_25092025_V1.2_IA000001_D10001.txt",
            "approved_by_checker": true,
            "individual_file_response": [
                {
                    "ckyc_id": "80024980223909",
                    "data": {
                        "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": "07ABCDE1234F1Z5",
                            "permanent_address_line_1": "123 Business Park",
                            "permanent_address_city": "New Delhi",
                            "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": 2,
                            "ckyc_number": "80024980223909",
                            "ckyc_reference_id": "LEFILB20063639"
                        },
                        "related_persons": [
                            {
                                "full_name": "VINEET KAPOOR",
                                "prefix": "MR",
                                "din": 1234567,
                                "pan": "ABCPK1234L",
                                "dob": "29-02-1996",
                                "gender": "M",
                                "mob_num": "9876543210",
                                "email": "vineet@example.com",
                                "relationship_type": 4,
                                "address_line_1": "Sample Address",
                                "address_city": "New Delhi",
                                "address_state": "DL",
                                "address_pin": 110001,
                                "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
                            }
                        ],
                        "image_details": {
                            "image_data": "aGVsbG8=",
                            "image_code": 19,
                            "sequence_no": 1,
                            "image_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Failed

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "Client ID not found",
    "message_code": "not_found"
}

:::caution Heads Up!

Polling rate limit -- Don't poll more frequently than every 30 seconds.

Terminal states -- Stop polling once state reaches uploaded (success) or a failure state.

Related persons -- Each legal entity can have multiple related persons. All are included in the download response with full details (DIN, PAN, address, photo).

Large responses -- Each entity record contains the full CKYC profile plus Base64-encoded images for all related persons. Plan for large payloads.
:::

Code Samples

cURL

Python

Node.js

Previous Steps

Legal Bulk Download Initialize -- Initialize the bulk download request

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ckyc-upload/legal/download/status' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "ckyc_legal_bulk_download_AbCdEfGhIjKlMnOp" }'

{ "data": { "client_id": "ckyc_legal_bulk_download_AbCdEfGhIjKlMnOp", "state": "uploaded", "response": { "batch_number": "IN7196_LE_25092025_V1.2_IA000001_D10001.txt", "approved_by_checker": true, "individual_file_response": [ { "ckyc_id": "80024980223909", "data": { "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": "07ABCDE1234F1Z5", "permanent_address_line_1": "123 Business Park", "permanent_address_city": "New Delhi", "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": 2, "ckyc_number": "80024980223909", "ckyc_reference_id": "LEFILB20063639" }, "related_persons": [ { "full_name": "VINEET KAPOOR", "prefix": "MR", "din": 1234567, "pan": "ABCPK1234L", "dob": "29-02-1996", "gender": "M", "mob_num": "9876543210", "email": "vineet@example.com", "relationship_type": 4, "address_line_1": "Sample Address", "address_city": "New Delhi", "address_state": "DL", "address_pin": 110001, "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 } ], "image_details": { "image_data": "aGVsbG8=", "image_code": 19, "sequence_no": 1, "image_type": "pdf" } } } ] } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

CKYC Legal Bulk Download Status

CKYC Legal Bulk Download Status#

Description#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Per-Entity Record (individual_file_response[])#

Entity Personal Details (data.personal_details)#

Related Persons (data.related_persons[])#

Identity Details (data.identity_details[])#

Image Details (data.image_details)#

Example Successful Response (Completed)#

Possible Error Responses#

Code Samples#

Request

Responses

CKYC Legal Bulk Download Status

Description

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Per-Entity Record (`individual_file_response[]`)

Entity Personal Details (`data.personal_details`)

Related Persons (`data.related_persons[]`)

Identity Details (`data.identity_details[]`)

Image Details (`data.image_details`)

Example Successful Response (Completed)

Possible Error Responses

Code Samples