Fetch PAN ID and Date of Birth API

API Usage Guidelines

The Fetch PAN ID and Date of Birth API is designed specifically for data auto-population purposes, not for PAN validation or verification.

API Description

Objective

The Fetch PAN ID and Date of Birth API, also known as the "Pre-Fill PAN API", retrieves a user's ten-digit Permanent Account Number (PAN) and date of birth using their registered name and mobile number.

Input	Output
The user's name as registered in their PAN The mobile number linked to their PAN	The ten-digit alphanumeric PAN ID of the user The date of birth of the user

API URL

https://ind-engine.thomas.hyperverge.co/v1/preFillPAN

Endpoint

preFillPAN

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	Description	Mandatory or Optional	Allowed Values	Default Value
consentPurpose	The remark representing the consent of the customer to fetch their PAN ID and date of birth along with its purpose of use. For example, "Customer consent provided to fetch the PAN data for testing".	Mandatory	Not Applicable	Not Applicable
name	The name of the user	Mandatory	Not Applicable	Not Applicable
mobile	The 10 digit mobile number of the user	Mandatory	Not Applicable	Not Applicable

Sample Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/preFillPAN' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "consentPurpose": "Fetch data for testing",
    "name": "<User_Name>",
    "mobile": "<User_Mobile_Number>"
}'

Success Response

The following is a sample success response.

{
  "status": "success",
  "statusCode": "200",
  "result": {
      "dob": "<The_DOB_of_the_User>",
      "pan": "<The_10_digit_PAN_of_the_User>"
  }
}

Success Response Details

The following table provides the details of the fields in a success response.

Parameter	Type	Description
dob	string	The date of birth of the user in “YYYY-MM-DD” format
pan	string	The ten-digit alphanumeric permanent account number (the PAN ID) associated with the user

Failure Response

The following is a sample response when no match is found against the name and the mobile number combination used in the request.

{
  "status": "failure",
  "statusCode": 404,
  "error": "Customer not found"
}

Error Responses

The following are the sample error responses for the API.

Missing Name Input

{
  "status": "failure",
  "statusCode": 400,
  "error": "Name cannot be empty"
}

Missing consentPurpose Input

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid consentPurpose"
}

Invalid Mobile Number Format

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid mobile number format"
}

Invalid Credentials

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

Customer Not found

{
  "status": "failure",
  "statusCode": 404,
  "error": "Customer not found"
}

Too Many Requests

{
  "status": "failure",
  "statusCode": 429,
  "error": "Rate Limit Exceeded"
}

Internal Server Error

{
    "statusCode": 500,
    "status": "failure",
    "error": "Internal Server Error"
}

Issue with External Service

{
  "status": "failure",
  "statusCode": 504,
  "error": "Issue with external service"
}

Failure and Error Response Details

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

Status Code	Error Message	Error Description
400	Invalid mobile number format	The mobile number of the customer should only be a ten digit input.
400	Name cannot be empty	The name of the customer is a mandatory input in the request.
400	Invalid consentPurpose	The consentPurpose parameter is a mandatory input in the request.
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials.
404	Customer not found	The customer's phone number and their name combination does not match any PAN record.
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit set for your credentials.
500	Internal Server Error	There was an error either with the request or with HyperVerge's server. Please check the API request's headers or contact the HyperVerge team for resolution.
504	Issue with external service	There is an issue with the service. Kindly contact the HyperVerge Team for support.