Test Numbers

Use these identifiers to simulate the scenarios your integration must handle. Requests made with a sandbox API key return these seeded responses instantly. No provider is called.

How Sandbox Works

• Determined by the API key you send. Sandbox and live keys are issued separately from your dashboard.
• Sandbox requests are free (priceUsdAtCall: 0) but still count toward your sandbox rate limits and show up in your verification list alongside live records.
• Async sandbox requests fire a real webhook to your registered webhook URL after a short delay (approximately 3 seconds).

Unknown identifiers

• Sending an identifier not listed on this page returns TEST_NUMBER_NOT_FOUND.
• Sending a bank code outside the per-country list below returns INVALID_BANK_CODE.

Account Verification (POST /verify/account)

Phone Verification (POST /verify/phone)

BVN Identity Verification (POST /verify/identity, NG)

SUCCESS: example response for 22222222201

{
  "id": "8f3a7b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "success",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "22222222201",
  "verifiedAt": "2026-04-21T09:15:32.104Z",
  "verified": true,
  "firstName": "Test",
  "lastName": "Okoye",
  "middleName": "Sandbox",
  "dateOfBirth": "1990-01-01",
  "phoneNumber": "+2348000000001",
  "gender": "Male",
  "enrollmentBranch": "Victoria Island",
  "enrollmentInstitution": "Access Bank",
  "registrationDate": "2010-05-15",
  "nin": "12345678901",
  "levelOfAccount": "Tier 3",
  "address": {
    "town": "Lagos",
    "lga": "Eti-Osa",
    "state": "Lagos",
    "street": "10 Sandbox Street"
  },
  "title": "Mr",
  "maritalStatus": "Single",
  "lgaOfOrigin": "Onitsha North",
  "otherMobile": "+2348000000099",
  "stateOfOrigin": "Anambra",
  "watchListed": "NO",
  "nameOnCard": "OKOYE TEST SANDBOX",
  "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
  "validation": null
}

id and verifiedAt vary per call; everything else is deterministic. image is a 1×1 transparent PNG encoded as base64 (lets you exercise your decoding pipeline end-to-end without a real photo). validation is populated only when your request includes a validation block (see the BVN reference for the full matcher schema).

NOT_FOUND: example response for 22222222202

{
  "id": "…",
  "status": "failed",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "22222222202",
  "verifiedAt": "…",
  "error": { "code": "BVN_NOT_FOUND", "message": "BVN not found" }
}

PROVIDER_ERROR: example response for 22222222203

{
  "id": "…",
  "status": "error",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "22222222203",
  "verifiedAt": "…",
  "error": { "code": "PROVIDER_ERROR", "message": "Simulated upstream provider error" }
}

Note the different status values: failed is a business failure (BVN does not exist upstream); error is an infrastructure failure (upstream provider returned 5xx). Matches live behavior.

NIN Identity Verification (POST /verify/identity, TZ)

NIN identifiers are exactly 20 digits. The validation object must include firstName and lastName; motherFirstName, placeOfBirth, dateOfBirth, and sex are optional and used to answer the identity challenge question.

SUCCESS: example response for 11111111111111111101

{
  "id": "…",
  "status": "success",
  "verificationType": "NIN",
  "idType": "nin",
  "country": "TZ",
  "identifier": "11111111111111111101",
  "verified": true,
  "firstName": "Test",
  "lastName": "Mwangi",
  "gender": "M",
  "dateOfBirth": "1990-01-01",
  "placeOfBirth": "Dar es Salaam",
  "verifiedAt": "…"
}

NIN_NOT_FOUND: example response for 11111111111111111102

{
  "id": "…",
  "status": "failed",
  "verificationType": "NIN",
  "idType": "nin",
  "country": "TZ",
  "identifier": "11111111111111111102",
  "verified": false,
  "verifiedAt": "…",
  "error": { "code": "NIN_NOT_FOUND", "message": "NIN not found" }
}

IDENTITY_MISMATCH: example response for 11111111111111111103

{
  "id": "…",
  "status": "failed",
  "verificationType": "NIN",
  "idType": "nin",
  "country": "TZ",
  "identifier": "11111111111111111103",
  "verified": false,
  "verifiedAt": "…",
  "error": { "code": "IDENTITY_MISMATCH", "message": "Identity attributes did not match" }
}

PROVIDER_ERROR: example response for 11111111111111111104

{
  "id": "…",
  "status": "error",
  "verificationType": "NIN",
  "idType": "nin",
  "country": "TZ",
  "identifier": "11111111111111111104",
  "verifiedAt": "…",
  "error": { "code": "PROVIDER_ERROR", "message": "Simulated upstream provider error" }
}

Ghana Identity Verification (POST /verify/identity, GH)

Ghana Card, Voter ID, and Passport document lookups. Send country: "GH" and the matching idType. SUCCESS returns the seeded identity; to exercise inconclusive, send a validation block whose firstName/lastName/dateOfBirth does not match the SUCCESS identity below.

Passport SUCCESS returns dateOfBirth: null (passport records often omit it) — treat DOB as optional downstream.

SUCCESS: example response for GHA-100000001-1

{
  "id": "…",
  "status": "success",
  "verificationType": "GHANA_CARD",
  "idType": "ghana_card",
  "country": "GH",
  "identifier": "GHA-100000001-1",
  "verifiedAt": "…",
  "verified": true,
  "firstName": "Kwame",
  "lastName": "Mensah",
  "middleName": "Kofi",
  "dateOfBirth": "1990-04-12",
  "gender": "M",
  "validation": null
}

IDENTIFIER_NOT_FOUND: example response for GHA-100000002-2

{
  "id": "…",
  "status": "failed",
  "verificationType": "GHANA_CARD",
  "idType": "ghana_card",
  "country": "GH",
  "identifier": "GHA-100000002-2",
  "verifiedAt": "…",
  "error": { "code": "IDENTIFIER_NOT_FOUND", "message": "No identity record found" }
}

Kenya Identity Verification (POST /verify/identity, KE)

National ID, Driver's License, and Passport document lookups. Send country: "KE" and the matching idType. SUCCESS returns the seeded identity. Kenya is success/fail only — there is no client-side cross-check, so a validation block is used for matching the request (and is required for drivers_license) but never produces an inconclusive result.

national_id returns discrete firstName/lastName; drivers_license and passport return only a combined fullName (with firstName/lastName null) — mirroring the upstream record. drivers_license also requires validation.firstName and validation.lastName on the request (a 422 is returned otherwise).

SUCCESS: example response for 30000001

{
  "id": "…",
  "status": "success",
  "verificationType": "KE_NATIONAL_ID",
  "idType": "national_id",
  "country": "KE",
  "identifier": "30000001",
  "verifiedAt": "…",
  "verified": true,
  "firstName": "Wanjiru",
  "lastName": "Kamau",
  "middleName": "Njeri",
  "fullName": "Wanjiru Njeri Kamau",
  "dateOfBirth": "1992-03-15",
  "gender": "F",
  "nationality": "Kenyan",
  "placeOfBirth": "Nairobi"
}

SUCCESS: example request for DL0000001 (drivers_license)

curl -X POST https://api.uselira.com/api/v1/verify/identity \
  -H "X-API-Key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "idType": "drivers_license",
    "idNumber": "DL0000001",
    "validation": { "firstName": "John", "lastName": "Omondi" }
  }'

IDENTIFIER_NOT_FOUND: example response for 30000002

{
  "id": "…",
  "status": "failed",
  "verificationType": "KE_NATIONAL_ID",
  "idType": "national_id",
  "country": "KE",
  "identifier": "30000002",
  "verifiedAt": "…",
  "error": { "code": "IDENTIFIER_NOT_FOUND", "message": "No identity record found" }
}

Ghana Card Facial Verification (POST /verify/identity/facial, GH)

Facial verification matches a live selfie against the Ghana Card holder. In sandbox the selfie content is ignored — send any non-empty images.selfie and the Ghana Card number alone selects the outcome. The example below embeds a ready-to-use dummy selfie (a small base64 PNG) you can copy verbatim.

A malformed request (missing images.selfie, bad card number) returns 422 before any lookup. FACE_QUALITY_LOW, FACIAL_LIVENESS_FAILED, and FACE_NOT_DETECTED are retake-able; FACE_MATCH_FAILED is a genuine non-match.

Example request

