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

# Customers and KYC

> Register the people you serve, and verify them to a tier.

With the wallet product, your customers can hold wallets with you. A customer's **KYC tier** decides their limits, and they move up a tier by passing identity checks.

Needs the `CUSTOMERS` feature, with `customers:write` and `kyc:write`.

## Create a customer

```bash theme={null}
curl https://$MESH_HOST/v1/customers \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "middle_name": "Chioma",
    "last_name": "Obi",
    "phone_number": "+2348012345678",
    "date_of_birth": "1994-03-21",
    "email": "ada@example.com",
    "customer_type": "individual"
  }'
```

| Field | |
| - | - |
| `first_name`, `last_name` | Required, 1 to 100 characters |
| `phone_number` | Required, E.164 (`+234…`), unique to your business |
| `date_of_birth` | Required, `YYYY-MM-DD`; 18 or older |
| `customer_type` | `individual` (see `GET /v1/reference/customer-types`) |
| `middle_name`, `email`, `alias`, `address` | Optional |

The customer starts at `kyc_tier: 0`, `kyc_status: unverified`. Mesh registers them with the bank in the background; until that's done (usually seconds), a check or a wallet for them answers `409` (code `62`): retry shortly.

> [!NOTE]
>
> Don't send a BVN or NIN here. They go to the checks below, so they're verified before they're stored.

## Verify them

`POST /v1/verifications/{checkType}` with the customer's `customer_id`:

```bash theme={null}
curl https://$MESH_HOST/v1/verifications/bvn_lookup \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "0b7e…", "id_number": "22222222222" }'
```

| Field | |
| - | - |
| `id_number` | The number being checked: a BVN, NIN, TIN, CAC registration number or bank account number |
| `customer_id` | The customer the check is about. Leave it out for a check about your business |
| `bank_code` | With `name_enquiry`: the account's bank |
| `photo_base64` | With `face_match` and `liveness` |
| `applicant`, `address` | With `address_verify` |

| Check | About |
| - | - |
| `bvn_lookup`, `nin_lookup` | A customer's identity numbers |
| `face_match`, `liveness` | That the person is real and matches their ID |
| `address_verify` | A customer's address |
| `cac_lookup`, `tin_lookup`, `pep_screen` | Your business and its directors (either product) |
| `name_enquiry` | The name on a bank account (either product) |

Most checks answer `200` with the verdict. `liveness` and `address_verify` take longer: they answer `202`, and you follow with `GET /v1/verifications/{verificationId}`.

## Tiers

| Tier | Needs |
| - | - |
| 1 | BVN or NIN, and liveness |
| 2 | BVN and NIN, and liveness |
| 3 | Tier 2, and a verified address |

The bank decides the tier from the checks, and the customer's record shows it. Each tier has its own balance, single-transaction and daily limits.

## Updating a customer

`PATCH /v1/customers/{customerId}` changes only the fields you send. Once a customer is verified, their name and date of birth can't change (`422`, code `52`). For an open business, nothing changes through the API once they reach tier 1 (`422`, code `55`).


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