CKYC Analyzer API-Standard
The Reserve Bank of India's notification (Nov 6, 2024) mandates an urgent overhaul of customer onboarding processes. Financial institutions must now retrieve KYC data directly from the Central KYC Registry (CKYCR) instead of repeatedly requesting documents from customers—unless specific updates or verifications are necessary. Delaying this transition not only risks non-compliance but also hampers customer experience.
There are four critical scenarios where additional action is required:
- Updated Customer Information: Changes in a customer's details recorded at the CKYCR.
- Incomplete KYC Records: Retrieval of KYC data that is incomplete or doesn't align with current standards.
- Expired Documents: Downloaded documents that have exceeded their validity period.
- Additional Verification Needed: Situations requiring further identity, address verification, or enhanced due diligence.
This is where our CKYC Analyzer Standard API becomes essential.
Our CKYC Analyzer Standard API offers foundational features to ensure compliance for Individual's CKYC data:
- Image Quality Analysis: Automatically assesses the quality of ID images to ensure they meet required standards for clarity and legibility.
- Document Type Classification: Identifies what each image actually is, independently determined to surface document mismatches.
- Expiry Date Verification: Automatically reads and validates validity dates from dated documents like passports and driving licenses.
- Aadhaar Image Masking: Every Aadhaar image is masked and returned in place in the response—ensuring legal compliance and data security.
By integrating the CKYC Analyzer Standard API, your organization can ensure document sets are usable and compliant—catching unreadable scans, expired documents, and misclassified records before they cause downstream rejections. Position your organization at the forefront of regulatory compliance while enhancing the onboarding experience.
API details
Endpoint
POST https://api.signzy.app/api/v3/ckyc/analyze-standardPOST https://api-preproduction.signzy.app/api/v3/ckyc/analyze-standardRequest headers
Name | Value | Required | Description |
|---|---|---|---|
Content-Type | application/json | Mandatory | The type of content that the request body contains. |
Authorization | XXXXXXXXXXXXXXX | Mandatory | An authentication token to authorize the request. Reach out to the Signzy support team to get one created. |
Request body parameters
Parameter Name | Data Type | Description | Required |
|---|---|---|---|
ckycData | object | The CKYC record exactly as CKYCR returned it after decryption. Do not flatten, re-map, or extract fields. Accepts full CKYC 2.0 download/get response body or CKYC 1.0 fetch records. | Yes |
imageQualityThreshold | number | Quality threshold for image assessment (0 – 0.99). Measures image clarity and legibility. Default: 0.6 | No |
Request body example
{
"ckycData": {
"data": {
"searchResult": {
"..." : "..."
},
"kycDetails": {
"..." : "..."
}
}
},
"imageQualityThreshold": 0.6
}Response
Response json
{
"status": "success",
"requestId": "0a1b2c3d-4e5f-6g7h-8i9j-10k11l12m13n",
"ckycData": {
"data": {
"searchResult": { "..." : "..." },
"kycDetails": { "..." : "..." }
}
},
"analysis": {
"documents": [
{
"imageCode": "02",
"docType": "photograph",
"imageQualityResult": {
"score": 0.83,
"threshold": 0.6,
"verdict": "pass"
},
"documentVerdict": "pass"
},
{
"imageCode": "04",
"docType": "aadhaar",
"imageQualityResult": {
"score": 0.91,
"threshold": 0.6,
"verdict": "pass"
},
"expiryResult": {
"verdict": "not_applicable"
},
"maskingResult": {
"verdict": "pass"
},
"masked": true,
"documentVerdict": "pass"
}
],
"idNumberMatch": [],
"faceMatch": null
},
"actionables": [],
"warnings": [],
"finalVerdict": "pass",
"completeness": "full",
"checksRun": [
"imageQuality",
"classification",
"expiry",
"aadhaarMasking"
],
"checksSkipped": [],
"unsupportedFlags": [],
"thresholds": {
"imageQualityThreshold": 0.6
}
}Response headers
Name | Description |
|---|---|
Content-Type | application/json; charset=utf-8 |
X-Request-ID | Unique identifier for the request |
Response body parameters
Parameter Name | Data Type | Description |
|---|---|---|
status | string | Response status: "success" or "error" |
requestId | string | Unique identifier for this request—quote this in any support request |
ckycData | object | Your input record, byte-faithful, with ONE change: every Aadhaar image is replaced by its masked version (or null if masking could not complete—never the original) |
analysis | object | Document-level and cross-check analysis results |
actionables | array | List of failed checks; empty if finalVerdict is "pass" |
warnings | array | Advisory-only warnings that do not cause failures |
finalVerdict | string | One-word answer: "pass" or "fail" |
completeness | string | "full" or "partial"—partial means at least one enabled check could not run |
checksRun | array | List of checks that ran: imageQuality, classification, expiry, aadhaarMasking |
checksSkipped | array | Checks that were skipped and their reasons |
unsupportedFlags | array | Unrecognized request fields |
thresholds | object | Echo of the thresholds applied to this analysis |
Checks performed (Standard Plan)
The Standard plan includes four document-level checks, all about the documents themselves—nothing is compared against the record's data yet:
1. Image Quality & Blur
Every image is scored 0–1 against your imageQualityThreshold. Catches unreadable scans before they cause downstream rejections. CKYCRR itself mandates quality floors: ≥512×512 px, 70 KB, ≥250 DPI.
Verdict values:
- pass: Image quality meets your threshold
- fail: Image quality below your threshold
- not_supported: Document type not supported for quality assessment
2. Document Type Classification
Identifies what each image actually is, independently determined. A document that contradicts its declared type surfaces as DOCUMENT_MISMATCH.
Verdict values:
- pass: Classification successful and matches declared type
- fail: Classification failed or contradicts declared type
- not_supported: Document type cannot be classified
3. Document Expiry Check
Validity dates are read off dated documents (passport, driving license). Expired documents fail.
Verdict values:
- pass: Document is not expired
- fail: Document is expired
- not_applicable: Document type carries no expiry date (e.g., Aadhaar Proof of Possession, PAN)
4. Aadhaar Image Masking
Every Aadhaar image is masked and returned in place in the response. The original never comes back, and if masking cannot complete the image is returned as null—never unmasked. Storing unmasked Aadhaar is legally prohibited for most entities, which is why this sits in the base plan.
Verdict values:
- pass: Aadhaar successfully masked
- fail: Aadhaar masking could not complete—document fails and no image is returned
- not_applicable: Not an Aadhaar document
Verdict reference
Verdict values and meanings
Verdict | Meaning | Typical handling |
|---|---|---|
pass | Check ran and met your threshold | — |
fail | Check ran and did not meet it | Review / reject |
not_applicable | Check is meaningless for this document (e.g., expiry on a PAN) | Counts as pass |
not_supported | No processing path for this document type | Not a failure — document is outside scope |
skipped_due_to_missing_input | Check enabled but the record lacks needed data | Listed in checksSkipped; completeness becomes partial |
skipped_due_to_prior_failure | An earlier check on this document already failed decisively | The earlier failure is the actionable |
skipped_due_to_upstream_failure | A Signzy-side verification service was unavailable | Record fails with UPSTREAM_CHECK_FAILED; retry later |
Error codes
Analysis-level error codes (actionables[].errorCode)
errorCode | Meaning |
|---|---|
IMAGE_QUALITY_FAILED | Image quality below your threshold |
CLASSIFICATION_FAILED | Document could not be classified |
DOCUMENT_MISMATCH | Classified type contradicts the type the record declares |
EXPIRY_FAILED | Document is expired |
AADHAAR_MASKING_FAILED | Aadhaar could not be masked—the document fails and no image is returned |
UPSTREAM_CHECK_FAILED | A required Signzy-side service was unavailable; retry later |
UPLOAD_FAILED | Internal upload problem; quote requestId to support |
PROCESSING_ERROR | Internal processing problem; quote requestId to support |
Request-level HTTP errors
HTTP Code | Meaning |
|---|---|
400 | Validation—missing ckycData, threshold out of range, or a field your plan doesn't accept. Message names the exact field. |
401 / 403 | API key missing, invalid, or not entitled to this endpoint |
413 | Request over 10 MB |
5xx | Transient—retry with backoff (calls are idempotent) |
Design behaviors
- Masked-image echo: Store the response's ckycData, discard what you sent. Same structure, Aadhaar masked. If masking fails, that document's image comes back null and the record fails—fail-closed, by design.
- Threshold visibility: A low threshold is your choice, visibly. verdict: "pass" at threshold: 0.6 is self-documenting in the response; auditors see both numbers.
- Completeness gates: A pass with completeness: "partial" is not a clean pass. Always inspect checksSkipped[] when completeness is partial.
- Idempotency: Analysis is stateless; identical requests return equivalent results. Retries are safe.
- No-photograph handling: A record with no photograph does not fail—the Standard plan only assesses documents present.
- Internal consistency only: This API verifies the record's internal consistency—that documents are legible, genuine-quality, and unexpired. It does not attest where the record came from. Pair it with your CKYCR download flow for provenance.
Use cases
The Standard plan fits:
- Record Storage: Ensure document sets are clean and legally storable before archival.
- Wallet Onboarding: Validate CKYC records for quick, frictionless digital wallet activation.
- Micro-Investment Onboarding: Fast-track simple KYC for small-ticket investment products by confirming document legibility and validity.
Anyone who ingests CKYC records and needs them clean and legally storable.
Quick-start checklist
- Obtain your UAT API key and plan endpoint from Signzy.
- Download any record via your CKYCR flow; POST the decrypted response as ckycData with your thresholds.
- Expect HTTP 200 with checksRun matching your plan's table (imageQuality, classification, expiry, aadhaarMasking).
- Wire your handling: finalVerdict → decision, actionables → ops queue, warnings → review queue, completeness → clean-pass gate, response ckycData → replace your stored record.
- Test the edge paths: a low-quality image, an expired document, a deliberately wrong threshold (0.99), and validation errors (send nameMatchThreshold to analyze-standard, expect 400).
- For any issue, contact Signzy support with the response requestId.
CKYC Image Codes Description
Image Code Description
Image Code | Description |
|---|---|
02 | Photograph |
03 | PAN |
04 | Proof of Possession of Aadhaar |
05 | Passport |
06 | Driving License |
07 | Voters Identity Card |
08 | NREGA Job Card |
09 | Signature |
10 | Simplified Measures Account - Identity card with applicant's photograph issued by Central/ State Government Departments, Statutory/ Regulatory Authorities, Public Sector Undertakings, Scheduled Commercial Banks, and Public Financial Institutions. |
11 | Simplified Measures Account - Letter issued by a gazetted officer, with a duly attested photograph of the person. |
12 | Utility bill which is not more than two months old of any service provider (electricity, telephone, post-paid mobile phone, piped gas, water bill). |
13 | Property or Municipal Tax receipt. |
14 | Bank account or Post Office savings bank account statement. |
15 | Pension or family pension payment orders (PPOs) issued to retired employees by Government Departments or Public Sector Undertakings, if they contain the address. |
16 | Letter of allotment of accommodation from employer issued by State or Central Government departments, statutory or regulatory bodies, public sector undertakings, scheduled commercial banks, financial institutions and listed companies. Similarly, leave and license agreements with such employers allotting official accommodation. |
17 | Documents issued by Government departments of foreign jurisdictions and letter issued by Foreign Embassy or Mission in India. |
18 | Officially valid document(s) in respect of person authorized to transact |
19 | Certificate of Incorporation/Formation |
20 | Registration Certificate |
21 | Memorandum and Articles of Association |
22 | Partnership Deed |
23 | Trust Deed |
24 | Resolution of Board/ Managing Committee |
25 | Power of Attorney granted to its manager, officers or employees to transact on its behalf. |
26 | Activity Proof – 1 (For Sole Proprietorship only) |
27 | Activity Proof – 2 (For Sole Proprietorship only) |
35 | National Population Registry Letter |
36 | E-KYC Authentication |
37 | Offline verification of Aadhaar |
98 | Other |
If you have any questions or need assistance, please reach out to our customer support team. You can contact us via email at [email protected]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.
We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!