CKYC Individual Search

Endpoint Overview

POST /api/v1/ckyc/v3/search/individual

Description

Search the CKYC registry for individual records by an identifier type and value. The response returns a SurePass client_id, a records array, and record_count.

Use this endpoint before individual download. After you find the correct record, pass that record's ckyc_identifier to POST /api/v1/ckyc/v3/download/individual/initiate.

The API normalizes id_type, validates the identifier, and returns records in an array-based shape.

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
`id_type`	String	Yes	Identifier type. The API normalizes case, spaces, and hyphens to lowercase snake_case.
`id_number`	String	Yes	Identifier value to search in CKYC.

Supported `id_type` Values

`id_type` value	Description	Format / Example
`passport`	Passport	Passport number
`voter_id`	Voter ID / EPIC	Alphanumeric voter ID
`pan`	PAN	`ABCDE1234F`
`driving_license`	Driving licence	State-specific licence number
`aadhaar_proof`	Proof of Possession of Aadhaar	Aadhaar proof / composite value
`nrega_job_card`	NREGA job card	State-specific job card number
`npr_letter`	NPR letter	NPR letter number
`ckyc_number`	CKYC number	14-digit number
`ckyc_reference_id`	CKYC reference ID	Usually starts with `IN`
`mobile_number`	Registered mobile number	10 digits

PAN, Pan, pan, Driving License, and driving-license style inputs are normalized before validation. Prefer sending the canonical lowercase value shown above.

For aadhaar_proofid_type, Format

[Last 4 digits of Aadhaar]|[Name]|[DOB in DD-MM-YYYY]|[Gender]

Example Request

{
  "id_type": "pan",
  "id_number": "ABCDE1234F"
}

{
  "id_type": "aadhaar_proof",
  "id_number": "8628|YASHVARDHAN|12-09-2003|M"
}

Response

Parameter	Type	Description
`data.client_id`	String	SurePass transaction ID for this search.
`data.records`	Array	Matching CKYC records. No-match cases normally return an error.
`data.record_count`	Integer	Number of records returned.
`status_code`	Integer	HTTP status code.
`success`	Boolean	Whether the operation succeeded.
`message`	String	Human-readable status.
`message_code`	String	Machine-readable status.

Common Record Fields

Record fields depend on the data CERSAI returns. Common fields are:

Field	Type	Description
`ckyc_identifier`	String	Canonical value to use in download calls. This resolves to `ckyc_reference_id` when available, otherwise `ckyc_no`.
`ckyc_no`	String	CKYC number. CERSAI may mask this when the search is not a CKYC-number search.
`ckyc_reference_id`	String	CKYC reference ID, usually starting with `IN` for individuals. Prefer this for download when present.
`name`	String	Customer name as returned in search.
`fathers_name`	String	Father's name.
`constitution_type`	String	Usually `Individual` for individual records when returned.
`age`	String	Age as a string, for example `"23"` rather than `23`.
`mob_code`	Integer or null	ISD calling-code prefix, for example `91`.
`mob_num`	String	Registered mobile number when returned.
`image_type`	String	Type of the search photo, for example `jpg`.
`photo`	String	Base64-encoded photograph when returned.
`kyc_date`	String	KYC date normalized to `YYYY-MM-DD` when parseable.
`updated_date`	String	Last update date normalized to `YYYY-MM-DD` when parseable.
`id_list`	Array	Identity documents attached to the record. See below.
`remarks`	String	Registry remarks when returned.

The `id_list` Field

id_list is an array of identity documents attached to the matched record.

Field	Type	Description
`type`	String	App-facing enum-like identity type, for example `PAN`, `PASSPORT`, `AADHAAR`, `NREGA_JOB_CARD`, or `EKYC_AUTHENTICATION`.
`type_code`	String	Raw CERSAI identity-type code, for example `C` for PAN or `E` for Proof of Possession of Aadhaar.
`type_value`	String	Human-readable identity label. Use this for display.
`status`	String	Raw verification status code: `1`/`01`, `2`/`02`, `3`/`03`, or `4`/`04`.
`status_value`	String	Human-readable status: `Not Verified`, `Verification in Progress`, `Verified`, or `Rejected`.

Example:

"id_list": [
  {
    "type": "PAN",
    "type_code": "C",
    "type_value": "PAN",
    "status": "03",
    "status_value": "Verified"
  }
]

Example Successful Response

{
  "data": {
    "client_id": "ckyc_realtime_search_DsZPqKmJvQXf",
    "records": [
      {
        "ckyc_identifier": "INRMFE49270123",
        "ckyc_no": "12345678901234",
        "ckyc_reference_id": "INRMFE49270123",
        "name": "MR VARUN GUPTA",
        "fathers_name": "MR AKSHAY GUPTA",
        "constitution_type": "Individual",
        "age": "23",
        "mob_code": 91,
        "mob_num": "9876543210",
        "image_type": "jpg",
        "photo": "BASE64_IMAGE_DATA",
        "kyc_date": "2021-02-18",
        "updated_date": "2024-03-06",
        "id_list": [
          {
            "type": "PAN",
            "type_code": "C",
            "type_value": "PAN",
            "status": "03",
            "status_value": "Verified"
          }
        ],
        "remarks": ""
      }
    ],
    "record_count": 1
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Code Samples

cURL

Python

Next Step

Use the chosen record's ckyc_identifier with POST /api/v1/ckyc/v3/download/individual/initiate. Send ckyc_identifier exactly as returned in the search response; you do not need to choose between ckyc_no and ckyc_reference_id.

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/search/individual' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "id_type": "pan", "id_number": "ABCDE1234F" }'

{ "data": { "client_id": "ckyc_realtime_search_DsZPqKmJvQXf", "records": [ { "ckyc_identifier": "INRMFE49270123", "ckyc_no": "12345678901234", "ckyc_reference_id": "INRMFE49270123", "name": "MR VARUN GUPTA", "fathers_name": "MR AKSHAY GUPTA", "constitution_type": "Individual", "age": "23", "mob_code": 91, "mob_num": "9876543210", "image_type": "jpg", "photo": "BASE64_IMAGE_DATA", "kyc_date": "2021-02-18", "updated_date": "2024-03-06", "id_list": [ { "type": "PAN", "type_code": "C", "type_value": "PAN", "status": "03", "status_value": "Verified" } ], "remarks": "" } ], "record_count": 1 }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Authentication#

Request Body#

Supported id_type Values#

Example Request#

Response#

Common Record Fields#

The id_list Field#

Example Successful Response#

Code Samples#

Next Step#

Request

Responses