Financial Rails Nigeria · NIBSS 2 Tiers

BVN Verification

Verify Bank Verification Numbers (BVN) against the NIBSS central database in real time. Confirm that a BVN belongs to a specific individual, retrieve their full biographical profile, and gate financial onboarding flows with a single API call.

Two tiers are available: Basic for fast identity confirmation (names, DOB, phone, Base64-encoded biometric photo), and Advance for full KYC disclosure including the Base64-encoded biometric photo — required for face-matching workflows.

< 1.5s

Typical latency

NIBSS

Authoritative source

11-digit

BVN format

Sandbox mode available

Use a test key prefixed with sk_test_ to run requests against a sandboxed dataset without consuming wallet credits or hitting the live NIBSS rails.

Basic Verification

POST /v1/ng/bvn-basic/ Requires API key

Confirms that a BVN belongs to a real registered individual and returns core biographical data. Use this tier when you need identity confirmation without biometric photo retrieval.

Returns name (first, last, middle), date of birth, gender, and registered phone number.

Request payload

Send as Content-Type: application/json with a valid Authorization: Bearer <api-key> header.

Field	Description
id_number	string · Required The 11-digit Bank Verification Number to look up. Must be numeric. Example: "22123456789"

Response fields

Top-level envelope

Field	Type	Description
success	boolean	`true` when the lookup completed without a fault. A `false` value means the request itself failed — not that the BVN was invalid.
code	string	Machine-readable result. `BVN_VERIFIED` on success. See Error Codes for failure values.
message	string	Human-readable status message.
verification_type	string	Always `"BVN"` for this endpoint.
data	object	BVN record from the NIBSS database. See data object below.
meta.request_id	string	Unique request identifier. Include in all support queries and audit logs.
meta.timestamp	string	UTC response time in ISO 8601 format.
meta.api_version	string	API version used to serve this request.

data object

Field	Type	Description
bvn	string	The BVN as registered in NIBSS.
firstname	string	First name as registered.
lastname	string	Surname as registered.
middlename	string	Middle name. May be an empty string if not registered.
birthdate	string	Date of birth. Format: `DD-MM-YYYY`.
gender	string	`"Male"` or `"Female"`.
phone	string	Phone number registered at BVN enrolment.
photo	string	Base64-encoded biometric photo. Present on Advance tier only.
match_result	string	Always `"CONFIRMED"` on a successful lookup.

Advance Verification

POST /api/v1/ng/bvn-advance/ Coming Soon

Retrieves the complete NIBSS record — including the Base64-encoded biometric photo, residential address, and full enrolment details. Required for face-matching workflows.

The Advance endpoint is required for biometric face-matching workflows. Chain the returned photo field with the Liveness Check and Face Comparison endpoints for a full identity verification flow.

Error Codes

HTTP	Code	Cause & Resolution
400	BVN_NOT_FOUND	The BVN does not exist in NIBSS. Check for transcription errors — must be exactly 11 digits.
400	BVN_VERIFICATION_FAILED	The NIBSS lookup returned an error outside of a not-found case. Verify the BVN format and retry.
400	API_COST_NOT_FOUND	Service pricing could not be resolved for your organisation. Contact support.
401	UNAPPROVED_ORGANISATION	Your organisation has not been approved. Complete the approval process in the Console before making live requests.
401	SUBSCRIPTION_REQUIRED	Your account is not subscribed to the BVN service. Enable it in the Console under Services.
402	INSUFFICIENT_FUNDS	Your organisation's wallet balance is too low. Top up in the Console before retrying.
500	SERVER_ERROR	Unexpected error connecting to the identity provider. Retry with exponential backoff. Include `meta.request_id` in any support query.
503	SERVICE_UNAVAILABLE	The NIBSS verification service is temporarily unreachable. Retry after a short delay.
504	TIMEOUT	The NIBSS database request timed out. Retry once — if it continues, check the API status page.

Features & Benefits

⚡

