> For the complete documentation index, see [llms.txt](https://docs.lumiid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumiid.com/api-integration/biometric-checks/face-match-api-or-biometric-face-verification-and-comparison.md). # Face Match API | Biometric Face Verification and Comparison Compare a live selfie with a government ID using LumiID's AI-powered biometric face verification API. Confirm that both images belong to the same person during KYC, authentication, and fraud-prevention workflows. The LumiID **Face Match API** performs a **1:1 biometric face comparison**. It returns a confidence score, match decision, and verification metadata within seconds. Designed for digital KYC, customer onboarding, account recovery, fraud prevention, AML compliance, workforce verification, and high-risk transaction authentication. *** ## Overview | | | | ---------------------- | -------------------------------- | | **Authentication** | API Key Required | | **Comparison Type** | 1:1 Face Verification | | **Input** | Base64 Image or Public Image URL | | **Response Time** | < 3 second | | **Image Formats** | JPEG • PNG • WebP | | **Maximum Image Size** | 10 MB per image | | **Sandbox** | Unavailable | *** ## Endpoint **POST** ``` {{baseUrl}}/v1/face-match/verify/ ``` *** ## Headers | Header | Description | | ------------- | ------------------------ | | Authorization | Bearer YOUR\_SECRET\_KEY | | Content-Type | application/json | *** ## Request Body | Field | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `reference_image` | string | ✅ | Trusted image to compare against. Accepts Base64 or a publicly accessible image URL. | | `probe_image` | string | ✅ | Live selfie captured from the user. Accepts Base64 or a publicly accessible image URL. | | `idempotency_key` | string | ✅ | Unique client-generated key for this request. Reuse it when retrying the same comparison to prevent duplicate processing. | *** ### Example Request ```json { "reference_image": "BASE64_OR_IMAGE_URL", "probe_image": "BASE64_OR_IMAGE_URL", "idempotency_key": "face-match-20260731-001" } ``` *** ## Successful Response ```json { "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 ### Top-Level Response | Field | Type | Description | | ------------------ | ------- | -------------------------------------------------------- | | `success` | boolean | Indicates whether the comparison completed successfully. | | `code` | string | Machine-readable result code. | | `message` | string | Human-readable result message. | | `summary` | object | High-level verification summary. | | `data` | object | Face comparison result. | | `meta.request_id` | string | Unique request identifier for auditing and support. | | `meta.timestamp` | string | Timestamp in ISO 8601 format. | | `meta.api_version` | string | API version that produced the response. | *** ### summary | Field | Type | Description | | ------------------- | ------- | -------------------------------------------------- | | `verified` | boolean | Indicates whether the biometric comparison passed. | | `verification_type` | string | Always returns `FACE_MATCH`. | *** ### data | Field | Type | Description | | ------------------ | ------- | ------------------------------------------------------------------------------------- | | `id` | string | Unique face-match comparison identifier. | | `decision` | string | Overall comparison decision. A successful match returns `MATCH`. | | `similarity_score` | float | Similarity score between both faces. | | `strategy_used` | string | Matching strategy used for the comparison. | | `review_required` | boolean | Indicates whether the result needs manual review. | | `created_at` | string | Timestamp when the comparison was created, in ISO 8601 format. | | `margin_band` | string | Indicates how close the decision was to the decision boundary. It does not expose it. | *** ## Decision results ### MATCH Both images belong to the same individual. **Recommended Action** Proceed with onboarding or authentication. *** ### When `decision` is not `MATCH` Review `code`, `message`, and `review_required` before taking action. **Recommended Action** Request new images or additional verification when required. *** ## Similarity score `similarity_score` measures face similarity. Use `decision` as the authoritative outcome. `margin_band` shows how close the decision was to the boundary. It does not reveal the underlying threshold. *** ## Common Use Cases The Face Match API is ideal for: * Digital KYC onboarding * NIN biometric verification * BVN biometric verification * Passport verification * Driver's license verification * Employee identity verification * Customer account recovery * Password reset verification * High-value transaction approval * Fraud prevention * AML and CFT compliance * SIM registration * Government digital identity services *** ## Recommended Identity Verification Flow For the highest identity assurance, LumiID recommends the following verification pipeline: 1. Capture a user selfie. 2. Run the **Liveness Detection API** to confirm a real, live person. 3. Verify the user's government-issued identity (NIN, BVN, Passport, CAC, etc.). 4. Pass the live selfie as `probe_image`. 5. Pass the government-issued photo as `reference_image`. 6. Compare both images using the **Face Match API**. 7. Complete onboarding when `decision` is `MATCH`. This workflow protects against impersonation, stolen identities, replay attacks, deepfakes, and synthetic identity fraud. *** ## Best Practices For optimal matching accuracy: * Always perform **Liveness Detection** before Face Match. * Use original camera images whenever possible. * Avoid screenshots or compressed messaging app images. * Ensure only one face appears in each image. * Both images should be well-lit and front-facing. * Use government-issued photos retrieved directly from LumiID verification APIs for maximum accuracy. *** ## Error Codes | HTTP | Code | Resolution | | ------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | **400** | `INVALID_REQUEST` | Missing or invalid request parameters. | | **400** | `INVALID_IMAGE` | One or both images could not be processed. | | **401** | `INVALID_API_KEY` | Invalid or missing API key. | | **413** | `IMAGE_TOO_LARGE` | Submitted image exceeds the maximum supported size. | | **422** | `NO_FACE_DETECTED` | A face was not detected in one of the supplied images. | | 422 | `MULTIPLE_FACES_DETECTED` | Only one face is allowed per image. | | 422 | `IMAGE_QUALITY_TOO_LOW` | Images could not be compared successfully. Retry with higher-quality images. | | **500** | `SERVER_ERROR` | Unexpected internal error. Retry once. If the issue persists, contact LumiID Support with the `request_id`. | *** ## Security & Compliance * All requests must use **HTTPS**. * Every request returns a unique `request_id` for compliance and audit logging. * Images are securely transmitted and processed over encrypted connections. * Handle biometric data in accordance with **NDPR**, GDPR, and applicable privacy regulations. * Never expose your API secret key in client-side applications. *** ### Face match API FAQ #### What is 1:1 face verification? 1:1 face verification compares two images. It determines whether both faces belong to the same person. #### Which images should I compare? Use a live user selfie as `probe_image`. Use a trusted government ID photo as `reference_image`. #### Should I run liveness detection before face matching? Yes. Verify selfie liveness first to reduce replay and presentation-attack risk. #### What happens when a face match is not confirmed? Request another image or identity document. Do not complete high-risk actions without additional verification. *** ## Example (Python) ```python import requests url = "https://api.lumiid.com/v1/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(data["code"]) ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.lumiid.com/api-integration/biometric-checks/face-match-api-or-biometric-face-verification-and-comparison.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.