Vendor Validation API

The following document outlines the details of the Vendor Validation API.

API Description

Objective

The Vendor Validation API streamlines Know Your Business (KYB) checks by combining five critical verification services into a single request.

Input	Output
PAN, name on card, date of birth, Udyam reference number, IFSC, account number, and GSTIN	Comprehensive verification results including PAN verification, Section 206AB compliance, Udyam Aadhaar verification, bank account validation, and GSTIN details. The complete list of output fields is available in the Success Response Details section

Vendor Validation API

The Vendor Validation API combines multiple verification services to provide a comprehensive KYB solution. This includes PAN verification through NSDL, Section 206AB compliance checks, Udyam Aadhaar verification, bank account validation via penny drop, and GSTIN verification - all in a single API call.

API URL

https://ind-engine.thomas.hyperverge.co/v1/async/vendorValidation

API Endpoint

vendorValidation

Overview

The Vendor Validation 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 Vendor Validation API.

Verification Services

The API automatically triggers the following verification services based on the provided parameters:

Service	Triggered When	Function
PAN Verification (NSDL)	`pan`, `nameOnCard`, `dateOfBirth` provided	Validates PAN against NSDL records and matches name/DOB
Section 206AB Compliance	`pan` provided	Checks if PAN falls under higher TDS category for non-filing
Udyam Aadhaar Verification	`udyamReferenceNumber` provided	Authenticates Udyam number and retrieves business details
Bank Account Verification	`accountNumber`, `ifsc` provided	Validates account ownership via ₹1 penny drop transaction
GSTIN Verification	`gstin` provided	Retrieves complete GST registration and compliance details

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
transactionid	Mandatory	The unique transaction ID for the user journey	Not Applicable - this is a unique value

Input

The following table provides the details of the parameters required for the Vendor Validation API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`pan`	Optional	The ten-digit alphanumeric PAN identifier	Format: 'CCCCCDDDDC' 'C' represents a character and 'D' represents a digit	Not Applicable
`nameOnCard`	Optional	The name as reflected in PAN	Not Applicable	Not Applicable
`dateOfBirth`	Optional	The date of birth as reflected in PAN	Not Applicable	Not Applicable
`udyamReferenceNumber`	Optional	The Udyam Number of the organisation	Not Applicable	Not Applicable
`ifsc`	Optional	The IFSC of the account's branch	Not Applicable	Not Applicable
`accountNumber`	Optional	The account number associated with the bank account	Not Applicable	Not Applicable
`gstin`	Optional	The GSTIN Number	Not Applicable	Not Applicable

Asynchronous API Workflow with Webhook Notification

This API follows an asynchronous processing model. When you initiate a request, the response only indicates that the request was received and is being processed. The final result is delivered via a webhook once processing is complete.

Three-Step Process Overview

The Vendor Validation API operates through a three-step asynchronous workflow that combines multiple validation services:

Step 1: Initiate Request - Submit your vendor validation request to the API endpoint
- Send a POST request with vendor details (PAN, name, DOB, Udyam number, IFSC, account number, GSTIN)
- Receive an immediate response with actionStatus: REQUEST_PROCESSING
- The response includes a requestId and transactionId for tracking the request
- This confirms your request was received and is being processed asynchronously
Step 2: Backend Processing & Webhook Notification - The system processes your request through multiple validation APIs
- The Vendor Validation API internally combines five different validation services
- Once all validations complete successfully, a webhook is automatically triggered
- You receive a webhook notification indicating processing is complete
- The webhook payload contains the requestId needed for retrieving final results
Step 3: Fetch Results - Retrieve the combined validation results
- Use the requestId received from the webhook notification
- Make a request to the Fetcher API endpoint with the requestId
- Receive a success response containing combined results
- Results include comprehensive vendor validation data and risk assessment from all integrated services

Step 1: Initiate Request To API

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/async/vendorValidation' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionid: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "pan": "<Enter_the_PAN>",
    "nameOnCard": "<Enter_the_name_on_card>",
    "dateOfBirth": "<Enter_the_date_of_birth>",
    "udyamReferenceNumber": "<Enter_the_udyam_reference_number>",
    "ifsc": "<Enter_the_IFSC>",
    "accountNumber": "<Enter_the_account_number>",
    "gstin": "<Enter_the_GSTIN>"
}'

