Endpoint Overview

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

Description

The CKYC Bulk Download Status API enables you to track the progress and retrieve results of bulk CKYC download requests initiated through the initialize endpoint. This endpoint provides real-time status updates on your bulk processing requests, including detailed CKYC record data once the processing is complete and approved.

The API supports multiple status states throughout the processing lifecycle - from initial submission ("pending") with empty response fields, through processing stages, to final completion ("uploaded") with comprehensive CKYC data including personal details, address information, identity verification, and associated images. This allows for efficient monitoring of large-scale CKYC verification operations.

Key Benefits

Real-time Status Tracking: Monitor bulk download progress with detailed state information

Comprehensive Data Retrieval: Access complete CKYC records including personal, address, and identity details

Batch Processing Insights: Track processing status with batch numbers and approval workflows

Image Data Access: Retrieve associated identity document images in base64 format

Use Cases

Banking & Finance

Insurance

Fintech & Digital Services

Monitor bulk customer onboarding verification progress during peak enrollment periods

Track compliance audit verification requests for regulatory reporting

Retrieve comprehensive customer data for portfolio migration processes

Monitor loan application batch processing status and results

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

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.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer JWT token for API authentication
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique client identifier returned from the initialize endpoint

Example Request

{
    "client_id": "ckyc_bulk_download_goVGkndCaEoKOsgCxrNp"
}

Process Response

Response Parameters

CKYC Bulk Download Response Parameters

Parameter	Type	Description
data	Object	Main container holding the bulk CKYC response data
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	General response message
message_code	String	Standardized message code

data

Parameter	Type	Description
client_id	String	Identifier of the bulk CKYC request
state	String	Current processing state (e.g., uploaded)
response	Object	Detailed response for the batch

data.response

Parameter	Type	Description
batch_number	String	Unique batch file identifier
approved_by_checker	Boolean	Indicates if batch was approved by checker
individual_file_response	Array	Array of individual CKYC record responses

individual_file_response (Object)

Parameter	Type	Description
ckyc_id	String	CKYC number of the individual
data	Object	Detailed data of the individual CKYC record

individual_file_response.data

