Face Match API - India

The following document highlights the details of the Face Match API.

API Description

Objective

The Face Match API determines whether two facial images belong to the same person.

What this API checks

The Face Match API compares two images and returns whether they match. It does not validate the completeness or quality of the images, nor does it verify whether inputs are selfies or ID images.

For proper input validation and reliable results, use the Selfie Validation API before the Face Match step.

API URL

https://ind-faceid.hyperverge.co/v1/photo/verifyPair

API Endpoint

verifyPair

Overview

The Face Match API is RESTful and uses standard HTTP verbs and status codes. Responses are in JSON format. Upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to access the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	Defines the media type for the request payload.	multipart/form-data
appId	Mandatory	The application ID shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the user's journey in your application(s)
uuid	Optional	An advanced parameter to prevent response tampering. When set, the response includes an X-Response-Signature header containing a checksum of the response body signed with the UUID and a private key.	This should be a unique value

Inputs

The Face Match API supports three combinations of input parameters depending on the use case:

• Selfie + ID image: selfie and id
• Selfie + face string: selfie and idFaceString
• Two-image match: image1, image2, and type

The following table provides the details of the parameters required for the Face Match API request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
selfie	Conditional	file	A selfie image. Required when matching a selfie with an ID image (id) or a face string (idFaceString).	JPEG, PNG, or TIFF	Not Applicable
id	Conditional	file	An image of the ID card. Used with selfie for selfie-to-ID matching.	JPEG, PNG, or TIFF	Not Applicable
idFaceString	Conditional	string	The faceString returned by the OCR API in base64 format. Used with selfie as an alternative to passing the id image.	Base64 string	Not Applicable
image1	Conditional	file	The first image in a two-image match. Used with image2 and type.	JPEG, PNG, or TIFF	Not Applicable
image2	Conditional	file	The second image in a two-image match. Used with image1 and type.	JPEG, PNG, or TIFF	Not Applicable
type	Conditional	string	Specifies the image type for two-image matching. Used with image1 and image2.	selfie / id	Not Applicable
allowMultipleFaces	Optional	string	When set to no, returns an error if multiple faces are detected in the selfie image.	yes / no	no

Request

The following code snippet demonstrates a standard curl request for the Face Match API (selfie and ID image):

curl --location --request POST 'https://ind-faceid.hyperverge.co/v1/photo/verifyPair' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--form 'selfie=@"<Enter_the_Selfie_Image_Path>"' \
--form 'id=@"<Enter_the_ID_Image_Path>"'

Advanced Request Variants

Selfie and Face String

The following is a sample request for matching a selfie with the face string returned by the OCR API.

curl --location --request POST 'https://ind-faceid.hyperverge.co/v1/photo/verifyPair' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--form 'selfie=@"<Enter_the_Selfie_Image_Path>"' \
--form 'idFaceString="<Enter_the_Face_String>"'

Selfie and Selfie

The following is a sample request for matching one selfie with another.

curl --location --request POST 'https://ind-faceid.hyperverge.co/v1/photo/verifyPair' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--form 'image1=@"<Enter_the_First_Image_Path>"' \
--form 'image2=@"<Enter_the_Second_Image_Path>"' \
--form 'type="selfie"'

ID and ID

The following is a sample request for matching one identity document with another.

curl --location --request POST 'https://ind.idv.hyperverge.co/v1/matchFace' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--form 'image1=@"<Enter_the_First_ID_Image_Path>"' \
--form 'image2=@"<Enter_the_Second_ID_Image_Path>"' \
--form 'type="id"'

Success Response

The following code snippet demonstrates a success response from the Face Match API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "match": "yes/no",
    "match-score": "<Match_Score>",
    "conf": "<Confidence_Score>",
    "to-be-reviewed": "yes/no"
  }
}

Success Response Details

The following table describes the fields returned in the Face Match API success response:

Parameter	Type	Description
status	string	The status of the request.
statusCode	string	The HTTP status code of the response.
result.match	string	Indicates whether the two images match. Returns yes or no.
result.match-score	number	The similarity score between the two faces, on a scale of 0 to 100.
result.conf	number	The confidence level of the match result.
result.to-be-reviewed	string	Indicates whether the result requires manual review. Returns yes or no.

Error Responses

The following are sample error responses from the Face Match API:

Face Not Detected in ID

{
  "status": "failure",
  "statusCode": "400",
  "error": "Face not detected in ID image"
}

Face Not Detected in Selfie

{
  "status": "failure",
  "statusCode": "400",
  "error": "Face not detected in Selfie image"
}

Wrong Parameter Combination

{
  "status": "failure",
  "statusCode": "400",
  "error": "Missing / Wrong combination of parameters. Valid Parameter combinations - (image1, image2, type) or (selfie, selfie2) or (selfie, id) or (selfie, idFaceString)"
}

Image Too Large

{
  "status": "failure",
  "statusCode": "400",
  "error": "image size cannot be greater than 12MB"
}

Invalid idFaceString

{
  "status": "failure",
  "statusCode": "400",
  "error": "Invalid value passed to idFaceString"
}

Multiple Faces Detected

{
  "status": "failure",
  "statusCode": "423",
  "error": "Multiple faces detected. Click Selfie/ID again"
}

Rate Limit Exceeded

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

Internal Server Error

{
  "status": "failure",
  "statusCode": "501",
  "error": "internal server error"
}

Server Busy

{
  "status": "failure",
  "statusCode": "503",
  "error": "DEPENDENCY SERVER BUSY"
}

Error Response Details

A failure response contains a failure status with a relevant status code and error message. The following table lists the error responses for the Face Match API:

Status Code	Error Message	Error Description	Error Resolution
400	Face not detected in ID image	The AI model failed to detect a face in the ID image.	Ensure the ID image clearly shows a face and retry.
400	Face not detected in Selfie image	The AI model failed to detect a face in the selfie image.	Ensure the selfie image clearly shows a face and retry.
400	Missing / Wrong combination of parameters	The request uses an unsupported combination of input parameters. Valid combinations: (image1, image2, type), (selfie, id), or (selfie, idFaceString).	Check the Inputs section and pass a valid parameter combination.
400	image size cannot be greater than 12MB	The input image exceeds the 12MB size limit.	Reduce the image size to under 12MB and retry.
400	Invalid value passed to idFaceString	The value provided for idFaceString is not a valid base64 face string.	Ensure the idFaceString value is the base64 face string returned by the OCR API.
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values.	Verify and provide valid appId and appKey credentials.
423	Multiple faces detected. Click Selfie/ID again	More than one face was detected in the image and allowMultipleFaces is set to no.	Ensure only one face appears in the image, or set allowMultipleFaces to yes.
429	Requests rate limit exceeded	The number of transactions per minute has exceeded the limit set for your credentials.	Retry after some time or contact the HyperVerge team to review your rate limit.
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution.
501	internal server error	An unexpected server error occurred.	Contact the HyperVerge team for resolution.
503	DEPENDENCY SERVER BUSY	The server is overloaded or a dependency service is unavailable.	Retry after some time or contact the HyperVerge team if the issue persists.