Government ID Face Match: NIN and BVN Selfie Verification

The LumiID Government ID Face Match API verifies a live selfie against the official biometric photo associated with a customer’s Nigerian NIN or BVN. Unlike a standard face match — where you must supply both images yourself — this API handles the reference image for you. Submit the selfie and the identity number, and LumiID automatically retrieves the trusted government-issued photo from NIMC or NIBSS, performs an AI-powered facial comparison, and returns a match result. This removes the need for you to store or manage sensitive government identity photos while providing stronger, authoritative identity assurance for KYC, AML, and fraud-prevention workflows.

Key capabilities

Capability	Detail
Government Data Integration	Reference photos retrieved directly from NIMC (NIN) and NIBSS (BVN)
AI-Powered Facial Recognition	Deep learning facial embeddings determine whether both images belong to the same individual
Built for Compliance	Satisfies KYC, AML, CDD, and NDPR requirements
Fast Response	Average response time under 2 seconds
Audit Ready	Every request returns a unique `request_id` and timestamp

Endpoint

POST /v1/face/id-match/

Headers

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

Request body

string

required

The type of government identity to look up. Supported values: nin, bvn.

string

required

The customer’s government-issued identity number corresponding to the selected id_type.

string

required

Base64-encoded selfie image captured live from your user.

float

Matching threshold between 0.0 and 1.0. Comparisons that score above this threshold are classified as a match. Defaults to 0.75. Use the default unless your risk model specifically requires a stricter value.

Supported identity sources

Identity	Authority	Status
National Identity Number (NIN)	NIMC	✅ Supported
Bank Verification Number (BVN)	NIBSS	✅ Supported
Passport	Nigeria Immigration Service	🔜 Coming Soon
Driver’s License	FRSC	🔜 Coming Soon
Voter Card	INEC	🔜 Coming Soon

Integration flow

Capture a live selfie

Use a live camera feed in your application to capture a front-facing selfie from your user.

Collect the identity number

Ask the customer to provide their NIN or BVN. This is the identity number you will pass as id_number.

Send both values to the endpoint

POST the selfie, id_type, and id_number to /v1/face/id-match/. Include your optional threshold if your risk policy requires it.

LumiID runs the comparison

LumiID automatically retrieves the official government biometric photograph from NIMC or NIBSS, performs an AI-powered facial comparison, calculates a similarity confidence score, and returns the result.

Approve or escalate

Use the match_result and confidence.score in the response to approve the onboarding, request a new selfie, or trigger a manual review based on your internal business rules.

Code examples

import requests
import base64

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

response = requests.post(
    "https://api.lumiid.com/v1/face/id-match/",
    json={
        "id_type": "nin",
        "id_number": "89184072280",
        "selfie": selfie,
        "threshold": 0.75
    },
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json"
    }
)

print(response.json())

const axios = require("axios");

const response = await axios.post(
  "https://api.lumiid.com/v1/face/id-match/",
  {
    id_type: "nin",
    id_number: "89184072280",
    selfie: "<BASE64_IMAGE>",
    threshold: 0.75
  },
  {
    headers: {
      Authorization: "Bearer YOUR_SECRET_KEY"
    }
  }
);

console.log(response.data);

curl --request POST \
  https://api.lumiid.com/v1/face/id-match/ \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id_type": "nin",
    "id_number": "89184072280",
    "selfie": "BASE64_IMAGE",
    "threshold": 0.75
  }'

Success response

{
  "success": true,
  "code": "FACE_MATCH_VERIFIED",
  "message": "Face match completed successfully",
  "summary": {
    "verified": true,
    "verification_type": "FACE_MATCH",
    "provider": "LumiID",
    "confidence_score": 0.9842
  },
  "data": {
    "match_result": "CONFIRMED",
    "confidence": {
      "score": 0.9842,
      "threshold": 0.75,
      "status": "STRONG_MATCH"
    },
    "details": {
      "reason_code": "MATCH_SUCCESS",
      "remarks": "Identity verified successfully"
    }
  },
  "meta": {
    "request_id": "req_634490e898c1",
    "timestamp": "2026-03-10T17:45:12Z"
  }
}

Response fields

boolean

Indicates whether the request completed successfully.

string

Machine-readable response code.

string

Human-readable response message.

object

High-level verification summary.

Show summary fields

boolean

Indicates whether both faces belong to the same individual.

string

Always FACE_MATCH.

string

Always LumiID.

float

Overall confidence score between 0 and 1.

object

Detailed face comparison result.

Show data fields

string

The verification outcome. Returns CONFIRMED, MISMATCH, or INCONCLUSIVE.

object

