CKYC Search API

Endpoint Overview

POST /api/v1/ckyc-v2/search

Description

The CKYC Search API enables businesses to retrieve comprehensive Central KYC (CKYC) information for individuals by searching with their identity document details. This powerful endpoint accepts document types such as PAN cards and returns detailed KYC information including personal details, identity verification status, photographs, and historical KYC data.

The API serves as a central hub for accessing verified customer information from the CKYC registry, providing businesses with authenticated identity data that can be used for customer onboarding, compliance verification, and risk assessment. The response includes a client ID for session management, complete personal information, identity document verification status, and Base64-encoded photographs for visual verification.

This endpoint is essential for financial institutions and businesses that need to verify customer identities against the central KYC database while maintaining regulatory compliance and ensuring data accuracy.

Key Benefits

Instant Identity Verification: Access verified CKYC data in real-time for immediate customer authentication

Comprehensive Data Retrieval: Get complete KYC information including personal details, document status, and photographs

Multi-Document Support: Search using various document types like PAN for flexible verification workflows

Regulatory Compliance: Ensure adherence to KYC norms with centrally verified and up-to-date information

Use Cases

Banking & Finance

Fintech & Digital Services

Enterprise & Compliance

Account Opening: Verify customer identity during new account creation process

Loan Processing: Authenticate loan applicants using existing CKYC records

Credit Card Issuance: Validate applicant information before card approval

Investment Services: Confirm investor identity for trading and investment accounts

Insurance Claims: Verify policyholder identity during claim processing

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	JWT Bearer token for API authentication
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	The identity document number (e.g., PAN number)
document_type	String	Yes	Type of document used for search (e.g., "PAN")

Example Request

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

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for response data
data.client_id	String	Unique client identifier for session management
data.id_number	String	The searched identity document number
data.ckyc_search_data	Object	Complete CKYC information container
data.ckyc_search_data.ckyc_id	String	Masked CKYC identifier
data.ckyc_search_data.full_name	String	Complete name as per CKYC records
data.ckyc_search_data.age	String	Age of the individual
data.ckyc_search_data.fathers_name	String	Father's name as per records
data.ckyc_search_data.identity_details	Object	Identity verification details
data.ckyc_search_data.identity_details.identity	Array	List of identity documents with verification status
data.ckyc_search_data.image	String	Base64-encoded photograph
data.ckyc_search_data.kyc_date	String	Original KYC completion date (YYYY-MM-DD)
data.ckyc_search_data.updated_date	String	Last update date (YYYY-MM-DD)
status_code	Integer	HTTP status code (200 for success)
success	Boolean	Overall operation success indicator
message	String	Human-readable response message (null for success)
message_code	String	Machine-readable message identifier

Example Successful Response

{
  "data": {
    "client_id": "ckyc_eoQNZknuKNdyfpqscxkg",
    "id_number": "CLGPG1234L",
    "ckyc_search_data": {
      "ckyc_id": "XXXXXXXXXX8928",
      "full_name": "MR Varun  Gupta",
      "age": "23",
      "fathers_name": "MR Akshay Gupta",
      "identity_details": {
        "identity": [
          {
            "type": "AADHAAR",
            "status": "3"
          },
          {
            "type": "H",
            "status": "3"
          },
          {
            "type": "PAN",
            "status": "3"
          }
        ]
      },
      "image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAZ/A6cDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/",
      "kyc_date": "2021-02-18",
      "updated_date": "2024-03-06"
    }
  },
  "status_code": 200,
  "success": true,
  "message": null,
  "message_code": "success"
}

Possible Error Responses

Invalid Input

Incorrect ID Number

Server Error

{
  "data": null,
  "status_code": 422,
  "success": false,
  "message": "Verification Failed. No data found for given input.",
  "message_code": "verification_failed"
}

Returned when the Input is incorrect or invalid.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement token rotation policies

Validate document numbers on the client side before API calls

Implement proper error handling for sensitive data operations

Log all API interactions for audit and compliance purposes

Handle Base64 image data securely and avoid unnecessary storage

Use HTTPS only for all API communications

User Experience Guidelines

Provide clear feedback during CKYC search operations

Display loading indicators while processing search requests

Handle image data gracefully with proper fallbacks

Implement proper error messages for invalid document numbers

Cache search results appropriately to improve performance

Provide clear status indicators for identity verification results

Code Samples

cURL

Python

Node.js

Related APIs

CKYC OTP Generation API - Initiates OTP-based verification for secure CKYC document downloads

CKYC OTP Verification API - Validates OTP and enables secure access to CKYC documents

CKYC Document Download API - Downloads complete CKYC documents after successful verification

CKYC Status Check API - Monitors the status of ongoing CKYC verification processes

Compliance and Legal Considerations

This API handles highly sensitive personal and financial information and must comply with:

Reserve Bank of India (RBI) guidelines for CKYC data access and usage

Prevention of Money Laundering Act (PMLA) requirements for customer identification

Information Technology Act provisions for secure data handling and privacy protection

Aadhaar Act regulations when processing Aadhaar-related identity information

Ensure proper data encryption, secure transmission, audit logging, and limited data retention periods

Implement proper consent mechanisms and data usage disclosures as required by law

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

{ "data": { "client_id": "ckyc_eoQNZknuKNdyfpqscxkg", "id_number": "CLGPG1234L", "ckyc_search_data": { "ckyc_id": "XXXXXXXXXX8928", "full_name": "MR Varun Gupta", "age": "23", "fathers_name": "MR Akshay Gupta", "identity_details": { "identity": [ { "type": "AADHAAR", "status": "3" }, { "type": "H", "status": "3" }, { "type": "PAN", "status": "3" } ] }, "image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAZ/A6cDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/", "kyc_date": "2021-02-18", "updated_date": "2024-03-06" } }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

CKYC Search

CKYC Search API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses