CKYC Analyzer API-Enterprise

The Reserve Bank of India's latest 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 Enterprise API becomes essential.

Our CKYC Analyzer Enterprise API offers the most comprehensive verification framework to ensure identity-level scrutiny for Individual's CKYC data:

Government-Source Verification: The document's identity number is verified directly with the issuing authority (PAN, Driving License, Voter ID, Passport), ensuring the document is genuine and registered.

Biometric Face Matching: The record's photograph is biometrically compared with the face cropped from each identity document, with extracted faces returned as base64 crops for your review.

Advanced Data Comparison: Extends Advanced-tier checking to include full government-backed validation, ensuring every claim in the record can be traced back to official sources.

Tamper & Spoof Detection: Reserved capability for future deployment—document integrity and spoofing flags will be added as the service matures.

By integrating the CKYC Analyzer Enterprise API, your organization gains identity-level assurance that goes beyond internal record consistency—you know the person and documents are genuine as verified by government authorities. This comprehensive analysis is designed for banks, high-ticket lending, and any flow where the CKYC record is the basis of trust. Position your organization at the forefront of regulatory compliance while mitigating identity fraud risk—the ultimate competitive advantage in today's regulatory landscape.

API details

Endpoint

POST https://api.signzy.app/api/v3/ckyc/analyze-enterprise

POST https://api-preproduction.signzy.app/api/v3/ckyc/analyze-enterprise

Request 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
nameMatchThreshold	number	Fuzzy-match threshold for name comparison (0 – 1). Tolerant of minor spelling variations. Default: 0.8	No
faceMatchThreshold	number	Biometric face match threshold (0 – 1). Compares record photograph against document faces. Default: 0.5	No

Request body example

{
  "ckycData": {
    "data": {
      "searchResult": {
        "..." : "..."
      },
      "kycDetails": {
        "..." : "..."
      }
    }
  },
  "imageQualityThreshold": 0.6,
  "nameMatchThreshold": 0.8,
  "faceMatchThreshold": 0.5
}

Response

Success response (HTTP 200)

//Payload too large
{
  "error": {
    "statusCode": 413,
    "name": "PayloadError",
    "message": "Request exceeds maximum size of 10 MB",
    "status": "PAYLOAD_TOO_LARGE"
  }
}

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, extraction, matching, government verification, and biometric 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 (e.g., tamperDetection NOT_IMPLEMENTED)
checksRun	array	List of checks that ran: imageQuality, classification, expiry, aadhaarMasking, ocr, nameMatch, dobMatch, pincodeMatch, idNumberMatch, govtVerification, faceMatch
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 (Enterprise Plan)

The Enterprise plan includes everything in Advanced, plus two checks that go outside the record—these verify the record against government sources and biometric databases:

Standard and Advanced Checks (carry-forward)

All checks from Standard and Advanced plans are included:

Image Quality & Blur

Document Type Classification

Document Expiry Check

Aadhaar Image Masking

OCR Extraction

Name Match

Date-of-Birth Match

Pincode Match

ID-Number Match

Please refer to the Advanced plan documentation for details on these checks.

10. Government-Source Verification (Enterprise)

The document's identity number is verified directly with the issuing authority. This is the only check with government pass-through costs, hence the plan's pricing model.

Supported verification document types:

PAN (Permanent Account Number) - Income Tax Department

Driving License - Regional Transport Authority

Voter ID - Election Commission of India

Passport - Ministry of External Affairs

Verdict values:

pass: Document verified with government source

fail: Document failed government verification or number not found

not_applicable: Document type does not support government verification

not_supported: Government verification not yet enabled for this document type

skipped_due_to_prior_failure: OCR failed on this document or earlier check failed decisively

skipped_due_to_upstream_failure: Government verification service was unavailable

11. Face Match (Enterprise)

The record's photograph is biometrically compared with the face cropped from each identity document, scored against your faceMatchThreshold. The cropped face is returned to you as docCroppedImage (base64).

Deliberate behaviors:

A record with no photograph produces a skip (not a failure)—we don't fail a record over a photo CKYCR didn't send.

A document that already failed ID-number match reports skipped_due_to_prior_failure rather than spending a biometric call on a document proven not to belong to the record.