Response:

{
    "status": "success",
    "statusCode": 200,
    "metadata": {
        "transactionId": "<Transaction_ID>",
        "requestId": "<Request_ID>"
    },
    "result": {
        "actionStatus": "REQUEST_PROCESSING"
    }
}

Step 2: Webhook Configuration

curl --location 'https://ind-thomas.hyperverge.co/v1/configWebhook' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionid: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "webhookUrl": "<Enter_the_webhook_URL>",
    "events": [
        "VENDOR_VALIDATION_STATUS"
    ]
}'

Webhook Response:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "message": "Final response is ready to fetch",
        "requestId": "<Request_ID>"
    }
}

Step 3: Request To Fetcher API

After receiving the final result from the webhook, you'll need to include the requestId—obtained from either the initial API response or the webhook notification—in your request to fetch the complete results.

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/async/vendorValidation?requestId=<Request_ID>' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--header 'content-type: application/json'

Success Response

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

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "apiStatusCode": 200,
        "apiOutput": {
            "status": "success",
            "statusCode": 200,
            "result": {
                "nsdlPanVerificationResult": {
                    "status": "success",
                    "statusCode": 200,
                    "result": {
                        "pan": "<PAN_Number>",
                        "panStatus": "<PAN_Status>",
                        "name": "<Name_Match_Status>",
                        "dateOfBirth": "<DOB_Match_Status>"
                    },
                    "metaData": {
                        "requestId": "<Request_ID>"
                    }
                },
                "Section206ABPANCheckResult": {
                    "status": "success",
                    "statusCode": "200",
                    "result": {
                        "data": {
                            "pan": "<PAN_Number>",
                            "name": "<Name>",
                            "pan_status": "<PAN_Status>",
                            "panAllotmentDate": "<Allotment_Date>",
                            "financialYear": "<Financial_Year>",
                            "specifiedPersonForHighRate": "<High_Rate_Status>"
                        },
                        "timestamp": "<Timestamp>"
                    }
                },
                "udyamAadhaarVerificationResult": {
                    "status": "success",
                    "statusCode": 200,
                    "result": {
                        "message": "<Message>",
                        "address": {
                            "door_no": "<Door_Number>",
                            "building": "<Building>",
                            "area": "<Area>",
                            "block": "<Block>",
                            "street": "<Street>",
                            "city": "<City>",
                            "district": "<District>",
                            "state": "<State>",
                            "pincode": "<Pincode>"
                        },
                        "documentId": "<Document_ID>",
                        "majorActivity": "<Major_Activity>",
                        "enterpriseType": "<Enterprise_Type>",
                        "yearOfClassification": "<Year_Of_Classification>",
                        "dateOfClassification": "<Date_Of_Classification>",
                        "organizationType": "<Organization_Type>",
                        "name": "<Organization_Name>",
                        "mobile": "<Mobile_Number>",
                        "email": "<Email_Address>",
                        "dateOfIncorporation": "<Incorporation_Date>",
                        "dateOfCommencement": "<Commencement_Date>",
                        "dateOfUdyamRegistration": "<Registration_Date>",
                        "districtIndustrialCentre": "<District_Industrial_Centre>",
                        "msmeDistrictIndustrialCentre": "<MSME_District_Industrial_Centre>",
                        "socialCategory": "<Social_Category>",
                        "nicData": {
                            "nic_2_digit": "<NIC_2_Digit>",
                            "nic_4_digit": "<NIC_4_Digit>",
                            "nic_5_digit": "<NIC_5_Digit>"
                        },
                        "enterpriseUnits": [
                            {
                                "name": "<Unit_Name>",
                                "address": {
                                    "door_no": "<Door_Number>",
                                    "building": "<Building>",
                                    "area": "<Area>",
                                    "block": "<Block>",
                                    "street": "<Street>",
                                    "city": "<City>",
                                    "district": "<District>",
                                    "state": "<State>",
                                    "pincode": "<Pincode>"
                                }
                            }
                        ]
                    },
                    "metaData": {
                        "requestId": "<Request_ID>"
                    }
                },
                "checkBankAccountResult": {
                    "status": "success",
                    "statusCode": "200",
                    "result": {
                        "bankResponse": "<Bank_Response>",
                        "ifsc": "<IFSC_Code>",
                        "accountNumber": "<Account_Number>",
                        "accountName": "<Account_Name>",
                        "bankTxnStatus": "<Transaction_Status>"
                    }
                },
                "GSTINDetailsRetrievalResult": {
                    "status": "success",
                    "statusCode": 200,
                    "result": {
                        "basicDetails": {
                            "gstin": "<GSTIN>",
                            "ekycFlag": "<EKYC_Flag>",
                            "compositionRate": "<Composition_Rate>",
                            "percentTaxInCash": "<Tax_Percentage>",
                            "aggreTurnOverFY": "<Aggregate_Turnover_FY>",
                            "registrationType": "<Registration_Type>",
                            "aggreTurnOver": "<Aggregate_Turnover>",
                            "businessNature": ["<Business_Nature>"],
                            "registrationDate": "<Registration_Date>",
                            "registrationStatus": "<Registration_Status>",
                            "percentTaxInCashFY": "<Tax_Percentage_FY>",
                            "memberDetails": ["<Member_Details>"],
                            "natureOfCoreBusinessActivity": "<Core_Business_Activity>",
                            "aadhaarVerified": "<Aadhaar_Verification_Status>",
                            "legalBusinessName": "<Legal_Business_Name>",
                            "constitutionOfBusiness": "<Business_Constitution>",
                            "tradeName": "<Trade_Name>",
                            "centralJurisdiction": "<Central_Jurisdiction>",
                            "isEInvoiceMandated": "<EInvoice_Mandated>",
                            "stateJurisdiction": "<State_Jurisdiction>",
                            "cancellationDate": "<Cancellation_Date>",
                            "isEInvoiceOpted": "<EInvoice_Opted>"
                        },
                        "hsnDetails": {
                            "goods": [
                                {
                                    "hsnCode": "<HSN_Code>",
                                    "hsnDescription": "<HSN_Description>"
                                }
                            ],
                            "services": [
                                {
                                    "hsnCode": "<HSN_Code>",
                                    "hsnDescription": "<HSN_Description>"
                                }
                            ]
                        },
                        "branchDetails": {
                            "message": "<Message>",
                            "principalAddress": {
                                "address": "<Principal_Address>",
                                "natureOfBusiness": "<Nature_Of_Business>"
                            },
                            "additionalAddresses": [
                                {
                                    "address": "<Additional_Address>",
                                    "natureOfBusiness": "<Nature_Of_Business>"
                                }
                            ]
                        },
                        "filingDetails": {
                            "filingStatus": [
                                [
                                    {
                                        "finYear": "<Financial_Year>",
                                        "returnType": "<Return_Type>",
                                        "returnPeriod": "<Return_Period>",
                                        "modeOfFiling": "<Filing_Mode>",
                                        "dateOfFiling": "<Filing_Date>"
                                    }
                                ]
                            ]
                        },
                        "allFiling": [],
                        "liabilityPaidDetails": {
                            "currFinYear": "<Current_Financial_Year>",
                            "prevFinYear": "<Previous_Financial_Year>",
                            "prevTotalPct": "<Previous_Total_Percentage>",
                            "currDetails": [
                                {
                                    "period": "<Period>",
                                    "liabPaidPct": "<Liability_Paid_Percentage>"
                                }
                            ],
                            "prevDetails": [
                                {
                                    "period": "<Period>",
                                    "liabPaidPct": "<Liability_Paid_Percentage>"
                                }
                            ]
                        },
                        "turnOver": null
                    },
                    "metaData": {
                        "requestId": "<Request_ID>",
                        "transactionId": "<Transaction_ID>"
                    }
                }
            },
            "metadata": {
                "requestId": "<Request_ID>",
                "transactionId": "<Transaction_ID>"
            }
        }
    }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	number	The HTTP status code of the response
