Biometric Checks 1:1 Face Match Identity Verification

Face Comparison

Submit a selfie and a government ID number to verify that the person in the selfie matches the photo on record in the identity database. Returns a match verdict, a similarity confidence score, and full identity data from the source.

The engine fetches the reference photo directly from the authoritative government database using the supplied ID number, then performs a 1:1 biometric comparison against the submitted selfie using deep facial embedding models. No third-party photo uploads are required.

Use this endpoint to gate onboarding flows, re-authenticate returning users, or validate that a document belongs to its presenter. The threshold parameter lets you adjust the strictness of the match to suit your risk tolerance.

🏦

KYC onboarding

🔐

Re-authentication

🛡️

Fraud prevention

📋

Document validation

Endpoint

POST /v1/face/id-match/ Requires API key

Request Payload

Send as Content-Type: application/json. All requests must include a valid Authorization: Bearer <api-key> header.

Field Description

selfie Base64 string · Required A clear, frontal selfie of the person to verify. Accepts raw Base64 or a data-URL prefix (data:image/jpeg;base64,...). Supported formats: JPEG, PNG, WebP. Maximum size: 10 MB.

id_number string · Required The government-issued identity number to look up. The reference photo is fetched directly from the authoritative source database using this number.

id_type

string · Required The identity document type. Determines which database to query for the reference photo.

Value	Source	Supported
nin	NIMC national identity database	✓
BVN	Bank Verification Number database	✓
vnin	Virtual NIN	—
drivers_license	FRSC database	—
passport	NIS database	—

threshold

float · Optional · Default: 0.75 Minimum cosine similarity score required to return a CONFIRMED match. Must be a number between 0.0 and 1.0.

0.85

Strict — regulated KYC

0.75

Balanced — recommended

0.60

Permissive — low friction

Response Fields

Top-level envelope

Field	Type	Description
success	boolean	`true` when the API call completed without a server-side fault. Always check `data.match_result` for the biometric outcome.
code	string	Machine-readable status. `SUCCESS` on success; an error code otherwise. See Error Codes.
message	string	Human-readable status message.
verification_type	string	Always `"ID_FACE_MATCH"` for this endpoint.
data	object	Match result, confidence score, identity data, and detail metadata. See data object below.
meta.request_id	string	Unique 12-character identifier for this request. Include in all support queries.

data object

Field	Type	Description
match_result	string	`"CONFIRMED"` — similarity score met or exceeded the threshold. `"MISMATCH"` — score fell below threshold.
confidence.score	float	Cosine similarity between the selfie and ID photo embeddings ∈ [0, 1]. Rounded to 2 decimal places.
confidence.threshold	float	The threshold that was applied to this request (from the payload or the default).
confidence.status	string	Strength classification of the match result. See Match Strength below.
identity	object	Full identity record returned from the source database (name, date of birth, address, and other registered attributes for the given ID number).
details.reason_code	string	`"MATCH_SUCCESS"` or `"SCORE_BELOW_THRESHOLD"`. Machine-readable reason for the verdict.
details.remarks	string	Plain-language description of the result, suitable for internal audit logs.

Match Strength

The confidence.status field classifies the match into three tiers regardless of the threshold setting.

STRONG_MATCH

Similarity score ≥ 0.85. High-confidence biometric match — same person with strong certainty.

→ Safe to approve in all risk contexts including regulated KYC and financial onboarding.

MATCH

Similarity score met the threshold but is below 0.85. Biometric match within your configured tolerance.

→ Suitable for standard onboarding flows. Consider a secondary check for high-value transactions.

NO_MATCH

Similarity score fell below the threshold. The faces do not match to the required confidence level.

→ Reject and flag for review. Log meta.request_id and confidence.score.

Similarity score reference

Score range	Interpretation
0.90 – 1.00	Highly confident — near-identical facial features. Extremely unlikely to be a different person.
0.85 – 0.89	Strong match — same person under varying conditions (lighting, age, expression).
0.75 – 0.84	Standard match — passes the default threshold. Minor variation in photo conditions.
0.60 – 0.74	Borderline — below the recommended threshold. Manual review advised.
0.00 – 0.59	No match — faces are dissimilar. Likely a different person or a spoofed image.

Error Codes

HTTP	Code	Cause & Resolution
400	VALIDATION_ERROR	One or more required fields are missing or malformed. Check `selfie`, `id_number`, and `id_type`.
400	INVALID_THRESHOLD	The `threshold` value is not a valid number. Provide a float between 0.0 and 1.0.
400	INVALID_THRESHOLD_RANGE	The `threshold` is outside the valid range. Must be between `0.0` and `1.0` inclusive.
400	INVALID_INPUT	A field contains an unexpected data type or value. Verify that `selfie` is a valid Base64 string.
403	FORBIDDEN	Your organisation has not been approved. Contact support to complete verification.
403	SUBSCRIPTION_REQUIRED	Your account is not subscribed to the Face Match service. Enable it in the Console under Services.
404	ID_NOT_FOUND	No photo was found for the supplied `id_number` in the source database. Verify the ID number is correct and the `id_type` matches.
422	LANDMARKS_NOT_FOUND	A face could not be detected in one or both images. Ensure the selfie is well-lit, frontal, and unobstructed. The ID photo on record may also be of insufficient quality.
500	SERVICE_ERROR	An unexpected server error occurred. Retry with exponential backoff. If the error persists, contact support with `meta.request_id`.

Billing on confirmed matches only

Your wallet is only debited when the comparison returns a CONFIRMED match (match_result: "CONFIRMED"). Failed verifications, face-not-found errors, and MISMATCH results are not charged.

Selfie Requirements

Accepted formats

JPEGRecommended

PNGAccepted

