Face and ID - Search, Enrol or Block API
API Endpoint
| Name of the API | User Inputs Required |
|---|---|
search | The details of the end user along with their selfie. |
API Description
Objective
The Search API determines if the given identity number and the selfie are present in the database.
API URL
https://ind-orion.hyperverge.co/v2/search
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 | Valid Values |
|---|---|---|---|
| content-type | Mandatory | This parameter defines the media type for the request payload. | application/json |
| appId | Mandatory | Application ID shared by HyperVerge | N/A. This is a unique value. |
| appKey | Mandatory | Application Key shared by HyperVerge | N/A. This is a unique value. |
Inputs
The following table provides the details of the input parameters used in the API request.
| Parameter | Mandatory or Optional | Type | Description |
|---|---|---|---|
name | Mandatory | string | The name of the customer. |
idNumber | Mandatory | string | The identification number of the customer from the identity document. |
idType | Mandatory | string | The type of the identity document. It can be PAN, Voter ID or Aadhaar. |
dob | Optional | string | The date of birth of the customer in dd-mm-yyyy format. |
transactionId | Mandatory | string | The unique identifier for the customer's application. |
block | Mandatory | string | To add this application to blocklist if enrol is yes. It accepts either of "yes" or "no" as its value. |
enrol | Mandatory | string | The flag to indicate if HyperVerge should enrol this application into your database. It accepts either of "yes" or "no" as its value. |
selfie | Mandatory | file | This is the selfie image of the user. The maximum image size is 6 MB. |
General Image Input Guidelines
- The API supports JPEG, PNG and TIFF images and PDFs inputs.
- Ensure that the document in the image is legible. This is a rule of thumb for our OCR servers to accurately extract any text from an image.
- Reduce the size of the image as much as possible to optimise the response time while also ensuring its legibility criteria as mentioned earlier. Larger image sizes lead to higher uploading and processing time.
- You can keep the width of the ID card image at least 800 pixels and the JPEG compression quality factor above 80%.
- For our DL server to extract text from the document, the aspect ratio of the input image should be the same as the aspect ratio of the original document. Hence utmost care should be taken while resizing the image to maintain the aspect ratio
Sample Request
The following code shows a standard curl request for the API:
curl --request POST \
--url https://ind-orion.hyperverge.co/v2/search \
--header 'accept: application/json' \
--header 'content-type: multipart/form-data' \
--form name=<enter_the_name> \
--form idNumber=<enter_the_id_number> \
--form idType=<enter_the_id_type> \
--form dob=<enter_the_dob> \
--form transactionId=<enter_the_transaction_id> \
--form block=no \
--form enrol=no \
--form selfie=<attach_the_image>
Success Response
The following is a sample response:
{
"statusCode": 200,
"status": "success",
"metaData": {
"requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
"transactionId": "290101"
},
"result": {
"data": {
"isEnrolled": {
"value": "yes",
"reason": "NA"
},
"matches": {
"count": 1,
"internal": [
{
"enrolDate": "11-04-2021",
"transactionId": "123456",
"clientId": "290101",
"matchScore": {
"selfie": "97.4"
},
"idNumber": {
"value": "XXXX",
"match": "yes | no | NA"
},
"dob": {
"value": "XXXX",
"match": "yes | no | NA"
},
"name": {
"value": "XXXX",
"match": "yes | no | NA"
},
"selfie": {
"url": "https://orion.com/1234/test.png",
"match": "yes | no | NA"
},
"category": "sameFaceSameDetails"
}
]
},
"suspiciousMatches": {
"count": 1,
"internal": [
{
"enrolDate": "11-04-2021",
"transactionId": "123456",
"clientId": "290101",
"matchScore": {
"selfie": "97.4"
},
"idNumber": {
"value": "XXXX",
"match": "yes | no | NA"
},
"dob": {
"value": "XXXX",
"match": "yes | no | NA"
},
"name": {
"value": "XXXX",
"match": "yes | no | NA"
},
"selfie": {
"url": "https://orion.com/1234/test.png",
"match": "yes | no | NA"
},
"category": "diffFaceSameDetails"
}
]
},
"blocklist": {
"count": 1,
"internal": [
{
"enrolDate": "11-04-2021",
"transactionId": "123456",
"clientId": "290101",
"matchScore": {
"selfie": "97.4"
},
"idNumber": {
"value": "XXXX",
"match": "yes | no | NA"
},
"dob": {
"value": "XXXX",
"match": "yes | no | NA"
},
"name": {
"value": "XXXX",
"match": "yes | no | NA"
},
"selfie": {
"url": "https://orion.com/1234/test.png",
"match": "yes | no | NA"
},
"category": "sameFaceSameDetails_BlockedApplication"
}
]
},
"dashboardUrl": "dashboardurl"
},
"summary": {
"value": "Match with blocklist",
"action": "Manual Review"
}
}
}
Error Responses
The following sample codes reflect the error responses of the API.
- ID Number Missing
- Missing/Invalid Credentials
- Face Undetected
- Limit Exceeded
- Internal Server Error
{
"status": "failure",
"metaData": {
"requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
"transactionId": "290101"
},
"statusCode": 400,
"error": "\"idNumber\" is required"
}
{
"status": "failure",
"metaData": {
"requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
"transactionId": "290101"
},
"statusCode": 401,
"error": "Missing/Invalid credentials"
}
{
"status": "failure",
"metaData": {
"requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
"transactionId": "290101"
},
"statusCode": 422,
"error": "Face not detected in Selfie image"
}
{
"status": "failure",
"message": "Requests rate limit exceeded",
"statusCode": 429
}
{
"status": "failure",
"metaData": {
"requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
"transactionId": "290101"
},
"error": "Internal Server Error",
"statusCode": 500
}
| Status Code | Error Message | Error Description |
|---|---|---|
| 400 | ""idNumber" is required | The request does not contain the identity number. |
| 400 | Face not detected in Selfie image | The AI model failed to detect the face in the image of the identification document. |
| 401 | Missing/Invalid credentials | The request either does not contain the mandatory credentials or contains invalid credentials. |
| 429 | Requests rate limit exceeded | The number of transactions per minute has crossed the limit set for your credentials. |
| 500 | Internal Server Error | There is an error with HyperVerge's server. Kindly contact the HyperVerge team for resolution. |