Initialize CKYC Update

Endpoint Overview

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

Description

This API endpoint is used to initialize the update process for CKYC (Central KYC) data. It allows organizations to submit updated KYC information for one or more individuals, including personal details, address, identification documents, and verifier information. The API is designed to streamline the CKYC update workflow, ensuring compliance and efficient data management for regulated entities.

Key Benefits

Enables bulk or single CKYC update initialization in a secure, automated manner.

Reduces manual paperwork and operational delays for KYC updates.

Ensures regulatory compliance with CKYC data standards.

Supports structured submission of verifier and individual details, including document uploads.

Use Cases

Banking & Financial Services

NBFCs & Lending

Insurance & Mutual Funds

Bulk update of customer KYC records for regulatory compliance.

Streamlined onboarding or re-KYC for new and existing account holders.

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.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token in the format `Bearer <JWT>`
Content-Type	Yes	`application/json`

Request Body

Parameter	Type	Required	Description
data	object	Yes	Main request payload.
data.purpose	string	Yes	Purpose of the CKYC update (e.g., "For bank account purpose").
data.verifier	object	Yes	Details of the verifier submitting the update.
data.verifier.name	string	Yes	Name of the verifier.
data.verifier.declaration_place	string	Yes	Place of declaration.
data.verifier.designation	string	Yes	Designation of the verifier.
data.verifier.branch	string	Yes	Branch name.
data.verifier.employment_code	string	Yes	Employment code of the verifier.
data.verifier.organization_name	string	Yes	Name of the organization.
data.verifier.organization_code	string	Yes	Organization code.
data.individuals	array	Yes	List of individuals whose CKYC data is being updated.
data.individuals[].identifier	string	Yes	Unique identifier for the individual (e.g., CKYC number).
data.individuals[].prefix	string	No	Name prefix (e.g., MR, MS).
data.individuals[].first_name	string	Yes	First name of the individual.
data.individuals[].middle_name	string	No	Middle name of the individual.
data.individuals[].last_name	string	Yes	Last name of the individual.
data.individuals[].gender	string	Yes	Gender (e.g., MALE, FEMALE, OTHER).
data.individuals[].date_of_birth	string	Yes	Date of birth (YYYY-MM-DD).
data.individuals[].address	object	Yes	Permanent address details.
data.individuals[].address.address	string	Yes	Full address.
data.individuals[].address.state_code	string	Yes	State code.
data.individuals[].address.pincode	string	Yes	Postal code.
data.individuals[].address.city	string	Yes	City name.
data.individuals[].address.district	string	Yes	District name.
data.individuals[].same_address	boolean	No	If true, current address is same as permanent address.
data.individuals[].current_address	object	No	Current address details (if different from permanent address).
data.individuals[].current_address.address	string	Yes*	Full current address.
data.individuals[].current_address.state_code	string	Yes*	State code for current address.
data.individuals[].current_address.pincode	string	Yes*	Postal code for current address.
data.individuals[].current_address.city	string	Yes*	City for current address.
data.individuals[].current_address.district	string	Yes*	District for current address.
data.individuals[].document_submission_type	string	Yes	Type of document submission (e.g., CKYC).
data.individuals[].ids	array	Yes	List of identification documents.
data.individuals[].ids[].id_number	string	Yes	ID number (e.g., Aadhaar, PAN).
data.individuals[].ids[].type	string	Yes	Type of ID (e.g., AADHAAR, PAN).
data.individuals[].documents	array	Yes	List of document images.
data.individuals[].documents[].image	string	Yes	Base64-encoded image string.
data.individuals[].documents[].type	string	Yes	Type of document (e.g., AADHAAR, PAN).

*Required if same_address is false.

Example Request

