Verification / KYC

Verify customer identities using a wide range of Nigerian and international identity documents. All verification endpoints support idempotency to prevent duplicate charges.

How it works

Choose the appropriate verification type for your use case
Send a POST request with the required identifier (BVN, NIN, etc.)
Receive a normalized result with the verification data

Available verification types

Identity

Endpoint	Description
`/api/v1/business/verification/bvn`	Bank Verification Number
`/api/v1/business/verification/bvn-advanced`	BVN with extended data
`/api/v1/business/verification/nin`	National Identification Number
`/api/v1/business/verification/pvc`	Permanent Voter’s Card
`/api/v1/business/verification/pvc-premium`	PVC with extended data
`/api/v1/business/verification/frsc`	Driver’s License (FRSC)
`/api/v1/business/verification/passport`	International Passport

Business

Endpoint	Description
`/api/v1/business/verification/cac-basic`	CAC Basic lookup
`/api/v1/business/verification/cac-advanced`	CAC with detailed info
`/api/v1/business/verification/cac-premium`	CAC with full records
`/api/v1/business/verification/cac-by-name`	CAC lookup by company name
`/api/v1/business/verification/tin`	Tax Identification Number

Financial

Endpoint	Description
`/api/v1/business/verification/bank-account`	Bank account verification
`/api/v1/business/verification/aml`	Anti-Money Laundering check

Phone

Endpoint	Description
`/api/v1/business/verification/phone-basic`	Basic phone number lookup
`/api/v1/business/verification/phone-advanced`	Phone with detailed data
`/api/v1/business/verification/phone-nin`	Phone + NIN cross-check

Credit

Endpoint	Description
`/api/v1/business/verification/{verificationCode}`	Generic verification (TriCredit, CRC, Kenya CRB, Kenya National ID)

History

Endpoint	Method	Description
`/api/v1/business/verification/history`	GET	List past verifications
`/api/v1/business/verification/{id}`	GET	Get verification details by ID

Authentication

All verification POST endpoints require:

X-Numero-Api-Key header
X-Numero-Signature header (request signature)

GET endpoints (history, details) only require X-Numero-Api-Key.

Idempotency

All verification POST endpoints accept an optional idempotencyKey parameter. If you send the same idempotencyKey twice, the second request will return the cached result without charging you again.

{
  "bvn": "12345678901",
  "idempotencyKey": "unique-key-for-this-request"
}

Standard response format

All verification endpoints return this structure:

{
  "data": {
    "verificationRequestId": 12345,
    "reference": "VER-abc123",
    "success": true,
    "statusCode": "00",
    "statusMessage": "Verification successful",
    "normalizedResult": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-15",
      "...": "..."
    },
    "walletTransactionReference": "TRX-abc123",
    "walletAmount": 100.0
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}

Field	Type	Description
`verificationRequestId`	number	Internal verification ID
`reference`	string	Verification reference
`success`	boolean	Whether the verification was successful
`statusCode`	string	Provider status code
`statusMessage`	string	Human-readable status
`normalizedResult`	object	The verified data (varies by verification type). Every value is a string or `null` — see below
`walletTransactionReference`	string	Transaction reference for the charge
`walletAmount`	number	Amount charged for this verification

Reading `normalizedResult`

normalizedResult is a flat map of the data the provider returned. Read it with these four rules in mind — they apply to every verification type. 1. A field can be null, and null is an answer. We return every field the provider sends, including the ones it has no value for. "email": null means the source holds no email for this subject — not that the field is unsupported. Handle null gracefully on every field; do not assume a value is present because it was present on a previous request.

"normalizedResult": {
  "customerId": "38572622",
  "businessId": null,
  "email": null,
  "score": null
}

2. The key set is stable per verification type. A field that is null for one subject and populated for another is present in both responses. You can code against a fixed shape and branch on null. 3. Every value is a string (or null) — numbers included. A credit score comes back as "658", not 658. Parse before doing arithmetic or comparisons. 4. Booleans are "True" / "False" — capitalised strings, not JSON booleans. Compare case-insensitively (value?.toLowerCase() === "true"), not against "true". 5. Nested data is flattened with dot and index notation. A nested object becomes "score.ficoScore.score": "658"; a list becomes "loans[0].amount". The key is the full path.

Getting Started

Transfers & Payouts

Collections (Virtual Accounts)

Wallet-as-a-Service

Customers

Invoices

Cards

Cardholders

Balance & Transactions

Value Added Services

Credit