CKYC Download API

Endpoint Overview

POST /api/v1/ckyc-v2/download

Description

The CKYC Download API enables businesses to retrieve comprehensive Central KYC (CKYC) data for verified clients after successful OTP authentication. This endpoint provides access to detailed personal information, complete address records, contact details, identity documents, and associated images in Base64 format. The API serves as the final step in the secure CKYC verification workflow, delivering complete customer profiles that can be used for comprehensive compliance and risk assessment.

This powerful endpoint returns structured data including personal identifiable information, family details, address verification data, contact information, identity document details, and high-quality document images. The response includes both photograph and document scans, enabling visual verification alongside data validation. The API is designed to provide complete customer profiles while maintaining the highest security standards through OTP-based authentication.

The downloaded data includes extensive personal details such as full names, father's and mother's information, date of birth, gender, contact details, permanent and correspondence addresses, PAN information, and identity document verification status with associated images.

Key Benefits

Complete Customer Profile: Access comprehensive personal, contact, and address information in a single API call

Document Image Access: Retrieve high-quality Base64-encoded photographs and identity document scans

Multi-Format Support: Handle both JPEG photographs and PDF documents seamlessly

Secure OTP Authentication: Ensure data access only after successful two-factor authentication

Use Cases

Banking & Financial Services

Fintech & Digital Platforms

Enterprise & Compliance

Account Opening: Complete customer onboarding with verified personal and address information

Loan Processing: Access comprehensive borrower profiles for credit assessment and approval

Credit Card Applications: Verify applicant details with complete identity documentation

Investment Services: Obtain detailed customer profiles for trading account setup and compliance

Insurance Underwriting: Access complete customer data for policy issuance and risk assessment

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
client_id	String	Yes	Client ID obtained from the OTP generation process
otp	String	Yes	6-digit OTP received via SMS for verification

Example Request

{
  "client_id": "ckyc_download_dBmyAFohBx",
  "otp": "968284"
}

Process Response

Response Structure Overview

{
  "data": {
    "client_id": "string",
    "ckyc_search_client_id": "string", 
    "id_number": "string",
    "dob": "string|null",
    "ckyc_download_data": {
      "personal_identifiable_data": {
        "personal_details": { /* Personal information object */ },
        "identity_details": { /* Identity verification object */ },
        "related_person_details": "string",
        "image_details": { /* Images and documents object */ }
      }
    }
  },
  "status_code": 200,
  "success": true,
  "message": "string",
  "message_code": "string"
}

Response Parameters

Root Level Parameters

Parameter	Type	Description
`data`	Object	Main response data container
`status_code`	Integer	HTTP status code (200 for success)
`success`	Boolean	Operation success indicator
`message`	String	Human-readable response message
`message_code`	String	Machine-readable message identifier

Data Object Parameters

Parameter	Type	Description
`client_id`	String	Download-specific client identifier
`ckyc_search_client_id`	String	Original search client identifier
`id_number`	String	Identity document number used for search
`dob`	String	Date of birth (nullable)
`ckyc_download_data`	Object	Complete CKYC data container

Personal Details (Key Fields)

Parameter	Type	Description
`first_name`	String	Customer's first name
`last_name`	String	Customer's last name
`full_name`	String	Complete formatted name with prefix
`dob`	String	Date of birth (YYYY-MM-DD format)
`gender`	String	Gender (MALE/FEMALE)
`pan`	String	PAN card number
`mob_num`	String	Mobile number
`email`	String	Email address
`ckyc_no`	String	CKYC reference number
`father_fullname`	String	Father's complete name
`mother_fullname`	String	Mother's complete name

Address Information

Parameter	Type	Description
`perm_line1`	String	Permanent address line 1
`perm_line2`	String	Permanent address line 2
`perm_city`	String	Permanent address city
`perm_state`	String	Permanent address state code
`perm_pin`	Integer	Permanent address PIN code
`perm_country`	String	Permanent address country code
`corres_line1`	String	Correspondence address line 1
`corres_city`	String	Correspondence address city
`corres_state`	String	Correspondence address state
`corres_pin`	Integer	Correspondence address PIN code

Identity Details Structure

Parameter	Type	Description
`identity`	Array	Array of identity document objects
`sequence_no`	Integer	Document sequence number
`identity_number`	String	Masked identity document number
`identity_type`	String	Type of identity document
`id_verification_status`	String	Verification status (YES/NO)

Image Details Structure

Parameter	Type	Description
`image`	Array	Array of image objects
`sequence_no`	Integer	Image sequence number
`image_code`	String	Image type (Photograph/Document name)
`image_type`	String	File format (jpeg/pdf)
`image_data`	String	Base64 encoded image data
`branch_code`	String	Branch identifier

Example Successful Response