Confidence details for the comparison.

Show confidence fields

float

Similarity score for the comparison.

float

The threshold applied during this comparison.

string

Match strength classification (e.g. STRONG_MATCH).

object

Additional decision context.

Show details fields

string

Internal decision code.

string

Human-readable explanation of the outcome.

object

Request metadata.

Show meta fields

string

Unique request identifier. Store this for audit and support purposes.

string

ISO 8601 timestamp of when the request was processed.

Confidence score guide

Score range	Interpretation
0.95 – 1.00	Extremely Strong Match
0.90 – 0.94	Very Strong Match
0.80 – 0.89	Strong Match
0.75 – 0.79	Acceptable Match
Below 0.75	Likely Mismatch

Match results

`CONFIRMED`

The live selfie matches the official government biometric record. Proceed with onboarding.

`MISMATCH`

The faces belong to different individuals. Reject the verification or ask the user to submit a new selfie.

`INCONCLUSIVE`

The system could not confidently compare the faces. Common causes include a blurry selfie, multiple faces in the frame, poor lighting, or a partially obscured face. Request a new capture before making a decision.

Error codes

HTTP	Code	Cause and resolution
`400`	`INVALID_REQUEST`	Missing or invalid request fields. Check all required parameters.
`400`	`INVALID_ID_TYPE`	Unsupported identity type. Supported values are `nin` and `bvn`.
`400`	`INVALID_IMAGE`	The selfie could not be decoded. Verify the Base64 encoding.
`401`	`INVALID_API_KEY`	Invalid or missing API key. Check your `Authorization` header.
`401`	`SUBSCRIPTION_REQUIRED`	Government ID Face Match is not enabled on your account. Contact LumiID support.
`402`	`INSUFFICIENT_FUNDS`	Your wallet balance is insufficient. Top up your account and retry.
`404`	`ID_NOT_FOUND`	The government identity record was not found. Verify the `id_number` is correct.
`422`	`FACE_NOT_DETECTED`	No face was detected in the uploaded selfie. Ask the user to retake the photo.
`422`	`MULTIPLE_FACES_DETECTED`	Only one face is allowed per image. Ensure the selfie shows a single face.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests in a short period. Back off and retry.
`500`	`SERVER_ERROR`	Unexpected server error. Retry the request.
`503`	`SERVICE_UNAVAILABLE`	The government identity provider is temporarily unavailable. Retry after a short delay.
`504`	`TIMEOUT`	Upstream verification timed out. Retry after a short delay.

Recommended identity verification flow

For the highest level of fraud protection, run these checks in sequence:

Passive Liveness Detection

Run the Liveness Detection API to confirm the selfie was captured from a real, live person — not a photo, replay, or deepfake.

Government Identity Verification

Validate the customer’s NIN or BVN against the official registry to confirm the identity number exists and belongs to a real person.

Government ID Face Match

Submit the verified selfie and identity number to this endpoint. LumiID compares the live selfie to the official government biometric photo.

Approve or Escalate

Use the match_result and confidence.score to complete onboarding or trigger a manual review. This layered approach protects against impersonation, synthetic identity fraud, and presentation attacks while providing a strong audit trail for KYC and AML compliance.

Best practices

Always run Passive Liveness Detection before this endpoint.
Capture selfies in good, even lighting without harsh shadows.
Ensure only one face appears in the selfie before submitting.
Avoid selfies where the user is wearing sunglasses, a mask, or heavy filters.
Use the default threshold of 0.75 unless your risk model requires stricter verification.
Store the returned request_id for every request — you will need it for audit trails and support queries.

Get Started

General

Government Verification

Business Verification

Biometric & AML

SDKs & Integration

Reference

Government ID Face Match: NIN and BVN Selfie Verification

Key capabilities

Endpoint

Headers

Request body

Supported identity sources

Integration flow

Code examples

Success response

Response fields

Confidence score guide

Match results

`CONFIRMED`

`MISMATCH`

`INCONCLUSIVE`

Error codes

Recommended identity verification flow

Best practices

​Key capabilities

​Endpoint

​Headers

​Request body

​Supported identity sources

​Integration flow

​Code examples

​Success response

​Response fields

​Confidence score guide

​Match results

​CONFIRMED

​MISMATCH

​INCONCLUSIVE

​Error codes

​Recommended identity verification flow

​Best practices

Key capabilities

Endpoint

Headers

Request body

Supported identity sources

Integration flow

Code examples

Success response

Response fields

Confidence score guide

Match results

`CONFIRMED`

`MISMATCH`

`INCONCLUSIVE`

Error codes

Recommended identity verification flow

Best practices