CKYC Individual Download

Endpoint Overview

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

Description

Complete an individual CKYC download after OTP initiation. Use this endpoint in one of two modes:

Submit the OTP with request_id and otp.

Request another OTP with request_id and resend: true.

The request_id comes from POST /api/v1/ckyc/v3/download/individual/initiate. Do not use client_id for OTP submission.

When OTP validation succeeds, the response status is downloaded and data.ckyc_download_data contains the CKYC record.

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
`request_id`	String	Yes	CKYC request ID returned by the initiate endpoint. Must contain digits only and must not exceed 8 digits.
`otp`	String	Conditional	6-digit OTP received on the registered mobile number. Required for OTP submission.
`resend`	Boolean	Conditional	Set to `true` to request another OTP.

Provide either otp or resend: true, not both. A request with neither value is rejected.

Example Request: Submit OTP

{
  "request_id": "18454383",
  "otp": "968284"
}

Example Request: Resend OTP

{
  "request_id": "18454383",
  "resend": true
}

Response

Parameter	Type	Description
`data.client_id`	String	SurePass transaction ID for the individual download session.
`data.request_id`	String	CKYC request ID associated with the OTP session.
`data.status`	String	Current status: `otp_resent` or `downloaded`.
`data.ckyc_download_data`	Object	Full CKYC record. Present when `status` is `downloaded`.
`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_resent`	A fresh OTP was sent. Submit the new OTP using the same `request_id`.
`downloaded`	OTP validation succeeded and `ckyc_download_data` is present.

Download Data Structure

ckyc_download_data contains:

Field	Type	Description
`record_count_details`	Object	Download/update counters returned by CKYC.
`personal_identifiable_data.personal_details`	Object	Individual personal, address, contact, declaration, and CKYC identifiers.
`personal_identifiable_data.identity_details.identity`	Array	Identity documents attached to the CKYC record.
`personal_identifiable_data.related_person_details.related_person`	Array	Related person records, if any.
`personal_identifiable_data.image_details.image`	Array	Photograph and document images, if any.

`personal_details`

Fields vary by record. Common fields include:

Field	Description
`constitution_type`	Display label for constitution type. Usually `Individual`.
`account_type`	Display label for account type, for example `Normal`, `Small`, `Simplified`, or `OTP based KYC`.
`prefix`	Name prefix.
`first_name`	First name. Mapped from CKYC `fname`.
`mname`	Middle name when returned.
`last_name`	Last name. Mapped from CKYC `lname`.
`full_name`	Full name. Mapped from CKYC `fullname`.
`father_or_spouse`	`FATHER` or `SPOUSE` when CKYC returns the relationship flag.
`father_fullname`	Father's full name.
`mother_fullname`	Mother's full name.
`gender`	Display label such as `MALE`, `FEMALE`, or `TRANSGENDER`.
`dob`	Date of birth normalized to `YYYY-MM-DD` when parseable.
`pan`	PAN.
`perm_line1`, `perm_line2`, `perm_line3`	Permanent address lines.
`perm_city`, `perm_dist`, `perm_state`, `perm_pin`, `perm_country`	Permanent address components.
`corres_line1`, `corres_line2`, `corres_line3`	Correspondence address lines.
`corres_city`, `corres_dist`, `corres_state`, `corres_pin`, `corres_country`	Correspondence address components.
`perm_corres_sameflag`	Whether correspondence address is same as permanent address, as returned by CKYC.
`perm_poa`	Display label for permanent proof of address.
`corres_poa`	Display label for correspondence proof of address.
`mob_code`	Mobile ISD code.
`mob_num`	Mobile number.
`email`	Email address.
`dec_date`	Declaration date normalized to `YYYY-MM-DD` when parseable.
`dec_place`	Declaration place.
`kyc_date`	KYC date when returned.
`kyc_name`, `kyc_designation`, `kyc_branch`, `kyc_empcode`	KYC officer or branch details when returned.
`num_identity`	Number of identity records.
`num_related`	Number of related person records.
`num_images`	Number of image records.
`ckyc_no`	CKYC number.
`ckyc_reference_id`	CKYC reference ID, usually starting with `IN`.
`doc_sub`	Raw document submission code, for example `01`.
`doc_sub_value`	Display label for `doc_sub`, for example `Certified Copies`.
`resi_status`	Raw residence status code when returned.
`resi_status_value`	Display label for residence status.
`dis_flag`	Disability flag as `0` or `1`. Render as No/Yes if displayed.
`dis_type`	Raw disability type code when returned.
`dis_type_value`	Display label for disability type.

Unknown or less common CKYC fields may also be included with lowercase keys.

`identity_details.identity`

Each identity item is normalized into this shape:

Field	Description
`identity_number`	Identity document number.
`identity_type`	App-facing enum-like value, for example `PAN`, `AADHAAR`, or `PASSPORT`.
`identity_type_code`	Raw CERSAI identity-type code, for example `C` for PAN or `E` for Aadhaar proof.
`identity_type_value`	Human-readable document label. Use this for display.
`id_verification_status`	`YES` when CKYC status code is `01`, otherwise `NO`.

related_person_details.related_person is always an array when present. The response keeps CKYC keys and adds companion display labels for selected coded fields.

Field	Description
`rel_type`	Raw relationship type code.
`rel_type_value`	Display label such as `Guardian of Minor`, `Director`, `Partner`, or `Beneficial Owner`.
`gender`	Raw gender code when returned.
`gender_value`	Display label such as `MALE` or `FEMALE`.
`perm_poi_type`	Raw permanent proof-of-identity/address type code.
`perm_poi_type_value`	Display label for `perm_poi_type`.
`corres_poi_type`	Raw correspondence proof type code.
`corres_poi_type_value`	Display label for `corres_poi_type`.
`resi_status`	Raw residence status code.
`resi_status_value`	Display label for residence status.
`dis_type`	Raw disability type code.
`dis_type_value`	Display label for disability type.