{
    "data": {
        "client_id": "ckyc_download_nNfWARdhysddWFiXddXF",
        "ckyc_search_client_id": "ckyc_coWcmlbmZtyeWjyeoylj",
        "id_number": "INRMFE49270123",
        "dob": null,
        "ckyc_download_data": {
            "personal_identifiable_data": {
                "personal_details": {
                    "father_fname": "AMAN SINGH",
                    "resi_status": "",
                    "perm_line1": "HOUSE NO 1234 3RD FLOOR",
                    "perm_line2": "GALI NO 11 NEW DELHI",
                    "kyc_designation": "********",
                    "prefix": "MR",
                    "resi_std_code": "",
                    "corres_pin": 111111,
                    "off_std_code": "",
                    "father_prefix": "MR",
                    "corres_line2": "GALI NO 11 NEW DELHI",
                    "mob_code": 91,
                    "corres_line1": "HOUSE NO 1234 3RD FLOOR",
                    "perm_state": "DL",
                    "corres_line3": "",
                    "corres_state": "DL",
                    "kyc_name": "********",
                    "off_tel_num": "",
                    "pan": "EIJPA8709P",
                    "perm_line3": "",
                    "dec_place": "NEW DELHI",
                    "mother_prefix": "MRS",
                    "perm_dist": "South East Delhi",
                    "maiden_mname": "",
                    "father_fullname": "MR AMAN SINGH",
                    "kyc_empcode": "********",
                    "resi_tel_num": "",
                    "num_images": 2,
                    "kyc_date": "********",
                    "corres_city": "NEW DELHI",
                    "dob": "2000-07-11",
                    "perm_country": "IN",
                    "num_identity": 1,
                    "maiden_lname": "",
                    "org_code": "********",
                    "mother_fullname": "MRS POOJA DEVI",
                    "doc_sub": "1",
                    "gender": "MALE",
                    "mob_num": "9650531384",
                    "maiden_prefix": "",
                    "maiden_fullname": "",
                    "perm_pin": 110019,
                    "mname": "JAI",
                    "kyc_branch": "********",
                    "corres_country": "IN",
                    "ckyc_no": "90055174951234",
                    "org_name": "********",
                    "maiden_fname": "",
                    "mother_fname": "POOJA DEVI",
                    "email": "JAINTHAKHSHAY1234@GMAIL.COM",
                    "perm_corres_sameflag": "Y",
                    "father_mname": "",
                    "corres_poa": 1,
                    "perm_city": "NEW DELHI",
                    "corres_dist": "South East Delhi",
                    "dec_date": "2024-11-23",
                    "ckyc_reference_id": "INRMFE41234632",
                    "mother_mname": "",
                    "father_lname": "SINGH",
                    "num_related": 0,
                    "mother_lname": "DEVI",
                    "perm_poa": "Proof of Possession of Aadhaar",
                    "remarks": "",
                    "constituiton_type": "Individual",
                    "account_type": "Normal",
                    "first_name": "AKHSHAY",
                    "last_name": "LASTNAMEUNKNOWN",
                    "full_name": "MR AKSHAY JAI LASTNAMEUNKNOWN",
                    "father_or_spouse": "FATHER"
                },
                "identity_details": {
                    "identity": [
                        {
                            "sequence_no": 1,
                            "identity_number": "XXXXXXXX1234",
                            "identity_type": "Proof of Possession of Aadhaar",
                            "id_verification_status": "NO"
                        }
                    ]
                },
                "related_person_details": "",
                "image_details": {
                    "image": [
                        {
                            "branch_code": "BR001",
                            "image_data": "/9j/4AAQSkZJRgABAQAASABIAAD/4QBMRXhpZgAATU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAB4KADAAQAAAABAAACgAAAAAD/wAARCAKAAeADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKB",
                            "image_code": "Photograph",
                            "global_flag": "",
                            "sequence_no": 1,
                            "image_type": "jpeg"
                        },
                        {
                            "branch_code": "BR001",
                            "image_data": "JVBERi0xLjcKJeLjz9MKNSAwIG9iago8PC9GaWx0ZXIvRmxhdGVEZWNvZGUvTGVuZ3RoIDExMjk+PnN0cmVhbQp4nIWYS3PbNhRG9/wVWLILw3gDXCZWHm7aJI3VzGTJWFTMWI+GotrJvy8uCJAUGV2OFppvxINzRYC4kH5kjGrGC0Om7823TBpijaRaEi0kkY4qS5oq22Z/ZT+yl+vs9jUnvCDrbSZkQT1jraGFIut",
                            "image_code": "Proof of Possession of Aadhaar",
                            "global_flag": "",
                            "sequence_no": 2,
                            "image_type": "pdf"
                        }
                    ]
                }
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid OTP

Client ID Not Found

OTP Expired

Invalid Input

Server Error

{
  "data": null,
  "status_code": 400,
  "success": false,
  "message": "Invalid OTP provided",
  "message_code": "invalid_otp"
}

Returned when the provided OTP is incorrect or has expired.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement token rotation policies

Handle Base64 image data securely without unnecessary persistent storage

Implement proper data encryption for downloaded sensitive information

Log all download activities for audit and compliance purposes

Validate OTP format on client side before API calls

Use secure transmission protocols (HTTPS) for all communications

Implement proper session management for client IDs

User Experience Guidelines

Provide clear feedback during the download process with loading indicators

Handle large response payloads gracefully with appropriate timeout settings

Display image data properly with fallback mechanisms for loading failures

Implement proper error handling with user-friendly messages for OTP-related errors

Show download progress for large data transfers

Cache downloaded data appropriately while respecting data sensitivity

Provide clear visual distinction between photographs and document images

Code Samples

cURL

Python

Node.js

Related APIs

CKYC Search API - Initial search endpoint to find CKYC records using document numbers before download

CKYC OTP Generation API - Generates OTP required for secure download authentication

CKYC OTP Verification API - Alternative verification method for accessing CKYC data

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

Compliance and Legal Considerations

This API provides access to highly sensitive personal and financial information and must comply with:

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

Prevention of Money Laundering Act (PMLA) requirements for customer data processing

Information Technology Act provisions for secure data storage and transmission

Aadhaar Act regulations when processing Aadhaar-related identity information and documents

Data Protection Laws requiring explicit consent for personal data processing and storage

Implement proper data encryption, secure storage, audit trails, and data retention policies

Ensure compliance with data localization requirements and cross-border data transfer restrictions

Maintain detailed logs of all data access and usage for regulatory audits

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

CKYC Download

CKYC Download API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Structure Overview#

Response Parameters#

Root Level Parameters#

Data Object Parameters#

Personal Details (Key Fields)#

Address Information#

Identity Details Structure#

Image Details Structure#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses