Customers
Manage individual and business customer accounts
For complete API specification including request/response schemas and interactive examples, see the API Reference.
Overview
Customers represent individual or business entities that hold wallets and initiate transfers. They are the primary identity in the system and can be created with minimal information, supporting both widget-based flows and full KYC verification.
Create Customer
Create a new customer account. Supports both individual (cus_xxx) and business (biz_xxx) types.
Use Cases
| When | What | Better For |
|---|---|---|
| Widget-based onramp flow | Create with empty object {} | Quick customer creation without KYC upfront |
| Full KYC verification | Create with customer data and shareToken | Importing existing KYC data from SumSub |
| Business customers | Set type: "business" | B2B applications requiring business accounts |
| Individual customers | Use default or type: "individual" | Consumer applications and personal wallets |
See Create Customer for details.
List Customers
Retrieve all customers with optional filtering and pagination.
Use Cases
| When | What | Better For |
|---|---|---|
| Displaying customer list | Use default pagination (limit=20) | Admin dashboards and customer management |
| Filtering by email | Add email query parameter | Finding specific customer by email address |
| Filtering by type | Add type=individual or type=business | Separating individual vs business customers |
| Large datasets | Use offset for pagination | Handling thousands of customers efficiently |
See Get All Customers for details.
Get Customer
Retrieve a specific customer by ID.
Use Cases
| When | What | Better For |
|---|---|---|
| Single customer lookup | Use customer ID directly | Displaying customer details in UI |
| After customer creation | Fetch immediately after POST | Verifying customer was created successfully |
| Before operations | Check customer exists and status | Validating customer before transfers or wallets |
See Get Customer by ID for details.
Update Customer
Update customer information like phone, email, or KYC data.
Use Cases
| When | What | Better For |
|---|---|---|
| KYC token refresh | Update with new shareToken | Crypto rails requiring fresh KYC verification |
| Profile updates | Update phone, email, address | Keeping customer information current |
| Partial updates | Send only changed fields | Efficient updates without full object replacement |
See Update Customer for details.
Get Customer Balance
Retrieve balance information for a customer across all wallets.
Use Cases
| When | What | Better For |
|---|---|---|
| Displaying balances | Fetch before showing wallet UI | Showing total balance across all chains |
| Balance reconciliation | Regular balance checks | Accounting and financial reporting |
| Before transfers | Verify sufficient balance | Preventing failed transfers due to low balance |
See Get Customer Balance for details.
Delete Customer
Delete a customer account. The customer ID can be reused after deletion.
Use Cases
| When | What | Better For |
|---|---|---|
| GDPR compliance | Delete customer data | Handling data deletion requests |
| Account closure | Delete after transferring funds | Closing customer accounts permanently |
| Testing cleanup | Delete test customers | Maintaining clean test environments |
See Delete Customer for details.