Skip to main content

Face Match API - India

API Description​

Objective​

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

info

The Face Match API verifies whether two images belong to the same person. It neither checks the completeness, quality of the face passed as input, nor does it validate whether the inputs are selfies or ID images. The model simply compares the two images and returns whether it is a match or not.

For proper input validation and reliable results, it is recommended to invoke the Selfie Validation module before the Face Match step. Please refer to our Selfie Validation API documentation for more details.

API URL​

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

API Endpoint​

verifyPair

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

ParameterMandatory or OptionalDescriptionValid Values
content-type Mandatory This parameter defines the media type for the request payload.multipart/form-data
appId Mandatory Application ID shared by HyperVerge N/A. This is a unique value.
appKey MandatoryApplication Key shared by HyperVerge N/A. This is a unique value.
transactionIdMandatoryUnique ID for the customer journey. N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs​

The following are the three variations of the request body based on the type of input images.

  1. Match selfie with photo on ID card:
    • selfie - A selfie image in JPEG, PNG or TIFF format.
    • id - An image of the ID card in JPEG, PNG or TIFF format.
  2. Match selfie with the face string provided by the OCR API:
    • selfie - A selfie image in JPEG, PNG or TIFF format.
    • idFaceString - The 'faceString' in base64 format returned by the OCR API.
  3. To match one selfie with another selfie (authentication use case):
    • image1 - A selfie image in JPEG, PNG or TIFF format.
    • image2 - A selfie image in JPEG, PNG or TIFF format.
    • type - "selfie".
    • image1 - An image of an identity document in JPEG, PNG or TIFF format.
    • image2 - An image of an identity document in JPEG, PNG or TIFF format.
    • type - "id".

General Image Input Guidelines​

  • The API supports JPEG, PNG and TIFF images and PDFs inputs.
  • Ensure that the document in the image is legible. This is a rule of thumb for our OCR servers to accurately extract any text from an image.
  • Reduce the size of the image as much as possible to optimise the reponse time while also ensuring its legibility criteria as mentioned earlier. Larger image sizes lead to higher uploading and processing time.
  • You can keep the width of the ID card image at least 800 pixels and the JPEG compression quality factor above 80%.
  • For our DL server to extract text from the document, the aspect ratio of the input image should be the same as the aspect ratio of the original document. Hence utmost care should be taken while resizing the image to maintain the aspect ratio

Sample Request​

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

The following is a sample request for the matching a selfie with an ID card image.

curl --location --request POST 'https://ind-faceid.hyperverge.co/v1/photo/verifyPair' \
--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 'selfie=@"<path_to_selfie_image>"' \
--form 'id=@"<path_to_id_image>"'

Success Response​

The following is a sample response for the matching a selfie with an ID card image.

 {
  	"status" : "success",
  	"statusCode" : "200",
  	"result" : {
          "match" : "yes/no",
          "match-score" : 95, // This is a number between 0-100
          "conf" :97,  
          "to-be-reviewed": "yes/no",
  	}
 }

Optional Configurations​

The following are the optional parameters configurable for the API.

ParameterPositionValueDefaultDescription
transactionIdHeaderStringnullThe unique identifier for the customer's application.
uuidHeaderStringnullThis 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.
allowMultipleFacesBody"yes" or "no"noAn error is returned when multiple faces are detected in the selfie image.

Error Responses​

The following sample responses reflect the status code 400.

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

Additionally, you might come across the following error responses.

{
   "status": "failure",
   "statusCode": "423",
   "error": "Multiple faces detected. Click Selfie/ID again"
}
Status CodeError MessageError Description
400Face not detected in Selfie image The AI model failed to detect the face in the selfie.
400Face not detected in ID imageThe AI model failed to detect the face in the image of the identification document.
400image size cannot be greater than 6MBThe maximum size of input image is 6MB. Crossing this will result in this error.
429Rate limit exceeded This error is returned when the number of transactions per minute has crossed the limit set for your credentials.
500/501Internal Server ErrorThis happens when there is an error with HyperVerge's server.
503Server busyThis happens when there is an overload on HyperVerge's server.
Last updated on
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: