CKYC Individual Download Initiate

Endpoint Overview

POST /api/v1/ckyc/v3/download/individual/initiate

Description

Initiate an individual CKYC download. This endpoint validates the selected ckyc_identifier and registered mobile_number, then asks CKYC to send an OTP to the registered mobile number.

Use this endpoint after POST /api/v1/ckyc/v3/search/individual. The search response gives you records[].ckyc_identifier; pass that value here.

The important continuation value is data.request_id. Store it and use it with POST /api/v1/ckyc/v3/download/individual to submit the OTP or request an OTP resend. The client_id is a SurePass transaction identifier.

Authentication

Environment	Base URL
Sandbox	`https://sandbox.surepass.app`
Production	`https://kyc-api.surepass.app`

Header	Required	Description
`Authorization`	Yes	Bearer token. Format: `Bearer YOUR_JWT_TOKEN`
`Content-Type`	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`ckyc_identifier`	String	Yes	Canonical CKYC identifier from search. This can be a CKYC reference ID such as `INRMFE49270123` or a CKYC number, depending on what search returned.
`mobile_number`	String	Yes	10-digit mobile number registered with the individual CKYC record.

Example Request

{
  "ckyc_identifier": "INRMFE49270123",
  "mobile_number": "9876543210"
}

Response

Parameter	Type	Description
`data.client_id`	String	SurePass transaction ID for this initiate call.
`data.request_id`	String	CKYC request ID. Use this in the OTP submit/resend endpoint.
`data.status`	String	Current workflow status.
`data.ckyc_download_data`	Object	Present only if CKYC returns an already completed download payload.
`status_code`	Integer	HTTP status code.
`success`	Boolean	Whether the operation succeeded.
`message`	String	Human-readable status.
`message_code`	String	Machine-readable status.

Status Values

Status	Meaning
`otp_sent`	OTP was sent to the registered mobile number. Continue with `request_id` and OTP.
`otp_resent`	OTP was resent. Continue with the latest OTP received by the customer.
`downloaded`	Download data is already available in `ckyc_download_data`.

Example Successful Response

{
  "data": {
    "client_id": "ckyc_realtime_individual_download_NXwKaQ",
    "request_id": "18454383",
    "status": "otp_sent"
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Common Errors

Message Code	Meaning
`auth_factor_mismatch`	The submitted mobile number did not match the CKYC record.
`mobile_not_registered`	The CKYC record does not have the submitted mobile registered.
`auth_factor_not_found`	CKYC could not find the submitted auth factor for the identifier.
`daily_limit_exceeded`	OTP or download limit was reached.
`invalid_ckyc_number`	CKYC number format was rejected.
`invalid_ckyc_reference_id`	CKYC reference ID format was rejected.
`downstream_request_timeout`	CKYC realtime service timed out.

Code Samples

cURL

Python

Next Step

Call POST /api/v1/ckyc/v3/download/individual with the returned request_id and either otp or resend: true.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location 'https://kyc-api.surepass.app/api/v1/ckyc/v3/download/individual/initiate' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "ckyc_identifier": "12345678901234", "mobile_number": "9876543210" }'

{ "data": { "client_id": "ckyc_realtime_individual_download_NXwKaQ", "request_id": "18451234", "status": "otp_sent" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

CKYC Individual Download Initiate

Description#

Authentication#

Request Body#

Example Request#

Response#

Status Values#

Example Successful Response#

Common Errors#

Code Samples#

Next Step#

Request

Responses