CKYC Validation API v1

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

API Description

Objective

The CKYC Validation API v1 verifies a user's personally identifiable information (PII) downloaded from their record in the Central KYC Registry and classifies the response into one of three outcomes based on an internal scoring mechanism: Approve, Review, or Reject.

Input	Output
The user's record from the Central KYC Registry, including the user's selfie, XML file, and officially valid documents	The classification result after matching the user's details across all of these files

API URL

https://ind-ckyc.hyperverge.co/api/v1/validate

API Endpoint

validate

Overview

The CKYC Validation API v1 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 v1.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	Defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application ID 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 v1's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
first_name	Optional	string	The first name of the user	String without special characters	Not Applicable
middle_name	Optional	string	The middle name of the user	Should be a string	Not Applicable
last_name	Optional	string	The last name of the user	Should be a string	Not Applicable
full_name	Optional	string	The full name of the user	Should be a string	Not Applicable
dob	Optional	string	The date of birth of the user	DD-MM-YYYY	Not Applicable
address1	Optional	string	The primary address line of the user	Should be a string	Not Applicable
address2	Optional	string	The secondary address line of the user	Should be a string	Not Applicable
address3	Optional	string	The tertiary address line of the user	Should be a string	Not Applicable
city	Optional	string	The city of residence of the user	Should be a string	Not Applicable
district	Optional	string	The district of residence of the user	Should be a string	Not Applicable
state	Optional	string	The state of residence of the user	Should be a string	Not Applicable
country	Optional	string	The country of residence of the user	Should be a string	Not Applicable
pincode	Optional	string	The postal code of residence of the user	Should be a string	Not Applicable
aadhaar	Selectively Optional: at least one of voter_id, passport, aadhaar, or driving_license is required	string	The Aadhaar number of the user	Should be a valid Aadhaar number	Not Applicable
driving_license	Selectively Optional: at least one of voter_id, passport, aadhaar, or driving_license is required	string	The driving license number of the user	Should be a valid driving license number	Not Applicable
voter_id	Selectively Optional: at least one of voter_id, passport, aadhaar, or driving_license is required	string	The voter ID number of the user	Should be a valid voter ID number	Not Applicable
passport	Selectively Optional: at least one of voter_id, passport, aadhaar, or driving_license is required	string	The passport number of the user	Should be a valid passport number	Not Applicable
pan	Optional	string	The PAN number of the user	Should be a valid PAN number	Not Applicable
validate_pan	Optional	string	Indicates whether to validate the PAN number	yes / no	Not Applicable
mask_aadhaar	Optional	string	Indicates whether to mask the Aadhaar number in the response	yes / no	Not Applicable
image_details	Selectively Optional: mandatory if imageDetails is not provided	file	The image file(s) containing the user's supporting documents to be validated against the input fields. You can also include a photo of the user for face match authentication. File Naming Convention For each image, the file name must contain one of the following document identifiers or names: Identifier Document Name 02 Photo 03 PAN 04 Proof of possession of Aadhaar 05 Passport 06 Driving Licence 07 Voters ID Accepted file formats: JPEG, PNG, TIFF, PDF. Base64 encoding is not accepted. For example, any of the following names is acceptable for an Aadhaar input: aadhaar.pdf, xyz_04_.pdf, xyz_aadhaar.pdf	Multipart file upload. File name must contain the document identifier or name	Not Applicable
imageDetails	Selectively Optional: mandatory if image_details is not provided	object	Allows sending images using URLs with an acceptable document code. Includes the code of the KYC document and the URL containing the image or PDF	Object with valid image URL strings	Not Applicable
returnOcrDump	Optional	string	If set to "yes", the response includes an additional ocrDump field with OCR-extracted text from each attached file	yes / no	no
standardOcrDump	Optional	string	If set to "yes", the response includes a standard ocrDump field with structured OCR-extracted text from each attached file	yes / no	no
returnMaskedAadhaarNumber	Optional	string	If set to "yes", the user's Aadhaar value is masked in the response	yes / no	no
returnInputImage	Optional	string	If set to "yes", the response includes an inputImageUrls key containing URLs of the input files	yes / no	no
returnSingleMaskedFile	Optional: works only when mask_aadhaar is enabled	string	If set to "yes", the response includes a masked_aadhaar_url key containing a single merged file of the masked Aadhaar documents. When not enabled, masked files are returned as individual unmerged documents	yes / no	no

Request

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

curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/validate' \
--header 'Content-Type: multipart/form-data' \
--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 'address3="<Enter_the_Address_3>"' \
--form 'city="<Enter_the_City>"' \
--form 'district="<Enter_the_District>"' \
--form 'state="<Enter_the_State>"' \
--form 'country="<Enter_the_Country>"' \
--form 'pincode="<Enter_the_Pincode>"' \
--form 'mask_aadhaar="<Enter_the_Yes_Or_No>"' \
--form 'image_details=@"<Enter_the_File_Path>"' \
--form 'pan="<Enter_the_PAN>"' \
--form 'validate_pan="<Enter_the_Yes_Or_No>"' \
--form 'aadhaar="<Enter_the_Aadhaar_Number>"' \
--form 'standardOcrDump="<Enter_the_Yes_Or_No>"' \
--form 'returnOcrDump="<Enter_the_Yes_Or_No>"'

Success Response

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

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

Success Response Details

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

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: approve (minimum weighted score less than 2), manual_review (score equal to 2), or reject (score greater than 3)
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. Valid documents include aadhaar, passport, driving_license, and voter_id
result.details	object	Per-document breakdown of field-level match results
result.details.[document].[field].matchFound	boolean	Indicates whether the field value extracted from the document matches the input 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)
result.masked_aadhaar_url	array of strings	URLs to the user's masked Aadhaar image with the first 8 digits masked. Valid for 15 minutes. Returned only when mask_aadhaar is set to "yes"

Error Responses

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

Missing Mandatory Field

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

Missing Input File

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "Selfie image not sent as part of the payload"
  }
}

Page Limit Exceeded

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_PAGE",
    "message": "pages exceeded the supported length of 5"
  }
}

File Too Large

{
  "status": "failure",
  "statusCode": "413",
  "error": {
    "code": "ER_SERVER",
    "message": "File too large"
  }
}

Missing/Invalid Credentials

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

Internal Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": {
    "code": "ER_SERVER",
    "message": "Internal server error"
  }
}

Error Response Details

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

Status Code	Error Message	Error Description	Error Resolution
400	first_name should not be null or undefined	A mandatory field was not provided in the request	Include the required field in the request body
400	Selfie image not sent as part of the payload	The selfie image was not included in the request payload	Include the selfie image in the request
400	pages exceeded the supported length of 5	The submitted document exceeds the maximum supported length of 5 pages	Reduce the document to 5 pages or fewer before submitting
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid credentials
413	File too large	The submitted file size exceeds the maximum allowed limit of 6 MB	Reduce the file size below 6 MB before submitting
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