Parameter	Type	Description
status	String	Processing status of the record
message	String	Message regarding the record processing
reference_no	String	CKYC reference number
record_type	String	Record type identifier
line_number	String	Line number in the uploaded file
application_type	String	Type of CKYC application
branch_code	String	Branch code of processing
applicant_name_update_flag	String	Flag indicating if applicant name was updated
personal_details_update_flag	String	Flag for personal details update
address_details_update_flag	String	Flag for address details update
contact_details_update_flag	String	Flag for contact details update
remarks_update_flag	String	Flag for remarks update
kyc_verification_update_flag	String	Flag for KYC verification update
identity_details_update_flag	String	Flag for identity details update
related_person_details_update_flag	String	Flag for related person details update
download_count_last_5_years	String	Count of downloads in last 5 years
image_details_update_flag	String	Flag for image details update
constitution_type	String	Constitution type of applicant
constitution_type_others	String	Other constitution type if applicable
update_count_last_5_years	String	Count of updates in last 5 years
account_type	String	Type of account
ckyc_no	String	CKYC number of individual
applicant_name_prefix	String	Prefix for applicant name (e.g., MR, MRS)
applicant_first_name	String	Applicant first name
applicant_middle_name	String	Applicant middle name
applicant_last_name	String	Applicant last name
entity_name	String	Full name of the entity/applicant
applicant_maiden_name_prefix	String	Maiden name prefix
applicant_maiden_first_name	String	Maiden first name
applicant_maiden_middle_name	String	Maiden middle name
applicant_maiden_last_name	String	Maiden last name
applicant_maiden_full_name	String	Full maiden name
father_or_spouse_flag	String	Indicates father or spouse name provided
father_spouse_name_prefix	String	Prefix for father/spouse name
father_spouse_first_name	String	Father/spouse first name
father_spouse_middle_name	String	Father/spouse middle name
father_spouse_last_name	String	Father/spouse last name
father_spouse_full_name	String	Full father/spouse name
mother_name_prefix	String	Prefix for mother's name
mother_first_name	String	Mother's first name
mother_middle_name	String	Mother's middle name
mother_last_name	String	Mother's last name
mother_full_name	String	Full mother's name
gender	String	Gender of applicant
marital_status	String	Marital status of applicant
nationality	String	Nationality of applicant
occupation_type	String	Type of occupation
date_of_birth	String	Date of birth
place_of_incorporation	String	Place of incorporation
date_of_commencement_business	String	Date of commencement of business
country_of_incorporation	String	Country of incorporation
country_of_residence_tax_laws	String	Country of tax residence
identification_type	String	Type of identification provided
tin_gst_registration_number	String	Tax ID or GST registration number
tin_issuing_country	String	Country issuing TIN/GST
pan_or_form60	String	PAN or Form 60 number
residential_status	String	Residential status
resident_tax_purposes_outside_india	String	Tax residency outside India
jurisdiction_of_residence	String	Jurisdiction of residence
tin_gst_registration_number_jurisdiction	String	TIN/GST in jurisdiction
country_of_birth	String	Country of birth
city_place_of_birth	String	City of birth
address_type	String	Address type
registered_address_line1	String	Registered address line 1
registered_address_line2	String	Registered address line 2
registered_address_line3	String	Registered address line 3
registered_address_city	String	Registered city
registered_address_district	String	Registered district
registered_address_state	String	Registered state
registered_address_country	String	Registered country
registered_address_pincode	String	Registered postal code
proof_of_registered_address	String	Proof document for registered address
registered_same_as_local_address_flag	String	Flag if local address is same as registered
local_address_line1	String	Local address line 1
local_address_line2	String	Local address line 2
local_address_line3	String	Local address line 3
local_address_city	String	Local city
local_address_district	String	Local district
local_address_state	String	Local state
local_address_country	String	Local country
local_address_pincode	String	Local postal code
proof_of_local_address	String	Proof document for local address
residence_telephone_std_code	String	STD code for residence phone
residence_telephone_number	String	Residence phone number
office_telephone_std_code	String	STD code for office phone
office_telephone_number	String	Office phone number
mobile_isd_code	String	Mobile ISD code
mobile_number	String	Mobile number
fax_std_code	String	Fax STD code
fax_number	String	Fax number
email_id	String	Email address
date_of_declaration	String	Date of declaration
place_of_declaration	String	Place of declaration
kyc_verification_date	String	KYC verification date
type_of_document_submitted	String	Type of submitted document
kyc_verification_name	String	Verifier name
kyc_verification_designation	String	Verifier designation
kyc_verification_branch	String	Verifier branch
kyc_verification_emp_code	String	Verifier employee code
organisation_name	String	Verifying organisation name
organisation_code	String	Verifying organisation code
number_of_identity_details	String	Number of identity details submitted
number_of_related_people	String	Number of related people
identity_verification_flag	String	Identity verification flag
number_of_local_address_details	String	Number of local address details
number_of_images	String	Number of images submitted
error_code	String	Error code if any
mobile_isd_code_2	String	Secondary mobile ISD code
mobile_number_2	String	Secondary mobile number
email_id_2	String	Secondary email
ckyc_reference_id	String	CKYC reference ID from search API
identity_details	Array	Array of identity objects
image_details	Object	Object containing `image_code` and `image_data`
additional_field_122	String	Additional field for future use

identity_details (Object)

Parameter	Type	Description
record_type	String	Identity record type code
line_number	String	Line number in identity records
identity_type	String	Type of identity document
identity_number	String	Identity document number
identity_issue_date	String	Date of issue
identity_expiry_date	String	Expiry date if applicable
identity_place_of_issue	String	Place of issue
identity_issued_by	String	Authority issuing the identity
identity_field_9	String	Additional identity field 9
identity_field_10	String	Additional identity field 10
identity_field_11	String	Additional identity field 11
identity_field_12	String	Additional identity field 12
identity_field_13	String	Additional identity field 13

image_details (Object)

Parameter	Type	Description
image_code	String	Code identifying the image type
image_data	String	Base64 encoded image data

Example Successful Response (Uploaded State)

