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

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Which KYC endpoint to use

> Card KYC or Create customer: which endpoint verifies a customer for each product, how to check status, and the field formats both expect.

A customer's identity reaches Bitnob in one of two ways. Which one you use depends on the product, not on the customer.

| You want to | Call | What it does |
| - | - | - |
| Issue a virtual card | [Card KYC](https://www.bitnob.dev/api-reference/cards/card-kyc.md) | Verifies the person and creates the customer in one step. Returns the `customer_id` you pass to Create card. |
| Issue a naira virtual account | [Create customer](https://www.bitnob.dev/api-reference/customers/create-customer.md), then [Create virtual account](https://www.bitnob.dev/api-reference/virtual-accounts/create-virtual-account.md) | You create the customer with their BVN. The BVN is verified when the account is created. |
| Create a customer for payouts or beneficiaries | [Create customer](https://www.bitnob.dev/api-reference/customers/create-customer.md) | Creates the record. No identity verification runs. |

## Cards: `POST /api/cards/kyc`

* Send the customer's details and one identity document. You don't create the customer first: a successful submission creates them and returns `customer_id`.
* Accepted `id_type` values: `bvn`, `nin`, `passport`, `drivers_license`, `national_id`, `vnin`, `voters_card`, `ghana_card`.
* Verification is instant for `bvn` and `nin`. Document types can sit at `pending` for up to 10 minutes. A card can only be created once the customer is `approved`.
* If the `id_number` or phone number already belongs to one of your customers under a different email, the call returns `400` and names the existing `customer_id`. Resubmit with that `customer_id`.
* Card KYC is enabled per account. If it isn't on for you, the call returns `403` `FEATURE_NOT_ENABLED`.

Walkthrough: [Issue your first card](https://www.bitnob.dev/docs/card-issuing/issue-your-first-card.md).

## Virtual accounts: `POST /api/customers`

* Create the customer with `first_name`, `last_name`, `email`, `phone_number`, `date_of_birth`, `id_type: "bvn"`, and the BVN as `id_number`.
* Then call [Create virtual account](https://www.bitnob.dev/api-reference/virtual-accounts/create-virtual-account.md) with that `customer_id`. The BVN is checked against the national registry at this point, not when the customer is created.
* The name and date of birth must match the BVN record exactly, or verification fails even when the BVN is valid.
* For a company, set `customer_type: "business"`. The personal fields are those of a director or authorized representative.

> [!WARNING]
>
> Customers are matched on `email`, `phone_number` and BVN (`id_number`). Creating a customer with an email, phone number or BVN you've already used returns `201` with the existing customer, and the other fields you sent are ignored.

Walkthrough: [Set up virtual accounts](https://www.bitnob.dev/docs/virtual-accounts/set-up-virtual-accounts.md).

## Check status

Use [Get card KYC status](https://www.bitnob.dev/api-reference/cards/get-card-kyc-status.md), or read the customer with [Get customer](https://www.bitnob.dev/api-reference/customers/get-customer.md):

```http theme={null}
GET /api/customers/:customerId
```

```json theme={null}
{
  "success": true,
  "message": "Customer retrieved successfully",
  "data": {
    "id": "01a114af-8ea6-79b7-be0b-2405531fe8ef",
    "customer_type": "individual",
    "card_program_kyc": [
      {
        "card_program": "prepaid",
        "normalized_status": "approved"
      }
    ]
  }
}
```

`card_program_kyc[].normalized_status` is one of `none`, `initiated`, `pending`, `approved`, or `rejected`. Prefer the `virtualcard.user.kyc.*` webhooks over polling.

Virtual accounts have no pending state. The create call either returns the account or an error naming what failed.

## Existing customers

A customer you already created with `POST /api/customers` can be given a virtual account once the fields above are on the record. Add missing ones with [Update customer](https://www.bitnob.dev/api-reference/customers/update-customer.md).

## Field formats

| Field | Format |
| - | - |
| `date_of_birth` | `YYYY-MM-DD`, for example `1994-03-21`. The customer must be 18 or over. |
| `id_number` for `bvn` | 11 digits |
| `id_type` `bvn` and `nin` | The customer's country must be Nigeria. |
| `country` | ISO 3166-1 alpha-3, for example `NGA`, `GHA`, `USA` |
| `phone_number` and `dial_code` | The number without the prefix (`8000000003`), and the prefix separately (`+234`) |
| `created_by` | Set by Bitnob to the ID of the API client that created the record. A value you send is ignored. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.