CKYC Upload Initialize

Endpoint Overview

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

Description

The CKYC Upload Initialize API enables financial institutions and authorized organizations to initiate bulk Central KYC (CKYC) record uploads to the CKYC registry. This endpoint accepts comprehensive customer information including personal details, identity documents, addresses, and verifier information, and creates a pending upload request that can be processed asynchronously.

This API streamlines the KYC compliance process by allowing organizations to submit multiple individual records in a single request, complete with all required documentation and verification details. The system validates the submission and returns a unique client ID for tracking the upload status.

Key Benefits

Bulk Processing: Submit multiple individual KYC records in a single API call for efficient batch processing

Comprehensive Data Capture: Supports complete customer profiles including personal details, documents, addresses, and identity proofs

Asynchronous Processing: Receive immediate acknowledgment with a tracking ID while the system processes records in the background

Regulatory Compliance: Ensures adherence to CKYC registry standards and RBI guidelines for customer verification

Use Cases

Banking & Financial Services

NBFCs & Fintech

Insurance & Securities

New customer onboarding for savings accounts, current accounts, or loan applications

Bulk migration of existing customer KYC records to the central CKYC registry

Periodic KYC updates for existing customers to maintain compliance

Digital account opening processes requiring CKYC registration

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 YOUR_JWT_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 YOUR_JWT_TOKEN`)
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
data	Object	Yes	Root object containing all CKYC upload information
data.purpose	String	Yes	Purpose of the CKYC upload (e.g., "For bank account purpose")
data.verifier	Object	Yes	Details of the verification officer conducting the KYC
data.verifier.name	String	Yes	Full name of the verification officer
data.verifier.declaration_place	String	Yes	Place where the declaration is made
data.verifier.designation	String	Yes	Official designation of the verifier
data.verifier.branch	String	Yes	Branch name where verification is conducted
data.verifier.employment_code	String	Yes	Employee code of the verification officer
data.verifier.organization_name	String	Yes	Name of the verifying organization
data.verifier.organization_code	String	Yes	Official organization code assigned by the registry
data.individuals	Array	Yes	Array of individual customer records to be uploaded
data.individuals[].identifier	String	Yes	Unique identifier for the individual
data.individuals[].prefix	String	Yes	Name prefix (e.g., "MR", "MS", "MRS")
data.individuals[].first_name	String	Yes	First name of the individual
data.individuals[].middle_name	String	No	Middle name of the individual (optional)
data.individuals[].last_name	String	Yes	Last name of the individual
data.individuals[].maiden_prefix	String	No	Maiden name prefix (optional, for married individuals)
data.individuals[].maiden_first_name	String	No	Maiden first name (optional)
data.individuals[].maiden_middle_name	String	No	Maiden middle name (optional)
data.individuals[].maiden_last_name	String	No	Maiden last name (optional)
data.individuals[].maiden_full_name	String	No	Complete maiden name (optional)
data.individuals[].gender	String	Yes	Gender of the individual (e.g., "MALE", "FEMALE", "OTHER")
data.individuals[].date_of_birth	String	Yes	Date of birth in YYYY-MM-DD format
data.individuals[].marital_status	String	Yes	Marital status (e.g., "MARRIED", "UNMARRIED", "DIVORCED", "WIDOWED")
data.individuals[].differently_abled_flag	Boolean	Yes	Indicates if the individual is differently abled
data.individuals[].type_of_impairment	String	Conditional	Type of impairment (required if differently_abled_flag is true)
data.individuals[].percentage_of_impairment	Number	Conditional	Percentage of impairment (required if differently_abled_flag is true)
data.individuals[].udid_number	String	Conditional	Unique Disability ID number (required if differently_abled_flag is true)
data.individuals[].address	Object	Yes	Permanent address details
data.individuals[].address.address	String	Yes	Complete address line
data.individuals[].address.state_code	String	Yes	Two-letter state code (e.g., "MH" for Maharashtra)
data.individuals[].address.city	String	Yes	City name
data.individuals[].address.district	String	Yes	District name
data.individuals[].address.pincode	String	Yes	Six-digit postal code
data.individuals[].address.country_code	String	Yes	Two-letter country code (e.g., "IN" for India)
data.individuals[].same_address	Boolean	Yes	Indicates if current address is same as permanent address
data.individuals[].current_address	Object	Yes	Current/correspondence address (same structure as address)
data.individuals[].document_submission_type	String	Yes	Type of KYC submission (e.g., "EKYC", "PAPER")
data.individuals[].relative	Array	Yes	Array of relative information
data.individuals[].relative[].prefix	String	Yes	Prefix for relative's name
data.individuals[].relative[].type	String	Yes	Relationship type (e.g., "FATHER", "MOTHER", "SPOUSE")
data.individuals[].relative[].first_name	String	Yes	Relative's first name
data.individuals[].relative[].middle_name	String	No	Relative's middle name (optional)
data.individuals[].relative[].last_name	String	Yes	Relative's last name
data.individuals[].documents	Array	Yes	Array of document images
data.individuals[].documents[].image	String	Yes	Base64 encoded image data
data.individuals[].documents[].type	String	Yes	Document type (e.g., "PHOTOGRAPH", "SIGNATURE")
data.individuals[].documents[].filename	String	Yes	Original filename with extension
data.individuals[].ids	Array	Yes	Array of identity documents
data.individuals[].ids[].id_number	String	Yes	Identity document number
data.individuals[].ids[].type	String	Yes	Identity type (e.g., "AADHAAR", "PAN", "PASSPORT")
data.individuals[].contact_details	Object	Yes	Contact information (all fields optional)
data.individuals[].contact_details.email	String	Optional	Email address
data.individuals[].contact_details.mobile_isd_code	String	Optional	Mobile country code (e.g., "91" for India)
data.individuals[].contact_details.mobile_number	String	Optional	Mobile number without country code
data.individuals[].contact_details.residential_std_number	String	Optional	Residential phone STD code
data.individuals[].contact_details.residential_telephone_number	String	Optional	Residential phone number
data.individuals[].contact_details.office_std_number	String	Optional	Office phone STD code
data.individuals[].contact_details.office_telephone_number	String	Optional	Office phone number
data.individuals[].contact_details.fax_std_code	String	Optional	Fax STD code
data.individuals[].contact_details.fax_number	String	Optional	Fax number

Example Request

{
    "data": {
        "purpose": "For bank account purpose",
        "verifier": {
            "name": "Anil Sharma",
            "declaration_place": "Mumbai",
            "designation": "Verification Officer",
            "branch": "Andheri",
            "employment_code": "EMP001",
            "organization_name": "Surepass",
            "organization_code": "FI999"
        },
        "individuals": [
            {
                "identifier": "11111111111111",
                "prefix": "MR",
                "first_name": "ronak",
                "middle_name": "",
                "last_name": "Singh",
                "maiden_prefix": null,
                "maiden_first_name": null,
                "maiden_middle_name": null,
                "maiden_last_name": null,
                "maiden_full_name": null,
                "gender": "MALE",
                "date_of_birth": "2003-12-19",
                "marital_status": "UNMARRIED",
                "differently_abled_flag": false,
                "type_of_impairment": null,
                "percentage_of_impairment": null,
                "udid_number": null,
                "address": {
                    "address": "45 Marine Drive",
                    "state_code": "MH",
                    "city": "Mumbai",
                    "district": "Mumbai City",
                    "pincode": "400020",
                    "country_code": "IN"
                },
                "same_address": true,
                "current_address": {
                    "address": "45 Marine Drive",
                    "state_code": "MH",
                    "city": "Mumbai",
                    "district": "Mumbai City",
                    "pincode": "400020",
                    "country_code": "IN"
                },
                "document_submission_type": "EKYC",
                "relative": [
                    {
                        "prefix": "MR",
                        "type": "FATHER",
                        "first_name": "FatherName",
                        "middle_name": null,
                        "last_name": "User"
                    }
                ],
                "documents": [
                    {
                        "image": "",
                        "type": "PHOTOGRAPH",
                        "filename": "photo.jpeg"
                    }
                ],
                "ids": [
                    {
                        "id_number": "123456789123",
                        "type": "AADHAAR"
                    }
                ],
                "contact_details": {
                    "email": "test1@example.com",
                    "mobile_isd_code": "91",
                    "mobile_number": "9999999991",
                    "residential_std_number": null,
                    "residential_telephone_number": null,
                    "office_std_number": null,
                    "office_telephone_number": null,
                    "fax_std_code": null,
                    "fax_number": null
                }
            }
        ]
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Response data container
data.client_id	String	Unique identifier for tracking the CKYC upload request
data.message	String	Human-readable message describing the upload status
data.state	String	Current state of the upload (e.g., "pending", "processing", "completed")
data.error	Array	Array of error messages (empty if no errors)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates whether the request was successful
message	String	General response message
message_code	String	Machine-readable message code for programmatic handling

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

Validation Error

Server Error

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

This error occurs when the JWT bearer token is invalid, expired, or missing from the request headers.

Integration Best Practices

Security Recommendations

Store JWT tokens securely using environment variables or secure credential management systems, never hardcode them in source code

Implement token refresh mechanisms to handle token expiration gracefully

Use HTTPS for all API communications to ensure data encryption in transit

Validate and sanitize all input data before encoding as Base64, especially document images

Implement rate limiting on your application side to prevent accidental API abuse

Log all API requests and responses (excluding sensitive data) for audit trail purposes

Rotate API credentials periodically and immediately revoke compromised tokens

User Experience Guidelines

Implement file size validation for document uploads before Base64 encoding to prevent large payload errors

Provide clear progress indicators during the upload process, as bulk uploads may take time

Display user-friendly error messages that guide users to correct validation issues

Implement client-side validation to catch common errors before API submission

Store the client_id returned in the response for status tracking and provide users a way to check upload status

Allow users to save draft submissions to avoid data loss during multi-step forms

Provide clear instructions on acceptable document formats and size limits

Code Samples

cURL

Python

Node.js

Related APIs

CKYC Upload Status: Check the processing status of your bulk upload using the client_id returned from this endpoint

CKYC Search: Search for existing CKYC records in the registry using various search parameters like PAN, Aadhaar, or CKYC number

CKYC Download: Download individual CKYC records from the registry in XML or PDF format for verification purposes

Document Upload: Standalone API for uploading additional documents to existing CKYC records

Compliance and Legal Considerations

This API facilitates compliance with the Prevention of Money Laundering Act (PMLA) and RBI Master Directions on Know Your Customer. Organizations must ensure they have proper authorization and legal basis to collect and submit customer KYC information to the CKYC registry. All data submitted must be accurate, verified, and collected with appropriate customer consent. The verifier details must correspond to authorized personnel within the regulated entity. Organizations are responsible for maintaining audit trails of all CKYC submissions and ensuring data accuracy. Non-compliance with KYC regulations may result in penalties under PMLA and other applicable laws. Ensure that all personal data handling complies with the Digital Personal Data Protection Act, 2023 and obtain necessary consents for data processing and sharing with the CKYC registry.

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/upload/initialize' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "data": { "purpose": "For bank account purpose", "verifier": { "name": "Anil Sharma", "declaration_place": "Mumbai", "designation": "Verification Officer", "branch": "Andheri", "employment_code": "EMP001", "organization_name": "Surepass", "organization_code": "FI999" }, "individuals": [ { "identifier": "11111111111111", "prefix": "MR", "first_name": "ronak", "middle_name": "", "last_name": "Singh", "maiden_prefix": null, "maiden_first_name": null, "maiden_middle_name": null, "maiden_last_name": null, "maiden_full_name": null, "gender": "MALE", "date_of_birth": "2003-12-19", "marital_status": "UNMARRIED", "differently_abled_flag": false, "type_of_impairment": null, "percentage_of_impairment": null, "udid_number": null, "address": { "address": "45 Marine Drive", "state_code": "MH", "city": "Mumbai", "district": "Mumbai City", "pincode": "400020", "country_code": "IN" }, "same_address": true, "current_address": { "address": "45 Marine Drive", "state_code": "MH", "city": "Mumbai", "district": "Mumbai City", "pincode": "400020", "country_code": "IN" }, "document_submission_type": "EKYC", "relative": [ { "prefix": "MR", "type": "FATHER", "first_name": "FatherName", "middle_name": null, "last_name": "User" } ], "documents": [ { "image": "", // base64 of images "type": "PHOTOGRAPH", "filename": "photo.jpeg" } ], "ids": [ { "id_number": "123456789123", "type": "AADHAAR" } ], "contact_details": { "email": "test1@example.com", "mobile_isd_code": "91", "mobile_number": "9999999991", "residential_std_number": null, "residential_telephone_number": null, "office_std_number": null, "office_telephone_number": null, "fax_std_code": null, "fax_number": null } }, { "identifier": "11111111111111", "prefix": "MR", "first_name": "ronak", "middle_name": "", "last_name": "Singh", "maiden_prefix": null, "maiden_first_name": null, "maiden_middle_name": null, "maiden_last_name": null, "maiden_full_name": null, "gender": "MALE", "date_of_birth": "2003-12-19", "marital_status": "UNMARRIED", "differently_abled_flag": false, "type_of_impairment": null, "percentage_of_impairment": null, "udid_number": null, "address": { "address": "45 Marine Drive", "state_code": "MH", "city": "Mumbai", "district": "Mumbai City", "pincode": "400020", "country_code": "IN" }, "same_address": true, "current_address": { "address": "45 Marine Drive", "state_code": "MH", "city": "Mumbai", "district": "Mumbai City", "pincode": "400020", "country_code": "IN" }, "document_submission_type": "EKYC", "relative": [ { "prefix": "MR", "type": "FATHER", "first_name": "FatherName", "middle_name": null, "last_name": "User" } ], "documents": [ { "image": "", // base64 of images "type": "PHOTOGRAPH", "filename": "photo.jpeg" } ], "ids": [ { "id_number": "123456789123", "type": "AADHAAR" } ], "contact_details": { "email": "test1@example.com", "mobile_isd_code": "91", "mobile_number": "9999999991", "residential_std_number": null, "residential_telephone_number": null, "office_std_number": null, "office_telephone_number": null, "fax_std_code": null, "fax_number": null } } ] } }'

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

CKYC Upload Initialize

CKYC Upload Initialize#

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

CKYC Upload Initialize

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples