Face and ID - Search, Enrol or Block API

Description

Objective

The Search, Enrol or Block API determines if the given identity number and the selfie are present in the database.

Input	Output
The details of the end user along with their selfie.	Search results indicating whether the identity and selfie match records in the database; optional enrolment or blocklist updates.

Next Step

To enrol a new face or add an application to the blocklist, use the Face and ID Dedupe Enrol and Block API.

API URL

https://ind-orion.hyperverge.co/v2/search

Overview

The Search, Enrol or Block 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 Search, Enrol or Block API.

API Request Details

Method

POST

Headers

The following table provides the complete information on the request headers for the Search, Enrol or Block API.

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload.	multipart/form-data
accept	Mandatory	This parameter defines the media type for the response.	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.

Input

The following table provides the complete information on the input parameters used in the request body for the Search, Enrol or Block API.

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
name	Mandatory	string	The name of the customer.	String	—
idNumber	Mandatory	string	The identification number of the customer from the identity document.	String	—
idType	Mandatory	string	The type of the identity document. It can be PAN, Voter ID or Aadhaar.	String (PAN, Voter ID, Aadhaar)	—
dob	Optional	string	The date of birth of the customer in dd-mm-yyyy format.	String (dd-mm-yyyy)	—
transactionId	Mandatory	string	The unique identifier for the customer's application.	String	—
block	Mandatory	string	To add this application to blocklist if enrol is yes. It accepts either of "yes" or "no" as its value.	String ("yes" or "no")	—
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.	String ("yes" or "no")	—
selfie	Mandatory	file	This is the selfie image of the user. The maximum image size is 6 MB.	Image file (max 6 MB)	—

General Image Input Guidelines

• The Search, Enrol or Block 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 Search, Enrol or Block 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 Sample

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"
    }
  }
}

Success Response Details

The following table provides the details of the parameters in a successful response from the Search, Enrol or Block API.

Field	Value	Description
statusCode	Integer	HTTP status code of the response.
status	String	Indicates whether the request was successful.
metaData.requestId	String	Unique identifier for the request.
metaData.transactionId	String	The transaction ID sent in the request.
result.data.isEnrolled	Object	Whether the application was enrolled; value and reason.
result.data.matches	Object	Count and list of matching records (same face and same details).
result.data.suspiciousMatches	Object	Count and list of suspicious matches (e.g. different face, same details).
result.data.blocklist	Object	Count and list of blocklist matches.
result.data.dashboardUrl	String	URL to view results in the dashboard.
result.summary	Object	Summary value and recommended action (e.g. Manual Review).

Error Response Samples

The following sample codes reflect the error responses of the Search, Enrol or Block API.

ID Number Missing

{
  "status": "failure",
  "metaData": {
    "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
    "transactionId": "290101"
  },
  "statusCode": 400,
  "error": "\"idNumber\" is required"
}

Missing/Invalid Credentials

{
  "status": "failure",
  "metaData": {
    "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
    "transactionId": "290101"
  },
  "statusCode": 401,
  "error": "Missing/Invalid credentials"
}

Face Undetected

{
  "status": "failure",
  "metaData": {
    "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
    "transactionId": "290101"
  },
  "statusCode": 422,
  "error": "Face not detected in Selfie image"
}

Limit Exceeded

{
  "status": "failure",
  "message": "Requests rate limit exceeded",
  "statusCode": 429
}

Internal Server Error

{
  "status": "failure",
  "metaData": {
    "requestId": "1622697947985-4cfbcaf8-28ca-497e-8d22-323dea6aa2f6",
    "transactionId": "290101"
  },
  "error": "Internal Server Error",
  "statusCode": 500
}

Failure and Error Response Details

A failure or error response from the Search, Enrol or Block API contains a failure status with a relevant status code and error message. The following table lists all error responses with suggested resolutions.

Status Code	Error Message	Error Description	Error Resolution
400	"idNumber" is required	The request does not contain the identity number.	Include a valid idNumber in the request body.
422	Face not detected in Selfie image	The Search, Enrol or Block API failed to detect a face in the selfie image.	Ensure the selfie contains a single, clearly visible face and retry.
401	Missing/Invalid credentials	The request either does not contain the mandatory credentials or contains invalid credentials.	Provide valid appId and appKey headers.
429	Requests rate limit exceeded	The number of transactions per minute has crossed the limit set for your credentials.	Throttle requests or contact HyperVerge to increase the rate limit.
500	Internal Server Error	There is an error with HyperVerge's server. Kindly contact the HyperVerge team for resolution.	Contact the HyperVerge team for resolution.