> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumiid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Face Match API: Biometric Face Verification and Comparison

> Compare two images with LumiID's AI-powered 1:1 face match API. Accepts Base64 or URL inputs and returns a similarity score and MATCH/MISMATCH decision.

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 |

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

***

## Endpoint

```text theme={null}
POST /v1/ml/face-match/verify/
```

### Headers

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

### Request body

**reference\_image** `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.

**probe\_image** `string` *required*

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

**idempotency\_key** `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

```json theme={null}
{
  "reference_image": "BASE64_OR_IMAGE_URL",
  "probe_image": "BASE64_OR_IMAGE_URL",
  "idempotency_key": "face-match-20260731-001"
}
```

### Success response

```json theme={null}
{
  "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

**success** `boolean`

Indicates whether the comparison completed successfully.

**code** `string`

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

**message** `string`

Human-readable result message.

**summary** `object`

High-level verification summary.

**summary fields**

**verified** `boolean`

Indicates whether the biometric comparison passed.

**verification\_type** `string`

Always returns `FACE_MATCH`.

**data** `object`

Face comparison result.

**data fields**

**id** `string`

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

**decision** `string`

The overall comparison decision. A confirmed match returns `MATCH`.

**similarity\_score** `float`

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

**strategy\_used** `string`

The internal matching strategy applied during this comparison.

**review\_required** `boolean`

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

**created\_at** `string`

ISO 8601 timestamp when the comparison was created.

**margin\_band** `string`

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

**meta** `object`

Request metadata.

**meta fields**

**request\_id** `string`

Unique request identifier for auditing and support.

**timestamp** `string`

ISO 8601 timestamp of when the request was processed.

**api\_version** `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. |

> [!NOTE]
>
> 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**](https://docs.lumiid.com/api-reference/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 Python theme={null}
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"])
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.