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

Terminal
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

JSON
{
  "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.

Terminal
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

JSON
{
  "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. 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.lira.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 4: 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