Central Database Check API

Objective

The Central Database Check API validates a user's information against their record retrieved from a central database for the following OVDs (Officially Valid Documents):

PAN
Voter ID
Passport
Driving License

Input	Output
The input fields vary with the OVD in the request. The mandatory input fields corresponding to each OVD type are mentioned under the Inputs section.	The output fields vary corresponding to the requested OVD details. The output fields corresponding to each OVD type are mentioned under the Success Response Details section.

API URL

https://ind-verify.hyperverge.co/api/centralDBCheck

API Endpoint

centralDBCheck

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

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	The media type for the request payload.	application/json
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 fields required for the API's request body.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`idNumber`	For PAN, Voter ID, and Driving License, this field represents the unique identification number printed on the respective document	Mandatory	Not Applicable	Not Applicable
`fileNumber`	The file number mentioned in the passport document, also known as the Passport Reference File Number (PRFN). This is a unique identifier assigned to a passport application and is distinct from the actual passport number. It's usually located on the last page of your passport booklet, often in a smaller font, and sometimes labeled as "File No."	Mandatory (only when `idType` is Passport)	Used when `idType` is `passport`	Not Applicable
`dob`	The date of birth of the user, as mentioned in the OVD	Mandatory (only for passport and DL)	The date should be in DD-MM-YYYY format	Not Applicable
`idType`	The type of identification document being verified, for example, "pan" or "voterid"	Mandatory	Not Applicable	Not Applicable

Requests

The following are the cURL requests with expected parameters corresponding to each OVD.

PAN
Voter ID
Passport
Driving Licence

curl --location --request POST 'https://ind-verify.hyperverge.co/api/centralDBCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "idNumber": "<Enter_PAN_Number>",
    "idType": "pan"
}'

curl --location --request POST 'https://ind-verify.hyperverge.co/api/centralDBCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "idNumber": "<Enter_Voter_ID_Number>",
    "idType": "voterid"
}'

curl --location --request POST 'https://ind-verify.hyperverge.co/api/centralDBCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "fileNumber": "<Enter_File_Number>",
    "dob": "<Enter_DOB_dd-mm-yyyy>",
    "idType": "passport"
}'

info

The fileNumber is the Passport Reference File Number (PRFN) found on the last page of the passport booklet, not the passport number itself.

curl --location --request POST 'https://ind-verify.hyperverge.co/api/centralDBCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "idNumber": "<Enter_DL_Number>",
    "dob": "<Enter_DOB_dd-mm-yyyy>",
    "idType": "dl"
}'

Success Response

The following are successful responses for the supported OVD types.

PAN
Voter ID
Driving Licence
Passport

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "details": {
      "name": "<User_Name>"
    },
    "summary": {
      "action": "pass",
      "details": []
    }
  }
}

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "details": {
      "name": "<Name>",
      "rln_name": "<Relative_Name>",
      "rln_type": "<Relative_Type>",
      "gender": "<Gender>",
      "district": "<District>",
      "ac_name": "<Assembly_Constituency_Name>",
      "pc_name": "<Parliamentary_Constituency_Name>",
      "state": "<State>",
      "dob": "<Date_of_Birth>",
      "age": "<Age>",
      "part_no": "<Part_Number>",
      "slno_inpart": "<Serial_Number_In_Part>",
      "ps_name": "<Polling_Station_Name>",
      "part_name": "<Part_Name>",
      "last_update": "<Last_Update_Date>",
      "ps_lat_long": "<Polling_Station_Latitude_Longitude>",
      "rln_name_v1": "",
      "rln_name_v2": "",
      "rln_name_v3": "",
      "section_no": "<Section_Number>",
      "id": "<ID>",
      "name_v1": "",
      "name_v2": "",
      "name_v3": "",
      "ac_no": "<Assembly_Constituency_Number>",
      "st_code": "<State_Code>",
      "house_no": "<House_Number>",
      "idNumber": "<ID_Number>"
    },
    "summary": {
      "action": "<Action>",
      "details": []
    }
  }
}

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "details": {
      "issue_date": "<Issue_Date>",
      "father/husband": "<Father_Husband_Name>",
      "name": "<Name>",
      "img": "",
      "blood_group": "<Blood_Group>",
      "dob": "<Date_of_Birth>",
      "validity": {
        "transport": "",
        "non-transport": "<Validity_Non-Transport>"
      },
      "cov_details": [
        {
          "cov": "<Class_of_Vehicle_1>",
          "issue_date": "<Issue_Date_1>"
        },
        {
          "cov": "<Class_of_Vehicle_2>",
          "issue_date": "<Issue_Date_2>"
        }
      ],
      "address": "<Address>",
      "idNumber": "<ID_Number>"
    },
    "summary": {
      "action": "pass",
      "details": []
    }
  }
}

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "details": {
      "name": "<Name>",
      "idNumber": "<ID_Number>",
      "givenName": "<Given_Name>",
      "surName": "<SurName>",
      "doi": "<Date_of_Issue>",
      "applicationDate": "<Application_Date>",
      "typeOfApplication": "<Type_of_Application>"
    },
    "summary": {
      "action": "pass",
      "details": []
    }
  }
}

Success Response Details

The following table lists all the Success Response fields returned across the four OVD Documents

Parameter	Type	Description
status	string	The status of the API response
statusCode	string	The HTTP status code indicating the result of the request
result	object	The main object containing the response details and summary
details	object	An object containing specific details related to the document being verified
name	string	The name of the individual as per the document
idNumber	string	The unique identifier number on the document
rln_name	string	The name of the relative as per the Voter ID
rln_type	string	The relationship type of the relative. Returns single-character codes representing the relationship. The following list defines what each character code represents: F → Father M → Mother H → Husband W → Wife O → Other
gender	string	The gender of the individual
district	string	The district name as per the Voter ID
ac_name	string	The name of the assembly constituency
pc_name	string	The name of the parliamentary constituency
state	string	The state name as per the document
dob	string	The date of birth of the individual
age	integer	The age of the individual
issue_date	string	The issue date of the Driving License
blood_group	string	The blood group of the individual as per the Driving License
validity	object	An object containing the validity details of the Driving License
transport	string	The validity of the license for transport vehicles
non-transport	string	The validity of the license for non-transport vehicles
cov_details	array	An array containing the class of vehicles and their issue dates
address	string	The address of the individual as per the Driving License
givenName	string	The given name of the individual as per the passport
surName	string	The surname of the individual as per the passport
doi	string	The date of issue of the passport
applicationDate	string	The application date of the passport
typeOfApplication	string	The type of passport application
summary	object	An object containing the summary of the verification
action	string	The action derived from the verification result

Error Responses

The following are some error responses from the API.

Invalid Type
Not Found

{
  "status": "failure",
  "statusCode": "400",
  "result": {
    "error": "idType should be one of [pan, voterid, passport, dl]",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "111",
          "message": "Invalid id type"
        },
        {
          "code": "110",
          "message": "Database check failed"
        }
      ]
    }
  }
}

{
    "status": "failure",
    "statusCode": "422",
    "error": "Entered id is not found in any database"
}

Error Response Details

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

Status Code	Error Message	Error Description
400	idType should be one of [pan, voterid, passport, dl]	The request has an invalid `idType` input
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
403	Access Denied	Please contact the HyperVerge team for resolution
422	Entered id is not found in any database	The provided idNumber or fileNumber has no matching record in the database
429	Too many requests	You have exceeded the configured limit on the number of transactions permitted in a minute. Please contact the HyperVerge team for resolution
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Inputs​

Requests​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​