CKYC Download

POST /api/v1/ckyc/download

Description

This API allows you to download comprehensive CKYC (Central Know Your Customer) data for a specific client. After successfully searching for a client using the CKYC Search endpoint, you can use this API to retrieve detailed personal information, identity documents, and associated images. The API returns structured data including personal details, address information, contact details, and document images in base64 format.

Use Cases

- Accelerate customer onboarding for banking and financial products - Verify customer identity for loan processing and account opening - Automate KYC compliance checks for regulatory requirements - Streamline policy issuance with pre-verified customer data - Reduce manual verification steps in claims processing - Ensure accurate customer information for underwriting - Enable instant account opening with verified KYC data - Implement paperless onboarding for digital financial services - Reduce customer drop-offs with simplified verification processes

Technical Implementation

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

1. Obtain API Credentials: Register with Surepass to receive your API key.
2. Generate JWT Token: Use your API key to generate a JWT token.
3. 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 Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT format)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Client ID received from the CKYC Search endpoint
dob	String	Yes	Date of birth in "YYYY-MM-DD" format

Example Request

{
    "client_id": "ckyc_PZeXxduarNWmcWLCLmgs",
    "dob": "2001-07-25"
}

### Response Parameters

Parameter	Type	Description
data	Object	Contains all the CKYC download data
data.client_id	String	Unique client ID for this download request
data.ckyc_search_client_id	String	Client ID from the CKYC search request
data.id_number	String	ID number of the client
data.dob	String	Date of birth in "YYYY-MM-DD" format
data.ckyc_download_data	Object	Contains personal details and image information
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 indicating the response status

Personal Details Object

Parameter	Type	Description
constituiton_type	String	Entity Constitution Type (e.g., "Individual")
account_type	String	Account Type (e.g., "Normal")
ckyc_no	String	CKYC Number
prefix	String	Name prefix (e.g., "MR")
first_name	String	Candidate's first name
last_name	String	Candidate's last name
full_name	String	Candidate's full name
father_or_spouse	String	Indicates if father or spouse details are provided
father_prefix	String	Father's name prefix
father_fname	String	Father's first name
father_lname	String	Father's last name
father_fullname	String	Father's full name
mother_prefix	String	Mother's name prefix
mother_fname	String	Mother's first name
mother_lname	String	Mother's last name
mother_fullname	String	Mother's full name
gender	String	Candidate's gender
dob	String	Date of birth in "YYYY-MM-DD" format
pan	String	PAN card number
perm_line1	String	Permanent address line 1
perm_line2	String	Permanent address line 2
perm_line3	String	Permanent address line 3
perm_city	String	Permanent address city
perm_dist	String	Permanent address district
perm_state	String	Permanent address state code
perm_country	String	Permanent address country code
perm_pin	String	Permanent address PIN code
perm_poa	String	Permanent address proof type
perm_corres_sameflag	String	Flag indicating if correspondence address is same as permanent ("Y"/"N")
corres_line1	String	Correspondence address line 1
corres_line2	String	Correspondence address line 2
corres_line3	String	Correspondence address line 3
corres_city	String	Correspondence address city
corres_dist	String	Correspondence address district
corres_state	String	Correspondence address state code
corres_country	String	Correspondence address country code
corres_pin	String	Correspondence address PIN code
resi_std_code	String	Residence STD code
resi_tel_num	String	Residence telephone number
off_std_code	String	Office STD code
off_tel_num	String	Office telephone number
mob_num	String	Mobile number
email	String	Email address
dec_date	String	Declaration date
dec_place	String	Declaration place
kyc_date	String	KYC verification date (may be masked)
doc_sub	String	Type of documents submitted
kyc_name	String	KYC verifier name (may be masked)
kyc_designation	String	KYC verifier designation (may be masked)
kyc_branch	String	KYC verifier branch (may be masked)
kyc_empcode	String	KYC verifier employee code (may be masked)
num_identity	String	Number of identity documents
num_related	String	Number of related persons
num_images	String	Number of images provided

Image Details Object

Parameter	Type	Description
sequence_no	String	Sequence number of the image
image_type	String	Format of the image (e.g., "JPG")
image_code	String	Type of document the image represents
global_flag	String	Flag indicating global aspect
branch_code	String	Branch code where document was verified
image_data	String	Base64 encoded image data

Example Successful Response

