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.

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.

{
  "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": "044",
  "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.

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

Query parameters

Response

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

[
  {
    "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

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:

# 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:

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:

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

Paginate through results

# 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

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