Skip to main content

CKYC Search and Download API

API No Longer Serviceable
This API is no longer serviceable due to regulatory updates from CERSAI.

CERSAI now mandates:

  • OTP-based user consent before CKYC downloads
  • CKYCRR records to remain within the Regulated Entity's infrastructure

To meet these compliance requirements, we have introduced a Docker-based CKYC Search & Download Solution that enables secure and compliant integration from your on-premises or cloud setup with no dependency on HyperVerge's cloud.

Please refer to our Docker-based CKYC Search & Download Solution release note for more details.

Objective​

The CKYC Search and Download API checks if a user's record is present on the Central KYC Records Registry (CKYCRR) maintained by the Central Registry of Securitisation Asset Reconstruction and Security Interest of India(CERSAI). If the user's record with matching details is present in the repository, they can be further used to perform the Know Your Customer(KYC) identification process for the user.
You can use any one of the following identification documents.

  • PAN
  • Aadhaar
  • Passport
  • Voter ID
  • Driving License
  • CKYC Number
InputOutput
The user's identity card type and the details associated with itThe user's personal identifiable information(PII) associated with their record in the CKYC repository.
Caution

Kindly ensure that you have completed the Upload Key API step prior to this API call.

API URL​

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

API Endpoint​

searchAndDownload

Overview​

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

Authentication​

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

ParameterMandatory or OptionalDescriptionValid Values
content-type Mandatory This parameter defines the media type for the request payload.multipart/form-data
appId Mandatory Application ID shared by HyperVerge N/A. This is a unique value.
appKey MandatoryApplication Key shared by HyperVerge N/A. This is a unique value.
transactionIdMandatoryUnique ID for the customer journey. N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs​

ParameterMandatory or OptionalDescriptionAccepted Values
idTypeMandatoryThe type of identity document used for the KYC process.


The following table provides the inputs expected against the accepted ID type.

Identity DocumentIdentifier Value In Request
PassportA
Voter IDB
PANC
Driving LicenseD
AadhaarE
CKYC IdentifierZ
idNoMandatoryThe unique ID number from the identity document.

The value for this parameter depends on the ID type, and the following table provides the input format for each such type.

ID TypeID number
PassportA valid passport number of the customer.
Voter IDA valid voter ID number of the customer.
PANA 10-digit PAN number of that customer.
AadhaarA combination of four details separated by vertical slashes (or the pipe symbol) "|" : 1. The last 4 digits of the Aadhaar, 2. Name as on the Aadhaar, 3. Date of birth as on the Aadhaar in dd-mm-yyyy format 4. Gender: Male 'M' or Female 'F' or Other 'T'. Sample input - 9906|NAME|01-01-2000|F
Driving LicenseA valid driving licence number of the customer
CKYC IdentifierThe CKYC number corresponding to the serial number in request file
mobileNoOptionalThe mobile number of the user.Not Applicable
dobOptionalThe date of birth of the user. The recommended format is DD-MM-YYYY.
pincodeOptionalThe PIN code of the user.Not Applicable
returnOnlySearchResponseOptionalIf set to "yes", only the search action is performed."yes" or "no"
entityTypeOptionalThe following three scenarios are possible depending on the value you set for this parameter.
  • Scenario 1: When this parameter is not used in the request, by default, the response returns all the fields relevant to the individual and also the legal entity.
  • Scenario 2: When this parameter is not used in the request and the PAN is also linked to both an individual and a legal entity, the response only returns the values for the individual entity.
  • Scenario 3: When you use the parameter in the request, the response will only have the fields relevant to the type of entity you choose.
"individual" or "legalEntity"
returnMaskedImageOptionalIt masks the Aadhaar document when it's returned in the API response. "yes" or "no"
Default: "no"
caution

It is mandatory to either have the mobileNo, the dob, or a combination of the pincode and the dob in the request.

Request​

The following code shows a standard curl request for the API.


curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/searchAndDownload' \
--header 'Content-Type: application/json' \
--header 'appId:  <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>'\
--header  'transactionID: <Enter_the_HyperVerge_transactionID>' \
--header 'Content-Type: application/json' \
--data-raw '{
      "idNo": "ID_number",
      "idType": "<Enter_the_ID_Type_>",  // character value for the ID Document
      "mobileNo": "<Enter_the_Phone_number>",
	  "dob": "<Enter_the_Date_of_Birth>", //DD-MM-YYYY format recommended
  	  "pincode": "<Enter_the_Pincode>",
	  "entityType": "<individual_or_legalEntity>", // (individual or legalEntity) (optional)
	  "returnOnlySearchResponse": "no", // (yes/no) (optional)
      "returnMaskedImage": "no" // (yes/no) (optional)
}'


Success Response​

