Facematch

Compares a client-provided reference image (e.g. an extracted document photo or a captured selfie) against the user’s live capture.

Authorization

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

Request (POST)

POST https://api.biometrysolutions.com/api-gateway/v2/face-match

Headers

• Authorization* - Your API Token.

request part fields

Field	Type	Description
user_id*	string	Opaque, customer-provided identity key.
session_id	string	Optional. Link this transaction to a session.
use_session_video	boolean	Optional. If true, reuse the video captured earlier in the session (from a Liveness / Verification call) instead of uploading a new one. Requires session_id.

Note

If the session has several verification transactions with a stored video, the first one is used to compare the face.

File parts

• reference_image* (formData file) — the reference portrait (document scan or selfie) to match against. JPEG, PNG, or JPG. Required.
• video (formData file) — the live capture. Required unless use_session_video is true.

Responses

200

The success envelope. data contains the raw face_recognition result; decision carries the scoring outcome when a scoring system is configured.

Response sample:

{
  "data": {
    "face_recognition": {
      "code": 0,
      "description": "Successful check",
      "result": true,
      "score": 83.58,
      "percentages": [87.49, 84.12, 83.35, 81.35]
    }
  },
  "decision": { "status": "pass", "score": 0.84, "reasons": [] },
  "meta": { "request_id": "fc5605c5-...", "message": "face matching completed" }
}

400

{ "error": { "code": "invalid_request", "message": "reference_image is required" }, "meta": {} }

422

{ "error": { "code": "face_not_detected", "message": "no face detected in the reference image" }, "meta": {} }

Sample

Request

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

curl --location 'https://api.biometrysolutions.com/api-gateway/v2/face-match' \
     --header 'Authorization: Bearer eyJhbGciO...ANYea8r2xOG-Urc' \
     --form 'request={"user_id":"user-123"}' \
     --form 'reference_image=@"/[path to your file]/image.jpg"' \
     --form 'video=@"/[path to your file]/video.mp4"'

Response

{
  "data": {
    "face_recognition": {
      "code": 0,
      "description": "Successful check",
      "result": true,
      "score": 83.58,
      "percentages": [87.49, 84.12, 83.35, 81.35, 81.43, 84.94, 83.79, 82.17]
    }
  },
  "decision": { "status": "pass", "score": 0.84, "reasons": [] },
  "meta": { "request_id": "fc5605c5-...", "message": "face matching completed" }
}