CKYC Bulk Upload File Update

Endpoint Overview

POST /api/v1/ckyc-upload/update/upload-file

Description

The CKYC Bulk Upload File Update API enables organizations to initiate bulk updates to Central KYC (CKYC) records by uploading a file containing customer information. This endpoint streamlines the process of updating multiple CKYC records simultaneously, eliminating the need for individual API calls for each customer update. The API accepts file uploads, validates the data, and initiates an asynchronous processing workflow to handle bulk CKYC updates efficiently.

This endpoint is designed to handle large-scale CKYC update operations, making it ideal for financial institutions, fintech companies, and service providers that need to maintain up-to-date KYC records for their customer base in compliance with regulatory requirements.

Key Benefits

Bulk Processing Efficiency: Update multiple CKYC records in a single API call, significantly reducing integration complexity and processing time

Asynchronous Workflow: Non-blocking operation allows your application to continue processing while CKYC updates are handled in the background

Error Tracking: Receive a unique client ID to track the status and errors of your bulk upload operation

Regulatory Compliance: Streamline compliance with KYC regulations by maintaining current customer information across the CKYC registry

Use Cases

Banking & Finance

Fintech & NBFCs

Insurance & Wealth Management

Periodic KYC Updates: Banks can upload quarterly or annual KYC refresh data for their entire customer base to maintain compliance with RBI guidelines

Customer Migration: During system migrations or mergers, bulk update CKYC records for thousands of customers in a single operation

Address Change Campaigns: Process bulk address updates when customers relocate, ensuring CKYC records reflect current information

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 token for API authentication. Format: `Bearer {JWT_TOKEN}`
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Request Body

Parameter	Type	Required	Description
file	File	Yes	The file containing CKYC update data. Supported formats typically include Zip Files then it contains CSV, Excel, or other structured data files. The file should contain customer information with fields required for CKYC updates

Example Request

{
    "file": "<zip_file>"
}

Note: This is a multipart/form-data request. The actual request will include the file as a binary upload rather than JSON format.

Process Response

Response Parameters

Parameter	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response (200 for success)
message	string	General message describing the result of the operation
message_code	string	Machine-readable code representing the message type
data	object	Container object for the response payload
data.client_id	string	Unique identifier for tracking this bulk upload operation
data.message	string	Detailed message about the upload initiation status
data.state	string	Current state of the bulk upload process (e.g., "pending", "processing", "completed")
data.error	array	Array of error objects. Empty array if no errors occurred during initiation

Example Successful Response

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

Possible Error Responses

Authentication Error

Invalid File Format

Server Error

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

This error occurs when the Bearer token is missing, invalid, or expired. Verify your JWT token and ensure it's correctly included in the Authorization header.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vaults, never hardcode them in your application

File Encryption: Consider encrypting sensitive customer data in files before upload, especially when transmitting over public networks

Access Control: Implement role-based access control to restrict who can initiate bulk CKYC uploads within your organization

Audit Logging: Maintain detailed logs of all bulk upload operations, including user, timestamp, and client_id for compliance auditing

Token Rotation: Regularly rotate JWT tokens and implement token expiration policies to minimize security risks

User Experience Guidelines

File Validation: Pre-validate file format and data structure before uploading to provide immediate feedback to users

Progress Tracking: Use the returned client_id to implement a status tracking mechanism, keeping users informed about upload progress

Error Handling: Display clear, actionable error messages to users when uploads fail, with guidance on how to correct issues

Batch Size Optimization: Test and determine optimal file sizes for your use case to balance processing time with user wait expectations

Confirmation Feedback: Provide immediate confirmation upon successful upload initiation, including the client_id for reference

Code Samples

cURL

Python

Node.js

Related APIs

CKYC Status Check API: Query the processing status of your bulk upload using the client_id returned by this endpoint

CKYC Download API: Retrieve the results and error reports from completed bulk upload operations

CKYC Search API: Search for individual CKYC records to verify successful updates

CKYC Download Template API: Download the correct file template with required fields and format specifications

Compliance and Legal Considerations

Regulatory Framework: This API facilitates compliance with the Central KYC Registry managed by the Central Registry of Securitisation Asset Reconstruction and Security Interest of India (CERSAI). Organizations using this API must ensure they have proper authorization to update customer KYC records.

Data Privacy: Ensure compliance with applicable data protection regulations including the Digital Personal Data Protection Act (DPDPA) and Information Technology Act. Customer consent must be obtained before updating their KYC information.

Data Accuracy: Organizations are responsible for the accuracy and completeness of data submitted through this API. Incorrect or fraudulent information may result in regulatory penalties.

Retention and Audit: Maintain records of all bulk upload operations, including original files and processing results, for the period mandated by regulatory authorities (typically 5-10 years).

Access Authorization: Restrict API access to authorized personnel only and implement proper authentication and authorization mechanisms as per your organization's security policy.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

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

CKYC Update Upload File

CKYC Bulk Upload File Update#

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