CKYC Bulk Download Initialize

Endpoint Overview

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

Description

The CKYC Bulk Download Initialize API enables financial institutions and regulated entities to initiate bulk download requests for Central Know Your Customer (CKYC) records. This endpoint allows you to submit multiple CKYC identifiers along with verification parameters to prepare for bulk data retrieval. The API validates the provided information and returns a unique client ID that can be used to track and retrieve the requested CKYC data.

This service streamlines the customer onboarding process by enabling bulk verification of CKYC records, reducing individual API calls and improving operational efficiency for organizations handling large volumes of customer verification requests.

Key Benefits

Bulk Processing: Submit multiple CKYC verification requests in a single API call

Flexible Verification: Support for both date of birth and mobile number verification parameters

Asynchronous Processing: Initialize bulk requests and track progress with unique client IDs

Compliance Ready: Seamlessly integrate CKYC verification into regulatory compliance workflows

Use Cases

Banking & Finance

Insurance

Fintech & Digital Services

Mass customer onboarding during account opening campaigns

Bulk verification of existing customer CKYC records for compliance audits

Portfolio migration verification when acquiring new customer bases

Batch processing of loan application verifications

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
data	Object	Yes	Main data container for the request
data.individuals	Array	Yes	Array of individual CKYC verification requests
data.individuals[].ckyc_id	String	Yes	CKYC Number or CKYC Reference ID returned from CKYC Search API
data.individuals[].dob	String	Conditional	Date of birth in DD-MM-YYYY format (required if mobile_number not provided)
data.individuals[].mobile_number	String	Conditional	Mobile number for verification (required if dob not provided)

Example Request

{
    "data": {
        "individuals": [
            {
                "ckyc_id": "20087395964123",
                "dob": "07-09-1997",
                "mobile_number": ""
            },
            {
                "ckyc_id": "20087395964123",
                "dob": "07-09-1997",
                "mobile_number": ""
            }
        ]
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Main response data container
data.client_id	String	Unique identifier for tracking the bulk download request
data.message	String	Descriptive message about the request status
data.state	String	Current state of the request (e.g., "Passed")
data.error	Array	Array of error messages (empty if successful)
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

Example Successful Response

{
    "data": {
        "client_id": "ckyc_bulk_download_tVjnhFvhsyCrmzwbiKHn",
        "message": "CKYC bulk Download has been initiated",
        "state": "pending",
        "error": []
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Validation Error

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Unauthorized",
    "message_code": "auth_failed"
}

Invalid or missing JWT bearer token

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement proper token rotation policies

Use HTTPS endpoints only for all API communications

Implement request rate limiting to prevent API abuse

Log API requests for audit trails while ensuring PII data protection

Validate all input parameters on the client side before API submission

User Experience Guidelines

Provide clear progress indicators for bulk processing operations

Implement proper error handling with user-friendly error messages

Use the client_id for tracking and displaying request status to users

Consider implementing retry mechanisms for failed individual verifications

Batch requests optimally to balance performance and resource utilization

Code Samples

cURL

Python

Node.js

Related APIs

CKYC Search API - Search for CKYC records to obtain ckyc_reference_id values for use with this endpoint

CKYC Bulk Download Status API - Check the status of initiated bulk download requests using the client_id

CKYC Bulk Download Retrieve API - Download the actual CKYC data once processing is complete

Individual CKYC Verification API - Verify single CKYC records for smaller-scale operations

Compliance and Legal Considerations

This API processes sensitive personal and financial data regulated under India's CKYC guidelines. Ensure your implementation complies with:

Data Protection: Implement proper data encryption and secure storage practices

Access Controls: Restrict API access to authorized personnel only

Audit Requirements: Maintain detailed logs of all CKYC data access and processing

Data Retention: Follow prescribed data retention and deletion policies

Regulatory Reporting: Ensure compliance with RBI and other regulatory reporting requirements

Consent Management: Verify proper customer consent before processing CKYC data

Organizations must have appropriate regulatory permissions and compliance frameworks before using this API in production environments.

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/download/initialize' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "data": { "individuals": [ { "ckyc_id": "20087395964123", "dob": "07-09-1997" }, { "ckyc_id": "20087395964123", "dob": "07-09-1997" } ] } }'

{ "data": { "client_id": "ckyc_bulk_download_tVjnhFvhsyCrmzwbiKHn", "message": "CKYC bulk Download has been initiated", "state": "pending", "error": [] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses