CKYC Validation API v2

The following document highlights the details of the CKYC Validation API v2.

API Description

Objective

The CKYC Validation API v2 verifies the quality and usability of documents retrieved from the Central KYC (CKYC) registry. It checks downloaded documents for readability, accuracy, and alignment with CKYC XML data.

Input	Output
CKYC XML data and document images (OVDs) downloaded from the CKYC registry	A validation result indicating whether the document is approved, flagged for manual review, or rejected, along with per-field match scores and OCR details

API URL

http://ind-ckyc.hyperverge.co/api/v2/validate

API Endpoint

validate

Overview

The CKYC Validation API v2 is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Method - `POST`

Authentication

You need a unique pair of application ID (appid) and application key (appkey) from HyperVerge to verify your identity for accessing the CKYC Validation API v2.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	multipart/form-data
appid	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appkey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionid	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the CKYC Validation API v2's request body:

Parameter Mandatory / Optional Type Description Input Format Default Value

first_name Mandatory string User's first name as declared in the CKYC XML Should be a string without special characters Not Applicable

address1 Mandatory string Primary address line as declared in the CKYC XML Should be a string Not Applicable

dob Mandatory string User's date of birth as declared in the CKYC XML YYYY-MM-DD Not Applicable

middle_name Optional string User's middle name Should be a string Not Applicable

last_name Optional string User's last name Should be a string Not Applicable

full_name Optional string User's full name Should be a string Not Applicable

address2 Optional string Secondary address line Should be a string Not Applicable

address3 Optional string Tertiary address line Should be a string Not Applicable

city Optional string City name Should be a string Not Applicable

district Optional string District name Should be a string Not Applicable

state Optional string State name Should be a string Not Applicable

country Optional string Country name Should be a string Not Applicable

pincode Optional string Postal code Should be a string Not Applicable

passport Optional string Passport number Should be a string and a valid passport number Not Applicable

aadhaar Optional string Aadhaar number Should be a string and a valid Aadhaar number Not Applicable

driving_license Optional string Driving license number Should be a string and a valid driving license number Not Applicable

voter_id Optional string Voter ID number Should be a string and a valid voter ID number Not Applicable

image_details

Optional

file[]

Document images (OVDs) downloaded from the CKYC registry to be validated.

Upload Criteria for OVD Files

Maximum file size: 5MB per file
Supported formats: PDF, JPG, PNG, TIFF
The file name must contain one of the following document identifiers or names:
Identifier Document Name
02 Photo
03 PAN
04 Aadhaar
05 Passport
06 Driving Licence
07 Voters ID

For example, any of the following names is acceptable for an Aadhaar input: aadhaar.pdf, xyz_04_.pdf, xyz_aadhaar.pdf, photo_self.jpg, passport_xyz.pdf

Multipart file upload. The file name must contain the document identifier or name (e.g., aadhaar.pdf, xyz_04_.pdf)

Not Applicable

returnInputImage Optional string Returns the input image in the response when enabled yes / no no

returnOcrDump Optional string Returns the OCR dump data in the response when enabled yes / no no

standardOcrDump Optional string Returns the standard OCR dump in the response when enabled yes / no no

weights

Optional

object

Configures penalty scores for mismatches across individual fields. Higher weights indicate greater importance during scoring.

Default Penalty Scores

When not configured, the following default penalty scores are applied:

Field	Default Penalty Score
name	3
address	2
city	0
district	0
state	0
country	0
pincode	1
dob	2
passport	3
aadhaar	3
driving license	2
voter_id	2
face	2

Suggested guidelines:

≥3: Critical fields (e.g., PAN, Aadhaar, DOB, Pincode, Name)
2: Important fields (e.g., Address, State, Name)
1: Optional fields (e.g., Address3)

JSON object with field names as keys and numeric penalty scores as values

Not Applicable

e_score Optional object Defines decisioning thresholds for the validation outcome: approve, manualReview, and reject. When not configured, default thresholds are applied JSON object with approve, manualReview, and reject as keys and numeric thresholds as values approve: 1, manualReview: 2, reject: 3

ignore_fields Optional string[] Excludes specific fields from validation and scoring. No penalty is applied for mismatched or missing fields in this list. When not configured, all fields are validated JSON array, comma-separated string, or single string Not Applicable

Request

The following code snippet demonstrates a standard curl request for the CKYC Validation API v2:

curl --location 'http://ind-ckyc.hyperverge.co/api/v2/validate' \
--header 'appid: <Enter_the_App_ID>' \
--header 'appkey: <Enter_the_App_Key>' \
--header 'transactionid: <Enter_the_Transaction_ID>' \
--form 'first_name="<Enter_the_First_Name>"' \
--form 'last_name="<Enter_the_Last_Name>"' \
--form 'dob="<Enter_the_Date_Of_Birth>"' \
--form 'address1="<Enter_the_Address_1>"' \
--form 'address2="<Enter_the_Address_2>"' \
--form 'city="<Enter_the_City>"' \
--form 'country="<Enter_the_Country>"' \
--form 'pincode="<Enter_the_Pincode>"' \
--form 'image_details=@"<Enter_the_File_Path>"' \
--form 'aadhaar="<Enter_the_Aadhaar_Number>"' \
--form 'return_ocr_d="<Enter_the_Yes_Or_No>"'

Advanced Request Variants

With Custom Penalty Scores
With Decisioning Thresholds
With Ignored Fields
With All Advanced Options

curl --location 'http://ind-ckyc.hyperverge.co/api/v2/validate' \
--header 'appid: <Enter_the_App_ID> ' \
--header 'appkey: <Enter_the_App_Key> ' \
--header 'transactionid: <Enter_the_Transaction_ID>' \
--form 'weights="{\"first_name\": 1,
  \"middle_name\": 2,
  \"last_name\": 3,
  \"full_name\": 4,
  \"address1\": 5,
  \"address2\": 6,
  \"address3\": 2,
  \"city\": 1,
  \"district\": 5,
  \"state\": 2,
  \"country\": 1,
  \"pincode\": 4,
  \"dob\": 1,
  \"passport\": 2,
  \"aadhaar\":5,
  \"driving_license\": 1,
  \"voter_id\": 2,
  \"pan\": 3}"' \
--form 'first_name="<Enter_the_First_Name>"' \
--form 'last_name="<Enter_the_Last_Name>"' \
--form 'dob="<Enter_the_Date_Of_Birth>"' \
--form 'address1="<Enter_the_Address_1>"' \
--form 'address2="<Enter_the_Address_2>"' \
--form 'city="<Enter_the_City>"' \
--form 'country="<Enter_the_Country>"' \
--form 'pincode="<Enter_the_Pincode>"' \
--form 'image_details=@"<Enter_the_File_Path>"' \
--form 'aadhaar="<Enter_the_Aadhaar_Number>"'

curl --location 'https://ind-ckyc.hyperverge.co/api/v2/validate' \
--header 'appid: <Enter_the_App_ID>' \
--header 'appkey: <Enter_the_App_Key>' \
--header 'transactionid: <Enter_the_Transaction_ID>' \
--form 'first_name="<Enter_the_First_Name>"' \
--form 'last_name="<Enter_the_Last_Name>"' \
--form 'b="<Enter_the_Value>"' \
--form 'address1="<Enter_the_Address_1>"' \
--form 'address2="<Enter_the_Address_2>"' \
--form 'city="<Enter_the_City>"' \
--form 'country="<Enter_the_Country>"' \
--form 'pincode="<Enter_the_Pincode>"' \
--form 'image_details=@"<Enter_the_File_Path>"' \
--form 'aadhaar="<Enter_the_Aadhaar_Number>"' \
--form 'e_score="{
\"approve\": 2,
\"manualReview\": 3,
\"reject\": 4
}"'

curl --location 'https://ind-ckyc.hyperverge.co/api/v2/validate' \
--header 'appid: <Enter_the_App_ID>' \
--header 'appkey: <Enter_the_App_Key>' \
--header 'transactionid: <Enter_the_Transaction_ID>' \
--form 'first_name="<Enter_the_First_Name>"' \
--form 'last_name="<Enter_the_Last_Name>"' \
--form 'dob="<Enter_the_Date_Of_Birth>"' \
--form 'address1="<Enter_the_Address_1>"' \
--form 'address2="<Enter_the_Address_2>"' \
--form 'city="<Enter_the_City>"' \
--form 'country="<Enter_the_Country>"' \
--form 'pincode="<Enter_the_Pincode>"' \
--form 'image_details=@"<Enter_the_File_Path>"' \
--form 'aadhaar="<Enter_the_Aadhaar_Number>"' \
--form 'ignore_fields="[\"middle_name\", \"address3\", \"passport\"]"'

