Facematch

Compares extracted image from user’s personal document with the frame from the /process-video.

Authorization

This endpoint requires a API token as Bearer in the Authorization header. Go to Authorization guide for details.

Request (POST)

POST https://api.biometrysolutions.com/api-gateway/match-faces

Headers

• Authorization* - Your API Token.
• X-User-Fullname (If consent is given) - Pass the full name of end-user to process Voice and Face recognition services.
• X-Session-ID - Include the session ID to link transactions within a unified group.
• X-Use-Prefilled-Video - If this header is set to true, the video will be taken from the /process-video from the same session that provided the X-Session-ID header.

Note

If the Session has several /process-video transactions, the first one will be used to compare the face.

Parameters

• video* (formData file) - Video file that you want to process. Required parameter. If X-Use-Prefilled-Video header is set to true, this parameter is not required.
• image* (formData file) - Image of the desired person’s face or a scan of their passport (or driver’s license). The image should be in JPEG, PNG, or JPG format. Required parameter.

Responses

200

The object with data, score, scoring_result, and message fields.

• data - Results of the facematch comparison.

  • anchor (object) - Result of processing the user’s document image, with fields code (number) and description (string).
  • code (number) - Overall facematch result code; 0 indicates a successful check.
  • description (string) - Human-readable description of the overall result (e.g. "Successful check").
  • percentages (array of numbers) - Per-frame match percentages, each in the range 0–100.
  • result (boolean) - true if the faces match, false otherwise.
  • score (number) - Overall facematch score in the range 0–100.
  • target (object) - Result of processing the captured video frame, with fields code (number) and description (string).

• score (number) - Top-level mirror of data.score, in the range 0–100. Useful when you only need the headline score.

• scoring_result (object) - Outcome of evaluating the project’s configured facematch_conditions against data.

  • failed_conditions (array of strings) - Conditions that failed and forced a fail status.
  • failed_refer_conditions (array of strings) - Conditions that failed within the refer range.
  • status (string) - One of pass, refer, or fail.

• message (string) - Status message for the facematch operation.

400

Bad Request error object.

Response sample:

{
  "error": "string"
}

500

Internal server error object.

Response sample:

{
  "error": "string"
}

Sample

Request

Pass the video and image from your local machine to the --form.

curl --location 'https://api.biometrysolutions.com/api-gateway/match-faces' \
     --header 'X-User-Fullname: John Doe' \
     --header 'Authorization: Bearer eyJhbGciO...ANYea8r2xOG-Urc' \
     --form 'video=@"/[path to your file]/video.mp4"' \
     --form 'image=@"/[path to your file]/image.jpg"' \

Response

{
  "data": {
    "anchor": {
      "code": 0,
      "description": "Successful check"
    },
    "code": 0,
    "description": "Successful check",
    "percentages": [87.49, 84.12, 83.35, 81.35, 81.43, 84.94, 83.79, 82.17],
    "result": true,
    "score": 83.58,
    "target": {
      "code": 0,
      "description": "Successful check"
    }
  },
  "scoring_result": {
    "failed_conditions": [],
    "failed_refer_conditions": [],
    "status": "pass"
  },
  "score": 83.58,
  "message": "faces match result is here"
}