Face Match API - Global

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.

Input	Output
Two different image sources with the individual's face	A "yes" or "no" for the face match evaluation across the two image sources

API URL

https://<regionCode>.idv.hyperverge.co/v1/matchFace

API Endpoint

matchFace

regionCode Details

The API URL accepts any of the following region code values against the regionCode placeholder. For example, "https://ind.idv.hyperverge.co/v1/matchFace"

Region	regionCode Value
India	ind
USA	usa
Africa	zaf
Europe	irl
Singapore	sgp

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	Accepted 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	Mandatory	Application Key shared by HyperVerge	N/A. This is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs

Type of Image Input

The API supports both image files and image URLs as input.

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

Selfie and ID Match

• selfie - A selfie image in JPEG, PNG or TIFF format.
• id - An image of the ID card in JPEG, PNG or TIFF format.

This match type compares a selfie against a complete ID card image.

Selfie and ID Face String Match

• selfie - A selfie image in JPEG, PNG or TIFF format.
• idFaceString - The 'faceString' (selfie) from the ID Card in base64 format.

This match type compares a selfie against a complete ID card image that has been converted to a base64 string format.

Use case: When identity documents (like Aadhaar, PAN, or Voter ID) are stored in a system in base64 format, verification is enabled by retrieving the selfie on the stored document and comparing it against the user's live selfie to confirm identity authenticity.

Selfie and Selfie Match

• image1 - A selfie image in JPEG, PNG or TIFF format.
• image2 - A selfie image in JPEG, PNG or TIFF format.
• type - "selfie".

This match type compares a selfie image against another selfie image.

Selfie and Selfie Face String Match

• selfie - A selfie image in JPEG, PNG or TIFF format.
• selfieFaceString - A base64 encoded string or base64 data URL of a selfie image.

This match type compares a selfie against a selfie that is in a base64 format.

Use case: In Digilocker workflows, the XML response contains the selfie from an ID in base64 format. This enables seamless identity verification by comparing the government-verified selfie against the user's newly captured selfie, ensuring the person matches their official records.

ID and ID Match

• 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".

This match type compares two complete ID card images against each other.

Requests

Selfie and ID Match

The following is a sample request for matching a selfie with an identity document's image:

curl --location --request POST 'https://<regionCode>.idv.hyperverge.co/v1/matchFace' \
--header 'appId:<Enter_the_HyperVerge_appId>' \
--header 'appKey:<Enter_the_HyperVerge_appKey>' \
--header 'transactionId:<Enter_the_HyperVerge_transactionID>' \
--header 'content-type: multipart/form-data' \
--form 'selfie=@abc.png' \
--form 'id=@xyz.png'

Selfie and ID Face String Match

The following is a sample request for matching a selfie with the face string extracted from an ID document by the OCR API:

curl --location --request POST 'https://<regionCode>.idv.hyperverge.co/v1/matchFace' \
--header 'appId:<Enter_the_HyperVerge_appId>' \
--header 'appKey:<Enter_the_HyperVerge_appKey>' \
--header 'transactionId:<Enter_the_HyperVerge_transactionID>' \
--header 'content-type: multipart/form-data' \
--form 'selfie=@abc.png' \
--form 'idFaceString=<FaceString_in_Base64_Format>'

Selfie and Selfie Match

The following is a sample request for matching a selfie with another:

curl --location --request POST 'https://<regionCode>.idv.hyperverge.co/v1/matchFace' \
--header 'appId:<Enter_the_HyperVerge_appId>' \
--header 'appKey:<Enter_the_HyperVerge_appKey>' \
--header 'transactionId:<Enter_the_HyperVerge_transactionID>' \
--form 'image1=@"/path/to/file"' \
--form 'image2=@"/path/to/file"' \
--form 'type="selfie"'

Selfie and Selfie Face String Match

The following is a sample request for matching a selfie with a selfie face string:

curl --location --request POST 'https://<regionCode>.idv.hyperverge.co/v1/matchFace' \
--header 'appId:<Enter_the_HyperVerge_appId>' \
--header 'appKey:<Enter_the_HyperVerge_appKey>' \
--header 'transactionId:<Enter_the_HyperVerge_transactionID>' \
--header 'content-type: multipart/form-data' \
--form 'selfie=@abc.png' \
--form 'selfieFaceString=<Base64_Encoded_Selfie_String_or_Data_URL>'

ID and ID Match

The following is a sample request for matching an identity document with another:

curl --location --request POST 'https://<regionCode>.idv.hyperverge.co/v1/matchFace' \
--header 'appId:<Enter_the_HyperVerge_appId>' \
--header 'appKey:<Enter_the_HyperVerge_appKey>' \
--header 'transactionId:<Enter_the_HyperVerge_transactionID>' \
--form 'image1=@"/path/to/file"' \
--form 'image2=@"/path/to/file"' \
--form 'type="id"'

Optional Configurations

The following are the optional parameters configurable for the API.

Parameter	Position	Value	Default	Description
preferences.returnScore	Body	"yes"/"no"	"no"	This will provide the match-score in the output when set to "yes".

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

Success Response

A success response from the API reflects the success status with a status code of 200 and a result object containing the response data with the following field-value pairs.

{
  "status": "success", 
  "statusCode": "200", 
  "result": 
  { 
    "details": 
    { 
        "match": { 
          "value": "yes"/"no", 
          "score": <face_match_score> // optional, 
          "confidence": "high"/"low", 
        },
      }, 
      "summary" : { 
        "action" : "pass/fail/manualReview", 
        "details : [], 
        } 
  },

  "metaData": { 
       "requestId": "<Request_ID>", 
       "transactionId": "<Transaction_ID>", 
   }, 
}

Error Responses

Face Not Detected

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

Selfie Image

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

Incorrect Parameters

{
"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)"
}

Incorrect Size

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

Invalid idFaceString

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

Invalid selfieFaceString

{
    "status": "failure",
    "statusCode": 400,
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    },
    "result": {
        "error": "Invalid value passed to selfieFaceString",
        "summary": {
            "action": "fail",
            "details": [
                {
                    "code": "111",
                    "message": "Bad Request. Please refer the documentation"
                }
            ]
        }
    }
}

Multiple Face Detected

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

Requests 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 or error response from the module 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 Selfie image	The AI model failed to detect the face in the selfie.
400	Face not detected in ID image	The AI model failed to detect the face in the image of the identification document.
400	Missing / Wrong combination of parameters	The request contains an invalid combination of parameters. Please refer to the valid parameter combinations in the documentation.
400	image size cannot be greater than 6MB	The maximum size of input image is 6MB which you have exceeded.
400	Invalid value passed to idFaceString	The provided idFaceString parameter contains an invalid or malformed value.
400	Invalid value passed to selfieFaceString	The provided selfieFaceString parameter contains an invalid or malformed value.
400	Unsupported file type	The request contains an unsupported file type. Please use one of the following file types: ".jpeg", ".png", ".tiff" or ".pdf".
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
423	Multiple faces detected. Click Selfie/ID again	The AI model detected multiple faces in the input image. Please provide an image with only one face.
429	Requests rate limit exceeded	The number of transactions per minute has crossed the limit set for your credentials.
500/501	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution.
503	DEPENDENCY SERVER BUSY	There is an overload on HyperVerge's server. Please try again after some time.