curl -X POST https://api.uselira.com/api/v1/verify/identity/facial \
  -H "X-API-Key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "GH",
    "idType": "ghana_card",
    "idNumber": "GHA-000000001-1",
    "images": { "selfie": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAAB/klEQVR42u3cwU0kMRAFUCgRAfGQB2dSQISBSIEzeRAMp7lxJwLQAO2pb/v966KV/V+XZxfcXH+cPq+kL6UCAAAEAAABAEAAABAAAAQAAAEAQAAAEAAABAAAAQBAAAAQAAAEAAA5JjczLvr0/vrdH93ePcy1l+uJrqf/0Pu8EnMA/Kr6uRjSAf5c/SwMtXz7B/49ewEc21qsQe3QfrJBbdJ+rEHt036mQW3VfqCBb0UA6Hgwc4bABABoeiRDhsAEAACw4fmTcwqZAAAABAAAAQBAAABoSdethYTbEiYAAIA9T6GQ21omAEDHI5lzWdEEALj4gxl1VzduAka3k3ZTOvEIGtdR4D310M+AEU1lviWQ+yF8bF+x72hE/yvoqNaS35DxjhiAMQzekuyR8J6wLPQhDEAAABAAAAQAAAEAQAAAEAAABAAAAQBAAACQf2Wy357++Px2zpe9PN3PsqP0WxFnNj6vRyjAIb1PIREHMKj6WIYggAtUH8gQAXDh6qMYmgEaqw9hKO33rqRnAnKqbx+F0n7v2kr7vSss7feus7Tfu9rSfu+aS/u9Ky/t966/tN+7Cz8Ra055/Hv3Utrv3ZEjaMUjaL3Hf9y+TMByE7Dq4z9odyZgrQlY+/EfsUcTsO5/xOTSADucP4fv1AQ4ggAIAAA+gZv2awIcQXvnCw1Swru63t7pAAAAAElFTkSuQmCC" }
  }'

SUCCESS: example response for GHA-000000001-1

{
  "id": "…",
  "status": "success",
  "verificationType": "GHANA_CARD_FACIAL",
  "idType": "ghana_card",
  "country": "GH",
  "identifier": "GHA-000000001-1",
  "verifiedAt": "…",
  "verified": true,
  "facialMatch": true,
  "firstName": "Test",
  "lastName": "Mensah",
  "middleName": "Kofi",
  "dateOfBirth": "1990-01-01",
  "gender": "MALE",
  "placeOfBirth": "Greater Accra",
  "nationalId": "GHA-000000001-1",
  "cardId": "AS0000001",
  "cardValidFrom": "2021-02-10",
  "cardValidTo": "2030-08-31",
  "nationality": "Ghana",
  "addresses": [
    {
      "type": "Hometown",
      "town": "Konongo",
      "countryName": "Ghana",
      "districtName": "Asante Akim Central Municipality",
      "region": "Ashanti"
    },
    {
      "type": "Residence",
      "community": "AB",
      "postalCode": "AT-1000",
      "town": "Abuontem",
      "countryName": "Ghana",
      "districtName": "Bosomtwe",
      "region": "Ashanti",
      "digitalAddress": "AT-1000-0000",
      "gps": {
        "name": "AT-1000-0000",
        "region": "Ashanti",
        "district": "Bosomtwe",
        "area": "Abuontem",
        "street": "[UNKNOWN]",
        "longitude": "-1.56362405749",
        "latitude": "6.5814001723572"
      }
    }
  ],
  "contact": {
    "email": null,
    "phoneNumbers": [{ "type": "Mobile", "phoneNumber": "0200000000", "network": "MTN" }]
  },
  "occupations": [{ "name": "Student" }],
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "validation": null
}

FACE_MATCH_FAILED: example response for GHA-000000002-2

{
  "id": "…",
  "status": "failed",
  "verificationType": "GHANA_CARD_FACIAL",
  "idType": "ghana_card",
  "country": "GH",
  "identifier": "GHA-000000002-2",
  "verifiedAt": "…",
  "facialMatch": false,
  "error": { "code": "FACE_MATCH_FAILED", "message": "Facial verification did not match" }
}

Lipa Na M-Pesa (POST /verify/lipa-na-mpesa, KE)

M-Pesa Agent (POST /verify/mpesa-agent, KE)

Bank Routing

