Disability Verification API

API Description

Objective

The Disability Verification API verifies an person with disability's disability information against authoritative government systems using the Unique Disability ID (UDID) and returns validated profile details, disability status, application state, and an optional certificate download link.

info

The Unique Disability ID (UDID) is a standardized identifier issued under the Government of India's UDID project (Department of Empowerment of Persons with Disabilities) to enable issuance and lifecycle management of disability certificates. Refer to the official portal for details: UDID portal.

Input	Output
The UDID, date of birth, and an optional flag to fetch certificate link	The verified disability profile. The complete list of output fields is available in the Success Response Details section

API URL

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

API Endpoint

disabilityVerification

Overview

The Disability Verification API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format 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	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 provides the details of the parameters required for the Disability Verification API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
idNumber	Mandatory	The UDID (Unique Disability ID) number assigned to the person with disability	Not Applicable	Not Applicable
dob	Mandatory	The date of birth of the person with disability	Format: DD-MM-YYYY	Not Applicable
getCertificate	Optional	The flag to include a certificate download URL in the response	Data Type: Boolean (true or false)	false

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/disabilityVerification' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
  "idNumber": "<Enter_the_UDID>",
  "dob": "<Enter_the_DoB_in_DD-MM-YYYY>",
  "getCertificate": <Enter_true_or_false>
}'

Success Response

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

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "data": {
      "id_number": "<ID_Number>",
      "dob": "<Date_of_Birth>",
      "details": {
        "application_number": "<Application_Number>",
        "udid_number": "<UDID_Number>",
        "regional_language": "<Regional_Language_Code>",
        "full_name": "<Full_Name>",
        "father_name": "<Father_Name>",
        "gender": "<Gender>",
        "mobile": "<Mobile_Number>",
        "email": "<Email_Address>",
        "current_address": "<Current_Address>",
        "current_state_code": "<Current_State_Code>",
        "current_district_code": "<Current_District_Code>",
        "current_subdistrict_code": "<Current_Subdistrict_Code>",
        "current_village_code": "<Current_Village_Code>",
        "current_pincode": "<Current_Pincode>",
        "disability_type_id": "<Disability_Type_Id>",
        "application_status": "<Application_Status_Code>",
        "pwd_card_expiry_date": "<PWD_Card_Expiry_Date>",
        "disability_type_pt": "<Disability_Type_Classification>",
        "certificate_generate_date": "<Certificate_Generate_Date>",
        "aadhaar_number": "<Aadhaar_Number>",
        "transfer_date": "<Transfer_Date>",
        "rejected_date": "<Rejected_Date>",
        "is_ekyc": "<Is_eKYC>",
        "disability_percentage": "<Disability_Percentage>",
        "disability_type": "<Disability_Type>",
        "pwd_application_status": {
          "status_name": "<Application_Status_Name>"
        },
        "pwd_dispatch": {
          "dispatch_date": "<Dispatch_Date>"
        }
      },
      "link": "<Certificate_Download_URL>" // returned when the getCertificate parameter is enabled in the request body
    },
    "status_code": 200,
    "success": true,
    "message": "<Message>",
    "message_code": "<Message_Code>"
  },
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The status code of the response
data	object	The container for the input echo and verified disability details
id_number	string	The UDID number assigned to the person with disability
dob	string	The date of birth the person with disability
details	object	The object containing verified disability and application information
application_number	string	The unique application reference number
udid_number	string	The verified UDID number
regional_language	string	The regional language code
full_name	string	The full name of the person with disability
father_name	string	The father’s name of the person with disability
gender	string	The gender of the person with disability
mobile	string	The registered mobile number
email	string	The registered email address
current_address	string	The current residential address
current_state_code	string	The state code for the current address
current_district_code	string	The district code for the current address
current_subdistrict_code	string	The sub-district code for the current address
current_village_code	string	The village code for the current address
current_pincode	string	The postal code for the current address
disability_type_id	string	The identifier representing the type of disability
application_status	string	The current application status code
pwd_card_expiry_date	string	The expiry date of the PWD card
disability_type_pt	string	The disability classification type
certificate_generate_date	string	The date when the certificate was generated
aadhaar_number	string	The Aadhaar number linked to the certificate
transfer_date	string	The date when the record was transferred
rejected_date	string	The date when the application was rejected
is_ekyc	string	The indicator of whether eKYC verification was completed
disability_percentage	string	The percentage representing the disability
disability_type	string	The name of the disability type
pwd_application_status	object	The container for the application status details
pwd_application_status.status_name	string	The human-readable application status description
pwd_dispatch	object	The container for the UDID card dispatch details
pwd_dispatch.dispatch_date	string	The date when the UDID card was dispatched
link	string	The direct URL to download the disability certificate
status_code	integer	The numeric status code of API response
success	boolean	The indicator of whether the request was successful
message	string	The descriptive message indicating the request status
message_code	string	The status of the request e.g., "success"
requestId	string	The unique identifier for the request
transactionId	string	The unique identifier for the user journey

Error Responses

The following are some error responses from the API:

Bad Request - Invalid DoB

{
  "message": "Input Validation Error: DoB should be in DD-MM-YYYY format",
  "statusCode": 400,
  "status": "failure"
}

Bad Request - Invalid idNumber Length

{
  "message": "Input Validation Error: idNumber does not meet minimum length of 18",
  "statusCode": 400,
  "status": "failure"
}

Bad Request - Invalid getCertificate

{
  "message": "Input Validation Error: getCertificate is not one of enum values: true,false",
  "statusCode": 400,
  "status": "failure"
}

Unprocessable Entity - Invalid idNumber

{
  "status": "failure",
  "error": "idnumber is invalid",
  "statusCode": 422,
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

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	Error Description
400	Input Validation Error: DoB should be in DD-MM-YYYY format	The request is missing the dob input or has an incorrect date format
400	Input Validation Error: idNumber does not meet minimum length of 18	The request is missing the idNumber input or has an invalid value
400	Input Validation Error: getCertificate is not one of enum values: true,false	The request has an invalid getCertificate input that is not true or false
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials
422	idnumber is invalid	The request has an idNumber value that is invalid or does not exist
500	Internal Server Error	The request has an internal server error. Please check the request headers or contact the HyperVerge team for investigation