curl --location 'http://ind-ckyc.hyperverge.co/api/v2/validate' \
--header 'appid: <Enter_the_App_ID> ' \
--header 'appkey: <Enter_the_App_Key> ' \
--header 'transactionid: <Enter_the_Transaction_ID>' \
--form 'weights="{\"first_name\": 1,
  \"middle_name\": 2,
  \"last_name\": 3,
  \"full_name\": 4,
  \"address1\": 5,
  \"address2\": 6,
  \"address3\": 2,
  \"city\": 1,
  \"district\": 5,
  \"state\": 2,
  \"country\": 1,
  \"pincode\": 4,
  \"dob\": 1,
  \"passport\": 2,
  \"aadhaar\":5,
  \"driving_license\": 1,
  \"voter_id\": 2,
  \"pan\ 3}"' \
--form 'first_name="<Enter_the_First_Name>"' \
--form 'last_name="<Enter_the_Last_Name>"' \
--form 'dob="<Enter_the_Date_Of_Birth>"' \
--form 'address1="<Enter_the_Address_1>"' \
--form 'address2="<Enter_the_Address_2>"' \
--form 'city="<Enter_the_City>"' \
--form 'country="<Enter_the_Country>"' \
--form 'pincode="<Enter_the_Pincode>"' \
--form 'image_details=@"<Enter_the_File_Path>"' \
--form 'aadhaar="<Enter_the_Aadhaar_Number>"'
--form 'e_score="{
\"approve\": 2,
\"manualReview\": 3,
\"reject\": 4
}"'\
--form 'ignore_fields="[\"middle_name\", \"address3\", \"passport\"]"'

Success Response

The following code snippet demonstrates a success response from the CKYC Validation API v2:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "action": "<Action>",
        "validPOA": [],
        "validPOI": [],
        "invalidDocs": {
            "aadhaar": [
                "ER_NAME"
            ]
        },
        "details": {
            "aadhaar": {
                "faceMatch": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "first_name": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "last_name": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "address1": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "address2": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "city": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "country": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "pincode": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "dob": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "aadhaar": {
                    "matchFound": "<Match_Found>",
                    "score": "<Match_Score>"
                },
                "doc_template": [
                    "<Doc_Template>"
                ]
            }
        },
        "aadhaar_type": "<Aadhaar_Type>"
    }
}

Success Response Details

The following table outlines the details of the success response from the CKYC Validation API v2:

Parameter	Type	Description
`status`	string	The status of the request
`statusCode`	string	The HTTP status code for the response
`result`	object	The JSON object containing the validation result details
`result.action`	string	The validation outcome for the document: `approve`, `manual_review`, or `reject`
`result.validPOA`	array	List of documents that passed validation as Proof of Address
`result.validPOI`	array	List of documents that passed validation as Proof of Identity
`result.invalidDocs`	object	Documents that failed validation, mapped to their associated error codes
`result.details`	object	Per-document breakdown of field-level match results
`result.details.[document].faceMatch`	object	Face match result for the document, including `matchFound` (boolean) and `score` (0–100)
`result.details.[document].[field].matchFound`	boolean	Indicates whether the field value extracted from the document matches the CKYC XML data
`result.details.[document].[field].score`	number	The match confidence score for the field (0–100)
`result.details.[document].doc_template`	array	The document template(s) identified during OCR processing
`result.aadhaar_type`	string	The type of Aadhaar document detected (e.g., `STANDARD`)

Error Responses

The following are some error responses from the CKYC Validation API v2:

Missing Mandatory Field
Missing/Invalid Credentials
Internal Server Error

{
  "status": "fail",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "first_name should not be null or undefined"
  }
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "message": "Internal Server Error",
    "statusCode": 500,
    "status": "failure"
}

Error Response Details

A failure or error response contains a fail status with a relevant status code and error message. The following table lists the error responses for the CKYC Validation API v2:

Status Code	Error Message	Error Description	Error Resolution
400	first_name should not be null or undefined	The mandatory `first_name` field was not provided in the request	Include the `first_name` field in the request body
401	Missing/Invalid credentials	The request is either missing the mandatory `appid` and `appkey` combination or has invalid values	Verify and provide valid `appid` and `appkey` credentials
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Method - POST​

Authentication​

Headers​

Inputs​

Request​

Advanced Request Variants​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​