Face Search, Enrol or Block

Description

Objective

The Face Search, Enrol or Block module enrols the customer in your database, returns the reason for rejecting the enrolment application or adds it to your 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.

Inputs

The following table provides the complete information on the input parameters.

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 module skips searching the database for a matching record. Note When both enrol and omitSearch are set to yes, the module only performs the enrollment for the application without searching for a matching record in the database.

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 input.

Error Response Sample

The following are the sample error responses.

Missing Transaction ID

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

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

Missing/Invalid Credentials

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

Failed Face Detection in Selfie

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

Exceeded

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

Internal Server Error

{
  	"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 relavant 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.
401	Missing/Invalid credentials	The request either does not contain the mandatory credentials or contains invalid credentials.
422	Face not detected in Selfie image	The model failed to detect a face in the selfie. Kindly retry with a new selfie.
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.