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" }
}

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

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

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: GH010100 (Ghana Commercial 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), ABOCCNBJ (business accounts).
• UG: bank-account verification is not supported. Use phone verification instead.
• KE: no bank code field, lipa-na-mpesa and mpesa-agent endpoints do not take one.

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