Skip to main content

​
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

  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

FieldTypeRequiredDescription
emailstringYesCustomer email address
firstNamestringYesFirst name
lastNamestringYesLast name
typestringNoindividual (default) or business
phonestringNoPhone number

​
Key fields to watch

FieldValues
statusactive, suspended, rejected
kycStatusnot_started, under_review, incomplete, approved, rejected
capabilitieswallets, virtualAccounts, transfers

​
Listing customers

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