Verify a Bank Account

Verify that a bank account exists and retrieve the account holder's name and address details before initiating a transfer.

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 account number, country code, and bank code to the verification endpoint.

curl -X POST https://api.lira.com/api/v1/verify/account \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0123456789",
    "country": "NG",
    "bankCode": "044"
  }'

Request body fields

Field	Type	Required	Description
`accountNumber`	string	Yes	The bank account number to verify. 10 digits for Nigerian NUBAN accounts.
`country`	string	Yes	ISO 3166-1 alpha-2 country code. Supported: `NG`, `GH`.
`bankCode`	string	Yes	The bank's routing or sort code.
`mode`	string	No	`sync` (default) or `async`. Use `async` to receive the result via webhook.

Note: In sandbox, use account number 0000000000 with bank code 044 and country NG 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_a1b2c3d4-...",
  "status": "success",
  "verificationType": "ACCOUNT_NUMBER",
  "identifier": "0123456789",
  "country": "NG",
  "verifiedAt": "2026-03-09T10:05:00.000Z",
  "verified": true,
  "accountNumber": "0123456789",
  "accountName": "Jane Doe",
  "bankCode": "044",
  "bankName": "Access Bank",
  "address": {
    "state": "Lagos",
    "lga": "Ikeja"
  }
}

Failed verification

{
  "id": "ver_a1b2c3d4-...",
  "status": "failed",
  "verificationType": "ACCOUNT_NUMBER",
  "identifier": "0123456789",
  "country": "NG",
  "verifiedAt": "2026-03-09T10:05:00.000Z",
  "verified": false,
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "No account found for the provided details"
  }
}

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 `ACCOUNT_NUMBER` for this endpoint.
`identifier`	string	The account number submitted in the request.
`country`	string	Country code from the request.
`verified`	boolean	`true` if the account was confirmed; `false` otherwise.
`verifiedAt`	string	ISO 8601 timestamp of when the verification completed.
`accountNumber`	string	The verified account number. Present when `status` is `success`.
`accountName`	string	The account holder's name as returned by the provider. Present when `status` is `success`.
`bankCode`	string	The bank code from the request. Present when `status` is `success`.
`bankName`	string	The full name of the bank. Present when `status` is `success`.
`address.state`	string	The state associated with the account. May be absent depending on provider.
`address.lga`	string	The local government area. May be absent depending on provider.
`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 bank account verifications for your organization, with optional filters:

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

Query parameters

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

Error handling

`status`	Meaning	Action
`success`	Account verified	Read `accountName`, `bankName`, and `address`
`failed`	Account not found or details mismatch	Check `error.code` — prompt user to recheck details
`error`	Provider 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
`ACCOUNT_NOT_FOUND`	Account number not found at the specified bank	Ask the user to check their account number and bank code
`INVALID_BANK_CODE`	Bank code not recognised	Validate against the supported banks list
`INVALID_ACCOUNT_NUMBER`	Account number format is invalid	Validate format (10 digits for Nigeria) before submitting
`PROVIDER_ERROR`	Upstream provider returned an error	Retry with exponential backoff
`PROVIDER_TIMEOUT`	Upstream provider 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. ACCOUNT_NOT_FOUND → "We couldn't find an account with those details. Please check your account number and bank.").

Next steps

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 bank account verifications

Overview

Verify a Phone Number