Face Authentication API (v2)

API Description

Objective

This Face Authentication API (v2) verifies if the selfie provided in the request matches the image corresponding to a unique identifier(UID) in database.

Input	Output
The selfie of the customer and the unique transaction ID.	It reflects if the database contains a record that matches the selfie.

API URL

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

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
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 parameters used in the request body for the API call.

Parameter	Mandatory or Optional	Type	Description
`transactionId`	Mandatory	string	The unique identifier for the customer's application.
`uidType`	Mandatory	string	The type of the unique identifier. It can be the transaction ID or any other unique identifier for the enrolment. Note It is commonly configured as "transaction_id".
`uid`	Mandatory	string	The unique identifier for the record in your database used during enrolment. Note It is commonly configured as the transaction ID for the record.
`selfie`	Mandatory	file	This is the selfie image of the user. The maximum image size is 6 MB.

Additional Quality and Fraud Checks

In addition to its liveness and face match checks, the API can also execute additional checks on the image (also known as the liveness checks).
You can view the complete list of additional checks under the Additional Checks For Liveness page.

note

If you include any quality check parameter in the request, the result is added to the qualityChecks object in the response.

Sample Request

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

curl --location --request POST 'https://ind-orion.hyperverge.co/v2/faceAuth' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--form 'transactionId="<Enter_the_HyperVerge_transactionID>"' \
--form 'uidType="transaction_id"' \
--form 'uid="<Enter_the_Unique_Identifier>"' \
--form 'selfie=@"<path_to_selfie_image>"' \
--form 'ignoreSelfieQuality="<yes_or_no>"'

Success Response Sample

The following is a sample response for a matching record in the database.

{
  "status": "success",
  "statusCode": 200,
  "metaData": {
    "requestId": "1679918521052-b71a052c-d686-4162-827e-04298699573e",
    "transactionId": "Kala-Orion-Test-2"
  },
  "result": {
    "data": {
      "matchScore": 99,
      "match": "yes"
    },
    "summary": {
      "action": "pass",
      "details": []
    }
  }
}

Failure Response Sample

The following are the sample failure responses for the API. Alternatively, you can find the details of the failure responses listed here.

{
    "status": "success",
    "statusCode": 200,
    "metaData": {
        "requestId": "<requestID>",
        "transactionId": "<transactionID>"
    },
    "result": {
        "data": {
            "matchScore": 13,
            "match": "no"
        },
        "summary": {
            "action": "fail",
            "details": [
                {
                    "code": "E200",
                    "message": "Face mismatch"
                }
            ]
        }
    }
}

{
  "status": "failure",
  "statusCode": 422,
  "metaData": {
    "requestId": "<requestID>",
    "transactionId": "<transactionID>"
  },
  "result": {
    "data": {},
    "summary": {
      "action": "<retake OR fail>",
      "details": [
        {
          "code": "E201",
          "message": "Selfie Quality is Insufficient"
        }
      ]
    },
    "error": "Selfie Quality is Insufficient"
  }
}

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

{
  "status": "failure",
  "statusCode": 422,
  "metaData": {
    "requestId": "<requestID>",
    "transactionId": "<transactionID>"
  },
  "result": {
    "data": {},
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E202",
          "message": "Selfie is Not Live"
        }
      ]
    },
    "error": "Selfie is Not Live"
  }
}

{
  "status": "failure",
  "statusCode": 404,
  "metaData": {
    "requestId": "<requestID>",
    "transactionId": "<transactionID>"
  },
  "result": {
    "data": {},
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E203",
          "message": "No Record Found"
        }
      ]
    },
    "error": "No Record Found"
  }
}

{
  "status": "failure",
  "statusCode": 404,
  "metaData": {
    "requestId": "<requestID>",
    "transactionId": "<transactionID>"
  },
  "result": {
    "data": {},
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E204",
          "message": "manualReview"
        }
      ]
    }
  }
}

Error Response Sample

The following are the sample error responses for the API.

Missing Transaction ID
Missing/Invalid Credentials
LenderNode Not Found
Service Unavailable
Internal Server Error

{
  "error": "\"transactionId\" is required",
  "statusCode": 400,
  "status": "failure",
  "requestId": "d00a7e14-dbc7-4489-aa5a-cdd56a544578",
  "transactionId": null
}

{
  "error": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure",
  "requestId": "76e8c846-40af-4fcb-9641-942379e3fcce",
  "transactionId": null
}

{
  "error": "Lendernode not found",
  "statusCode": 404,
  "status": "failure",
  "requestId": "b0e5e94c-2abf-45e8-972e-075ce37ff636",
  "transactionId": "test-20230308141758885"
}

{
  "error": "Rate limit exceeded",
  "statusCode": 429,
  "status": "failure",
  "requestId": "1678985904709-5a62b5bd-247a-41ad-91c7-234ba03ae63b",
  "transactionId": "test_arjun"
}

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

Failure and Error Response Details

A response from the API can be either a failure or an error. The following table lists all failure and error responses, along with their respective status codes, error messages, and descriptions.

Status Code	Error Message	Error Description
200	Face Mismatch	The face matching score is below the threshold, resulting in a failed match.
422	Selfie Quality Issue	The quality of the selfie image is insufficient for the face match.
400	Face Not Detected	The API failed to detect a face in the selfie image.
422	Non-Live Selfie	The selfie provided is not live.
404	No Record Found	No matching record was found in the database for the transaction ID used in the request.
404	Manual Review	When the model is not confident about the face match result, the API requests for a manual review.
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.
404	Lendernode not found	The API failed to get the lender node.
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​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Input​

Additional Quality and Fraud Checks​

Sample Request​

Success Response Sample​

Failure Response Sample​

Error Response Sample​

Failure and Error Response Details​