> 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/government-id-face-match-api-or-nin-and-bvn-selfie-verification.md).

# Government ID Face Match API | NIN and BVN Selfie Verification

Verify a user's live selfie against a Nigerian NIN or BVN biometric photo with the **LumiID Government ID Face Match API**. LumiID retrieves the trusted reference photo from the identity provider, so your integration only submits the selfie and identity number.

Use the API for digital KYC, customer onboarding, financial services, lending, telecoms, and identity-fraud prevention. It reduces integration complexity while providing stronger identity assurance.

***

### Overview

Traditional face comparison APIs require developers to upload both the live selfie and a reference image. LumiID removes this complexity by securely retrieving the official government-issued biometric photo using the customer's identity number.

This enables developers to build secure onboarding flows without storing or managing sensitive identity photos themselves.

#### Common Use Cases

* Digital KYC & Customer Onboarding
* Banking & Financial Services
* Loan Applications
* Account Recovery
* SIM Registration
* Employee Verification
* High-Risk Transaction Authentication
* Identity Proofing
* Fraud Prevention

***

### Features

#### Government Data Integration

Reference photos are retrieved directly from trusted government identity databases including:

* National Identity Number (NIN)
* Bank Verification Number (BVN)

Additional identity sources will be supported in future releases.

***

#### AI-Powered Facial Recognition

Our biometric engine compares facial embeddings using advanced deep learning models to determine whether both images belong to the same individual.

***

#### Built for Compliance

The API helps organizations satisfy identity verification requirements for:

* KYC
* AML
* CDD
* NDPR Compliance
* Financial onboarding

***

#### Fast Response Times

Average response time is under **2 seconds** depending on the identity provider.

***

#### Audit Ready

Every request includes a unique **request\_id** and timestamp for compliance, monitoring, and support.

***

### Endpoint

```http
POST {{baseUrl}}/v1/face/id-match/
```

***

### Authentication

All requests require your LumiID Secret API Key.

#### Headers

| Header        | Value                    |
| ------------- | ------------------------ |
| Authorization | Bearer YOUR\_SECRET\_KEY |
| Content-Type  | application/json         |

***

### Request Body

| Field      | Type   | Required | Description                                                   |
| ---------- | ------ | -------- | ------------------------------------------------------------- |
| id\_type   | string | Yes      | Government identity type. Supported values: `nin`, `bvn`      |
| id\_number | string | Yes      | Government-issued identity number                             |
| selfie     | string | Yes      | Base64 encoded selfie image                                   |
| threshold  | float  | No       | Matching threshold between `0.0` and `1.0`. Default is `0.75` |

***

### 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

#### Step 1

Capture a live selfie from your user.

***

#### Step 2

Collect the customer's identity number.

Example:

* NIN
* BVN

***

#### Step 3

Send both values to the Face Match endpoint.

***

#### Step 4

LumiID automatically:

* Retrieves the official government biometric photograph.
* Performs AI-powered facial comparison.
* Calculates similarity confidence.
* Returns the verification result.

***

#### Step 5

Approve or reject the onboarding process based on your internal business rules.

***

## Python Example

```python
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())
```

***

## Node.js Example