The following JSON code snippet demonstrates a success response from the API:

  {
    "status": "success",
    "statusCode": "200",
    "result": {
        "constituitonType": "Public Limited Company",
        "constitutionTypeOthers": "",
        "accountType": "",
        "ckycNo": "",
        "preFix": "",
        "firstName": "",
        "middleName": "",
        "lastName": "",
        "fullName": "",
        "fatherOrSpouse": "",
        "fatherPrefix": "",
        "fatherFname": "",
        "fatherMname": "",
        "fatherLname": "",
        "fatherFullName": "",
        "motherPrefix": "",
        "motherFname": "",
        "motherMname": "",
        "motherLname": "",
        "motherFullName": "",
        "gender": "",
        "dob": "14-08-1989",
        "idList": "",
        "placeOfIncorporation": "",
        "countryOfInscorporation": "IN",
        "tinGst": "",
        "tinCountry": "",
        "age": "",
        "address1": "",
        "address2": "",
        "address3": "",
        "city": "",
        "district": "",
        "state": "TS",
        "country": "IN",
        "pincode": "500003",
        "poa": "others",
        "poaOthers": "",
        "permAndCorresAddSame": "Y",
        "corresAddress1": "",
        "corresAddress2": "",
        "corresAddress3": "",
        "corresCity": "",
        "corresDist": "",
        "corresState": "TS",
        "corresCountry": "IN",
        "corresPin": "",
        "corresPoa": "",
        "proffOfAddress": "",
        "offStdCode": "",
        "offtelNo": "",
        "faxCode": "",
        "faxNo": "",
        "resiStdCode": "",
        "resiTelNo": "",
        "mobileCode": "",
        "mobileNumber": "",
        "email": "",
        "decDate": "",
        "decPlace": "",
        "kycDate": "********",
        "updatedDate": "",
        "DocSub": "01",
        "kycName": "********",
        "kycDesignation": "********",
        "kycBranch": "********",
        "kycEmpCode": "********",
        "numIdentity": "1",
        "numRelated": "2",
        "numImages": "2",
        "aadhaar": "",
        "pan": "",
        "voterId": "",
        "passport": "",
        "drivingLicense": "",
        "nregaJobCard": "",
        "nationalPopulationReg": "",
        "officiallyValidDoc": "",
        "certOfIncorporation": "",
        "regcertificate": "",
        "articleOfAssociation": "",
        "partnershipDeed": "",
        "trustDeed": "",
        "boardResolution": "",
        "powerOfAttorney": "",
        "activityProof1": "",
        "activityProof2": "",
        "imageDetails": [
            {
                "code": "19",
                "type": "JPG",
                "imageUrl": "<Image_URL>"
            },
            {
                "code": "98",
                "type": "JPG",
                "imageUrl": "<Image_URL>"
            }
        ],
        "relatedPersonDetails": [
            {
                "relationype": "Authorised Signatory",
                "ckycNo": "",
                "prefix": "",
                "firstName": "",
                "middleName": "",
                "lastName": "",
                "maidenPrefix": "",
                "maidenFirstName": "",
                "maidenMiddleName": "",
                "maidenLastName": "",
                "fatherOrSpouse": "",
                "fatherPrefix": "",
                "fatherFname": "",
                "fatherMname": "",
                "fatherLname": "",
                "motherPrefix": "",
                "motherFname": "",
                "motherMname": "",
                "motherLname": "",
                "dob": "",
                "gender": "",
                "nationality": "",
                "pan": "",
                "formSixty": "",
                "address1": "",
                "address2": "",
                "address3": "",
                "city": "",
                "district": "",
                "state": "",
                "country": "",
                "pincode": "",
                "poiType": "",
                "permAndCorresAddSame": "",
                "corresAddress1": "",
                "corresAddress2": "",
                "corresAddress3": "",
                "corresCity": "",
                "corresDist": "",
                "corresState": "",
                "corresCountry": "",
                "corresPin": "",
                "corresPoiType": "",
                "resiStdCode": "",
                "resiTelNo": "",
                "mobileCode": "",
                "mobileNumber": "",
                "offStdCode": "",
                "offTelNum": "",
                "email": "",
                "aadhaar": "",
                "voterId": "",
                "nregaJobCard": "",
                "passport": "",
                "drivingLicense": "",
                "nationalPopulationReg": "",
                "ekycAuth": "",
                "decDate": "",
                "decPlace": "",
                "kycDate": "",
                "DocSub": "",
                "kycName": "",
                "kycDesignation": "",
                "kycBranch": "",
                "kycEmpCode": "",
                "din": "",
                "photoUrl": "<Photo_URL>",
                "poiUrl": "<Proof_of_Identity_URL>"
            },
            {
                "relationype": "",
                "ckycNo": "",
                "prefix": "",
                "firstName": "",
                "middleName": "",
                "lastName": "",
                "maidenPrefix": "",
                "maidenFirstName": "",
                "maidenMiddleName": "",
                "maidenLastName": "",
                "fatherOrSpouse": "",
                "fatherPrefix": "",
                "fatherFname": "",
                "fatherMname": "",
                "fatherLname": "",
                "motherPrefix": "",
                "motherFname": "",
                "motherMname": "",
                "motherLname": "",
                "dob": "",
                "gender": "",
                "nationality": "",
                "pan": "",
                "formSixty": "",
                "address1": "",
                "address2": "",
                "address3": "",
                "city": "",
                "district": "",
                "state": "",
                "country": "",
                "pincode": "",
                "poiType": "",
                "permAndCorresAddSame": "",
                "corresAddress1": "",
                "corresAddress2": "",
                "corresAddress3": "",
                "corresCity": "",
                "corresDist": "",
                "corresState": "",
                "corresCountry": "",
                "corresPin": "",
                "corresPoiType": "",
                "resiStdCode": "",
                "resiTelNo": "",
                "mobileCode": "",
                "mobileNumber": "",
                "offStdCode": "",
                "offTelNum": "",
                "email": "",
                "aadhaar": "",
                "voterId": "",
                "nregaJobCard": "",
                "passport": "",
                "drivingLicense": "",
                "nationalPopulationReg": "",
                "ekycAuth": "",
                "decDate": "",
                "decPlace": "",
                "kycDate": "",
                "DocSub": "",
                "kycName": "",
                "kycDesignation": "",
                "kycBranch": "",
                "kycEmpCode": "",
                "din": "",
                "photoUrl": "<Photo_URL>",
                "poiUrl": "<Proof_of_Identity_URL>"
            }
        ]
    }
}

