Verify a BVN (Bank Verification Number)

Verify a Nigerian Bank Verification Number (BVN) and retrieve the holder's personal details — name, date of birth, gender, address, and linked NIN — before processing a transaction or onboarding a customer.

Prerequisites

You'll need an API key. See Quickstart or Authentication if you don't have one yet.

Note: Verification endpoints use an API key in the X-API-Key header — not a Bearer token.

Step 1 — Make the verification request

Submit the BVN, country code, and identity type to the verification endpoint.

curl -X POST https://api.lira.com/api/v1/verify/identity \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "idType": "bvn",
    "idNumber": "12345678901"
  }'

Request body fields

Field	Type	Required	Description
`country`	string	Yes	ISO 3166-1 alpha-2 country code. Currently supported: `NG`.
`idType`	string	Yes	Identity document type. Use `bvn` for Nigeria.
`idNumber`	string	Yes	The 11-digit BVN to verify.
`mode`	string	No	`sync` (default) or `async`. Use `async` to receive the result via webhook.
`webhookUrl`	string	No	Required when `mode` is `async`. Must be an HTTPS URL.

Note: In sandbox, use BVN 00000000000 with country NG and idType bvn to get a predictable successful result. See Environments for the full list of sandbox test data.

Step 2 — Read the result

Successful verification

{
  "id": "ver_c3d4e5f6-...",
  "status": "success",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "12345678901",
  "verifiedAt": "2026-03-18T10:05:00.000Z",
  "verified": true,
  "firstName": "Ada",
  "lastName": "Obi",
  "middleName": "Chisom",
  "dateOfBirth": "1990-05-15",
  "phoneNumber": "08012345678",
  "gender": "Female",
  "nin": "98765432101",
  "enrollmentBranch": "Lagos Island",
  "enrollmentInstitution": "Access Bank",
  "registrationDate": "2016-11-20",
  "levelOfAccount": "Level 1",
  "address": {
    "street": "1 Marina Road",
    "town": "Lagos Island",
    "lga": "Lagos Island",
    "state": "Lagos"
  }
}

Failed verification

{
  "id": "ver_c3d4e5f6-...",
  "status": "failed",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "12345678901",
  "verifiedAt": "2026-03-18T10:05:00.000Z",
  "verified": false,
  "error": {
    "code": "IDENTITY_NOT_FOUND",
    "message": "No record found for the provided BVN"
  }
}

Note: A 200 OK HTTP response does not mean the verification succeeded. Always check the status field. failed is a valid, expected outcome — not an API error.

Response fields reference

Field	Type	Description
`id`	string	Unique verification ID (`VERIFICATION_ID`). Store this to retrieve the result later or correlate with a webhook.
`status`	string	`success`, `failed`, `error`, or `pending` (async only).
`verificationType`	string	Always `BVN` for this endpoint.
`idType`	string	Always `bvn` for this endpoint.
`identifier`	string	The BVN submitted in the request.
`country`	string	Country code from the request.
`verified`	boolean	`true` if the BVN was confirmed; `false` otherwise.
`verifiedAt`	string	ISO 8601 timestamp of when the verification completed.
`firstName`	string	First name as held on the BVN record. Present when `status` is `success`.
`lastName`	string	Last name as held on the BVN record. Present when `status` is `success`.
`middleName`	string	Middle name. Present when `status` is `success`. May be absent if not registered.
`dateOfBirth`	string	Date of birth in `YYYY-MM-DD` format. Present when `status` is `success`.
`phoneNumber`	string	Phone number linked to the BVN. Present when `status` is `success`.
`gender`	string	Gender as registered on the BVN. Present when `status` is `success`.
`nin`	string	National Identification Number linked to the BVN. Present when `status` is `success`. May be absent if not linked.
`enrollmentBranch`	string	Branch where the BVN was enrolled. Present when `status` is `success`.
`enrollmentInstitution`	string	Bank or institution where the BVN was enrolled. Present when `status` is `success`.
`registrationDate`	string	Date the BVN was registered. Present when `status` is `success`.
`levelOfAccount`	string	KYC tier of the account holder. Present when `status` is `success`.
`address.street`	string	Street address. May be absent depending on the registry.
`address.town`	string	Town or city. May be absent depending on the registry.
`address.lga`	string	Local government area. May be absent depending on the registry.
`address.state`	string	State. May be absent depending on the registry.
`error`	object	Present when `status` is `failed` or `error`.
`error.code`	string	Machine-readable failure code. See error handling table below.
`error.message`	string	Human-readable description.

Step 3 — Retrieve the result later

If you need to fetch a verification result again, use its id:

curl https://api.lira.com/api/v1/verify/VERIFICATION_ID \
  -H "X-API-Key: YOUR_API_KEY"

Step 4 — List past verifications

View all BVN verifications for your organization, with optional filters:

curl "https://api.lira.com/api/v1/verify?type=BVN&status=success" \
  -H "X-API-Key: YOUR_API_KEY"

Query parameters

Parameter	Description
`type`	Filter by verification type. Use `BVN`.
`status`	Filter by result: `success`, `failed`, `error`, `pending`.
`limit`	Number of results to return.
`offset`	Pagination offset.

Error handling

`status`	Meaning	Action
`success`	BVN verified	Read `firstName`, `lastName`, `dateOfBirth`, `address`, and other identity fields
`failed`	BVN not found or details do not match	Check `error.code` — prompt user to recheck their BVN
`error`	Upstream or system error	Retry with exponential backoff
`pending`	Async verification in progress	Poll `GET /verify/VERIFICATION_ID` or wait for webhook

`error.code`	Cause	Action
`IDENTITY_NOT_FOUND`	BVN not found in the registry	Ask the user to check their BVN is correct
`INVALID_ID_NUMBER`	BVN format is invalid (must be 11 digits)	Validate format before submitting
`UNSUPPORTED_COUNTRY`	Country code is not supported	Check the supported countries list
`UNSUPPORTED_ID_TYPE`	`idType` is not valid for the given country	Use `bvn` for `NG`
`PROVIDER_ERROR`	Upstream system returned an error	Retry with exponential backoff
`PROVIDER_TIMEOUT`	Upstream system timed out	Retry — transient error

For the full error code reference, see Errors.

Warning: Do not surface raw error.code values directly to end users. Map them to user-friendly messages in your application (e.g. IDENTITY_NOT_FOUND → "We couldn't find a record for that BVN. Please double-check the number and try again.").

Next steps

Verify a Bank Account — verify account holder details for bank-to-bank transfers
Verify a Phone Number — verify phone subscriber details across Nigeria and Ghana
Async Verification with Webhooks — run verifications asynchronously and receive results via webhook
Errors — complete error code reference
Environments — sandbox test data for identity verifications

Overview

Testing on the Sandbox Environment