Face extraction and return:

docCroppedImage: Base64-encoded cropped face from the identity document (or null if extraction failed)

Can be stored, displayed in review UIs, or sent to your own biometric systems for re-verification

Verdict values:

pass: Face match score meets your threshold

fail: Face match score does not meet your threshold

not_applicable: Document or record carries no usable face image

not_supported: Document type not supported for face extraction

no_photograph_uploaded: CKYCR did not include a record photograph

skipped_due_to_prior_failure: An earlier check on this document already failed decisively

skipped_due_to_upstream_failure: Biometric matching service was unavailable

12. Tamper & Spoof Detection (Enterprise – Reserved)

Reserved for future deployment. Currently reported as skipped_due_to_upstream_failure with reason NOT_IMPLEMENTED. Your integration will not need changes when this capability goes live—the check will begin running and reporting verdicts without API changes.

When live, will detect:

Document tampering or alterations

Spoofed or synthetic document images

Signs of document replay or cloning

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	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
NAME_MATCH_FAILED	Name matching scores did not meet the required threshold
DOB_MATCH_FAILED	Date of birth does not match between record and document
PINCODE_MATCH_FAILED	Pincode does not match between record and document
ID_NUMBER_MATCH_FAILED	Identity number does not match between record and document
ID_VERIFICATION_FAILED	Government-source verification failed (Enterprise)
FACE_MATCH_FAILED	Face match score did not meet your threshold
EXTRACTION_FAILED	OCR could not read a document (advisory—listed in warnings[])
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 invalid field values. 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.

Threshold visibility: All thresholds are visibly applied. verdict: "pass" at threshold: 0.5 is self-documenting; auditors see both numbers.

Redacted Aadhaar: CKYC 2.0 Aadhaar numbers are last-4 only (the registry never ships the full number). ID-number matching on Aadhaar compares the last 4 digits of the record against the last 4 read off the document.

Face crop return: The docCroppedImage is base64-encoded and can be stored, displayed in review UIs, or sent to your own biometric systems for verification.

Completeness gates: A pass with completeness: "partial" is not a clean pass. Inspect checksSkipped[] when completeness is partial. Currently, tamper detection is NOT_IMPLEMENTED and will be reported as skipped.

Warnings vs. failures: warnings[] carries advisory codes like EXTRACTION_FAILED. It does not fail the record by itself—dependent checks report skipped.

No-photograph handling: A record with no photograph produces a face match skip, not a failure. We don't fail a record over a photo CKYCR didn't send.

Fail-fast on proven mismatches: A document that fails ID-number match will skip face match with skipped_due_to_prior_failure rather than wasting a biometric call on a document proven not to belong to the record.

Idempotency: Analysis is stateless; identical requests return equivalent results. Retries are safe.

Government verification costs: This plan carries pass-through costs for government verification lookups. Each document type verified incurs an issuing-authority check.

Use cases

The Enterprise plan fits:

Banking & High-Risk Lending: Banks and high-ticket lenders where the CKYC record is the KYC basis of record and identity-level assurance is non-negotiable.

Regulated Financial Services: Brokers, mutual fund distributors, and insurance companies subject to stringent identity verification mandates.

Fraud Prevention: Organizations requiring biometric verification and government-source checks to mitigate identity fraud and account takeover risk.

Regulatory Compliance: Financial institutions in highly regulated jurisdictions where audit trails showing government-backed verification provide critical compliance evidence.

Anyone who requires identity-level scrutiny backed by government-source verification and biometric matching.

Quick-start checklist

Obtain your UAT API key and Enterprise 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 including govtVerification and faceMatch. Note that tamperDetection may appear in checksSkipped with reason NOT_IMPLEMENTED until the capability deploys.

Wire your handling: finalVerdict → decision, actionables → ops queue, warnings → review queue, extractionDetails + docCroppedImage → fraud scoring and review UIs, verificationStatus → compliance audit trail, response ckycData → replace your stored record.

Store or display docCroppedImage (base64 face crops) in your review interfaces for manual verification if needed.

Test the edge paths: government verification success and failure, face match scores at and below your threshold, no-photograph records, and a document with a prior failure being skipped in face match.

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!