Managing Verifications

After submitting verifications, you can retrieve individual results by ID or list past verifications with filters. This is useful for polling async verifications, building audit trails, or reconciling records.

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.

Retrieve a single verification

Fetch the result of a previous verification by its id. This is especially useful for polling async verifications that returned status: pending.

Terminal

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

Response

The response includes the full verification result, including type-specific fields. The shape matches the original response from the verification endpoint.

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"
}

Note

If the verification belongs to a different organization, you will receive a 403 Forbidden response. Each API key is scoped to the organization that created it.

List verifications

Retrieve a paginated list of all verifications for your organization.

Terminal

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

Query parameters

Parameter	Type	Default	Description
`type`	string	—	Filter by verification type: `ACCOUNT_NUMBER`, `PHONE_NUMBER`, `BVN`, `LIPA_NA_MPESA`, `MPESA_AGENT`.
`status`	string	—	Filter by status: `pending`, `success`, `failed`, `error`.
`limit`	integer	50	Number of results to return. Maximum `100`.
`offset`	integer	0	Pagination offset. Use with `limit` to page through results.

Response

Returns an array of verification summary records, ordered by creation date (newest first).

JSON

[
  {
    "id": "a1b2c3d4-...-...-...-...",
    "organizationId": "x1y2z3-...",
    "type": "ACCOUNT_NUMBER",
    "identifier": "0123456789",
    "status": "success",
    "mode": "sync",
    "source": "provider",
    "createdAt": "2026-03-09T10:05:00.000Z",
    "updatedAt": "2026-03-09T10:05:01.000Z"
  },
  {
    "id": "b2c3d4e5-...-...-...-...",
    "organizationId": "x1y2z3-...",
    "type": "BVN",
    "identifier": "12345678901",
    "status": "success",
    "mode": "sync",
    "source": "cache",
    "createdAt": "2026-03-09T09:30:00.000Z",
    "updatedAt": "2026-03-09T09:30:00.000Z"
  }
]

List response fields

Field	Type	Description
`id`	string	Unique verification ID. Use this with `GET /verify/:id` to fetch the full result.
`organizationId`	string	The organization that owns this verification.
`type`	string	Verification type: `ACCOUNT_NUMBER`, `PHONE_NUMBER`, `BVN`, `LIPA_NA_MPESA`, or `MPESA_AGENT`.
`identifier`	string	The account number, phone number, or BVN that was verified.
`status`	string	`success`, `failed`, `error`, or `pending`.
`mode`	string	`sync` or `async`.
`source`	string	`provider` if the result came from a live registry query, or `cache` if served from a previous lookup.
`createdAt`	string	ISO 8601 timestamp of when the verification was submitted.
`updatedAt`	string	ISO 8601 timestamp of the last status change.

Note

The list endpoint returns summary records. To get the full verification result with type-specific fields (e.g. accountName, firstName, validation), fetch the individual verification by ID.

Polling async verifications

When you submit a verification with "mode": "async", the initial response returns status: pending. You can either wait for the webhook delivery or poll the result:

Terminal

# Poll until status is no longer "pending"
curl https://api.lira.com/api/v1/verify/VERIFICATION_ID \
  -H "X-API-Key: YOUR_API_KEY"

We recommend using webhooks instead of polling for async verifications. See Async Verification with Webhooks for the full walkthrough.

Common patterns

Filter by type

Retrieve only bank account verifications:

Terminal

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

Filter by status

Retrieve only failed verifications for investigation:

Terminal

curl "https://api.lira.com/api/v1/verify?status=failed&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

Paginate through results

Terminal

# First page
curl "https://api.lira.com/api/v1/verify?limit=20&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Second page
curl "https://api.lira.com/api/v1/verify?limit=20&offset=20" \
  -H "X-API-Key: YOUR_API_KEY"

Error handling

HTTP status	Cause	Action
`200`	Verification found	Read the response body
`403`	Verification belongs to a different organization	Ensure you are using the correct API key
`404`	Verification ID not found	Check the ID is correct and was returned by a previous verification request

For the full error code reference, see Errors.

Next steps

Verifications Overview

Verification types, modes, and lifecycle

Async Verification with Webhooks

Receive results via webhook instead of polling

Errors

Complete error code reference

← PreviousNational ID, Driver's Licence & Passport Next →Overview