> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenumero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verification / KYC

> Verify customer identities and businesses using a wide range of Nigerian and international identity documents.

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

1. Choose the appropriate verification type for your use case
2. Send a POST request with the required identifier (BVN, NIN, etc.)
3. 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.

```json theme={null}
{
  "bvn": "12345678901",
  "idempotencyKey": "unique-key-for-this-request"
}
```

## Standard response format

All verification endpoints return this structure:

```json theme={null}
{
  "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.

```json theme={null}
"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.