{
  "data": {
    "purpose": "For bank account purpose",
    "verifier": {
      "name": "Amit Shroff",
      "declaration_place": "Mumbai",
      "designation": "CEO",
      "branch": "Mumbai",
      "employment_code": "Afsl147",
      "organization_name": "Finkurve Financial Services Limited",
      "organization_code": "IN7196"
    },
    "individuals": [
      {
        "identifier": "78945612378901",
        "prefix": "MR",
        "first_name": "Rohit",
        "middle_name": "Anil",
        "last_name": "Deshmukh",
        "gender": "MALE",
        "date_of_birth": "1993-08-15",
        "address": {
          "address": "Flat 402, Green Heights, Sector 5, Navi Mumbai",
          "state_code": "MH",
          "pincode": "410210",
          "city": "Navi Mumbai",
          "district": "Raigad"
        },
        "same_address": true,
        "current_address": {
          "address": "Flat 402, Green Heights, Sector 5, Navi Mumbai",
          "state_code": "MH",
          "pincode": "410210",
          "city": "Navi Mumbai",
          "district": "Raigad"
        },
        "document_submission_type": "CKYC",
        "ids": [
          {
            "id_number": "XXXXXXXX5678",
            "type": "AADHAAR"
          },
          {
            "id_number": "BNTPD1234L",
            "type": "PAN"
          }
        ],
        "documents": [
          {
            "image": "base64dummyimage",
            "type": "AADHAAR"
          }
        ]
      }
    ]
  }
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Main response payload.
data.client_id	string	Unique client identifier for the CKYC update session.
data.message	string	Status message.
data.state	string	State of the CKYC update (e.g., "pending").
data.error	array	List of errors, if any.
status_code	number	HTTP status code (e.g., 200 for success).
success	boolean	Indicates if the request was successful.
message	string	Human-readable status message.
message_code	string	Machine-readable status code.

Example Successful Response

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

Possible Error Responses

Invalid or Missing Token

Not Registered CKYC

Internal Server Error

{
  "status_code": 401,
  "success": false,
  "message": "Unauthorized: Invalid or missing token",
  "message_code": "unauthorized"
}

The request is missing a valid Bearer token or the token is invalid.

Integration Best Practices

Security Recommendations

Always use HTTPS to protect sensitive KYC data in transit.

Store JWT tokens securely and rotate them periodically.

Never expose your API keys or tokens in client-side code or public repositories.

User Experience Guidelines

Display clear error messages to users in case of authentication or data validation failures.

Validate all user inputs before submission to the API.

Code Samples

cURL

Python

Node.js

Related APIs

CKYC Upload API: For bulk or single CKYC data uploads.

CKYC Status API: To check the status of CKYC uploads or updates.

CKYC Download API: To retrieve CKYC data for individuals.

Compliance and Legal Considerations

Ensure all CKYC data submissions comply with regulatory requirements and data privacy laws. Only authorized personnel should have access to KYC data. Securely store and transmit sensitive information, and never share JWT tokens or personal data in unsecured channels.

This documentation provides a comprehensive, implementation-focused guide for integrating the CKYC Update Initialization API into your applications. For further support, refer to Surepass developer resources or contact your Surepass representative.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ckyc-upload/update/initialize' \ --header 'Content-Type: application/json' \ --data-raw '{ "data": { "purpose": "For bank account purpose", "verifier": { "name": "Amit Shroff", "declaration_place": "Mumbai", "designation": "CEO", "branch": "Mumbai", "employment_code": "Afsl147", "organization_name": "Finkurve Financial Services Limited", "organization_code": "IN7196" }, "individuals": [ { "identifier": "78945612378901", "prefix": "MR", "first_name": "Rohit", "middle_name": "Anil", "last_name": "Deshmukh", "gender": "MALE", "date_of_birth": "1993-08-15", "address": { "address": "Flat 402, Green Heights, Sector 5, Navi Mumbai", "state_code": "MH", "pincode": "410210", "city": "Navi Mumbai", "district": "Raigad" }, "same_address": true, "current_address": { "address": "Flat 402, Green Heights, Sector 5, Navi Mumbai", "state_code": "MH", "pincode": "410210", "city": "Navi Mumbai", "district": "Raigad" }, "document_submission_type": "CKYC", "ids": [ { "id_number": "XXXXXXXX5678", "type": "AADHAAR" }, { "id_number": "BNTPD1234L", "type": "PAN" } ], "documents": [ { "image": "base64dummyimage", "type": "AADHAAR" } ] } ] } }'

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

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

CKYC Update Initialize

Initialize CKYC 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