CKYC Technology
API Integration
BFSI Tech Teams
|
By HSS Technology Team
|
May 16, 2026
|
15 min read
CKYC API Integration Guide for BFSI Tech Teams: Search, Download and Generate in One Flow
Most CKYC integration documentation tells you what the APIs do. This guide tells you how to integrate them into a production-grade flow - covering request structures, response handling, error management, and the ongoing maintenance obligations your team must plan for from day one.
Integration Overview - Three Patterns, One Flow
A complete CKYC integration is not a single API call. It is a conditional flow of up to four distinct API patterns that must be orchestrated in the correct sequence. Getting the sequence wrong - for example, calling the Generation API without first calling Search - is the most common integration error and results in duplicate record rejections from CERSAI.
All CKYC APIs use REST over HTTPS, accept and return JSON, and require an API key in the request header. The base URL for all endpoints is the same - only the path changes per pattern.
Base URL
https://abcd.sharedocsdms.com/ckyc_api/
4
Distinct API endpoints in a complete CKYC integration
REST
HTTPS JSON API - standard modern stack integration
Async
Generation is asynchronous - requires status polling
1 MB
Maximum total document size per submission
⚠️
Always call Search before Generation
The CKYC Search API must be called for every customer before the Generation API is considered. Submitting a Generation request for a customer who already has a CKYC record will result in a duplicate record rejection. Search is mandatory - it is not an optional optimisation.
Authentication
Every API call requires the api_key header. There are no session tokens or OAuth flows - it is a simple static key passed with each request.
Required Header - All Endpoints
api_key: your_api_key_here
Content-Type: application/json
| Error | HTTP Status | Response Body | Fix |
|---|
| Missing API key | 400 | {"status": false, "error": "API Key required"} | Add api_key header to every request |
| Invalid API key | 400 | {"status": false, "error": "Invalid API Key"} | Verify key value - contact your provider if correct key fails |
Pattern 1 - Search API
The Search API is the entry point for every CKYC flow. It checks whether a CKYC record already exists in CERSAI for the customer and returns their KIN if found. The result of this call determines which path to follow next.
Request Body
[
{
"PAN_Card": "ABCDE1234F",
"Date_Of_Birth": "15-06-1985",
"First_Name": "RAHUL",
"Last_Name": "SHARMA"
}
]
Success - Record Found (200)
{
"status": true,
"ckyc_id": "12345678901234",
"message": "Record found"
}
Success - No Record Found (200)
📌
Decision logic after Search
If status is true and ckyc_id is returned: store the KIN and proceed to Download (Pattern 2A). If status is false with no record found: proceed to Generation (Pattern 2B). Do not treat a false response as an error - it is a valid outcome requiring a different downstream action.
Pattern 2A - Download API
The Download API is a two-step flow. Step 1 initiates the download request and triggers an OTP to the customer's registered mobile. Step 2 validates the OTP and returns the full CKYC record. Both steps are required - you cannot skip the OTP validation.
Step 1 - Download Initiate
Request Body
[
{
"ckyc_id": "12345678901234"
}
]
Success Response (200)
{
"status": true,
"message": "OTP sent to registered mobile",
"request_id": "REQ_abc123xyz"
}
Step 2 - Validate OTP
Request Body
[
{
"request_id": "REQ_abc123xyz",
"otp": "482910"
}
]
Success Response (200)
{
"status": true,
"ckyc_id": "12345678901234",
"First_Name": "RAHUL",
"Last_Name": "SHARMA",
"Date_Of_Birth": "15-06-1985",
"Address": { ... },
"Documents": [ ... ]
}
✅
Log every OTP consent event
Under CKYCRR 2.0, every successful OTP validation must be logged with timestamp, customer identifier, institution code, and purpose. This is a mandatory audit requirement. Store this log in a durable, queryable system - not just an application log file.
Pattern 2B - Generation API
The Generation API accepts the full customer KYC data package and submits it to CERSAI for a new CKYC record creation. This is the most complex API call in the integration - it requires the most fields, carries the highest validation overhead, and is the only asynchronous pattern in the flow.
Request Body Structure (key fields)
[
{
"Type": "Individual",
"Loan_No": "LN20260001",
"Customer_Id": "CUST_001",
"Prefix": "MR",
"First_Name": "RAHUL",
"Last_Name": "SHARMA",
"Date_Of_Birth": "15-06-1985",
"Gender": "M",
"PAN_Card": "ABCDE1234F",
"Marital_Status": "M",
"Father_or_Spouse_Name_Prefix": "MR",
"Father_or_Spouse_First_Name": "SURESH",
"Mother_Name_Prefix": "MRS",
"Mother_First_Name": "SUNITA",
"CP_Line1": "123 MG ROAD",
"CP_City": "PUNE",
"CP_District": "PUNE",
"CP_Pincode": "411001",
"CP_State_Code": "MAHARASHTRA",
"flag_indicating_if_cpi_address_is_same_as_cl_address": "Y",
"CP_Proof_Of_Address_Need_to_be_submitted": "AadharCard",
"Applicant_Declaration_Date": "15-05-2026",
"Applicant_Declaration_Place": "PUNE",
"KYC_Verification_Date": "15-05-2026",
"kyc_verification_name": "VIKRAM PATIL",
"KYC_Verification_Emp_Code": "EMP001",
"KYC_Verification_Emp_Designation": "BRANCH MANAGER",
"KYC_Verification_Emp_Branch": "PUNE",
"Residential_Status": "01",
"Differently_Abled_Flag": "0",
"files": {
"Documents": [
{
"DocumentType": "02",
"DocumentNumber": "02",
"DocumentBase64": "/9j/4AAQSkZJRgABAQ...",
"DocumentExtension": "jpg"
},
{
"DocumentType": "04",
"DocumentNumber": "4321",
"DocumentBase64": "/9j/4AAQSkZJRgABAQ...",
"DocumentExtension": "jpg"
}
]
}
}
]
Success Response (201)
{
"status": true,
"message": "Data inserted successfully",
"transaction_id": "H_ZvU_896"
}
Key Field Requirements Summary
| Field Group | Required Fields | Key Validation Rules |
|---|
| Identity | Type, Prefix, First_Name, DOB, Gender, PAN_Card or Form60, Marital_Status | Names: letters and spaces only, max 50 chars. DOB: DD-MM-YYYY, age 18+ |
| Family | Father/Spouse Name Prefix and First Name, Mother Name Prefix and First Name | Same rules as identity name fields. All four fields required. |
| Address (CP) | CP_Line1, CP_City, CP_District, CP_Pincode, CP_State_Code | Pincode exactly 6 digits. State code from approved CERSAI list. |
| KYC Verifier | Declaration Date and Place, KYC Date, Verifier Name, Emp Code, Designation, Branch | KYC date must be on or after Declaration date. No future dates. |
| Documents | Photo (Type 02) and at least one POA document | Total size under 1MB. JPG, JPEG, PNG, PDF only. Aadhaar: last 4 digits in DocumentNumber. |
Managing CKYC API integration in-house?
CERSAI updates field requirements, state code lists, and validation rules as regulations change. Your integration must change with it. See how HSS's managed service handles API maintenance as an ongoing function - not a one-time project.
Talk to Our Team
Status API - Polling for Generation Results
The Generation API is asynchronous. After a successful 201 response, CERSAI processes the submission and allocates a CKYC number (KIN) - but not immediately. Your system must poll the Status API using the transaction_id until the KIN is assigned or a rejection is returned.
Request Body
[
{
"transaction_id": "H_ZvU_896"
}
]
KIN Assigned (200)
{
"status": true,
"message": "CKYC ID generated",
"ckyc_id": "12345678901234",
"transaction_id": "H_ZvU_896"
}
Rejected - Document (400)
{
"status": false,
"error": "Document Validation Failed",
"reason": "POA IS BLUR...",
"transaction_id": "H_ZvU_896"
}
Rejected - CERSAI (400)
{
"status": false,
"error": "Rejected by CERSAI",
"reason": "Mother Name Prefix...",
"transaction_id": "H_ZvU_896"
}
📌
Recommended polling strategy
Poll the Status API every 30 minutes for the first 4 hours, then hourly for the next 48 hours, then daily until resolved. Most CERSAI responses arrive within 24 hours. Implement a maximum retry limit and an alert for records that remain unresolved after 5 working days. Store all transaction IDs in a persistent queue - never rely on in-memory state for pending generations.
API Flow Diagram
The diagram below maps all four API patterns in sequence, showing the decision points and the correct path through each.
Error Handling Reference
All CKYC API errors return JSON with a status: false flag and a descriptive error field. Build your error handling around the error string value, not just the HTTP status code - two different problems can both return 400.
| HTTP Status | Error Value | Cause | Action |
|---|
| 400 | API Key required | Header missing | Add api_key to all requests |
| 400 | Invalid API Key | Wrong key value | Verify key - contact provider |
| 400 | Data already submitted | Duplicate Customer_Id | Run Search first - Customer_Id must be unique |
| 400 | Only 1 customer record at a time | Array has more than 1 object | Submit exactly 1 record per call |
| 400 | Customer ID is required | Missing Customer_Id field | Add Customer_Id to every Generation request |
| 400 | Photo not found | No Type 02 document in array | Always include a photograph document |
| 400 | Proof of Address and Identity not found | No POA document in array | Include at least one POA document |
| 400 | Invalid Applicant Type | Type field not "Individual" | Set Type to exactly "Individual" |
| 400 | Document Validation Failed | Image quality or POA issues | See rejection reason field for specific cause |
| 400 | Data Validation Failed | Field format or content issue | See rejection reason field for specific cause |
| 400 | Rejected by CERSAI | CKYCRR registry business rule | See rejection reason field for specific cause |
| 400 | Transaction ID Invalid | Wrong or expired transaction_id | Verify transaction_id from original Generation response |
| 404 | Documents not found | Record missing from system | Re-check submission - may need to resubmit |
| 500 | Internal Server Error | Server-side issue | Retry with exponential backoff - log for monitoring |
The Maintenance Reality - What Changes After Go-Live
This is the section most integration guides skip. A successful CKYC API go-live is not the end of the engineering work - it is the beginning of an ongoing maintenance obligation. CERSAI updates its API specifications, field requirements, and validation rules as regulatory changes come into effect. Every change requires a corresponding update to your integration.
API Spec Updates
CERSAI adds new mandatory fields, changes allowed values, and deprecates old patterns with regulatory amendments. Each change requires development, testing in sandbox, and a production deployment - often against a regulatory deadline.
State and Code List Changes
CERSAI's approved state code lists, residential status codes, document type codes, and impairment type codes change as new categories are added. Hard-coded lookup tables break silently and cause rejections until updated.
CKYC Number Format Migration
CERSAI migrated to masked CKYC number format in January 2025. Systems storing legacy unmasked KINs must handle both formats during matching and storage. Any downstream system referencing KINs needs to be tested against the new format.
OTP Consent Flow Updates
CKYCRR 2.0 introduced mandatory OTP consent logging. As the framework matures, additional consent or audit requirements may be added. Your logging schema must be extensible - not a fixed database column.
Sandbox and Certification
CERSAI provides a sandbox environment for testing. Major specification changes require re-certification against the sandbox before production deployment. This adds testing time to every change cycle.
Circular Monitoring
CERSAI publishes technical and operational circulars that announce upcoming API changes. Someone on your team must monitor, read, and action every circular. If no one owns this, changes arrive as production failures.
💡
Build vs manage: the total cost question
The initial CKYC API integration typically takes 3 to 6 months of development effort. Ongoing maintenance - spec updates, code list refreshes, format migrations, circular monitoring, sandbox re-certification - adds up to 2 to 4 weeks of engineering time per year at minimum, spiking to 6 to 8 weeks during major regulatory cycles. Institutions that outsource CKYC API maintenance to a specialist managed service eliminate this ongoing overhead entirely. The integration is maintained in production by a team whose sole function is CKYC operations - with no competing priorities and no dependency on internal development sprint cycles.
Want to skip the integration build and get straight to production?
HSS provides a fully managed CKYC API integration service - your system connects to our middleware, we handle CERSAI connectivity, spec maintenance, and compliance updates. No internal CKYC engineering required.
Frequently Asked Questions
What APIs are needed for a complete CKYC integration? ▼
A complete integration requires four API calls: Search (POST /search) to check for existing records, Download Initiate (POST /download-initiate) and OTP Validate (POST /validate-otp) to retrieve existing records, and Upload Data (POST /upload-data) to submit new records for generation. A fifth call, POST /get-status, is required to poll the result of a Generation submission until CERSAI assigns a KIN.
How does CKYC API authentication work? ▼
All CKYC API calls require an API key passed in the request header as api_key: your_api_key. There are no session tokens or OAuth flows. The key must be included in every request. Missing or invalid keys return HTTP 400 with a specific error message.
What is the Generation API response format? ▼
The Generation API returns HTTP 201 on success with status: true, a success message, and a transaction_id. This transaction_id must be stored persistently and used to poll the Status API until CERSAI assigns a CKYC number. Error responses return HTTP 400 with status: false and an error message identifying the rejection category.
How should documents be submitted in the CKYC API? ▼
Documents are submitted as base64-encoded strings in the files.Documents array. Each document needs DocumentType (02 for photo, 04 for Aadhaar, etc.), DocumentNumber (last 4 digits for Aadhaar, 02 placeholder for photo, full number for others), DocumentBase64 (base64-encoded file), and DocumentExtension (jpg, jpeg, png, or pdf). Total document size must not exceed 1MB across all documents in the submission.
What is the difference between CKYC Search and Download? ▼
Search checks whether a CKYC record exists and returns the KIN if found - it does not retrieve the record content. Download retrieves the full CKYC record including identity details, address, photograph, and documents. Search must always be called first. If it finds a record, Download is triggered. If no record is found, Generation is used to create one.
Skip the Build - Go Live Faster
HSS's managed CKYC service handles the entire API integration, maintenance, and compliance layer. Connect once to our middleware and let our team manage CERSAI connectivity, spec updates, and rejection handling on your behalf.
Talk to Our Team
Explore Our Services
H
HSS Technology Team
Hridayam Soft Solutions Pvt. Ltd. - CKYC Operations Specialists
HSS provides end-to-end CKYC managed services for banks, NBFCs, HFCs, and insurance companies across India. Our ShareDocs DMS platform handles document management, API integration, and CERSAI compliance operations at scale.
Last Reviewed: May 16, 2026 |
Sources: CERSAI CKYC API documentation, HSS ShareDocs DMS integration specifications, RBI Master Direction on KYC (amended August 2025).
This article is for informational purposes only. For institution-specific integration guidance, consult your technology and compliance teams.
Comments
Post a Comment