Images

image_details.image is always an array when present.

Field	Description
`image_code`	Display label for the image type, for example `Photograph`, `PAN`, or `NREGA Job Card`.
`image_type`	File type, for example `jpg` or `pdf`.
`image_data`	Base64-encoded image or document data.
`global_flag`	Raw global/local flag when returned.
`global_flag_value`	Display label for `global_flag`.

Example Successful Response

{
  "data": {
    "client_id": "ckyc_realtime_individual_download_NXwKaQ",
    "request_id": "18454383",
    "status": "downloaded",
    "ckyc_download_data": {
      "record_count_details": {
        "download_count": "1",
        "update_count": "0"
      },
      "personal_identifiable_data": {
        "personal_details": {
          "constitution_type": "Individual",
          "account_type": "Normal",
          "first_name": "Aarav",
          "last_name": "Mehta",
          "full_name": "Aarav Mehta",
          "father_or_spouse": "FATHER",
          "father_fullname": "Rajesh Mehta",
          "gender": "MALE",
          "dob": "1992-07-14",
          "pan": "ABCDE1234F",
          "perm_line1": "221B Demo Street",
          "perm_city": "Mumbai",
          "perm_state": "Maharashtra",
          "perm_pin": "400001",
          "perm_country": "India",
          "corres_line1": "221B Demo Street",
          "corres_city": "Mumbai",
          "corres_state": "Maharashtra",
          "corres_pin": "400001",
          "corres_country": "India",
          "perm_poa": "Proof of Possession of Aadhaar",
          "corres_poa": "Proof of Possession of Aadhaar",
          "mob_code": "91",
          "mob_num": "9876543210",
          "email": "aarav.mehta@example.com",
          "dec_date": "2024-07-14",
          "dec_place": "Mumbai",
          "num_identity": 1,
          "num_related": 0,
          "num_images": 1,
          "ckyc_no": "12345678901234",
          "ckyc_reference_id": "INMOCK12345678",
          "doc_sub": "01",
          "doc_sub_value": "Certified Copies"
        },
        "identity_details": {
          "identity": [
            {
              "identity_number": "ABCDE1234F",
              "identity_type": "PAN",
              "identity_type_code": "C",
              "identity_type_value": "PAN",
              "id_verification_status": "YES"
            }
          ]
        },
        "related_person_details": {
          "related_person": []
        },
        "image_details": {
          "image": [
            {
              "image_code": "Photograph",
              "image_type": "jpg",
              "image_data": "BASE64_IMAGE_DATA"
            }
          ]
        }
      }
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Example OTP Resend Response

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

Common Errors

Message Code	Meaning
`bad_request`	Request supplied both `otp` and `resend`, or supplied neither.
`invalid_otp`	OTP was incorrect.
`otp_attempts_exhausted`	OTP validation attempts were exhausted. Restart the flow from initiate.
`otp_expired`	OTP expired. Request resend or restart based on the returned message.
`otp_resend_throttled`	Resend was requested before the allowed interval.
`otp_resend_exhausted`	Resend attempts were exhausted.
`daily_limit_exceeded`	CERSAI daily limit was reached.
`downstream_request_timeout`	CKYC realtime service timed out.

Code Samples

cURL - Submit OTP

cURL - Resend OTP

Python

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' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "request_id": "18454383", "otp": "968284" }'

{ "data": { "client_id": "ckyc_realtime_individual_download_NXwKaQ", "request_id": "18454383", "status": "downloaded", "ckyc_download_data": { "record_count_details": { "download_count": "1", "update_count": "0" }, "personal_identifiable_data": { "personal_details": { "constitution_type": "Individual", "account_type": "Normal", "first_name": "Aarav", "last_name": "Mehta", "full_name": "Aarav Mehta", "father_or_spouse": "FATHER", "father_fullname": "Rajesh Mehta", "gender": "MALE", "dob": "1992-07-14", "pan": "ABCDE1234F", "perm_line1": "221B Demo Street", "perm_city": "Mumbai", "perm_state": "Maharashtra", "perm_pin": "400001", "perm_country": "India", "corres_line1": "221B Demo Street", "corres_city": "Mumbai", "corres_state": "Maharashtra", "corres_pin": "400001", "corres_country": "India", "perm_poa": "Proof of Possession of Aadhaar", "corres_poa": "Proof of Possession of Aadhaar", "mob_code": "91", "mob_num": "9876543210", "email": "aarav.mehta@example.com", "dec_date": "2024-07-14", "dec_place": "Mumbai", "num_identity": 1, "num_related": 0, "num_images": 1, "ckyc_no": "12345678901234", "ckyc_reference_id": "INMOCK12345678", "doc_sub": "01", "doc_sub_value": "Certified Copies" }, "identity_details": { "identity": [ { "identity_number": "ABCDE1234F", "identity_type": "PAN", "identity_type_code": "C", "identity_type_value": "PAN", "id_verification_status": "YES" } ] }, "related_person_details": { "related_person": [] }, "image_details": { "image": [ { "image_code": "Photograph", "image_type": "jpg", "image_data": "BASE64_IMAGE_DATA" } ] } } } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Authentication#

Request Body#

Example Request: Submit OTP#

Example Request: Resend OTP#

Response#

Status Values#

Download Data Structure#

personal_details#

identity_details.identity#

Related Persons#

Images#

Example Successful Response#

Example OTP Resend Response#

Common Errors#

Code Samples#

Request

Responses