result.apiStatusCode	number	The API status code for the vendor validation process
result.apiOutput.status	string	The status of the API output
result.apiOutput.statusCode	number	The status code of the API output
result.apiOutput.result.nsdlPanVerificationResult.status	string	The status of the NSDL PAN verification
result.apiOutput.result.nsdlPanVerificationResult.statusCode	number	The status code of the NSDL PAN verification
result.apiOutput.result.nsdlPanVerificationResult.result.pan	string	The permanent account number identifier
result.apiOutput.result.nsdlPanVerificationResult.result.panStatus	string	The validity status of the PAN in the ITD database
result.apiOutput.result.nsdlPanVerificationResult.result.name	string	The status indicating whether the provided name matches PAN records
result.apiOutput.result.nsdlPanVerificationResult.result.dateOfBirth	string	The status indicating whether the provided date of birth matches PAN records
result.apiOutput.result.Section206ABPANCheckResult.status	string	The status of the Section 206AB PAN check
result.apiOutput.result.Section206ABPANCheckResult.statusCode	string	The status code of the Section 206AB PAN check
result.apiOutput.result.Section206ABPANCheckResult.result.data.pan	string	The permanent account number
result.apiOutput.result.Section206ABPANCheckResult.result.data.name	string	The name associated with the PAN
result.apiOutput.result.Section206ABPANCheckResult.result.data.pan_status	string	The PAN status for TDS applicability under Section 206AB
result.apiOutput.result.Section206ABPANCheckResult.result.data.panAllotmentDate	number	The allotment date of the PAN
result.apiOutput.result.Section206ABPANCheckResult.result.data.financialYear	string	The financial year for the Section 206AB check
result.apiOutput.result.Section206ABPANCheckResult.result.data.specifiedPersonForHighRate	string	The Section 206AB higher TDS category applicability
result.apiOutput.result.udyamAadhaarVerificationResult.status	string	The status of the Udyam Aadhaar verification
result.apiOutput.result.udyamAadhaarVerificationResult.statusCode	number	The status code of the Udyam Aadhaar verification
result.apiOutput.result.udyamAadhaarVerificationResult.result.message	string	The message confirming if the Udyam enterprise exists
result.apiOutput.result.udyamAadhaarVerificationResult.result.address	object	The registered address of the organisation
result.apiOutput.result.udyamAadhaarVerificationResult.result.documentId	string	The Udyam Aadhaar number
result.apiOutput.result.udyamAadhaarVerificationResult.result.majorActivity	string	The primary business activity
result.apiOutput.result.udyamAadhaarVerificationResult.result.enterpriseType	string	The MSME classification
result.apiOutput.result.udyamAadhaarVerificationResult.result.yearOfClassification	string	The financial year for MSME classification
result.apiOutput.result.udyamAadhaarVerificationResult.result.dateOfClassification	string	The date MSME classification was assigned
result.apiOutput.result.udyamAadhaarVerificationResult.result.organizationType	string	The legal structure of the organisation
result.apiOutput.result.udyamAadhaarVerificationResult.result.name	string	The name of the organisation
result.apiOutput.result.udyamAadhaarVerificationResult.result.mobile	string	The registered mobile number
result.apiOutput.result.udyamAadhaarVerificationResult.result.email	string	The registered email ID
result.apiOutput.result.udyamAadhaarVerificationResult.result.dateOfIncorporation	string	The organisation's incorporation date
result.apiOutput.result.udyamAadhaarVerificationResult.result.dateOfCommencement	string	The business commencement date
result.apiOutput.result.udyamAadhaarVerificationResult.result.dateOfUdyamRegistration	string	The Udyam Aadhaar registration date
result.apiOutput.result.udyamAadhaarVerificationResult.result.districtIndustrialCentre	string	The district industrial centre name
result.apiOutput.result.udyamAadhaarVerificationResult.result.msmeDistrictIndustrialCentre	string	The MSME district industrial centre name
result.apiOutput.result.udyamAadhaarVerificationResult.result.socialCategory	string	The social category of the owner
result.apiOutput.result.udyamAadhaarVerificationResult.result.nicData	object	The national industrial classification codes
result.apiOutput.result.udyamAadhaarVerificationResult.result.enterpriseUnits	array	The name and address of enterprise units
result.apiOutput.result.checkBankAccountResult.status	string	The status of the bank account verification
result.apiOutput.result.checkBankAccountResult.statusCode	string	The status code of the bank account verification
result.apiOutput.result.checkBankAccountResult.result.bankResponse	string	The bank verification result
result.apiOutput.result.checkBankAccountResult.result.ifsc	string	The bank branch identifier
result.apiOutput.result.checkBankAccountResult.result.accountNumber	string	The account number provided
result.apiOutput.result.checkBankAccountResult.result.accountName	string	The name on the bank account
result.apiOutput.result.checkBankAccountResult.result.bankTxnStatus	boolean	The transaction success status
result.apiOutput.result.GSTINDetailsRetrievalResult.status	string	The status of the GSTIN details retrieval
result.apiOutput.result.GSTINDetailsRetrievalResult.statusCode	number	The status code of the GSTIN details retrieval
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.gstin	string	The goods and services tax identification number
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.ekycFlag	string	The flag indicating if eKYC was performed
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.compositionRate	string	The simplified composition tax rate
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.percentTaxInCash	string	The percentage of tax paid in cash
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.aggreTurnOverFY	string	The aggregate turnover for the financial year
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.registrationType	string	The type of GST registration
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.aggreTurnOver	string	The aggregate turnover details
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.businessNature	array	The nature of business activities
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.registrationDate	string	The GST registration date
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.registrationStatus	string	The GST registration status
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.percentTaxInCashFY	string	The cash tax paid for the financial year
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.memberDetails	array	The names of director members associated with GSTIN
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.natureOfCoreBusinessActivity	string	The primary business domain
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.aadhaarVerified	string	The Aadhaar verification status
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.legalBusinessName	string	The legal name as per GSTIN
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.constitutionOfBusiness	string	The type of business constitution
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.tradeName	string	The trade name of the business
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.centralJurisdiction	string	The central government tax jurisdiction
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.isEInvoiceMandated	string	The flag indicating whether e-Invoicing is mandated
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.stateJurisdiction	string	The state government tax jurisdiction
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.cancellationDate	string	The GSTIN cancellation date if applicable
result.apiOutput.result.GSTINDetailsRetrievalResult.result.basicDetails.isEInvoiceOpted	string	The flag indicating whether e-Invoicing is opted
result.apiOutput.result.GSTINDetailsRetrievalResult.result.hsnDetails	object	The harmonized system of nomenclature codes
result.apiOutput.result.GSTINDetailsRetrievalResult.result.branchDetails	object	The list of branches with address and nature of business
result.apiOutput.result.GSTINDetailsRetrievalResult.result.filingDetails	object	The tax return filing status and history
result.apiOutput.result.GSTINDetailsRetrievalResult.result.liabilityPaidDetails	object	The details of paid tax liabilities
metadata.requestId	string	The unique request identifier
metadata.transactionId	string	The transaction identifier

Error Responses

The following are some error responses from the Vendor Validation API:

Invalid Parameters
Missing/Invalid Credentials
Record Not Found

{
    "status": "failure",
    "statusCode": 400,
    "error": "Invalid parameters provided",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

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

{
    "status": "failure",
    "statusCode": 404,
    "error": "Record Not Found",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error
External Source Downtime

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

{
    "status": "failure",
    "statusCode": 503,
    "error": "External source downtime"
}

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
400	Invalid parameters provided	This error occurs when invalid parameters are provided in the request
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
404	Record Not Found	This error occurs when the provided parameters do not match any records in the database
500	Internal Server Error	Please contact HyperVerge for investigation
503	External source downtime	This error occurs when the external source is down

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

Verification Services​

API Request Details

Method - POST

Headers

Input​

Asynchronous API Workflow with Webhook Notification​

Three-Step Process Overview​

Step 1: Initiate Request To API​

Step 2: Webhook Configuration​

Step 3: Request To Fetcher API​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​