BVN Verification in Nigeria

Verify a Nigerian Bank Verification Number (BVN) and retrieve the holder's identity details — including full name, date of birth, phone number, and address.

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. Verification POST requests also require an Idempotency-Key header.

Make the verification request

Submit the BVN via the identity verification endpoint. Set country to NG and idType to bvn.

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

Request body fields

Field	Type	Required	Description
`country`	string	Yes	Always `NG`.
`idType`	string	Yes	Always `bvn`.
`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	Override webhook URL for this request. Only used in `async` mode.
`validation`	object	No	Optional fields to match against the BVN record. See validation section below.

Optional validation

You can include a validation object to check whether specific fields match the BVN record. The response will include a validation object indicating whether each field matched.

curl -X POST https://api.lira.com/api/v1/verify/identity \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "idType": "bvn",
    "idNumber": "12345678901",
    "validation": {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-15"
    }
  }'

Validation field	Type	Description
`firstName`	string	First name to match against the BVN record.
`lastName`	string	Last name to match against the BVN record.
`dateOfBirth`	string	Date of birth in `YYYY-MM-DD` format.
`selfie`	string	Base64-encoded selfie image for facial comparison.

Read the result

Successful verification

{
  "id": "c3d4e5f6-...-...-...-...",
  "status": "success",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "12345678901",
  "verifiedAt": "2026-03-15T14:30:00.000Z",
  "verified": true,
  "firstName": "Jane",
  "lastName": "Doe",
  "middleName": "Amara",
  "dateOfBirth": "1990-01-15",
  "phoneNumber": "08012345678",
  "gender": "Female",
  "nin": "12345678901",
  "registrationDate": "2015-06-20",
  "address": {
    "state": "Lagos",
    "lga": "Ikeja",
    "town": "Oregun",
    "street": "1 Test Street"
  }
}

Successful verification with validation

When you include a validation object in the request, the response includes match results for each field you submitted:

{
  "id": "c3d4e5f6-...-...-...-...",
  "status": "success",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "12345678901",
  "verifiedAt": "2026-03-15T14:30:00.000Z",
  "verified": true,
  "firstName": "Jane",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-15",
  "validation": {
    "firstName": { "value": "Jane", "match": true },
    "lastName": { "value": "Doe", "match": true },
    "dateOfBirth": { "value": "1990-01-15", "match": true }
  }
}

Failed verification

{
  "id": "c3d4e5f6-...-...-...-...",
  "status": "failed",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "12345678901",
  "verifiedAt": "2026-03-15T14:30:00.000Z",
  "verified": false,
  "error": {
    "code": "IDENTITY_NOT_FOUND",
    "message": "No identity record found for the provided BVN"
  }
}

Note: A 200 OK HTTP response does not mean the verification succeeded. Always check the status field.

Response fields reference

Field	Type	Description
`id`	string	Unique 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`.
`country`	string	Always `NG`.
`identifier`	string	The BVN submitted in the request.
`verified`	boolean	`true` if the BVN was confirmed; `false` otherwise.
`verifiedAt`	string	ISO 8601 timestamp of when the verification completed.
`firstName`	string	Holder's first name. Present when `status` is `success`.
`lastName`	string	Holder's last name. Present when `status` is `success`.
`middleName`	string	Holder's middle name. May be `null`.
`dateOfBirth`	string	Date of birth in `YYYY-MM-DD` format. Present when `status` is `success`.
`phoneNumber`	string	Registered phone number. Present when `status` is `success`.
`gender`	string	Gender as recorded in the BVN registry.
`nin`	string	National Identification Number linked to the BVN.
`registrationDate`	string	Date the BVN was registered.
`enrollmentBranch`	string	Bank branch where the BVN was enrolled. May be `null`.
`enrollmentInstitution`	string	Financial institution where the BVN was enrolled. May be `null`.
`levelOfAccount`	string	Account level classification. May be `null`.
`address`	object	Address on file. Fields may be `null` depending on the record.
`address.state`	string	State of residence.
`address.lga`	string	Local government area.
`address.town`	string	Town or city.
`address.street`	string	Street address.
`validation`	object	Present only when `validation` was included in the request. Contains match results.
`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.

Nigeria-specific notes

A BVN is an 11-digit number issued by the Central Bank of Nigeria. Validate the length before submitting.
BVN verification returns significantly more identity data than bank account or phone number verification — use it for KYC and onboarding flows where you need the holder's full profile.
The nin field (National Identification Number) is linked to the BVN and returned when available.

Error handling

`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	Ensure the BVN is exactly 11 digits
`UNSUPPORTED_ID_TYPE`	`idType` is not supported for the given country	Use `bvn` for Nigeria
`UNSUPPORTED_COUNTRY`	Country code not supported for identity verification	Currently only `NG` is supported
`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 verify that BVN. Please check the number and try again.").

Next steps

Identity Verification Overview — supported identity document types and countries
Bank Account in Nigeria — verify Nigerian bank accounts
Phone Number in Nigeria — verify Nigerian phone subscribers
Async Verification with Webhooks — receive results via webhook
Errors — complete error code reference

Overview

Testing on the Sandbox Environment