Customers and KYC - Ledger

Create a customer

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.

{
  "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

Create the customer via POST /v1/customers
Direct the customer to complete verification via kycLink and tosLink
Once approved, capabilities unlock based on verification level
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

curl "https://api.ledger.so/v1/customers?limit=10" \
  -H "Authorization: Bearer $LEDGER_API_KEY"