CKYC Search

Endpoint Overview

POST /api/v1/ckyc/search

Description

The CKYC Search API allows you to search for a customer's record in the Central KYC (Know Your Customer) Registry using various identification documents. This API helps financial institutions and regulated entities verify if a customer already has a CKYC record, retrieve their CKYC number, and access associated KYC information, eliminating the need for redundant KYC processes.

Key Benefits

Quickly verify if a customer already has a CKYC record using multiple ID types (PAN, Aadhaar, Voter ID, etc.)

Retrieve the customer's CKYC ID and associated KYC information in a single API call

Reduce customer onboarding time by leveraging existing KYC data

Ensure compliance with regulatory requirements for customer verification

Use Cases

Banking

Insurance

Fintech

Verify new customer's existing CKYC records during account opening

Retrieve customer KYC information for loan application processing

Validate customer identity during high-value transactions

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 for authentication (JWT format)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	The identification number to search with
document_type	Enum	Yes	Type of the identification document

document_type Options

Value	Description	Format Example
PAN	Candidate's PAN Number	ABCDE1234F
VOTER	Valid Voter ID Card Number	ABC1234567
AADHAAR	Combination of Aadhaar details (format below)	1234\|MINAL TOMAR\|01-12-1997\|F
DRIVING_LICENSE	Valid Driving License Number	RJ1320120123456
CKYC_NUMBER	Valid 14 Digit CKYC ID Number	12345678912345

AADHAAR Format Details

When using AADHAAR as document_type, the id_number should be a pipe-separated string with:

Last 4 digits of Aadhaar

Full name as on Aadhaar

Date of birth in DD-MM-YYYY format

Gender (M: Male, F: Female, T: Transgender)

Example Request

{
    "id_number": "ABCDE1234F",
    "document_type": "PAN"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the search results
data.client_id	String	Unique client identifier for the request
data.id_number	String	The identification number used for search
data.ckyc_search_data	Object	CKYC data retrieved from the registry
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the response message

ckyc_search_data Object

Parameter	Type	Description
ckyc_id	String	CKYC ID Number of the customer
full_name	String	Full name of the customer
age	String	Age of the customer
fathers_name	String	Father's name of the customer
identity_details	Object	Contains identity document information
kyc_date	String	Date when KYC was completed (YYYY-MM-DD)
updated_date	String	Date when KYC was last updated (YYYY-MM-DD)

identity_details Object

Parameter	Type	Description
identity	Array	List of identity documents
identity[].status	String	Document status code
identity[].type	String	Document type

Document Status Codes

Code	Description
3	ID Is Available
4	ID Not Provided

Example Successful Response

{
    "data": {
        "client_id": "ckyc_gwtSCuwoKfucbNnETsDa",
        "id_number": "XXXXXXXXX",
        "ckyc_search_data": {
            "ckyc_id": "123456789",
            "full_name": "Mr DUMMAY NAME",
            "age": "24",
            "fathers_name": "Mr FATHER NAME",
            "identity_details": {
                "identity": [
                    {
                        "status": "3",
                        "type": "PAN"
                    }
                ]
            },
            "kyc_date": "2020-04-11",
            "updated_date": "2020-04-11"
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Document Type

Record Not Found

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid document type provided",
    "message_code": "invalid_document_type"
}

The document_type value is not one of the supported types.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications

Rotate JWT tokens periodically and implement token expiration

Implement IP whitelisting for production environments if supported

User Experience Guidelines

Implement proper validation for ID formats before making API calls

Display clear error messages to users when verification fails

Implement retry mechanisms with appropriate backoff strategies

Cache successful responses where appropriate to improve performance

Provide clear instructions when asking users for Aadhaar details in the required format

Code Samples

cURL

Python

Node.js

Related APIs

CKYC Upload API - Upload KYC documents to create a new CKYC record

CKYC Update API - Update an existing CKYC record with new information

CKYC Download API - Download the complete CKYC record including document images

Compliance and Legal Considerations

Ensure you have proper consent from customers before accessing their CKYC data

The use of this API must comply with RBI guidelines and CKYC Registry regulations

Maintain proper audit logs of all CKYC searches for regulatory compliance

Handle all personal data in accordance with applicable privacy laws and regulations

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ckyc/search' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "ABCDE1234F", "document_type": "PAN" }'

{ "data": { "client_id": "ckyc_gwtSCuwoKfucbNnETsDa", "id_number": "XXXXXXXXX", "ckyc_search_data": { "ckyc_id": "123456789", "full_name": "Mr DUMMAY NAME", "age": "24", "fathers_name": "Mr FATHER NAME", "identity_details": { "identity": [ { "status": "3", "type": "PAN" } ] }, "kyc_date": "2020-04-11", "updated_date": "2020-04-11" } }, "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 Search

CKYC Search#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

document_type Options#

AADHAAR Format Details#

Example Request#

Response Parameters#

ckyc_search_data Object#

identity_details Object#

Document Status Codes#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

CKYC Search

Description

Use Cases

Technical Implementation

Request Headers

Request Body

document_type Options

AADHAAR Format Details

Example Request

Response Parameters

ckyc_search_data Object

identity_details Object

Document Status Codes

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples