Prefill Orchestration API

The following document outlines the details of the Prefill Orchestration API.

API Description

Objective

The Prefill Orchestration API, also known as Prefill PAN API, retrieves user data using their name and mobile number. The retrieved details of the user enable automated form pre-filling and identity verification processes.

Input	Output
The user's name and mobile number	The complete user profile including personal details, contact information, address history, email data, and identity documents. The complete list of output fields is available in the Success Response Details section

API URL

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

API Endpoint

prefillOrchestration

Overview

The 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	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 API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`name`	Mandatory	The user's full name	Not Applicable	Not Applicable
`mobile`	Mandatory	The user's mobile number	10-digit mobile number format	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/prefillOrchestration' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "name": "<Enter_the_user_name>",
    "mobile": "<Enter_the_mobile_number>"
}'

Success Response

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

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "personalInfo": {
            "fullName": "<Full_Name>",
            "gender": "<Gender>",
            "totalIncome": "XXXXX",
            "occupation": "<Occupation>",
            "age": "XX",
            "dateOfBirth": "XX-XX-XXXX",
            "mobile": "<Mobile_Number>"
        },
        "phoneInfo": [
            {
                "sequence": "1",
                "typeCode": "H",
                "reportedDate": "<Reported_Date>",
                "number": "<Phone_Number>"
            }
        ],
        "emailInfo": [
            {
                "sequence": "1",
                "reportedDate": "<Reported_Date>",
                "emailAddress": "<Email_Address>"
            }
        ],
        "identityInfo": {
            "passportNumber": [],
            "aadhaarNumber": [
                {
                    "sequence": "1",
                    "reportedDate": "<Reported_Date>",
                    "idNumber": "XXXXXXXXXXXX"
                }
            ],
            "rationCard": [],
            "otherId": [
                {
                    "sequence": "1",
                    "reportedDate": "<Reported_Date>",
                    "idNumber": "<ID_Number>"
                }
            ],
            "drivingLicense": [],
            "voterId": [],
            "panNumber": [
                {
                    "sequence": "1",
                    "reportedDate": "<Reported_Date>",
                    "idNumber": "<PAN_Number>"
                }
            ]
        },
        "addressInfo": [
            {
                "sequence": "1",
                "reportedDate": "<Reported_Date>",
                "address": "<Full_Address>",
                "state": "<State>",
                "postal": "<Postal_Code>",
                "type": "<Address_Type>"
            }
        ]
    },
    "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
status	string	The status of the request
statusCode	number	The HTTP status code of the response
result.personalInfo.fullName	string	The user's full legal name
result.personalInfo.gender	string	The user's gender
result.personalInfo.totalIncome	string	The reported or estimated monthly total income
result.personalInfo.occupation	string	The user's occupation or job title
result.personalInfo.age	string	The user's age
result.personalInfo.dateOfBirth	string	The user's date of birth
result.personalInfo.mobile	string	The user's mobile number
result.phoneInfo[].sequence	string	The sequence number of the phone record
result.phoneInfo[].typeCode	string	The phone type: H (Home), M (Mobile), T (Telephone)
result.phoneInfo[].reportedDate	string	The date when the phone number was last reported
result.phoneInfo[].number	string	The phone number
result.emailInfo[].sequence	string	The sequence number of the email record
result.emailInfo[].reportedDate	string	The date when the email was last reported
result.emailInfo[].emailAddress	string	The email address
result.identityInfo.aadhaarNumber[].sequence	string	The sequence number for Aadhaar records
result.identityInfo.aadhaarNumber[].reportedDate	string	The date when Aadhaar was reported (if available)
result.identityInfo.aadhaarNumber[].idNumber	string	The Aadhaar number (masked)
result.identityInfo.panNumber[].sequence	string	The sequence number for PAN records
result.identityInfo.panNumber[].reportedDate	string	The date when PAN was reported
result.identityInfo.panNumber[].idNumber	string	The PAN number
result.identityInfo.otherId[].sequence	string	The sequence number for other IDs
result.identityInfo.otherId[].reportedDate	string	The date when other IDs were reported
result.identityInfo.otherId[].idNumber	string	The other ID numbers (e.g., user-specific IDs)
result.addressInfo[].sequence	string	The sequence number of the address record
result.addressInfo[].reportedDate	string	The date when the address was last reported
result.addressInfo[].address	string	The full address details
result.addressInfo[].state	string	The state associated with the address
result.addressInfo[].postal	string	The postal or ZIP code
result.addressInfo[].type	string	The address type (e.g., Permanent, Owns)
metadata.requestId	string	The unique request identifier
metadata.transactionId	string	The transaction identifier

Error Responses

The following are some error responses from the API:

Empty Name
Invalid Mobile Number
Invalid Mobile Format
Missing/Invalid Credentials

{
    "status": "failure",
    "statusCode": 400,
    "error": "Name cannot be empty",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

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

{
    "status": "failure",
    "statusCode": 400,
    "error": "Invalid mobile number format",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

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

Customer Not Found
Internal Server Error
External Source Downtime

{
    "status": "failure",
    "statusCode": 404,
    "error": "Customer not found",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "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	Name cannot be empty	This error occurs when the name parameter is passed as an empty string
400	Input Validation Error: mobile does not meet minimum length of 10	This error occurs when the mobile number is not in 10-digit format
400	Invalid mobile number format	This error occurs when the mobile number format is invalid
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
404	Customer not found	This error occurs when the given mobile number is not found in the credit bureau
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​

API Request Details

Method - POST