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 provider queries are made and no charges are incurred. See Environments for the full list of sandbox test data.

Step 1 — Log in and get a Bearer token

Your Bearer token is used to manage resources like API keys and webhooks. See Authentication for full details including token refresh.

curl -X POST https://api.lira.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@yourcompany.com",
    "password": "your-password"
  }'

Response

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "eyJhbGci...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Copy the accessToken. You'll use it in the next step.

Step 2 — Generate a sandbox API key

Use your Bearer token to create an API key scoped to the sandbox environment.

curl -X POST https://api.lira.com/api/v1/client/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first sandbox key",
    "environment": "sandbox"
  }'

Response 201 Created

{
  "id": "3f4a1b2c-...",
  "name": "My first sandbox key",
  "key": "lira_sandbox_a3f08c1d4e2b9f3c...",
  "keyPrefix": "lira_sandbox_a3f0...",
  "environment": "sandbox",
  "createdAt": "2026-03-09T10:00:00.000Z",
  "warning": "Save this key securely. It will not be shown again."
}

Warning: The key field is only returned once. Copy it immediately and store it in an environment variable or secrets manager. It cannot be retrieved after this response.

Step 3 — Verify a bank account

Use your API key in the X-API-Key header to call the verification endpoint. This example uses a sandbox test account number that always returns a successful result.

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

Step 4 — Read the result

Successful verification

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

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

What's next

• How It Works — understand the full mental model: verifications, auth, environments, and webhooks
• Verify a Bank Account — the complete guide with all request options, response fields, and error handling
• Verify a Phone Number — verify phone subscriber details across Nigeria and Ghana
• Async Verification with Webhooks — queue verifications and receive results via signed webhook delivery