Overview

Lira verifies bank accounts, phone numbers, and identity documents against official registries, giving remittance companies, diaspora platforms, and African fintechs the confidence to know who they are paying before a transaction is processed.

When you submit a verification, Lira queries the relevant registry and returns the verified account holder or subscriber details, or a structured failure reason if the identifier could not be confirmed. Results can be used to pre-validate recipient details, reduce fraud, prevent failed transactions, or power downstream KYC and onboarding flows.

Before you start

You'll need an API key to call verification endpoints. API keys use the X-API-Key header, not a Bearer token.

Verification POST requests also require an Idempotency-Key header. Use a unique key for each logical request and reuse that same key when retrying after a timeout or network failure. If Lira has already processed the request, the retry returns the original response instead of running the verification again.

If you don't have an API key yet, follow the Quickstart to create one in under 5 minutes.
For a full explanation of how the two auth methods work together, see Authentication.
To understand sandbox test data and expected outcomes, see Environments.

Verification types

Type	Endpoint	What it verifies	Key data returned
Bank Account	`POST /verify/account`	Account number + bank code	Account name, bank name, address
Phone Number	`POST /verify/phone`	Mobile number + country	Full name, date of birth
Identity Document	`POST /verify/identity`	National ID, passport, or driver's licence number + country	Full name, date of birth

Idempotency

Include both headers on every verification mutation:

Terminal

-H "X-API-Key: YOUR_API_KEY"
-H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY"

Status	`error.code`	Meaning
`422`	`IDEMPOTENCY_KEY_REQUIRED`	The endpoint requires an `Idempotency-Key` header.
`422`	`IDEMPOTENCY_KEY_INVALID`	The key must be 1-255 printable ASCII characters.
`409`	`IDEMPOTENCY_IN_PROGRESS`	A request with this key is still being processed. Retry after a short delay.
`409`	`IDEMPOTENCY_KEY_CONFLICT`	The key was already used with a different request body. Generate a new key for the new request.

Dashboard and first-party clients should generate the key at submit time, keep it with the in-flight request state, and reuse it for retrying the same request. Generate a new key when the user changes the form inputs or starts a new verification.

Modes

Mode	How it works	Best for
`sync`	Result returned immediately in the HTTP response	Real-time checks at the point of payment
`async`	Returns `pending` immediately; result delivered via webhook	High-throughput batch flows, background processing

The default mode is sync. To use async mode, include "mode": "async" in the request body. See Async Verification with Webhooks for the full end-to-end walkthrough.

Verification lifecycle

flowchart TD
    A[Request submitted] --> B{Mode}
    B -->|sync| C[Result returned immediately in the HTTP response]
    B -->|async| D["status: pending, returned immediately; Lira queues the request"]
    D --> E[Lira queries the registry]
    E -->|success| F["status: success, verified data"]
    E -->|failed| G["status: failed, error.code (e.g. ACCOUNT_NOT_FOUND)"]
    E -->|error| H["status: error, error.code (e.g. PROVIDER_TIMEOUT)"]
    F --> I["Webhook delivered to your endpoint (async mode only)"]
    G --> I
    H --> I

Note

A 200 OK HTTP response does not mean the verification succeeded. Always check the status field in the response body. failed is a valid, expected outcome. It means the account or number was not found, not that the API call itself failed.

Verification response fields

These fields are common across all verification types. Type-specific fields are documented in each guide.

Field	Type	Description
`id`	string	Unique verification ID. Store this to retrieve the result later or correlate with a webhook event.
`status`	string	`success`, `failed`, `error`, or `pending` (async only).
`verificationType`	string	`ACCOUNT_NUMBER`, `PHONE_NUMBER`, or an identity document type (e.g. `BVN`, `KE_NATIONAL_ID`).
`identifier`	string	The account number, phone number, or document number that was submitted.
`country`	string	ISO 3166-1 alpha-2 country code (e.g. `NG`, `GH`).
`verified`	boolean	`true` if the identifier was confirmed; `false` otherwise.
`verifiedAt`	string	ISO 8601 timestamp of when the verification completed.
`error`	object	Present when `status` is `failed` or `error`. Contains `code` and `message`.
`error.code`	string	Machine-readable error code. See Errors for the full list.
`error.message`	string	Human-readable description of the failure reason.

Guides

Verify a Bank Account: step-by-step with request, response, and error examples
Verify a Phone Number: includes country-specific requirements and supported network codes
Verify an identity document — government ID verification by country: Nigeria (BVN), Ghana, and Kenya
Async Verification with Webhooks: async mode, webhook delivery, signature verification, and retry handling

Next steps

Errors

Complete reference for all verification error codes

Environments

Sandbox test data for all verification types

Go Live

Checklist before switching to live traffic

← PreviousCountry Requirements Next →Bank Verification Number (BVN)