In sandbox, the bank routing endpoints return seeded fixture data for the identifiers below only. Any other identifier returns TEST_NUMBER_NOT_FOUND (HTTP 422) — sandbox never validates or looks up arbitrary values, so a sandbox key can never return real correspondent data. Sandbox requests are free (priceUsdAtCall: null) and are not billed.

BIC validation (POST /verifications/bic)

Routing-number validation (POST /verifications/routing-codes)

Correspondent lookup (POST /verifications/correspondents)

Batch (POST /verifications/batch)

Each item is resolved from the fixtures above by its type (bic, routing, or route). If any item uses an identifier not listed here, the whole batch returns TEST_NUMBER_NOT_FOUND (HTTP 422).

Sandbox-valid bank & operator codes

Any bank/operator code outside this list returns INVALID_BANK_CODE.

• NG: 000014 (Access), 000013 (GTBank), 000015 (Zenith), 000004 (UBA), 000016 (First Bank)
• GH: GCB (GCB Bank)
• ZM: 014 (FNB), 016 (Stanbic), 017 (Standard Chartered), 022 (UBA), 023 (Zanaco), 025 (ZICB), 028 (AB Bank)
• CI, SN, CM, BF, ML, BJ, TG: ORANGE, MTN, MOOV, WAVE
• TZ: 003 (CRDB Bank), 004 (NMB Bank), 013 (Exim Bank), 015 (NBC Bank), 006 (Stanbic Bank), 011 (Diamond Trust Bank), 009 (Bank of Africa), 020 (ABSA Bank), 021 (I&M Bank), 040 (Ecobank Tanzania), 046 (Amana Bank), 031 (Azania Bank), 024 (DCB Commercial Bank), 034 (BancABC), 039 (Mkombozi Bank), 048 (TPB Bank); phone operator codes: 503 (Vodacom M-Pesa), 504 (Airtel Money), 501 (Tigo Pesa / Zantel), 506 (Halotel HaloPesa), 507 (Azam Mobile Money)
• ET: 231402 (Commercial Bank of Ethiopia). Live calls accept all 43 ET institution codes, see supported banks; sandbox is a single bank to keep test surface focused.
• GB: 200000 (sandbox sort-code).
• CN: CN-INDIV (individual accounts). Business account verification is not currently supported.
• UY/CL/CO/EC: BROUUYMM (UY), BCHICLRM (CL), COLOCOBM (CO), PICHECEQ (EC). BR/MX/AR/PE need no bank code — omit it.
• AE: no bank code — the IBAN carries routing; omit bankCode. Sandbox seeds three UAE IBANs (AE…001 succeeds).
• AU: 062000 (6-digit BSB; sandbox dummy BSB for all AU test accounts).
• US: 123456789 (9-digit ABA routing number; sandbox dummy ABA for all US test accounts).
• Europe (SEPA): no bank code — the IBAN carries routing; omit bankCode. Sandbox seeds Germany, France, Netherlands, and Spain (DE…01, FR…01, NL…01, ES…01 succeed); all 21 SEPA countries are live (see Bank Account: Country Requirements).
• IN: HDFC0000001 (11-character IFSC).
• ID: BMRIIDJA (BIC).
• VN: BFTVVNVX (BIC).
• NP: NABLNPKA (BIC).
• PK: HABBPKKA (BIC).
• KR: CZNBKRSE (BIC).
• BD: MTBLBDDH (BIC).
• MY: MBBEMYKL (BIC).
• TH: BKKBTHBK (BIC; account-existence check, no name match).
• PH: BOPIPHMM (BIC; format/syntax check, no name match).
• UG: EQBLUGKA (BIC; name-match check).
• ZA: 250655 (6-digit branch code; account-existence check, no name match).
• KE: account verification uses the two-digit bank code (01–42) — sandbox accepts 01 (KCB). The lipa-na-mpesa and mpesa-agent endpoints do not take a bank code.

Testing Async Webhooks

1. Register a webhook URL in your dashboard and subscribe to verification.completed.

2. POST a verification request with "mode": "async". You will receive a pending response immediately.

3. After about 3 seconds, your webhook URL receives a verification.completed event:

   JSON

   {
     "event": "verification.completed",
     "data": {
       "id": "verif_abc123",
       "status": "success",
       "type": "ACCOUNT_NUMBER",
       "accountName": "Test Okoye"
     }
   }

4. If your process crashes before delivery, the verification stays pending. This is intentional (lets you test crash recovery in your own code).