```javascript
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 Example

```bash
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
}'
```

***

## Successful Response

```json
{
  "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

### Top-level Response

| Field   | Type    | Description                                           |
| ------- | ------- | ----------------------------------------------------- |
| success | boolean | Indicates whether the request completed successfully. |
| code    | string  | Machine-readable response code.                       |
| message | string  | Human-readable response message.                      |
| summary | object  | High-level verification summary.                      |
| data    | object  | Face comparison result.                               |
| meta    | object  | Request metadata.                                     |

***

### Summary Object

| Field              | Type    | Description                                                 |
| ------------------ | ------- | ----------------------------------------------------------- |
| verified           | boolean | Indicates whether both faces belong to the same individual. |
| verification\_type | string  | Always `FACE_MATCH`.                                        |
| provider           | string  | Always `LumiID`.                                            |
| confidence\_score  | float   | Overall confidence score between `0` and `1`.               |

***

### Data Object

| Field                | Type   | Description                    |
| -------------------- | ------ | ------------------------------ |
| match\_result        | string | `CONFIRMED` or `MISMATCH`.     |
| confidence.score     | float  | Similarity score.              |
| confidence.threshold | float  | Threshold used for comparison. |
| confidence.status    | string | Match strength classification. |
| details.reason\_code | string | Internal decision code.        |
| details.remarks      | string | Human-readable explanation.    |

***

### Meta Object

| Field       | Type   | Description                |
| ----------- | ------ | -------------------------- |
| request\_id | string | Unique request identifier. |
| timestamp   | string | ISO 8601 timestamp.        |

***

## Confidence Score Guide

| Score      | Meaning                |
| ---------- | ---------------------- |
| 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 request another selfie.

***

### INCONCLUSIVE

The system could not confidently compare the faces.

Common causes include:

* Blurry selfie
* Multiple faces
* Poor lighting
* Face partially hidden

Request another capture.

***

## Error Codes

| HTTP | Code                      | Cause & Resolution                                          |
| ---- | ------------------------- | ----------------------------------------------------------- |
| 400  | INVALID\_REQUEST          | Missing or invalid request fields.                          |
| 400  | INVALID\_ID\_TYPE         | Supported values are `nin` and `bvn`.                       |
| 400  | INVALID\_IMAGE            | Selfie could not be decoded.                                |
| 401  | INVALID\_API\_KEY         | Invalid or missing API key.                                 |
| 401  | SUBSCRIPTION\_REQUIRED    | Face Match is not enabled for your account.                 |
| 402  | INSUFFICIENT\_FUNDS       | Wallet balance is insufficient.                             |
| 404  | ID\_NOT\_FOUND            | Government identity record was not found.                   |
| 422  | FACE\_NOT\_DETECTED       | No face detected in the uploaded selfie.                    |
| 422  | MULTIPLE\_FACES\_DETECTED | Only one face is allowed per image.                         |
| 429  | RATE\_LIMIT\_EXCEEDED     | Too many requests sent in a short period.                   |
| 500  | SERVER\_ERROR             | Unexpected server error. Retry the request.                 |
| 503  | SERVICE\_UNAVAILABLE      | Government identity provider is temporarily unavailable.    |
| 504  | TIMEOUT                   | Upstream verification timed out. Retry after a short delay. |

***

## Security & Privacy

LumiID is designed with privacy and regulatory compliance in mind.

* All requests must use HTTPS.
* API keys should only be used on secure backend servers.
* Images are encrypted during transmission.
* Every request is assigned a unique `request_id`.
* Biometric data should be handled in accordance with the Nigeria Data Protection Act (NDPA) and other applicable privacy regulations.

***

## Best Practices

* Run **Passive Liveness Detection** before Face Match.
* Capture images in good lighting.
* Ensure only one face appears in the selfie.
* Avoid sunglasses, masks, and heavy image filters.
* Use the default threshold (`0.75`) unless your risk model requires stricter verification.
* Store the returned `request_id` for audit and support purposes.

***

## Recommended Identity Verification Flow

For the highest level of fraud protection, we recommend the following verification sequence:

1. **Passive Liveness Detection** — Confirm that the selfie was captured from a real, live person.
2. **Government Identity Verification** — Validate the customer's NIN or BVN against the official registry.
3. **Government ID Face Match** — Compare the live selfie with the official government biometric photo.
4. **Approve or Escalate** — Use the verification outcome to complete onboarding or trigger manual review.

This layered approach helps prevent impersonation, synthetic identity fraud, presentation attacks, account takeover, and deepfake-assisted identity fraud while providing a strong audit trail for KYC, AML, and regulatory compliance.

***

### Government ID face match FAQ

#### What does Government ID Face Match verify?

It checks whether a live selfie matches the biometric photo associated with a NIN or BVN.

#### Which Nigerian identity sources are supported?

NIN and BVN are supported. Passport, driver's license, and voter card support are coming soon.

#### Do I need to upload a government ID photo?

No. Submit the selfie and identity number. LumiID retrieves the trusted reference photo automatically.

#### Should I run liveness detection first?

Yes. Run passive liveness detection before face matching to reduce spoofing and replay risk.


---

# 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/government-id-face-match-api-or-nin-and-bvn-selfie-verification.md?ask=<question>&goal=<endgoal>
```

`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.