Overview

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

Step 1: Make the verification request

Submit the account number, country code, and bank code to the verification endpoint.

Terminal

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

Request body fields

Field	Type	Required	Description
`accountNumber`	string	Yes	The bank account number to verify. 10 digits for Nigerian NUBAN accounts; the UnionPay card number for China personal accounts.
`country`	string	Yes	ISO 3166-1 alpha-2 country code. See Country Requirements for every supported country (African, UK/China, Asia, LATAM, and Europe/SEPA corridors).
`bankCode`	string	Yes	The receiving institution's routing code. Its form depends on the country: the local bank/clearing code for African corridors, the 6-digit sort code for the UK, or the bank's BIC/SWIFT code for China business accounts. Supply whichever routing code applies to the destination country in this single field.
`accountName`	string	Conditional	The claimed account holder name. Required for `GB` and `CN`, where verification confirms whether this name matches the bank's record. Optional elsewhere.
`accountHolderType`	string	Conditional	`INDIVIDUAL` or `BUSINESS`. Required for `CN` to select the right matching rules.
`identifiers`	array	Conditional	Corridor-specific identity codes for the account holder, each `{ "type": ..., "value": ... }`. Required for `CN` business accounts (a `BUSINESS_REGISTRATION` entry carrying the 18-character Uniform Credit Code), and for Brazil (`CPF`/`CNPJ`), Chile (`RUT`), Colombia (`CC`/`NIT`), and Ecuador (`CC`/`RUC`).
`mode`	string	No	`sync` (default) or `async`. Use `async` to receive the result via webhook. Not supported for `TZ`, `ET`, `GB`, `CN`, or the Asia, LATAM, and Europe/SEPA corridors; those are synchronous only.

Formats, bank codes, and required fields vary by country. See Country Requirements for every supported country.

Note

In sandbox, use account number 0000000001 with bank code 000014 and country NG to get a predictable successful result. See Environments for the full list of sandbox test data.

Name-match corridors (UK & China)

For GB and CN, verification works differently from the African corridors. Instead of returning the account holder's name from a registry, the bank confirms whether the accountName you supplied matches the account on record.

You must send accountName in the request.
When verified is true, the name matched. The accountName in the response is the name you submitted. These corridors do not return a separately sourced name.
When verified is false, the account was not found or the name did not match. accountName is omitted.

This keeps the response shape uniform across every country while reflecting that name-match corridors never disclose the registered name.

Step 2: Read the result

Successful verification

JSON

{
  "id": "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": "000014",
  "bankName": "Access Bank",
  "address": {
    "state": "Lagos",
    "lga": "Ikeja"
  }
}

Failed verification

JSON

{
  "id": "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	For `NG`/`GH`/`ZM`/`TZ`/`ET`, the account holder's name as returned by the bank. For `GB`/`CN`, the name you submitted, confirmed to match the bank's record. 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 the bank.
`address.lga`	string	The local government area. May be absent depending on the bank.
`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:

Terminal

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:

Terminal

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`	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
`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 recognized	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 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.

Next steps

Country Requirements

Formats, bank codes, and extras for every supported country

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

← PreviousGo Live Next →Country Requirements