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

# BVN Verification API: Nigerian Bank Verification Number

> Verify Nigerian Bank Verification Numbers via NIBSS. Retrieve identity data for KYC, onboarding, and fraud prevention with Basic or Advance tiers.

Use the LumiID BVN Verification API to verify Nigerian Bank Verification Numbers (BVNs) against records held by the Nigeria Inter-Bank Settlement System (NIBSS). Submit an 11-digit BVN to retrieve verified customer identity data including name, date of birth, gender, and registered phone number. This API supports KYC, customer onboarding, compliance checks, and fraud prevention workflows across Nigerian financial institutions and fintechs.

## Overview

| Property | Details |
| - | - |
| **Country** | 🇳🇬 Nigeria |
| **Identifier** | Bank Verification Number (BVN) |
| **BVN Format** | 11-digit numeric |
| **Verification Tiers** | Basic • Advance |
| **Advance Status** | Coming soon |
| **Sandbox** | Supported |

***

## Basic BVN Verification

The Basic endpoint returns core identity information for a given BVN, including name, date of birth, gender, and registered phone number.

### Endpoint

```text theme={null}
POST https://api.lumiid.com/v1/ng/bvn-basic/
```

### Request Headers

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

### Request Body

**id\_number** `string` *required*

A valid 11-digit Bank Verification Number (BVN).

#### Example Request

```json theme={null}
{
  "id_number": "22123456789"
}
```

### Success Response

```json theme={null}
{
  "success": true,
  "code": "BVN_VERIFIED",
  "message": "BVN verification successful",
  "verification_type": "BVN",
  "summary": {
    "verified": true,
    "verification_type": "BVN",
    "provider": "LumiID",
    "confidence_score": 1.0
  },
  "data": {
    "bvn": "22123456789",
    "firstname": "JOHN",
    "lastname": "MUSA",
    "middlename": "DOE",
    "birthdate": "16-05-1997",
    "gender": "Male",
    "phone": "08012345678",
    "match_result": "CONFIRMED"
  },
  "meta": {
    "request_id": "req_8d4fa1bc22e",
    "timestamp": "2026-07-28T10:20:13Z"
  }
}
```

### Response Fields

**success** `boolean`

Indicates whether the request completed successfully.

**code** `string`

Machine-readable response code. Returns `BVN_VERIFIED` on success.

**message** `string`

Human-readable status message.

**verification\_type** `string`

Always `BVN`.

**summary** `object`

Verification summary.

**summary fields**

**verified** `boolean`

Whether the BVN was successfully verified.

**verification\_type** `string`

Always `BVN`.

**provider** `string`

Always `LumiID`.

**confidence\_score** `number`

Confidence score for the verification result. Returns `1.0` for a confirmed match.

**data** `object`

Verified BVN information.

**data fields**

**bvn** `string`

Verified Bank Verification Number.

**firstname** `string`

First name.

**lastname** `string`

Last name.

**middlename** `string`

Middle name, if available.

**birthdate** `string`

Date of birth (DD-MM-YYYY).

**gender** `string`

Gender of the BVN holder.

**phone** `string`

Registered phone number.

**match\_result** `string`

Verification result. Returns `CONFIRMED` for successful lookups.

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

***

## Advance BVN Verification *(Coming Soon)*

The Advance endpoint retrieves the complete BVN record from NIBSS for enhanced KYC and biometric verification.

> [!NOTE]
>
> The Advance endpoint is not yet available. It is currently in development and will be announced when released.

### Endpoint

```text theme={null}
POST https://api.lumiid.com/v1/ng/bvn-advance/
```

### Sample Response

```json theme={null}
{
  "success": true,
  "code": "BVN_VERIFIED",
  "message": "BVN verification successful",
  "verification_type": "BVN",
  "summary": {
    "verified": true,
    "verification_type": "BVN",
    "provider": "LumiID",
    "confidence_score": 1.0
  },
  "data": {
    "bvn": "22123456789",
    "firstname": "JOHN",
    "lastname": "MUSA",
    "middlename": "DOE",
    "birthdate": "16-05-1997",
    "gender": "Male",
    "phone": "08012345678",
    "email": "john@example.com",
    "photo": "BASE64_IMAGE",
    "title": "Mr",
    "marital_status": "Single",
    "nationality": "Nigerian",
    "profession": "Engineer",
    "employment_status": "Employed",
    "residential_address": "12 Admiralty Way, Lekki",
    "state_of_residence": "Lagos",
    "state_of_origin": "Osun",
    "lga_of_origin": "Osogbo",
    "tracking_id": "S000000000000001"
  },
  "meta": {
    "request_id": "req_8d4fa1bc22e",
    "timestamp": "2026-07-28T10:20:13Z"
  }
}
```

### Additional Response Fields

In addition to all Basic fields, the Advance endpoint returns:

**photo** `string`

Base64-encoded biometric photograph.

**email** `string`

Registered email address.

**title** `string`

Customer title (e.g., `Mr`, `Mrs`, `Miss`).

**marital\_status** `string`

Marital status.

**profession** `string`

Occupation or profession.

**employment\_status** `string`

Employment status.

**nationality** `string`

Nationality.

**residential\_address** `string`

Registered residential address.

**state\_of\_residence** `string`

State of residence.

**state\_of\_origin** `string`

State of origin.

**lga\_of\_origin** `string`

Local Government Area of origin.

**tracking\_id** `string`

NIBSS tracking identifier.

***

## Sandbox Testing

> [!TIP]
>
> Use the test BVN `22123456789` in the sandbox environment to verify your integration without consuming wallet credits or querying live NIBSS infrastructure. The sandbox always returns deterministic test data and should only be used for development and integration testing.

***

## Error Codes

| HTTP | Code | Resolution |
| - | - | - |
| **400** | `BVN_VERIFICATION_FAILED` | Verification failed. Retry once before contacting support. |
| **400** | `BVN_NOT_FOUND` | No record exists for the supplied BVN. Ensure it contains exactly 11 digits. |
| **401** | `INVALID_API_KEY` | Verify your API credentials. |
| **401** | `UNAPPROVED_ORGANIZATION` | Complete organization approval before using the Production API. |
| **401** | `SUBSCRIPTION_REQUIRED` | Enable BVN Verification from the LumiID Console. |
| **402** | `INSUFFICIENT_FUNDS` | Fund your LumiID wallet before retrying. |
| **500** | `SERVER_ERROR` | Unexpected internal error. Retry once. |
| **503** | `SERVICE_UNAVAILABLE` | The NIBSS service is temporarily unavailable. Retry with exponential backoff. |
| **504** | `TIMEOUT` | The request timed out. Retry after a short delay. |

***

## Code Example

```python theme={null}
import requests

url = "https://api.lumiid.com/v1/ng/bvn-basic/"

headers = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json"
}

payload = {
    "id_number": "22123456789"
}

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

print(response.json())
```


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