Skip to content
Lira APILira API

Quickstart

Make your first Lira API call in 5 minutes, from creating an account to reading a verification result.

Prerequisites

  • A Lira account with an active organization. Sign up if you don't have one.
  • curl installed, or any HTTP client.

Note

This guide uses the sandbox environment. No real external queries are made and no charges are incurred. See Environments for the full list of sandbox test data.

Step 1: Get your sandbox API key

API keys are created in the dashboard.

  1. Sign in at app.uselira.com.
  2. Open API Keys from the sidebar and click Create API key.
  3. Give it a name (for example, My first sandbox key) and choose the Sandbox environment.
  4. Copy the key — it is shown only once. It looks like lira_sandbox_a3f08c1d4e2b9f3c....

Warning

The full key is displayed only once, right after you create it. Copy it immediately and store it in an environment variable or secrets manager. If you lose it, revoke the key and create a new one.

See API Keys for managing, rotating, and revoking keys.

Step 2: Verify a bank account

Use your API key in the X-API-Key header to call the verification endpoint. Verification POST requests also require an Idempotency-Key; reuse the same key only when retrying the same logical request. This example uses a sandbox test account number that always returns a successful result.

Terminal
curl -X POST https://api.uselira.com/api/v1/verify/account \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0000000000",
    "country": "NG",
    "bankCode": "000014"
  }'

Step 3: Read the result

Successful verification

JSON
{
  "id": "a1b2c3d4-...-...-...-...",
  "status": "success",
  "verificationType": "ACCOUNT_NUMBER",
  "identifier": "0000000000",
  "country": "NG",
  "verifiedAt": "2026-03-09T10:05:00.000Z",
  "verified": true,
  "accountNumber": "0000000000",
  "accountName": "Test Account",
  "bankCode": "000014",
  "bankName": "Access Bank",
  "address": {
    "state": "Lagos",
    "lga": "Ikeja"
  }
}

Note

A 200 OK HTTP response does not mean the verification succeeded. Always check the status field in the response body. A status of failed means the account was not found or the details did not match. This is a valid, expected outcome, not an API error.

Failed verification, for example, using account number 0000000001

JSON
{
  "id": "a1b2c3d4-...-...-...-...",
  "status": "failed",
  "verificationType": "ACCOUNT_NUMBER",
  "identifier": "0000000001",
  "country": "NG",
  "verifiedAt": "2026-03-09T10:05:00.000Z",
  "verified": false,
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "No account found for the provided details"
  }
}

Check error.code to understand why a verification failed and take the appropriate action. See Errors for the full list of error codes.

Error handling

StatusCodeCauseAction
401—Missing or invalid X-API-KeyCheck the key is correct and not revoked
422—Missing required fieldCheck request body for accountNumber, country, bankCode
429—Rate limit exceededBack off and retry after the Retry-After header value

What's next

← PreviousWelcome to LiraNext →How It Works