Overview

Verify that a mobile phone number is registered with a mobile operator and retrieve the subscriber's name and date of birth before processing 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 phone number and country code. Most countries also require a networkCode identifying the mobile operator. See Country Requirements for each country's format and supported codes.

Terminal

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

With a networkCode (here Ghana, where it's required):

Terminal

curl -X POST https://api.lira.com/api/v1/verify/phone \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "0241234567",
    "country": "GH",
    "networkCode": "MTN"
  }'

Request body fields

Field	Type	Required	Description
`phoneNumber`	string	Yes	The phone number to verify. Accepts local format (e.g. `08012345678`) or E.164 (e.g. `+2348012345678`).
`country`	string	Yes	ISO 3166-1 alpha-2 country code. See Country Requirements for the supported list.
`networkCode`	string	Varies	Mobile operator code. Required in most countries; values and casing differ per country. See Country Requirements.
`mode`	string	No	`sync` (default) or `async`. Use `async` to receive the result via webhook.

Note

In sandbox, use phone number 08000000000 with 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

JSON

{
  "id": "b2c3d4e5-...-...-...-...",
  "status": "success",
  "verificationType": "PHONE_NUMBER",
  "identifier": "08012345678",
  "country": "NG",
  "verifiedAt": "2026-03-09T10:06:00.000Z",
  "verified": true,
  "phoneNumber": "08012345678",
  "firstName": "Jane",
  "lastName": "Doe",
  "fullName": "Jane Doe",
  "dateOfBirth": "1990-01-15"
}

Failed verification

JSON

{
  "id": "b2c3d4e5-...-...-...-...",
  "status": "failed",
  "verificationType": "PHONE_NUMBER",
  "identifier": "08012345678",
  "country": "NG",
  "verifiedAt": "2026-03-09T10:06:00.000Z",
  "verified": false,
  "error": {
    "code": "SUBSCRIBER_NOT_FOUND",
    "message": "No subscriber found for the provided phone number"
  }
}

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 `PHONE_NUMBER` for this endpoint.
`identifier`	string	The phone number submitted in the request.
`country`	string	Country code from the request.
`verified`	boolean	`true` if the subscriber was confirmed; `false` otherwise.
`verifiedAt`	string	ISO 8601 timestamp of when the verification completed.
`phoneNumber`	string	The verified phone number. Present when `status` is `success`.
`firstName`	string	Subscriber's first name as returned by the operator. Present when `status` is `success`. Not available in every country. See Country Requirements.
`lastName`	string	Subscriber's last name. Present when `status` is `success`. Not available in every country.
`fullName`	string	Subscriber's full name. Present when `status` is `success`.
`dateOfBirth`	string	Subscriber's date of birth in `YYYY-MM-DD` format. Currently returned for Nigeria only, and may be absent depending on the operator.
`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

Terminal

curl https://api.lira.com/api/v1/verify/VERIFICATION_ID \
  -H "X-API-Key: YOUR_API_KEY"

Step 4: List past verifications

Terminal

curl "https://api.lira.com/api/v1/verify?type=PHONE_NUMBER&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Query parameters

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

Error handling

`status`	Meaning	Action
`success`	Subscriber confirmed	Read `firstName`, `lastName`, `fullName`, `dateOfBirth`
`failed`	Number not found or unregistered	Check `error.code`; prompt user to verify their number
`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
`SUBSCRIBER_NOT_FOUND`	Phone number not registered with the operator	Ask the user to verify their number is correct and active
`INVALID_PHONE_NUMBER`	Phone number format is invalid	Validate format (local or E.164) before submitting
`INVALID_NETWORK_CODE`	`networkCode` not recognized for the given country	Check the values in Country Requirements
`NETWORK_CODE_REQUIRED`	Verification submitted without a required `networkCode`	Add `networkCode` to the request
`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, networkCode values, and returned fields per country

Async Verification with Webhooks

Run verifications asynchronously and receive results via webhook

Errors

Complete error code reference

Environments

Sandbox test data for phone number verifications

← PreviousOverview Next →Country Requirements