CKYC Analyzer API-Advance

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 Advanced API becomes essential.

Our CKYC Analyzer Advanced API offers intelligent verification features to ensure seamless compliance for Individual's CKYC data:

Document OCR Extraction: Automatically extracts critical data (name, DOB, ID number, pincode) from document images using advanced optical character recognition.

Data Comparison Between Documents and Records: Compares information extracted from documents with metadata from the CKYC record, ensuring consistency and accuracy.

Multi-field Matching: Cross-verifies name, date of birth, pincode, and identity numbers to detect mismatches between record claims and document content.

Image Quality & Classification: Assesses image clarity and automatically identifies document types to prevent downstream rejections.

By integrating the CKYC Analyzer Advanced API, your organization can efficiently determine when CKYC data alone suffices and when discrepancies signal need for additional documentation. This intelligent analysis streamlines your underwriting processes and reduces fraud risk. Position your organization at the forefront of regulatory compliance while enhancing the onboarding experience—a clear competitive advantage in today's regulatory landscape.

API details

Endpoint

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

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

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

Request body example

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

Response

Success response (HTTP 200)

{
  "status": "success",
  "requestId": "4c2d5e6f-7a8b-9c0d-1e2f-3g4h5i6j7k8l",
  "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"
        },
        "extractionDetails": {
          "name": "RAKESHBHAI KUMAR SOLANKI",
          "dob": "12/06/1988",
          "uid": "XXXXXXXX8888",
          "pincode": "401105"
        },
        "nameMatchResult": {
          "ocrDataVsInputDataScore": 0.97,
          "threshold": 0.8,
          "verdict": "pass"
        },
        "dobMatchResult": {
          "ocrDataVsInputDataScore": 1,
          "threshold": 0.8,
          "verdict": "pass"
        },
        "pincodeMatchResult": {
          "ckycPincode": "401105",
          "ocrPincode": "401105",
          "score": 1,
          "verdict": "pass"
        },
        "maskingResult": {
          "verdict": "pass"
        },
        "masked": true,
        "documentVerdict": "pass"
      }
    ],
    "idNumberMatch": [
      {
        "identityType": "AADHAAR",
        "docType": "aadhaar",
        "ckycIdNumber": "8888",
        "ocrIdNumber": "XXXXXXXX8888",
        "score": 1,
        "verdict": "pass",
        "reason": "masked_aadhaar_last4_match"
      }
    ],
    "faceMatch": null
  },
  "actionables": [],
  "warnings": [],
  "finalVerdict": "pass",
  "completeness": "full",
  "checksRun": [
    "imageQuality",
    "classification",
    "expiry",
    "aadhaarMasking",
    "ocr",
    "nameMatch",
    "dobMatch",
    "pincodeMatch",
    "idNumberMatch"
  ],
  "checksSkipped": [],
  "unsupportedFlags": [],
  "thresholds": {
    "imageQualityThreshold": 0.6,
    "nameMatchThreshold": 0.8
  }
}

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, 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, ocr, nameMatch, dobMatch, pincodeMatch, idNumberMatch
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 (Advanced Plan)

The Advanced plan includes everything in Standard, plus OCR extraction and four cross-checks—this is where the analyzer starts reading and comparing:

1. Image Quality & Blur (Standard carry-forward)

Every image is scored 0–1 against your imageQualityThreshold. Catches unreadable scans before they cause downstream rejections.

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 (Standard carry-forward)

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 (Standard carry-forward)

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

4. Aadhaar Image Masking (Standard carry-forward)

Every Aadhaar image is masked and returned in place. The original never comes back.

Verdict values:

pass: Aadhaar successfully masked

fail: Aadhaar masking could not complete

not_applicable: Not an Aadhaar document

5. OCR Extraction (Advanced)

Name, DOB, ID number, and pincode are extracted from each document image using optical character recognition. Everything below depends on OCR success.

Extraction fields:

name: Extracted full name from document

dob: Extracted date of birth (tolerant of format variation)

uid: Extracted identity number (Aadhaar always redacted to last-4 in responses)

pincode: Extracted postal code from address-bearing documents

Verdict values:

pass: Extraction successful

fail: Extraction could not complete

not_applicable: Document does not contain this field

not_supported: Document type not supported for extraction

6. Name Match (Advanced)

Record name is compared against document name using fuzzy matching, scored 0–1 against your nameMatchThreshold.

Verdict values:

pass: Names match above your threshold

fail: Names do not match at or above your threshold

not_applicable: Document carries no name field

skipped_due_to_prior_failure: OCR failed on this document

extraction_failed: OCR could not read the name

7. Date-of-Birth Match (Advanced)

Record DOB is compared against document DOB, tolerant of format variation.

Verdict values:

pass: DOBs match

fail: DOBs do not match

not_applicable: Document carries no DOB field

skipped_due_to_prior_failure: OCR failed on this document

8. Pincode Match (Advanced)

Pincode OCR'd from address-bearing documents is compared against the record's permanent-address pincode.

Verdict values:

pass: Pincodes match

fail: Pincodes do not match

not_applicable: Document carries no address (e.g., PAN, Driving License without address)

skipped_due_to_prior_failure: OCR failed on this document

9. ID-Number Match (Advanced)

The record's identity number is compared against the number read off the document. For CKYC 2.0 Aadhaar, this compares last-4 digits (the registry never ships the full number)—still decisive for catching a wrong document attached to a record.

Verdict values:

pass: ID numbers match

fail: ID numbers do not match

not_applicable: Document carries no identity number

skipped_due_to_prior_failure: OCR failed on this document

partial_match: Last-4 digits match (Aadhaar only)

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
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 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.

Threshold visibility: A low threshold is your choice, visibly. verdict: "pass" at threshold: 0.8 is self-documenting in the response; 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—still decisive for catching a wrong document.

Completeness gates: A pass with completeness: "partial" is not a clean pass. Always inspect checksSkipped[] when completeness is partial.

Warnings vs. failures: warnings[] carries advisory codes like EXTRACTION_FAILED (OCR could not read a document). It does not fail the record by itself—dependent checks report skipped—but a warned record deserves a human look.

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

Internal consistency: This API verifies the record's internal consistency—that documents agree with the record's own data. Mismatches signal fraud risk but do not attest to external authenticity. Pair with Enterprise for government-source verification.

Use cases

The Advanced plan fits:

Lending & Underwriting: Lenders, NBFCs, and brokers underwriting against a CKYC record where a mismatch between claimed and documented data is fraud risk.

Microfinance Onboarding: Detect discrepancies early in the lending pipeline to reduce defaults and fraud.

High-volume KYC Refresh: Efficiently re-verify existing customer records when policies change or refreshes are mandated.

Anyone who needs to verify that a CKYC record's data agrees with its documents.

Quick-start checklist

Obtain your UAT API key and Advanced 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 ocr, nameMatch, dobMatch, pincodeMatch, idNumberMatch.

Wire your handling: finalVerdict → decision, actionables → ops queue, warnings → review queue, extractionDetails → fraud scoring, response ckycData → replace your stored record.

Test the edge paths: a name mismatch, a DOB mismatch, a mismatched pincode, OCR failures, and validation errors (send faceMatchThreshold to analyze-advanced, 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!