{
  "data": {
    "client_id": "ckyc_bulk_download_XYZ123456789",
    "state": "uploaded",
    "response": {
      "batch_number": "IN1234_DL_25092025_V1.2_IA000001_D10001.txt",
      "approved_by_checker": true,
      "individual_file_response": [
        {
          "ckyc_id": "20010020030040",
          "data": {
            "status": "success",
            "message": "Record processed successfully",
            "reference_no": "20010020030040",
            "record_type": "20",
            "line_number": "1",
            "application_type": "Download",
            "branch_code": "MUM001",
            "applicant_name_update_flag": "",
            "personal_details_update_flag": "",
            "address_details_update_flag": "",
            "contact_details_update_flag": "",
            "remarks_update_flag": "",
            "kyc_verification_update_flag": "",
            "identity_details_update_flag": "",
            "related_person_details_update_flag": "",
            "download_count_last_5_years": "12",
            "image_details_update_flag": "",
            "constitution_type": "",
            "constitution_type_others": "",
            "update_count_last_5_years": "2",
            "account_type": "",
            "ckyc_no": "20010020030040",
            "applicant_name_prefix": "MR",
            "applicant_first_name": "Rohit",
            "applicant_middle_name": "Kumar",
            "applicant_last_name": "Sharma",
            "entity_name": "MR Rohit Kumar Sharma",
            "applicant_maiden_name_prefix": "",
            "applicant_maiden_first_name": "",
            "applicant_maiden_middle_name": "",
            "applicant_maiden_last_name": "",
            "applicant_maiden_full_name": "",
            "father_or_spouse_flag": "01",
            "father_spouse_name_prefix": "MR",
            "father_spouse_first_name": "Suresh",
            "father_spouse_middle_name": "",
            "father_spouse_last_name": "Sharma",
            "father_spouse_full_name": "MR Suresh Sharma",
            "mother_name_prefix": "Mrs",
            "mother_first_name": "Sunita",
            "mother_middle_name": "",
            "mother_last_name": "",
            "mother_full_name": "Mrs Sunita Sharma",
            "gender": "Male",
            "marital_status": "Single",
            "nationality": "Indian",
            "occupation_type": "Salaried",
            "date_of_birth": "15-08-1992",
            "place_of_incorporation": "",
            "date_of_commencement_business": "",
            "country_of_incorporation": "",
            "country_of_residence_tax_laws": "",
            "identification_type": "",
            "tin_gst_registration_number": "",
            "tin_issuing_country": "",
            "pan_or_form60": "ABCPK1234L",
            "residential_status": "Resident",
            "resident_tax_purposes_outside_india": "",
            "jurisdiction_of_residence": "",
            "tin_gst_registration_number_jurisdiction": "",
            "country_of_birth": "India",
            "city_place_of_birth": "Jaipur",
            "address_type": "",
            "registered_address_line1": "Flat 502, Green Residency",
            "registered_address_line2": "Sector 21, Andheri East",
            "registered_address_line3": "",
            "registered_address_city": "Mumbai",
            "registered_address_district": "Mumbai Suburban",
            "registered_address_state": "Maharashtra",
            "registered_address_country": "India",
            "registered_address_pincode": "400069",
            "proof_of_registered_address": "Electricity Bill",
            "proof_of_registered_address_others": "",
            "registered_same_as_local_address_flag": "Y",
            "correspondence_address_type": "",
            "local_address_line1": "Flat 502, Green Residency",
            "local_address_line2": "Sector 21, Andheri East",
            "local_address_line3": "",
            "local_address_city": "Mumbai",
            "local_address_district": "Mumbai Suburban",
            "local_address_state": "Maharashtra",
            "local_address_country": "India",
            "local_address_pincode": "400069",
            "proof_of_local_address": "Electricity Bill",
            "address_same_as_jurisdiction_flag": "",
            "address_in_jurisdiction_type": "",
            "address_in_jurisdiction_line1": "",
            "address_in_jurisdiction_line2": "",
            "address_in_jurisdiction_line3": "",
            "address_in_jurisdiction_city": "",
            "address_in_jurisdiction_state": "",
            "address_in_jurisdiction_country": "",
            "address_in_jurisdiction_pincode": "",
            "proof_of_address_in_jurisdiction": "",
            "residence_telephone_std_code": "022",
            "residence_telephone_number": "26543210",
            "office_telephone_std_code": "022",
            "office_telephone_number": "26543211",
            "mobile_isd_code": "91",
            "mobile_number": "9876543210",
            "fax_std_code": "",
            "fax_number": "",
            "email_id": "rohit.sharma92@gmail.com",
            "remarks": "",
            "date_of_declaration": "01-09-2025",
            "place_of_declaration": "Mumbai",
            "kyc_verification_date": "********",
            "type_of_document_submitted": "Aadhaar Card",
            "kyc_verification_name": "********",
            "kyc_verification_designation": "********",
            "kyc_verification_branch": "********",
            "kyc_verification_emp_code": "********",
            "organisation_name": "********",
            "organisation_code": "********",
            "number_of_identity_details": "1",
            "number_of_related_people": "",
            "identity_verification_flag": "",
            "number_of_local_address_details": "",
            "number_of_images": "2",
            "error_code": "",
            "mobile_isd_code_2": "",
            "mobile_number_2": "",
            "email_id_2": "",
            "ckyc_reference_id": "INMUM12345678",
            "identity_details": [
              {
                "record_type": "30",
                "line_number": "1",
                "identity_type": "E - Proof of Possession of Aadhaar",
                "identity_number": "XXXXXXXX1234",
                "identity_issue_date": "",
                "identity_expiry_date": "",
                "identity_place_of_issue": "",
                "identity_issued_by": "01",
                "identity_field_9": "",
                "identity_field_10": "",
                "identity_field_11": "",
                "identity_field_12": "",
                "identity_field_13": ""
              }
            ],
            "image_details": [
              {
                "image_code": null,
                "image_data": "/9j/4AAQSkZJRgABAQEAyADIAAD/4QAiRXhpZgAATU0AKgAAAAgAAQESAAMAAAABAAEAAAAAAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYH........"
              },
              {
                "image_code": null,
                "image_data": "/9j/4AAQSkZJRgABAQEAyADIAAD/4QAiRXhpZgAATU0AKgAAAAgAAQESAAMAAAABAAEAAAAAAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYH........"
              }
            ],
            "additional_field_122": ""
          }
        }
      ]
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

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

The provided client_id does not exist or has expired

Integration Best Practices

Security Recommendations

Implement secure storage for client_id values to track ongoing requests

Use HTTPS endpoints exclusively for all sensitive CKYC data transmission

Implement proper access controls for viewing complete CKYC records

Store image data securely and implement proper data retention policies

Log all status check requests for audit and compliance purposes

User Experience Guidelines

Implement polling mechanisms with exponential backoff for pending requests

Provide clear status indicators showing processing progress to end users

Handle large response payloads efficiently when processing uploaded results

Implement proper error handling for network timeouts during large data transfers

Consider pagination or chunking for very large bulk download responses

Code Samples

cURL

Python

Node.js

Related APIs

CKYC Bulk Download Initialize API - Initiate bulk download requests to obtain client_id for status tracking

CKYC Search API - Search for CKYC records before initiating bulk downloads

Individual CKYC Verification API - Verify single CKYC records for comparison with bulk results

CKYC Data Export API - Export processed CKYC data in various formats for downstream systems

Compliance and Legal Considerations

This API provides access to comprehensive personal and financial data regulated under India's CKYC framework. Ensure compliance with:

Data Security: Implement encryption for storing and transmitting complete CKYC records

Access Logging: Maintain detailed audit logs of all status checks and data retrievals

Data Minimization: Only retrieve and store necessary CKYC data fields for your use case

Image Handling: Properly secure base64 encoded identity document images

Retention Policies: Follow prescribed data retention periods and secure deletion practices

Regulatory Reporting: Maintain records for regulatory audits and compliance verification

Consent Verification: Ensure proper customer consent before accessing complete CKYC profiles

Organizations must implement appropriate data protection measures and maintain regulatory compliance when handling the comprehensive CKYC data returned by this API.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

CKYC Bulk Download Status

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

CKYC Bulk Download Response Parameters#

data#

data.response#

individual_file_response (Object)#

individual_file_response.data#

identity_details (Object)#

image_details (Object)#

Example Successful Response (Uploaded State)#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses