Central Database Check API

This document outlines the details of the Central Database Check API.

API Description

Objective

The Central Database Check API validates a user's information against their record retrieved from central government databases for the following OVDs (Officially Valid Documents). Each OVD type is verified against a specific database.

PAN (Income Tax Department)
Voter ID (Election Commission of India - ECI)
Passport (Ministry of External Affairs - MEA)
Driving License (Ministry of Road Transport and Highways - VAHAN/Sarathi)

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 Central Database Check 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 Central Database Check API.

API Request Details

Method - `POST`

Headers

Header	Mandatory / Optional	Description	Input Format
`content-type`	Mandatory	This parameter defines 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.	Not Applicable - this is a unique value
`appKey`	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	Not Applicable - this is a unique value
`transactionId`	Mandatory	A unique identifier for tracking a user journey	Not Applicable - 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 Central Database Check API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
`idType`	Mandatory	string	The type of identification document being verified	`pan`, `voterid`, `passport`, or `dl`	Not Applicable
`idNumber`	Mandatory (for PAN, Voter ID, and Driving License)	string	The unique identification number printed on the respective document. Not required when `idType` is `passport`.	Not Applicable	Not Applicable
`fileNumber`	Mandatory (only when `idType` is `passport`)	string	The Passport Reference File Number (PRFN) found on the last page of the passport booklet. This is distinct from the actual passport number.	Not Applicable	Not Applicable
`dob`	Mandatory (only for `passport` and `dl`)	string	The date of birth of the user, as mentioned in the OVD	DD-MM-YYYY	Not Applicable

Request

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 '{
    "idType": "pan",
    "idNumber": "<Enter_PAN_Number>"
}'

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 '{
    "idType": "voterid",
    "idNumber": "<Enter_Voter_ID_Number>"
}'

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 '{
    "idType": "passport",
    "fileNumber": "<Enter_File_Number>",
    "dob": "<Enter_DOB_dd-mm-yyyy>"
}'

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 '{
    "idType": "dl",
    "idNumber": "<Enter_DL_Number>",
    "dob": "<Enter_DOB_dd-mm-yyyy>"
}'

Success Response

The following are the success 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 Central Database Check 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 Central Database Check 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 Central Database Check API 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	Error Resolution
400	idType should be one of [pan, voterid, passport, dl]	The request has an invalid `idType` input	Provide a valid `idType` value: `pan`, `voterid`, `passport`, or `dl`
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values	Provide valid `appId` and `appKey` in the request headers. Check the dashboard's credentials tab
403	Access Denied	The provided credentials do not have access to this API	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	Verify that the provided document number is correct and corresponds to an existing record
429	Too many requests	You have exceeded the configured limit on the number of transactions permitted in a minute	Contact the HyperVerge team to review your rate limit configuration
500	Internal Server Error	There is an issue with the service. Kindly contact the HyperVerge Team for support.	Contact the HyperVerge team for investigation and resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​