Failure Responses​

The following code snippet demonstrates a failure response where the API fails to detect a document from the image.

{
    "status": "failure",
    "statusCode": "404",
    "error": {
        "code": "ER_CKYC_SEARCH_AND_DOWNLOAD",
        "message": "No record found"
    }
}

Error Responses​

The following code snippets demonstarte the error responses from the API:

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "idNo should not be null or undefined"
  }
}
{
    "status": "failure",
    "statusCode": "404",
    "error": {
        "code": "ER_CKYC_SEARCH_AND_DOWNLOAD",
        "message": "Public key not available in the server. Please upload key"
    }
}
{
    "status": "failure",
    "statusCode": "404",
    "error": {
        "code": "ER_CKYC_SEARCH_AND_DOWNLOAD",
        "message": "Validation failure"
    }
}

Failure and Error Response Details​

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status CodeError MessageError Description
400idNo should not be null or undefinedThe request does not contain the ID number. It is a mandatory field
400Please send a proper values for idNoThe request does not contain a valid idNo
400Please send a proper values for idTypeThe request does not contain a valid idType
400mobileNo must be of length 10The mobile number in the request is incorrect
400pincode must be of length 6The pin code in the request is incorrect
400DoB should be in DD-MM-YYYY format or valid dateThe format of the date of birth in the request is invalid
400property Dob should not exist-
400idType should not be null or undefinedThe request does not contain the ID type. It is a mandatory field
400Invalid IDThe length of idNo is less than 4 or greater than 165
400No key and ficode configured for this appidHyperVerge has not received the key and fincancial institution code against your application ID
400wrong pan sent for entityType individualThe PAN used in the request is not of an individual type
401Missing/Invalid credentialsThe request is either missing the mandatory appId and appKey combination or has invalid values
404Document not detected from ImageThe module failed to detect a document in the image. Ensure that the image captures the document following the guidlines mentioned under the Input Image Guidelines section.
404Public key not available in the server. Please upload keyThe required public key for the operation is missing. Ensure the key is uploaded before making the request.
404<IP_No>: IP does not match with IP registered on CKYCRR portalThe provided IP address does not match the one registered on the CKYCRR portal
404Please configure your IP address.The request cannot be processed as the IP address is not configured
404The given IP does not match with the institution's registered IP.The IP address provided in the request does not align with the registered IP of the institution
404Please enter valid CKYC NumberThe CKYC number entered in the request is invalid
404Please enter valid FI CodeThe Financial Institution (FI) code provided is invalid
404Date of birth does not match with the given CKYC NumberThe date of birth entered does not match the records for the given CKYC number
404Authentication Failed: Pincode and Year of birth entered does not match with the CKYC NumberThe pincode and year of birth provided do not match the records associated with the CKYC number
404Authentication Failed: Mobile number entered does not match with the CKYC NumberThe mobile number provided does not match the CKYC number
404Authentication Failed: Mobile number entered does not exist for CKYC Number The mobile number does not exist for the given CKYC number
404Institution wallet does not have sufficient balance, please top up the walletThe institution's wallet does not have adequate balance to process the request
404Digital signature cannot be verified. The certificate is expired.The digital signature verification failed as the certificate has expired
404Validation failureThe input validation for the request has failed
404Institution does not existThe requested financial institution does not exist in the system
404Session Key Decryption error. Please encrypt with correct public KeyThe session key decryption failed due to incorrect encryption with the public key
404KYC Number should be of length 14 digitsThe CKYC number must be exactly 14 digits long
404KYC Number <<KYC_NO>> does not exist in systemThe provided CKYC number is not found in the system
500Internal server errorPlease check the request headers or contact the HyperVerge team for resolution
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: