Face Match API: Biometric Face Verification and Comparison

The LumiID Face Match API performs a 1:1 biometric face comparison between two images and tells you whether both faces belong to the same person. Submit a trusted reference image — such as a government-issued ID photo — and a live selfie captured from your user. The API returns a similarity score, a MATCH or MISMATCH decision, and verification metadata within under 3 seconds. Use it during KYC onboarding, account recovery, fraud prevention, and any workflow where you need to confirm a user’s identity against a known reference.

Overview

Property	Value
Comparison Type	1:1 Face Verification
Input	Base64 Image or Public Image URL
Response Time	< 3 seconds
Maximum Image Size	10 MB per image
Supported Formats	JPEG, PNG, WebP
Sandbox	Unavailable

Sandbox testing is not available for the Face Match API. Use your live credentials and real images during development.

Endpoint

POST /v1/ml/face-match/verify/

Headers

Header	Value
`Authorization`	`Bearer YOUR_SECRET_KEY`
`Content-Type`	`application/json`

Request body

string

required

The trusted reference image to compare against. Typically a government-issued ID photo retrieved from a LumiID verification API. Accepts a Base64-encoded string or a publicly accessible image URL.

string

required

The live selfie captured from your user during the current session. Accepts a Base64-encoded string or a publicly accessible image URL.

string

required

A unique, client-generated key that identifies this specific comparison request. Reuse the same key when retrying a failed request to prevent duplicate processing and billing.

Example request

{
  "reference_image": "BASE64_OR_IMAGE_URL",
  "probe_image": "BASE64_OR_IMAGE_URL",
  "idempotency_key": "face-match-20260731-001"
}

Success response

{
  "success": true,
  "code": "FACE_MATCH_CONFIRMED",
  "message": "Faces matched",
  "summary": {
    "verified": true,
    "verification_type": "FACE_MATCH"
  },
  "data": {
    "id": "ac6f6822-be58-41df-97a0-0d2546070f6e",
    "decision": "MATCH",
    "similarity_score": 0.9823,
    "strategy_used": "primary_embedding",
    "review_required": false,
    "created_at": "2026-07-31T05:31:58.264099Z",
    "margin_band": "NARROW"
  },
  "meta": {
    "request_id": "req_fac220fc9da4",
    "timestamp": "2026-07-31T05:31:58.276562+00:00",
    "api_version": "1.0"
  }
}

Response fields

boolean

Indicates whether the comparison completed successfully.

string

Machine-readable result code (e.g. FACE_MATCH_CONFIRMED).

string

Human-readable result message.

object

High-level verification summary.

Show summary fields

boolean

Indicates whether the biometric comparison passed.

string

Always returns FACE_MATCH.

object

Face comparison result.

Show data fields

string

Unique identifier for this face-match comparison. Store this for audit and support purposes.

string

The overall comparison decision. A confirmed match returns MATCH.

float

Numerical similarity score between both faces. Use decision as the authoritative outcome rather than thresholding this value directly.

string

The internal matching strategy applied during this comparison.

boolean

Indicates whether the result requires manual review before you take action.

string

ISO 8601 timestamp when the comparison was created.

string

Indicates how close the decision was to the decision boundary without exposing the underlying threshold. Useful for flagging borderline cases for additional scrutiny.

object

Request metadata.

Show meta fields

string

Unique request identifier for auditing and support.

string

ISO 8601 timestamp of when the request was processed.

string

API version that produced this response.

Decision guide

`decision`	Meaning	Recommended action
`MATCH`	Both images belong to the same individual.	Proceed with onboarding or authentication.
Not `MATCH`	The faces could not be confirmed as the same individual.	Review `code`, `message`, and `review_required`. Request new images or escalate to additional verification.

Use decision as the authoritative outcome. similarity_score provides additional context, and margin_band signals how close the result was to the decision boundary — but neither should override decision in automated workflows.

Error codes

HTTP	Code	Resolution
`400`	`INVALID_REQUEST`	Missing or invalid request parameters. Check that all required fields are present and correctly formatted.
`400`	`INVALID_IMAGE`	One or both images could not be processed. Verify the Base64 encoding or URL accessibility.
`401`	`INVALID_API_KEY`	Invalid or missing API key. Check your `Authorization` header.
`413`	`IMAGE_TOO_LARGE`	A submitted image exceeds the 10 MB maximum. Resize and resubmit.
`422`	`NO_FACE_DETECTED`	A face was not detected in one of the supplied images. Ask the user to submit a clearer photo.
`422`	`MULTIPLE_FACES_DETECTED`	Only one face is allowed per image. Ensure each image contains a single face.
`422`	`IMAGE_QUALITY_TOO_LOW`	Images could not be compared due to quality issues. Retry with higher-quality images.
`500`	`SERVER_ERROR`	Unexpected internal error. Retry once. If the problem persists, contact LumiID Support with your `request_id`.

Best practices

Always run Liveness Detection before Face Match to confirm the selfie came from a real, live person.
Ensure only one face appears in each image before submitting.
Use well-lit, front-facing images for both the reference and probe.
Submit original camera images — avoid screenshots or images forwarded through messaging apps.
Use government-issued photos retrieved directly from LumiID verification APIs as your reference_image for maximum accuracy and compliance.

Code example

Python

import requests

url = "https://api.lumiid.com/v1/ml/face-match/verify/"

payload = {
    "reference_image": "BASE64_OR_URL",
    "probe_image": "BASE64_OR_URL",
    "idempotency_key": "face-match-20260731-001"
}

headers = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data["success"]:
    print("Decision:", data["data"]["decision"])
    print("Similarity score:", data["data"]["similarity_score"])
    print("Request ID:", data["meta"]["request_id"])
else:
    print("Error:", data["code"])

Get Started

General

Government Verification

Business Verification

Biometric & AML

SDKs & Integration

Reference

Face Match API: Biometric Face Verification and Comparison

Overview

Endpoint

Headers

Request body

Example request

Success response

Response fields

Decision guide

Error codes

Best practices

Code example

​Overview

​Endpoint

​Headers

​Request body

​Example request

​Success response

​Response fields

​Decision guide

​Error codes

​Best practices

​Code example

Overview

Endpoint

Headers

Request body

Example request

Success response

Response fields

Decision guide

Error codes

Best practices

Code example