Find Face API

API Description

Objective

The Find Face API identifies whether a target face exists in a group image and returns data about the closest match.

Input	Output
Target face image and group image containing multiple faces	Match status, similarity score, and face crop of the closest match

API URL

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

API Endpoint

findFace

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The requests are in form-data format and responses are in JSON format.

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	The application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
transactionId	Optional	The unique ID for the customer journey	Not Applicable

Inputs

The following table provides the details of the parameters required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
image	Mandatory	The target face image to search for	JPEG,PNG, or TIFF format	Not Applicable
groupimage	Mandatory	The group image containing multiple faces	JPEG, PNG, or TIFF format	Not Applicable
type	Optional	The type of target image	id or selfie	id

Optional Parmaters

The following are optional parameters that can be set as part of the request body:

Parameter	API Body / Header	Value	Default	Description
referenceId	Header	String	null	referenceId is an identifier for the API call and is echoed back by the server in the response. This referenceId can be used to create logical grouping of single/multiple API calls based on business logic of the consumer of API. HyperVerge's QC dashboard can be used to fetch logs grouped by the Reference ID.
uuid	Header	String	null	This is an advanced feature designed to prevent tampering of response by a man in the middle. If uuid is set, the response will include an X-Response-Signature header which will have a checksum of the response body signed with the uuid and a private key.
enableDashboard	Body	"yes"/"no"	"no"	This will give access to an exclusive dashboard built by HyperVerge for Quality Check and debugging purpose.

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-faceid.hyperverge.co/v1/photo/findFace' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image=@"<path_to_target_image>"' \
--form 'groupimage=@"<path_to_group_image>"' \
--form 'type="<Enter_type_of_target_image>"'

Success Responses

The following code snippets demonstrate success responses from the API:

Match Found

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "match-score": 88,
        "face-found": "yes/no",
        "to-be-reviewed": "yes/no",
        "matching-face-crop": "<Base64_image_of_the_closest_matching_face_crop>"
    }
}

No Match Found

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "match-score": 22,
        "face-found": "no",
        "to-be-reviewed": "no"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code of the response
match-score	integer	The similarity score between the target face and the closest match in the group image. It is a number between 0 to 100
face-found	string	Indicates whether a match was found above the threshold. Returns 'yes' if the match score is greater than or equal to the determined threshold, and 'no' otherwise
to-be-reviewed	string	Indicates whether the match needs manual verification. Returns 'yes' if manual review is required, and 'no' otherwise
matching-face-crop	string	The base64 encoded image of the closest matching face from the group image

Error Responses

The following are some error responses from the API:

Face Not Detected in Image

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

Face Not Detected in Group Image

{
    "status": "failure",
    "statusCode": "400",
    "error": "Face not detected in group image",
    "errorCode": "E1033G"
}

Image Size Exceeded

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

Rate Limit Exceeded

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

Server Error

{
    "status": "failure",
    "statusCode": "500",
    "error": "Internal Server Error"
}

Server Busy

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

Error Response Details

An 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
400	Face not detected in image	The face could not be detected in the individual's image by the AI model
400	Face not detected in group image	No face could be detected in the group image by the AI model
400	image size cannot be greater than 6MB	The maximum size of input image is 6MB. Crossing this will result in this error
422	FACENOTDETECTED	The face could not be detected in either the target image or the group image. Please ensure both images contain valid faces
429	Rate limit exceeded	This error occurs when you have exceeded the configured rate limit for transactions per minute
433	BADFACESIZE	The target face image resolution is less than 200x200 pixels. Please use a higher resolution image
500	Internal Server Error	An internal server error occurred. Please contact the HyperVerge team for resolution
503	DEPENDENCY SERVER BUSY	The server is currently overloaded. Please try again later