Masked PAN from DIN API

This document highlights the Masked PAN from DIN API details.

API Description

Objective

The Masked PAN from DIN API retrieves the PAN and identity details of an organization's director using their Director Identification Number (DIN).

Input	Output
The 8 digit DIN of the user	The director's masked PAN, the DIN status, personal details, and residency information. A complete list of details returned by the API is provided under the Success Response Details section

API URL

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

API Endpoint

maskedPanFromDin

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.

Parameter	Mandatory or Optional	Description	Allowed Values
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.	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)

Input

The following table outlines the parameter required in the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
dinNumber	The Director Identification Number (DIN) of the individual serving as the director in an organization	Mandatory	Not Applicable	Not Applicable

Request

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

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

Success Response

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

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "message": "<Message_About_The_Result>",
    "details": {
      "dinNumber": "<Masked_DIN_Number>",
      "dinStatus": "<DIN_Status>",
      "panNumber": "<Masked_PAN_Number>",
      "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": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

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

Parameter	Type	Description
dinNumber	string	The Director Identification Number (DIN), a unique identifier assigned to an individual who is a director of a company in India
dinStatus	string	The status of DIN
panNumber	string	The PAN of the user
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
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 API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
      "dinNumber": "<Masked_DIN_Number>",
      "dinStatus": "<DIN_Status>", // deactivated 
      "panNumber": "<PAN_Number>",
      "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": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Responses

The following are the error responses from the API:

Invalid DIN

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

Input Validation Error: Invalid format

{
    "message": "Number must be an 8-digit numeric value",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Incorrect Data Type

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

Missing Parameter: DIN

{
    "message": "Input Validation Error: requires property \"dinNumber\"",
    "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>"
      }
   }

Failure and 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
200		The DIN Status of the director is deactivated, or the DIN is no longer in use
400	Din Not Found	The request has an invalid DIN that yielded no match in the database
400	Number must be an 8-digit numeric value	The entered DIN is incorrect
400	Input Validation Error: is not of a type(s) string	The entered DIN is not a string value. Please check for missing "".
400	Input Validation Error: requires property "dinNumber"	The DIN is missing in the API request made
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	External Downtime	Please contact the HyperVerge team for resolution