Driving Licence Verification and Extraction API

API Description

Objective

The Driving Licence Verification and Extraction API authenticates a user by verifying their identity details against the central database maintained by the Ministry of Road Transport and Highways (VAHAN/Sarathi).

Input	Output
The driving licence number and the date of birth of the customer.	A JSON response with the details of the customer extracted from their driving licence record.

API URL

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

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	Type	Description	Valid Values
content-type	Mandatory	string	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	string	The application ID shared by HyperVerge	Not Applicable - this is a unique value.
appKey	Mandatory	string	The application key shared by HyperVerge	Not Applicable - this is a unique value.
transactionId	Mandatory	string	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application.

Input

The following table provides the complete information on the parameters used in the request body for the API call.

Parameter	Mandatory or Optional	Type	Description	Valid Values
dlNumber	Mandatory	string	The sixteen digit unique number associated with the customer's driving licence.	Not Applicable - this is a unique value.
dob	Mandatory	string	The date of birth of the customer in 'DD-MM-YYYY' format.	Not Applicable.
returnState	Optional	string	The parameter determines if the response should include the state information associated with the driving licence.	"yes" or "no" Note The default value is "no" when the parameter is not used in the request.

Sample Request

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

curl --location --request POST 'https://ind-verify.hyperverge.co/api/checkDL' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "dlNumber": "<Enter_The_DL_Number>",
    "dob": "<DD-MM-YYYY>",
    "returnState": "<yes_or_no>"
}'

Success Response Sample

The following is a sample success response.

Including State

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "issue_date": "19-06-2018",
    "father/husband": "<The_Name_Of_The_Father_Or_Husband",
    "name": "ABHISHEK THOMAS T",
    "img": "",
    "blood_group": "B+",
    "dob": "<DD_MM_YYYY>",
    "dl_number": "TN702018000XXXX",
    "validity": {
      "transport": "",
      "non-transport": "19-06-2018 to 18-06-2038"
    },
    "cov_details": [
      {
        "cov": "MCWG",
        "issue_date": "19-06-2018"
      },
      {
        "cov": "LMV",
        "issue_date": "19-06-2018"
      }
    ],
    "address": "<The_Complete_Address>",
    "state": "TAMIL NADU"
  }
}

Generic Template without State

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "issue_date": "<Date of issue in DD-MM-YYYY format>",
    "father/husband": "<Name_Of_The_Father_Or_Husband>",
    "name": "<The_Name_of_the_User>",
    "img": "<The_Base64_Image_Of_The_Users_Profile_Photo>",
    "blood_group": "<The_Blood_Group_Of_The_User>",
    "dob": "<The_Date_Of_Birth_in_DD-MM-YYYY_Format>",
    "validity": {
      "non-transport": "<Date_Range, DD-MM-YYYY to DD-MM-YYYY>",
      "transport": ""
    },
    "cov_details": [
      {
        "issue_date": "<The_Date_Of_Issue/Issuing Authority>",
        "cov": "The_Coverage_Type_Of_License"
      }
    ],
    "address": "Address_Of_The_User_In_the_DL"
  }
}

Success Response Details

The following table provides the details of the optional field in the success response.

Parameter	Description
state	The field provides the state information associated with the driving license. Note This field is returned in the response only when the returnState parameter is set to yes in the request.

Failure Response Sample

The following is a sample response when no matching record is found against the input parameters.

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

Error Response Sample

The following are the sample error responses for the API.

Missing Date of Birth Input

{
  "status": "failure",
  "statusCode": "400",
  "error": "dob is required"
}

Missing Driving License Input

{
  "status": "failure",
  "statusCode": "400",
  "error": "dlNumber is required"
}

Blank Input - Driving License

{
    "status": "failure",
  	"statusCode": "400",
  	"error": "dlNumber is not allowed to be empty"
}

Blank Input - Date of Birth

{
    "status": "failure",
  	"statusCode": "400",
  	"error": "dob is not allowed to be empty"
}

Invalid Type used for DOB - 1

{
  	"status": "failure",
  	"statusCode": "400",
  	"error": "dob must be a number of milliseconds or valid date string"
}

Invalid Type used for DOB - 2

{
  	"status": "failure",
  	"statusCode": "400",
  	"error": "dob must be a string with one of the following formats [DD-MM-YYYY]"
}

Invalid Type used for returnState

{
  "status": "failure",
  "statusCode": "400",
  "error": "returnState must be one of [yes, no]"
}

Incorrect DL Number Length - Short

{
  	"status": "failure",
  	"statusCode": "400",
  	"error": "dlNumber length must be at least 9 characters long"
}

Incorrect DL Number Length - Long

{
  	"status": "failure",
  	"statusCode": "400",
  	"error": "dlNumber length must be less than or equal to 20 characters long"
}

Invalid Input

{
  "status": "failure",
  "statusCode": "422",
  "error": "Invalid value passed for an input"
}

Server Error 1

{
  "status": "failure",
  "statusCode": "500",
  "error": "internal server error"
}

Server Error 2

{
  "status": "failure",
  "statusCode": "500",
  "error": "Unexpected server error"
}

Service Unavailable - 1

{
  "status": "failure",
  "statusCode": "503",
  "error": "Data Source not Available"
}

Service Unavailable - 2

{
  "status": "failure",
  "statusCode": "503",
  "error": "Govt. database service unavailable"
}

Status Code	Error Message	Error Description
400	dob is required	The request does not have the mandatory dob parameter.
400	dlNumber is required	The request does not have the mandatory dlNumber parameter.
400	dlNumber is not allowed to be empty	The request has no value against the dlNumber parameter.
400	dob is not allowed to be empty	The request has no value against the dob parameter.
400	dob must be a number of milliseconds or valid date string	The data type of the dob input in the request is invalid. Kindly retry sending the request with a number representing milliseconds or a valid date string.
400	dob must be a string with one of the following formats [DD-MM-YYYY]	The format of the dob input in the request is invalid. Kindly retry sending the request with DD-MM-YYYY format.
400	returnState must be one of [yes, no]	The returnState input in the request is invalid. Kindly use either "yes" or "no" for the parameter.
400	dlNumber length must be at least 9 characters long	The length of the dlNumber input is too short. Kindly ensure that it is at least 9 characters long.
400	dlNumber length must be less than or equal to 20 characters long	The length of the dlNumber input is too long. Kindly ensure that it is less than or equal to twenty characters in length.
422	Invalid value passed for an input	The request has invalid values.
500	internal server error	Kindly check the request headers or contact the HyperVerge team for resolution.
500	Unexpected server error	Kindly check the request headers or contact the HyperVerge team for resolution.
503	Data Source not Available	There is some issue with the government service. Kindly retry the request after some time.
503	Govt. database service unavailable	There is some issue with the government service. Kindly retry the request after some time.