Face Authentication API (v3)

API Description

Objective

The Face Authentication API (v3) verifies a user's identity by matching a user selfie with an image linked to a unique identifier (UID) in the database. It ensures the selfie is captured live and also supports additional quality and fraud checks on the image. You can configure the face-match scores to suit your business needs.

Input	Output
The user selfie and the unique identifier for their facial data stored in your database	Verification result indicating if the provided selfie matches the stored image for the given unique ID, along with quality checks and liveness detection

note

Face authentication requires access to the user's stored facial data linked to their unique ID.

API URL

https://ind-orion.hyperverge.co/v3/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 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.	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 tracking a user journey
uidType	Mandatory	string	The type of the unique identifier. It can be the transaction ID or any other unique identifier for the enrolment. It is commonly configured as the "transaction_id".
uid	Mandatory	string	The unique identifier for the user's facial record stored in your database and used during enrolment
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/v3/faceAuth' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--form 'uid="<Unique_ID>"' \
--form 'image=@"<path_to_image_file>"' \
--form 'transactionId="<Enter_the_HyperVerge_transactionID>"' \
--form 'uidType="transaction_id"'

Success Response Sample

Face Authentication

The following is an example of a successful response for a matching database record.

{
  "status": "success",
  "statusCode": 200,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "yes",
          "confidence": "high"
        }
      },
      "faceMatch": {
        "matchScore": 99,
        "match": "yes"
      }
    },
    "summary": {
      "action": "pass",
      "details": []
    }
  }
}

Face Authentication with Additional Checks

The following is an example of a successful response for a matching database record with a couple of additional checks enabled.

{
  "status": "success",
  "statusCode": 200,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "no",
          "confidence": "high"
        },
        "qualityChecks": {
          "faceOccluded": {
            "value": "no",
            "confidence": "high"
          },
          "blur": {
            "value": "no",
            "confidence": "high"
          }
        }
      },
      "faceMatch": {}
    },
    "error": "Liveness Failed",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "119",
          "message": "Liveness failed with high confidence"
        }
      ]
    }
  }
}

Failure Responses

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

Face Mismatch

The following is an example of a failure scenario when the face match check fails.

{
  "status": "failure",
  "statusCode": 200,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "yes",
          "confidence": "high"
        }
      },
      "faceMatch": {
        "matchScore": 3,
        "match": "no"
      }
    },
    "error": "Face match failed",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E200",
          "message": "Face mismatch"
        }
      ]
    }
  }
}

Low Match Score - Manual Review

The following is an example of a failure scenario with a low match score leading to manual review.

{
  "status": "failure",
  "statusCode": 200,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "yes",
          "confidence": "high"
        }
      },
      "faceMatch": {
        "matchScore": 35,
        "match": "no"
      }
    },
    "error": "Face match failed",
    "summary": {
      "action": "manualReview",
      "details": [
        {
          "message": "Face mismatch"
        }
      ]
    }
  }
}

Liveness Failed

The following is an example of a failure scenario when the liveness check on the image fails.

{
  "status": "success",
  "statusCode": 200,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "no",
          "confidence": "high"
        }
      },
      "faceMatch": {}
    },
    "error": "Liveness Failed",
    "summary": {
      "action": "manualReview",
      "details": [
        {
          "code": "119",
          "message": "Liveness failed with high confidence"
        }
      ]
    }
  }
}

Face Not Detected

The following is an example of a failure scenario when the API fails to detect a face in the image.

{
  "status": "failure",
  "statusCode": 422,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {},
      "faceMatch": {}
    },
    "error": "No face detected",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "121",
          "message": "Face Not detected"
        }
      ]
    }
  }
}

Transaction ID Not Found

The following is an example of a failure scenario when the transactionId in the request has no matching record in the database.

{
  "status": "failure",
  "statusCode": 404,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "yes",
          "confidence": "high"
        }
      },
      "faceMatch": {}
    },
    "error": "No Record Found",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E203",
          "message": "No Record Found"
        }
      ]
    }
  }
}

Error Responses

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

Internal Server Error - 1

{
  "status": "failure",
  "statusCode": 500,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "yes",
          "confidence": "high"
        }
      },
      "faceMatch": {}
    },
    "error": "Internal Server Error",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E205",
          "message": "Lender Node Call Failed"
        }
      ]
    }
  }
}

Internal Server Error - 2

{
  "status": "failure",
  "statusCode": 500,
  "metadata": {
    "requestId": "<Request_Identifier>",
    "transactionId": "<Transaction_Identifier>"
  },
  "result": {
    "details": {
      "liveness": {
        "liveFace": {
          "value": "yes",
          "confidence": "high"
        }
      },
      "faceMatch": {}
    },
    "error": "Internal Server Error",
    "summary": {
      "action": "fail",
      "details": [
        {
          "code": "E207",
          "message": "Digitize Service Error"
        }
      ]
    }
  }
}

Missing Image

{
  "error": "API call requires image",
  "statusCode": 400,
  "status": "failure",
  "requestId": "<Request_Identifier>",
  "transactionId": "<Transaction_Identifier>"
}

UID Type Missing

{
  "error": "\"uidType\" missing required peer \"uid\"",
  "statusCode": 400,
  "status": "failure",
  "requestId": "<Request_Identifier>",
  "transactionId": "<Transaction_Identifier>"
}

UID Missing

{
  "error": "\"uid\" missing required peer \"uidType\"",
  "statusCode": 400,
  "status": "failure",
  "requestId": "<Request_Identifier>",
  "transactionId": "<Transaction_Identifier>"
}

Internal Server Error

{
  "error": "\"transactionId\" is required",
  "statusCode": 400,
  "status": "failure",
  "requestId": "<Request_Identifier>",
  "transactionId": null
}

Failure and Error Response Details

A failure or error response from the API 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
200	Face mismatch	The face match check failed. The API detected a live face but the face match score was too low
200	Face mismatch	The face match score was low, leading to manual review despite detecting a live face
200	Liveness failed with high confidence	The liveness check on the image failed with high confidence
422	No face detected	The API failed to detect a face in the provided image
404	No Record Found	The provided transactionId has no matching record in the database
500	Internal Server Error: Lender Node Call Failed	Please contact the HyperVerge team for resolution
500	Internal Server Error: Digitize Service Error	Please contact the HyperVerge team for resolution
400	API call requires image	The request is missing the required image input
400	"uidType" missing required peer "uid"	The request is missing the required uid field, which is necessary when uidType is provided
400	"uid" missing required peer "uidType"	The request is missing the required uidType field, which is necessary when uid is provided
400	"transactionId" is required	The request is missing the required transactionId field