{
    "data": {
        "client_id": "ckyc_download_rtdNQdlKgZcaABfQikzH",
        "ckyc_search_client_id": "ckyc_PZeXxduarNWmcWLCLmgs",
        "id_number": "123456789",
        "dob": "2001-07-25",
        "ckyc_download_data": {
            "personal_identifiable_data": {
                "personal_details": {
                    "constituiton_type": "Individual",
                    "account_type": "Normal",
                    "ckyc_no": "50013085428728",
                    "prefix": "MR",
                    "first_name": "DUMMY",
                    "last_name": "NAME",
                    "full_name": "MR DUMMY  NAME",
                    "father_or_spouse": "FATHER",
                    "father_prefix": "MR",
                    "father_fname": "FATHER",
                    "father_lname": "NAME",
                    "father_fullname": "MR FATHER  NAME",
                    "mother_prefix": "MRS",
                    "mother_fname": "MOTHER",
                    "mother_lname": "NAME",
                    "mother_fullname": "MRS MOHTER  NAME",
                    "gender": "MALE",
                    "dob": "1998-09-03",
                    "pan": "ABCPK1128D",
                    "perm_line1": "DOODWA",
                    "perm_line2": "SIKAR DOODAWA",
                    "perm_line3": "RAJASTHAN",
                    "perm_city": "SIKAR",
                    "perm_dist": "SIKAR",
                    "perm_state": "RJ",
                    "perm_country": "IN",
                    "perm_pin": "332316",
                    "perm_poa": "Proof of Possession of Aadhaar",
                    "perm_corres_sameflag": "N",
                    "corres_line1": "DOODWA",
                    "corres_line2": "SIKAR DOODAWA",
                    "corres_line3": "RAJASTHAN",
                    "corres_city": "SIKAR",
                    "corres_dist": "SIKAR",
                    "corres_state": "RJ",
                    "corres_country": "IN",
                    "corres_pin": "332316",
                    "resi_std_code": "0",
                    "resi_tel_num": "0",
                    "off_std_code": "0",
                    "off_tel_num": "0",
                    "mob_num": "9123456780",
                    "email": "TEST@GMAIL.COM",
                    "dec_date": "2020-04-09",
                    "dec_place": "THANE",
                    "kyc_date": "********",
                    "doc_sub": "Certified Copies",
                    "kyc_name": "********",
                    "kyc_designation": "********",
                    "kyc_branch": "********",
                    "kyc_empcode": "********",
                    "num_identity": "0",
                    "num_related": "0",
                    "num_images": "4"
                },
                "image_details": {
                    "image": [
                        {
                            "sequence_no": "1",
                            "image_type": "JPG",
                            "image_code": "Proof of Possession of Aadhaar",
                            "global_flag": "1",
                            "branch_code": "HOBRANCH",
                            "image_data": ""
                        },
                        {
                            "sequence_no": "2",
                            "image_type": "JPG",
                            "image_code": "PAN",
                            "global_flag": "1",
                            "branch_code": "HOBRANCH",
                            "image_data": ""
                        },
                        {
                            "sequence_no": "3",
                            "image_type": "JPG",
                            "image_code": "Photograph",
                            "global_flag": "1",
                            "branch_code": "HOBRANCH",
                            "image_data": ""
                        },
                        {
                            "sequence_no": "4",
                            "image_type": "JPG",
                            "image_code": "Signature",
                            "global_flag": "1",
                            "branch_code": "HOBRANCH",
                            "image_data": ""
                        }
                    ]
                },
                "identity_details": {
                    "identity": [
                        {
                            "sequence_no": "1",
                            "identity_type": "Proof of Possession of Aadhaar",
                            "identity_number": "XXXXXXXX2905",
                            "id_verification_status": "NO"
                        },
                        {
                            "sequence_no": "2",
                            "identity_type": "E-KYC Authentication",
                            "identity_number": "XXXXXXXX2905",
                            "id_verification_status": "NO"
                        }
                    ]
                }
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

```json { "status_code": 400, "success": false, "message": "Invalid client_id provided", "message_code": "invalid_client_id" } ``` This error occurs when the client_id provided doesn't exist or is invalid. ```json { "status_code": 400, "success": false, "message": "Invalid date format. Please use YYYY-MM-DD format", "message_code": "invalid_date_format" } ``` This error occurs when the date of birth is not provided in the correct format. ```json { "status_code": 401, "success": false, "message": "Authentication failed. Invalid token provided", "message_code": "authentication_failed" } ``` This error occurs when the JWT token is invalid, expired, or not provided.

Integration Best Practices

- Store the retrieved KYC data securely with appropriate encryption - Implement proper access controls for staff accessing customer KYC information - Do not store sensitive document images longer than necessary for your business purpose - Implement data masking for sensitive fields when displaying information to users - Implement this API as part of a background process rather than making users wait - Display a progress indicator when fetching CKYC data - Provide clear error messages to users when verification fails - Allow users to review and confirm the fetched information before proceeding

Code Samples

```bash