Guides

Verify a Phone Number

Verify that a mobile phone number is registered with a carrier 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.

Supported networks by country

Country Code networkCode required Supported values
Nigeria NG No —
Ghana GH Yes MTN, Vodafone, AirtelTigo

Important: Ghana phone number verifications will return NETWORK_CODE_REQUIRED if networkCode is omitted. Always include the carrier code for GH verifications.

Step 1 — Make the verification request

Nigeria (NG)

No networkCode is required for Nigerian numbers.

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

Ghana (GH)

Ghana requires a networkCode to identify the carrier.

curl -X POST https://api.lira.com/api/v1/verify/phone \
  -H "X-API-Key: YOUR_API_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. Supported: NG, GH.
networkCode string Required for GH Mobile network code. Required for Ghana. Not used for Nigeria.
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 

{
  "id": "ver_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 

{
  "id": "ver_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 carrier. Present when status is success.
lastName string Subscriber's last name. Present when status is success.
fullName string Subscriber's full name. Present when status is success.
dateOfBirth string Subscriber's date of birth in YYYY-MM-DD format. Present when status is success. May be absent depending on carrier.
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 

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

Step 4 — List past verifications 

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 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
SUBSCRIBER_NOT_FOUND Phone number not registered with the carrier 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 recognised for the given country Check the supported values in the table above
NETWORK_CODE_REQUIRED Ghana verification submitted without networkCode Add networkCode to the request
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. SUBSCRIBER_NOT_FOUND → "We couldn't find a registered subscriber for that number. Please check it and try again.").

Next steps

Previous
Verify a Bank Account
Next
Async Verification