WebPAccepted

Constraints

Max file size10 MB

Min resolution224 × 224 px

EncodingBase64 or data-URL

Faces per image1 (primary only)

Best practices for highest match accuracy

Capture the selfie in neutral, even lighting — avoid heavy shadows or glare on the face.
The subject should face the camera directly — match accuracy degrades at yaw or pitch angles beyond ±25°.
Ensure the full face is visible — no occlusion from masks, heavy sunglasses, or hands.
Use a neutral expression; avoid extreme open-mouth or squinting poses.
Do not apply beauty filters, skin-smoothing, or AI retouching — these alter the facial embedding and lower match scores.

Features & Benefits

🏛️

Authoritative source data

The reference photo is pulled directly from the government identity database — not from a user-uploaded document. No photo tampering or document forgery is possible on the reference side.

⚙️

Configurable threshold

Adjust the match sensitivity per request to match your risk profile — stricter for regulated financial products, more permissive for low-friction consumer flows.

📦

Identity data in one call

The identity field in the response returns the full identity record alongside the match result — eliminating the need for a separate identity lookup API call.

For higher-assurance use cases, chain this endpoint with the Liveness Check API to first confirm the selfie was captured from a live person before running the identity match. This two-step pattern catches both spoofed selfies and identity fraud in a single onboarding flow.

Example Request

import requests, base64

with open("selfie.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

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

payload = {
    "selfie":     b64,
    "id_number":  "89184072280",
    "id_type":    "nin",
    "threshold":  0.75
}

headers = {
    "Authorization": "Bearer Your-Secret-Key",
    "Content-Type":  "application/json"
}

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

if not data["success"]:
    print("Error:", data["code"], data["message"])
else:
    result = data["data"]
    match  = result["match_result"]
    score  = result["confidence"]["score"]
    status = result["confidence"]["status"]

    print(f"Result:    {match}")
    print(f"Score:     {score}")
    print(f"Strength:  {status}")
    print(f"Request:   {data['meta']['request_id']}")

    identity = result["identity"]
    print(f"Name:      {identity.get('firstname')} {identity.get('surname')}")

const fs = require('fs');

const b64 = fs.readFileSync('selfie.jpg')
              .toString('base64');

const response = await fetch(
  'https://api.lumiid.com/v1/face/id-match/',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer Your-Secret-Key',
      'Content-Type':  'application/json'
    },
    body: JSON.stringify({
      selfie:    b64,
      id_number: '89184072280',
      id_type:   'nin',
      threshold: 0.75
    })
  }
);

const data = await response.json();

if (!data.success) {
  console.error(`Error [${data.code}]: ${data.message}`);
} else {
  const { match_result, confidence, identity } = data.data;
  console.log(`Result:   ${match_result}`);
  console.log(`Score:    ${confidence.score}`);
  console.log(`Strength: ${confidence.status}`);
  console.log(`Name:     ${identity.firstname} ${identity.surname}`);
  console.log(`Req ID:   ${data.meta.request_id}`);
}

# Encode your selfie
B64=$(base64 -w 0 selfie.jpg)

curl -s -X POST \
  https://api.lumiid.com/v1/face/id-match/ \
  -H "Authorization: Bearer Your-Secret-Key" \
  -H "Content-Type: application/json" \
  -d "{
    \"selfie\":    \"$B64\",
    \"id_number\": \"89184072280\",
    \"id_type\":   \"nin\",
    \"threshold\": 0.75
  }"

# Extract match result only
curl -s -X POST \
  https://api.lumiid.com/v1/face/id-match/ \
  -H "Authorization: Bearer Your-Secret-Key" \
  -H "Content-Type: application/json" \
  -d "{\"selfie\":\"$B64\",\"id_number\":\"89184072280\",\"id_type\":\"nin\"}" \
  | jq '.data | {match_result, score: .confidence.score, status: .confidence.status}'

Confirmed Match 200 OK

{
  "success": true,
  "code": "SUCCESS",
  "message": "Verification completed successfully.",
  "verification_type": "ID_FACE_MATCH",
  "data": {
    "match_result": "CONFIRMED",
    "confidence": {
      "score": 0.91,
      "threshold": 0.75,
      "status": "STRONG_MATCH"
    },
    "identity": {
      "firstname": "CHUKWUEMEKA",
      "surname": "OKONKWO",
      "middlename": "JAMES",
      "dob": "1990-03-14",
      "gender": "m",
      "phone": "08012345678",
      "state_of_origin": "Anambra",
      "nin": "89184072280"
    },
    "details": {
      "selfie": "SELFIE_IMAGE",
      "reference": "ID_PHOTO",
      "reason_code": "MATCH_SUCCESS",
      "remarks": "Identity verified successfully"
    }
  },
  "meta": {
    "request_id": "a3f9c12b8d01"
  }
}

Mismatch 200 OK

{
  "success": true,
  "code": "SUCCESS",
  "message": "Verification completed successfully.",
  "verification_type": "ID_FACE_MATCH",
  "data": {
    "match_result": "MISMATCH",
    "confidence": {
      "score": 0.48,
      "threshold": 0.75,
      "status": "NO_MATCH"
    },
    "identity": { /* identity data still returned */ },
    "details": {
      "reason_code": "SCORE_BELOW_THRESHOLD",
      "remarks": "Face similarity score too low"
    }
  },
  "meta": {
    "request_id": "b7e2d40f9c33"
  }
}

Error — Face Not Found 422

{
  "success": false,
  "code": "LANDMARKS_NOT_FOUND",
  "message": "Face landmarks not found in one or both images.",
  "verification_type": "ID_FACE_MATCH",
  "data": null,
  "meta": {
    "request_id": "c1a9e03b7f55"
  }
}