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

# Customers and KYC

> Create customers, start verification, and understand capability unlocks.

## Create a customer

```bash theme={null}
curl -X POST https://api.ledger.so/v1/customers \
  -H "Authorization: Bearer $LEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-cust-1" \
  -d '{
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "type": "individual"
  }'
```

Customers are created as `active` immediately. Ledger returns hosted verification links in the response.

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "cus_...",
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "type": "individual",
    "status": "active",
    "kycStatus": "not_started",
    "kycLink": "https://...",
    "tosLink": "https://...",
    "capabilities": {
      "wallets": false,
      "virtualAccounts": false,
      "transfers": false
    },
    "createdAt": 1710000000000,
    "updatedAt": 1710000000000
  }
}
```

## KYC lifecycle

1. Create the customer via `POST /v1/customers`
2. Direct the customer to complete verification via `kycLink` and `tosLink`
3. Once approved, capabilities unlock based on verification level
4. You can now create wallets, virtual accounts, and initiate transfers

Listen for `customer.updated` webhooks to track KYC progress in real-time.

## Request fields

| Field       | Type   | Required | Description                          |
| ----------- | ------ | -------- | ------------------------------------ |
| `email`     | string | Yes      | Customer email address               |
| `firstName` | string | Yes      | First name                           |
| `lastName`  | string | Yes      | Last name                            |
| `type`      | string | No       | `individual` (default) or `business` |
| `phone`     | string | No       | Phone number                         |

## Key fields to watch

| Field          | Values                                                              |
| -------------- | ------------------------------------------------------------------- |
| `status`       | `active`, `suspended`, `rejected`                                   |
| `kycStatus`    | `not_started`, `under_review`, `incomplete`, `approved`, `rejected` |
| `capabilities` | `wallets`, `virtualAccounts`, `transfers`                           |

## Listing customers

```bash theme={null}
curl "https://api.ledger.so/v1/customers?limit=10" \
  -H "Authorization: Bearer $LEDGER_API_KEY"
```