CKYC Update Initialize

Endpoint Overview

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

Description

Initializes an update request for existing CKYC records via SFTP. Submit one or more individuals with updated personal details, addresses, identity documents, and verifier information. Returns a client_id for tracking the async processing.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token:

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.

Environment URLs:

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	Verifier details
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	Array of individuals to update
data.individuals[].identifier	string	Yes	CKYC number of the existing record
data.individuals[].prefix	string	No	Name prefix (e.g., MR, MS)
data.individuals[].first_name	string	Yes	First name
data.individuals[].middle_name	string	No	Middle name
data.individuals[].last_name	string	Yes	Last name
data.individuals[].gender	string	Yes	Gender (`MALE`, `FEMALE`, `OTHER`)
data.individuals[].date_of_birth	string	Yes	Date of birth (`YYYY-MM-DD`)
data.individuals[].address	object	Yes	Permanent address
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
data.individuals[].current_address	object	No	Current address (required if `same_address` is false)
data.individuals[].document_submission_type	string	Yes	Type of document submission (e.g., `CKYC`)
data.individuals[].ids	array	Yes	Identity documents
data.individuals[].ids[].id_number	string	Yes	ID number (e.g., Aadhaar, PAN)
data.individuals[].ids[].type	string	Yes	Type of ID (`AADHAAR`, `PAN`, etc.)
data.individuals[].documents	array	Yes	Document images
data.individuals[].documents[].image	string	Yes	Base64-encoded image
data.individuals[].documents[].type	string	Yes	Document type (`AADHAAR`, `PAN`, etc.)

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	Response payload
data.client_id	string	Unique identifier for tracking this update request
data.message	string	Status message
data.state	string	Initial state (`pending`)
data.error	array	Validation errors, if any
status_code	number	HTTP status code
success	boolean	Whether 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

Authentication Failed

Not Registered

Server Error

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

The JWT token is missing, expired, or invalid.

Heads Up

Billing -- Billed per individual record in the batch, not per API call.

180-day TTL -- Update records are automatically deleted after 6 months.

State machine -- After initialization, the request moves through pending → started → ready_to_upload → uploading → uploaded → upload_succeeded/upload_failed. See the parent index for full state and sub-state reference.

Mutual exclusivity -- Requests must contain individuals only. Do not mix with legal_entities.

Code Samples

cURL

Python

Node.js

Next Steps

Update Status -- Poll the processing status using your client_id

Update Upload File -- Alternate ZIP entrypoint if you want to start the batch from CSV + images instead of JSON

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/update/initialize' \ --header 'Authorization: Bearer <token>' \ --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" }

CKYC Update Initialize

CKYC Update Initialize#

Description#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Code Samples#

Request

Responses

CKYC Update Initialize

Description

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Code Samples