Real-time sovereign rail

Connected directly to the NIBSS central database — the same authoritative source used by Nigerian banks. Results are live, not cached or stale.

🧪

Sandbox mode

Test the full integration cycle using sk_test_ keys against sandboxed data without consuming credits or hitting production infrastructure.

🗂️

Tiered access

Choose the data depth you need. Basic for lightweight confirmation. Advance for full biometric KYC including the profile photo for face matching.

📋

Audit-ready logging

Every request returns a unique request_id and ISO 8601 timestamp — ready to attach to compliance reports and KYC audit trails.

Recommended KYC flow

Call BVN Basic to confirm the identity record exists and retrieve biographical data.
Call the Liveness Check API to confirm the selfie was captured from a real, live person.
Call BVN Advance (or Face Comparison) to match the selfie against the NIBSS biometric photo.

This three-step pattern satisfies CBN KYC Tier 2 requirements and covers both identity fraud and presentation attack vectors.

Example Request

import requests

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

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

response = requests.post(
    url, json={"id_number": "22123456789"}, headers=headers
)
data = response.json()

if not data["success"]:
    print(f"Error [{data['code']}]: {data['message']}")
else:
    r = data["data"]
    print(f"Name:   {r['firstname']} {r['lastname']}")
    print(f"DOB:    {r['birthdate']}")
    print(f"Phone:  {r['phone']}")
    print(f"Gender: {r['gender']}")
    print(f"Req ID: {data['meta']['request_id']}")

const response = await fetch(
  'https://api.lumiid.com/v1/ng/bvn-basic/',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer Your-Secret-Key',
      'Content-Type':  'application/json'
    },
    body: JSON.stringify({ id_number: '22123456789' })
  }
);

const data = await response.json();

if (!data.success) {
  console.error(`Error [${data.code}]: ${data.message}`);
} else {
  const r = data.data;
  console.log(`Name:   ${r.firstname} ${r.lastname}`);
  console.log(`DOB:    ${r.birthdate}`);
  console.log(`Phone:  ${r.phone}`);
  console.log(`Req ID: ${data.meta.request_id}`);
}

curl -s -X POST \
  https://api.lumiid.com/v1/ng/bvn-basic/ \
  -H "Authorization: Bearer Your-Secret-Key" \
  -H "Content-Type: application/json" \
  -d '{"id_number": "22123456789"}'

# Extract name and DOB only
curl -s -X POST \
  https://api.lumiid.com/v1/ng/bvn-basic/ \
  -H "Authorization: Bearer Your-Secret-Key" \
  -H "Content-Type: application/json" \
  -d '{"id_number": "22123456789"}' \
  | jq '.data | {firstname, lastname, birthdate, phone}'

Success Response 200 OK

{
  "success": true,
  "code": "BVN_VERIFIED",
  "message": "BVN verification successful",
  "verification_type": "BVN",
  "data": {
    "bvn":          "22123456789",
    "firstname":    "ADAEZE",
    "lastname":     "OKAFOR",
    "middlename":   "CHIDINMA",
    "birthdate":    "14-09-1992",
    "gender":       "Female",
    "phone":        "08098765432",
    "photo":        "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABGdBTUEAAK/INwWK6QAAABl0RVh0U29...",
    "match_result": "CONFIRMED"
  },
  "meta": {
    "request_id":  "req_97f1eed8156c",
    "timestamp":   "2026-03-19T06:00:38.693326+00:00",
    "api_version": "1.0"
  }
}

Error — BVN Not Found 400

{
  "success": false,
  "code": "BVN_NOT_FOUND",
  "message": "Identity record not found. Please ensure the 11-digit BVN is correct.",
  "verification_type": "BVN",
  "data": null,
  "meta": null
}

Error — Gateway Timeout 504

{
  "success": false,
  "code": "TIMEOUT",
  "message": "Verification service timed out. Please try again later.",
  "verification_type": "BVN",
  "data": null,
  "meta": null
}