DIN from PAN API

This document outlines the details of the DIN from PAN API.

API Description

Objective

The DIN from PAN API facilitates the retrieval of a Director Identification Number (DIN) from a Permanent Account Number (PAN).

Input	Output
The 10-digit PAN of the user	The details corresponding to the user such as name, address, tax status, and more.

API URL

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

API Endpoint

dinFromPan

Overview

The DIN from PAN 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 DIN from PAN 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)

Input

The following table provides the details of the parameters required for the DIN from PAN API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
panNumber	Mandatory	string	The PAN of the user, which is a unique identifier for taxpayers in India	Format: 'CCCCCDDDDC' format, where 'C' represents a character and 'D' represents a digit	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the DIN from PAN API:

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/dinFromPan' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "panNumber": "<Enter_the_PAN>"
}'

Success Response

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

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "message": "<Message_About_The_Result>",
    "details": {
      "panNumber": "<Masked_PAN_Number>",
      "dinNumber": "<Masked_DIN_Number>",
      "dinStatus": "<DIN_Status>",
      "firstName": "<First_Name_Of_The_user>",
      "middleName": "<Middle_Name_Of_The_user_If_Available>",
      "lastName": "<Last_Name_Of_The_user>",
      "dateOfBirth": "<Date_Of_Birth_in_DD-MMM-YYYY_Format>",
      "fatherFirstName": "<Father's_First_Name>",
      "fatherMiddleName": "<Father's_Middle_Name_If_Available>",
      "fatherLastName": "<Father's_Last_Name>",
      "residentOfIndia": "<Is_Resident_Of_India_Y/N>",
      "membershipNumber": "<Membership_Number_If_Available>"
    }
  },
  "metaData": {
    "requestId": "<Unique_Request_Identifier>",
    "transactionId": "<Unique_Transaction_Identifier>"
  }
}

Success Response Details

The following table outlines the details of the success response from the DIN from PAN API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code of the response
message	string	The result message of the request
panNumber	string	The PAN of the user
dinNumber	string	The DIN of the user
dinStatus	string	The status of the DIN
firstName	string	The first name of the user
middleName	string	The middle name of the user
lastName	string	The last name of the user
dateOfBirth	string	The date of birth of the user in DD-MMM-YYYY format (the first three letters of the month's name are returned, e.g., NOV)
fatherFirstName	string	The first name of the user's father
fatherMiddleName	string	The middle name of the user's father
fatherLastName	string	The last name of the user's father
residentOfIndia	string	Indicates whether the user is a resident of India (Y/N)
membershipNumber	string	The membership number of the user
requestId	string	The unique identifier for the request
transactionId	string	The transaction ID associated with the request

Failure Response

The following is a failure response from the DIN from PAN API:

{
    "status": "failure",
    "statusCode": 404,
    "result": {
        "message": "Din Not Found"
    },
    "metaData": {
         "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Responses

The following are the error responses from the DIN from PAN API:

Invalid PAN

{
    "message": "Invalid Pan format",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Input Validation Error: Missing Parameter

{
    "message": "Input Validation Error: requires property \"panNumber\"",
    "statusCode": 400,
    "status": "failure"
}

Incorrect Data Type

{
    "message": "Input Validation Error: is not of a type(s) string",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials

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

Internal Server Error

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

External Downtime

{
          "message": "External vendor downtime",
          "statusCode": 503,
          "status": "failure",
          "error": "EXTERNAL_DOWNTIME",
          "metaData": {
             "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the DIN from PAN 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	Missing required request parameters	Some mandatory request parameters are missing in the API request made	Ensure all mandatory parameters are included in the request
400	Invalid Pan format	The 10-digit PAN is not in the CCCCCDDDDC format	Provide a valid PAN in the correct format
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
404	Din Not Found	The request has an invalid DIN that yielded no match in the database	Verify the PAN provided is correct and associated with a registered director
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
503	External Downtime	The external vendor service is temporarily unavailable	Retry the request after some time. If the issue persists, contact the HyperVerge team