Face Search, Enrol or Block API

API Description

Objective

The Face Search, Enrol or Block API enrols a user in the database, provides a reason for the enrolment rejection or adds it to a block-list.

Input	Output
The selfie of the customer and the unique transaction ID.	A response that reflects the success or failure of the customer enrolment process, or the addition to your block-list. The reason for rejecting the enrolment application is also returned if the enrolment fails.

API URL

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

API Endpoint

search/face

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 ﬁles 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.	multipart/form-data
appId	Mandatory	Application ID shared by HyperVerge	Not Applicable - this is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	Not Applicable - this is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Input

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

Parameter	Mandatory or Optional	Valid Values	Type	Description
`transactionId`	Mandatory	N/A. This is a unique value.	string	The unique identifier for the customer's application.
`selfie`	Mandatory	N/A	file	The selfie image of the user. Note The maximum image size supported is 6 MB.
`block`	Optional	`yes` or `no`	string	To add this application to blocklist if enrol is set to `yes`.
`enrol`	Optional	`yes` or `no`	string	If this flag is set to `yes`, this customer application will be enrolled in your database.
`omitSearch`	Optional	`yes` or `no`	string	If this flag is set to `yes`, the API skips searching the database for a matching record. Note When both `enrol` and `omitSearch` are set to yes, the API only performs the enrollment for the application without searching for a matching record in the database.

Sample Request

The following code shows a standard curl request for the API.

curl --request POST \
 --url https://ind-orion.hyperverge.co/v2/search/face \
 --header 'accept: application/json' \
 --header 'appId: <Enter_the_appId>' \
 --header 'appKey: <Enter_the_appKey>' \
 --header 'Content-Type: multipart/form-data' \
 --form 'transactionId=<Enter_the_Transaction_ID>' \
 --form 'selfie=<Attach_The_Image>' \
 --form 'enrol=<Yes_or_No>' \
 --form 'omitSearch=<Yes_or_No>'

Success Response Sample

{
  "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"
            },
            "selfie": {
              "url": "https://orion.com/1234/test.png",
              "match": "yes | no | NA"
            },
            "category": "sameFace"
          }
        ]
      },
      "blocklist": {
        "count": 1,
        "internal": [
          {
            "enrolDate": "11-04-2021",
            "transactionId": "123456",
            "clientId": "290101",
            "matchScore": {
              "selfie": "97.4"
            },
            "selfie": {
              "url": "https://orion.com/1234/test.png",
              "match": "yes | no | NA"
            },
            "category": "BlockedApplication"
          }
        ]
      },
      "dashboardUrl": "dashboardurl"
    },
    "summary": {
      "value": "Match with blocklist",
      "action": "Manual Review"
    }
  }
}

Success Response Details

Object Field Description

isEnrolled value If the value is yes, the application was successfully enrolled in your database. If the value is no, the reason field explains the corresponding reason of non-enrollment.

summary

action

It displays the recommended decision for the customer. It can take any of the values from the following table.

Action	Recommendation
`Pass`	You can proceed with the application as nothing suspicious was found.
`Manual Review`	Requires manual review for further approval or rejection.
`Fail`	The enrolment failed either because of an image quality issue or a matching `transactionId` pre-existing in the database.

metaData requestId A unique identifier to track the customer's application.

metaData transactionId The same transactionId used in the API request.

Error Response Sample

The following are the sample error responses for the API.

Missing Transaction ID
Failed Face Detection in Selfie
Missing/Invalid Credentials
Exceeded
Internal Server Error

The following is a sample response for a request missing the transactionId.

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "290101"
  },
  "statusCode": 400,
  "error": "\"transactionId\" is required"
}

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "290101"
  },
  "statusCode": 400,
  "error": "Face not detected in Selfie image"
}

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "290101"
  },
  "statusCode": 401,
  "error": "Missing/Invalid credentials"
}

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

{
  	"status": "failure",
  	"statusCode": "500",
  	"error": {
    	"message": "Internal server error",
    	"timestamp": 1662720725493
  	}
}

Failure and 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	""transactionId" is required	The request does not contain the transaction identification number.
400	Face not detected in Selfie image	The model failed to detect a face in the selfie. Kindly retry with a new selfie.
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.

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Input​

Sample Request​

Success Response Sample​

Success Response Details​

Error Response Sample​

Failure and Error Response Details​