Face Match Advanced

11 min

Introduction

Face Match Advanced API verifies whether two facial images belong to the same individual and also provides detailed assessments of each image’s quality and facial attributes.

In addition to performing face matching between two images, the API returns image quality and facial analysis signals such as orientation and occlusion. Clients can use the combination of face match results and image-level checks to make more accurate and confident automated or manual verification decisions.

Image-Level Evaluation (Per Image)

Each image is assessed independently for:

1. Face Quality

Blur & sharpness

Brightness

Overall image qulaity

2. Face Orientation

Orientation category: FRONTAL, LEFT, RIGHT

Head pose values:

Pitch

Roll

3. Face Occlusion

Detects if the face is covered

Identifies face gears such as:

Sunglasses

Helmet

Cap / Hat

Note: Wearing a gear does not automatically fail the image unless the face is actually covered.

Face Detection

Detects if multiple faces are present in the image

Face counts

Cropped image of faces

Pair-Level Evaluation

Face Match

Computes facial similarity between the two images

Returns:

Match percentage (0–100)

Threshold-based verification result (true / false)

How to call the API

You must first login before sending the request. The authorization header in the request must include the access token obtained from the login API call.

API Input Guidelines

Both firstImage url and secondimage url are Mandatory parameters.

Sample Curl

curl --location --request POST 'https://api-preproduction.signzy.app/api/v3/face-match/advanced' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Token>' \
--data-raw '{
    "firstImage": "<URL of image 1>",
    "secondImage": "<URL of image 2",
    "threshold":0.65
}'

Input Parameters

Parameter	Required/Optional	Description
Authorization	Required	Contains the id parameter returned from the login step
Content-Type	Required	application/json
firstImage	Required	URL of the first image to be matched
secondImage	Required	URL of the second image with which first image to be compared
threshold	Optional	Threshold of face match, between 0.1 and 0.99

Sample Response

{
  "result": {
    "firstImage": {
      "face_occlusions": {
        "isFaceCovered": false,
        "faceGears": [
          "Hat"
        ]
      },
      "image_quality": {
        "quality": "good",
        "score": 0.99
      },
      "face_orientation": {
        "faceValid": true,
        "faceOrientation": "FRONT_FACING",
        "yaw": -0.11,
        "pitch": -2.1,
        "roll": 0.19
      },
      "face_detection": {
          "multipleFaces": true,
          "faceCount": 1,
           "faceImages": [
                    <image url>
                ]
            },
      "image_verdict": "PASS"
    },
    "second_image": {
      "face_occlusions": {
        "isFaceCovered": false
      },
      "image_quality": {
        "quality": "good",
        "score": 1
      },
      "face_orientation": {
        "faceValid": false,
        "faceOrientation": null,
        "yaw": null,
        "pitch":null,
        "roll": null
      },
     "face_detection": {
         "multipleFaces": true,
         "faceCount": 2,
         "faceImages": [
              <image url>,
              <image url>
                ]
            },
      "image_verdict": "FAIL"
    },
    "face_match": {
      "verified": false,
      "message": "Verification completed with negative result",
      "matchPercentage": "0.00%"
    }
  }
}

Response Parameters

Parameter	Type	Description
result	Object	Contains image-level analysis for both images and the final face match result.
firstImage	Object	Analysis details for the first input image. Structure is identical to secondImage.
secondImage	Object	Analysis details for the second input image. Structure is identical to firstImage.
face_match	Object	Face match result computed between the two images.
face_match.verified	Boolean	Indicates whether the two images are verified as belonging to the same individual based on the configured threshold. Face match results should be used only when both images have image_verdict = PASS.
face_match.message	String	Human-readable message describing the verification outcome.
face_match.matchPercentage	String	Percentage similarity between the two faces.

Image Analysis Object (Applicable to firstImage and secondImage)

Parameter	Type	Description
image_verdict	String (PASS, FAIL)	Final decision indicating whether the image is suitable for face matching based on quality and facial checks.
multiple_faces	Boolean	Indicates whether more than one face was detected in the image.
face_occlusions	Object	Face coverage and gear detection details.
face_occlusions.isFaceCovered	Boolean	Indicates whether the face is covered or obstructed.
face_occlusions.faceGears	Array<String>	Detected face gear such as Hat, Helmet, or Sunglasses. Presence of gear alone does not imply face coverage.
image_quality	Object	Image quality assessment for face matching suitability.
image_quality.quality	String	Overall image quality classification (e.g. good, poor).
image_quality.score	Float	Normalized image quality score between 0 and 1, where higher values indicate better quality.
face_orientation	Object	Face orientation and face detection details.
face_orientation.faceValid	Boolean	valid face is present in image. Comes true only when single valid face is ther ein image.
face_orientation.faceOrientation	String	Detected face orientation (e.g. FRONT_FACING, LEFT, RIGHT, null).
face_orientation.yaw	Float	Horizontal head rotation angle in degrees.
face_orientation.pitch	Float	Vertical head rotation angle in degrees.
face_orientation.roll	Float	Head tilt angle in degrees.
face_detection	Object
face_detection.multipleFaces	Boolean	return true when multiple faces are found
face_detection.faceCount	Integer	returns number of faces found
face_detection.faceImages	Array	array containg all face extracted images

Error Status Codes

CODE	MESSAGE
400	Error in downloading file
422	Unable to download the file

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected].