Verifications

Lira verifies bank accounts and phone numbers against provider data, 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 provider 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.

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

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

Request submitted
      │
      ▼
  [sync mode] ─────────────────────────► Result returned immediately in HTTP response
      │
  [async mode]
      │
      ▼
  status: pending          ← returned immediately; Lira queues the request
      │
      ▼
  Lira queries provider
      │
      ├── success → status: success + verified data
      │
      ├── failed  → status: failed  + error.code (e.g. ACCOUNT_NOT_FOUND)
      │
      └── error   → status: error   + error.code (e.g. PROVIDER_TIMEOUT)
              │
              ▼
       Webhook delivered to your endpoint (async mode only)

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 both 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` or `PHONE_NUMBER`.
`identifier`	string	The account number or phone 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
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

Supported Countries

Verify a Bank Account