Udyam Aadhaar Verification API

API Description

Objective

The Udyam Aadhaar Verification API validates an Udyam Aadhaar registration number associated with an organisation and retrieves its details.

Input	Output
The Udyam registration or reference number and the consent of the user	The details associated with the Udyam registration certificate. A complete list of details returned by the API is provided under the Success Response Details section

Udyam Registration

Udyam Registration is a system for registering Micro, Small, and Medium Enterprises (MSMEs) in India. The "Udyam" or "MSME" registration number is a unique 19-digit identification number given to entities registered under this system.

API URL

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

API Endpoint

udyamAadhaarVerification

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	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.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge.	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 specific user's interaction in your application(s).

Inputs

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

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
udyamReferenceNumber	Mandatory	The unique 19 character Udyam number of the organisation	Sample format: "UDYAM-AB-34-1234567"	Not Applicable
consent	Mandatory	The consent of the user to verify the Udyam number	"Y" or "N"	"Y"
returnClassificationDate	Optional	When enabled, this parameter returns the date and year when the business was last registered with Udyam in the response	"yes" or "no"	"no"

Request

The following section shows the standard curl request for the API.

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/udyamAadhaarVerification' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "udyamReferenceNumber": "<Enter_the_Udyam_ID>",
    "consent": "<Y/N>",
    "returnClassificationDate":"<yes/no>" 
}'

Success Response

The following is a sample response from the API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "message": "Enterprise exists",
        "address": {
            "door_no": "<door_no>",
            "building": "<building>",
            "area": "<area>",
            "block": "<block>",
            "street": "<street>",
            "city": "<city>",
            "state": "<state>",
            "district": "<district>",
            "pincode": "<pincode>"
        },
        "documentId": "<Udyam_registration_number>",
        "majorActivity": "Services",
        "enterpriseType": "Small",
        "yearOfClassification": "YYYY-YY", // returned when returnClassificationDate is enabled in the request 
        "dateOfClassification": "YYYY-MM-DD", // returned when returnClassificationDate is enabled in the request 
        "organizationType": "Private Limited Company",
        "name": "<name_of_the_organisation>",
        "mobile": "93*****594",
        "email": "john@example.com",
        "dateOfIncorporation": "2000-03-21",
        "dateOfCommencement": "2000-12-13",
        "dateOfUdyamRegistration": "2020-02-23",
        "districtIndustrialCentre": "<districtIndustrialCentre>",
        "msmeDistrictIndustrialCentre": "<msmeDistrictIndustrialCentre>",
        "socialCategory": "General",
        "nicData": {
            "nic_2_digit": "62 - Computer programming, consultancy and related activities",
            "nic_4_digit": "6201 - Computer programming activities",
            "nic_5_digit": "62013 - Providing software support and maintenance to the clients"
        },
        "enterpriseUnits": [
            {
                "name": "<name_of_the_organisation>",
                "address": {
                    "door_no": "<door_no>",
                    "building": "<building>",
                    "area": "<area>",
                    "block": "<block>",
                    "street": "<street>",
                    "city": "<city>",
                    "state": "<state>",
                    "district": "<district>",
                    "pincode": "<pincode>"
                }
            }
        ]
    },
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

Success Response Details

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

Parameter	Description
message	Confirms if the organisation exists on the Udyam Aadhaar database. For example, "Enterprise exists".
address	The registered address of the organisation
documentId	The Udyam registration number received from the user
majorActivity	The primary business activity of the organisation such as "Services" and "Manufacturing"
enterpriseType	The latest classification or enterprise type of the organisation such as "Small", "Medium" or "Large"
yearOfClassification	The year when the organization was last classified with Udyam
dateOfClassification	The date when the organization was last classified with Udyam (YYYY-MM-DD)
organizationType	The type of the organisation such as "Private Limited" or "LLP"
name	The name of the organisation
mobile	The mobile number of the organisation
email	The email-ID of the organisation
dateOfIncorporation	The date of incorporation of the organisation
dateOfCommencement	The date of commencement of the organisation
dateOfUdyamRegistration	The organisation's Udyam registration date
districtIndustrialCentre	The District Industrial Centre (DIC) of the organisation
msmeDistrictIndustrialCentre	The Ministry of Micro, Small and Medium Enterprises (MSME) District Industrial Centre of the Organisation
socialCategory	The social category of the organisation. For example,"General".
nicData	The National Industrial Classification codes of the organisation
enterpriseUnits	The name and address of all enterprise units of the organisation

Failure Response

The following is a response for no records found against the mobile number input:

{
    "statusCode": 400,
    "status": "failure",
    "error": "Udyam Registration Number does not exist"

    "metaData": {
      "requestId": "123456789",
      "transactionId": "abcd"
  }
}

Error Responses

The following are some error responses from the API:

Incorrect Udyam Format

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

Incorrect Consent Format

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

Bad Request

{
  "statusCode": 400,
  "status": "failure",
  "error": "Bad Request",
  	"metaData": {
      "requestId": "123456789",
      "transactionId": "abcd"
  }
}

User Consent is 'N'

{
  "statusCode": 400,
  "status": "failure",
  "error": "Consent should be provided",
  	"metaData": {
      "requestId": "123456789",
      "transactionId": "abcd"
  } 
}

Missing/Invalid Credentials

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

Internal Server Error

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error"
  	"metaData": {
      "requestId": "123456789",
      "transactionId": "abcd"
  }
}

Failure and Error Response Details

An error response from the 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
400	Input Validation Error: does not meet minimum length of 1	Either the Udyam reference number or the consent parameter in the request has an incorrect format.
400	Bad Request	Please recheck the request
400	Consent should be provided	The API failed to retrieve the information as the user's consent is mandatory to proceed with the processing.
400	Missing required request parameters.	Some mandatory request parameters are missing in the API request made. Check if "udyogReferenceNumber" and "consent" are provided in the request body.
400	Udyam Registration Number does not exist	The Udyam registration number in the request is invalid.
401	Missing/Invalid credentials	The appId / appKey is missing or incorrect in the request headers.
403	Access Denied	Please contact the HyperVerge team for resolution.
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution.