BVN Verification API: Nigerian Bank Verification Number

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

POST https://api.lumiid.com/v1/ng/bvn-basic/

Request Headers

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

Request Body

string

required

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

Example Request

{
  "id_number": "22123456789"
}

Success Response

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

boolean

Indicates whether the request completed successfully.

string

Machine-readable response code. Returns BVN_VERIFIED on success.

string

Human-readable status message.

string

Always BVN.

object

Verification summary.

Show summary fields

boolean

Whether the BVN was successfully verified.

string

Always BVN.

string

Always LumiID.

number

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

object

Verified BVN information.

Show data fields

string

Verified Bank Verification Number.

string

First name.

string

Last name.

string

Middle name, if available.

string

Date of birth (DD-MM-YYYY).

string

Gender of the BVN holder.

string

Registered phone number.

string

Verification result. Returns CONFIRMED for successful lookups.

object

Request metadata.

Show meta fields

string

Unique request identifier for auditing and support.

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.

The Advance endpoint is not yet available. It is currently in development and will be announced when released.

Endpoint

POST https://api.lumiid.com/v1/ng/bvn-advance/

Sample Response

{
  "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:

string

Base64-encoded biometric photograph.

string

Registered email address.

string

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

string

Marital status.

string

Occupation or profession.

string

Employment status.

string

Nationality.

string

Registered residential address.

string

State of residence.

string

State of origin.

string

Local Government Area of origin.

string

NIBSS tracking identifier.

Sandbox Testing

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

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

Get Started

General

Government Verification

Business Verification

Biometric & AML

SDKs & Integration

Reference

BVN Verification API: Nigerian Bank Verification Number

Overview

Basic BVN Verification

Endpoint

Request Headers

Request Body

Example Request

Success Response

Response Fields

Advance BVN Verification (Coming Soon)

Endpoint

Sample Response

Additional Response Fields

Sandbox Testing

Error Codes

Code Example

​Overview

​Basic BVN Verification

​Endpoint

​Request Headers

​Request Body

​Example Request

​Success Response

​Response Fields

​Advance BVN Verification (Coming Soon)

​Endpoint

​Sample Response

​Additional Response Fields

​Sandbox Testing

​Error Codes

​Code Example

Overview

Basic BVN Verification

Endpoint

Request Headers

Request Body

Example Request

Success Response

Response Fields

Advance BVN Verification (Coming Soon)

Endpoint

Sample Response

Additional Response Fields

Sandbox Testing

Error Codes

Code Example