Customer management API — individual and business profiles, KYC verification, endorsements.

Customers

Customers represent individuals or businesses that use your platform. Each customer can have multiple accounts, wallets, and external accounts. Customers must complete KYC verification before accessing full platform capabilities.

The Customer Object

{
  "id": "cus_abc123",
  "object": "customer",
  "type": "individual",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",
  "date_of_birth": "1990-01-15",
  "tax_id_provided": true,
  "address": {
    "line1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "status": "active",
  "kyc_status": "approved",
  "risk_rating": "low",
  "endorsements": ["can_trade_stablecoins", "can_wire_transfer"],
  "created_at": "2026-01-15T10:00:00.000Z"
}

Attributes

Field	Type	Description
`id`	string	Unique identifier
`type`	string	`individual` or `business`
`email`	string	Customer email address
`status`	string	`pending`, `active`, `suspended`, `deleted`
`kyc_status`	string	`not_started`, `pending`, `incomplete`, `manual_review`, `under_review`, `awaiting_ubo`, `approved`, `rejected`
`risk_rating`	string	`low`, `medium`, `high`
`endorsements`	array	Capabilities granted to customer

Endorsements

Endorsement	Description
`can_trade_stablecoins`	Convert fiat to stablecoins
`can_wire_transfer`	Send/receive wire transfers
`can_ach_transfer`	Send/receive ACH transfers
`can_sepa_transfer`	Send/receive SEPA transfers
`can_swift_transfer`	Send/receive SWIFT transfers
`can_hold_custody`	Use custodial wallets
`can_use_mpc`	Use MPC wallets

Create a Customer

POST /v0/customers

const customer = await lux.customers.create({
  type: 'individual',
  email: 'john@example.com',
  first_name: 'John',
  last_name: 'Doe',
  phone: '+1234567890',
  date_of_birth: '1990-01-15',
  address: {
    line1: '123 Main St',
    city: 'New York',
    state: 'NY',
    postal_code: '10001',
    country: 'US',
  },
});

// Direct user to KYC flow
console.log(customer.kyc_link);

KYC Status Lifecycle

not_started → pending → incomplete → under_review → approved
                                   ↘ manual_review → approved
                                   ↘ rejected

Status	Description
`not_started`	KYC not initiated
`pending`	Awaiting document submission
`incomplete`	Additional documents required
`under_review`	Documents being reviewed
`manual_review`	Requires manual compliance review
`awaiting_ubo`	Waiting for Ultimate Beneficial Owner info (businesses)
`approved`	KYC approved, customer can transact
`rejected`	KYC rejected, see `rejection_reasons`

Submit KYC Documents

POST /v0/customers/{customer_id}/kyc

{
  "document_type": "passport",
  "document_front": "data:image/png;base64,...",
  "selfie": "data:image/png;base64,..."
}

Document types: passport, drivers_license, national_id

List / Retrieve / Update / Delete

GET    /v0/customers                    # List (paginated)
GET    /v0/customers/{customer_id}      # Retrieve
PATCH  /v0/customers/{customer_id}      # Update
DELETE /v0/customers/{customer_id}      # Soft delete
GET    /v0/customers/{customer_id}/wallets           # Customer wallets
GET    /v0/customers/{customer_id}/external-accounts  # Linked bank accounts

Customers

On this page