Customers
A customer is a saved bank account of yours: a payee you pay, or a payer who pays you. customerId is the id you see as customer.customerId on declarations, transactions, payouts and events.
| Method | Path | Purpose |
|---|---|---|
GET | /v1/customers | List active customers |
POST | /v1/customers | Create a customer |
GET | /v1/customers/:customerId | Read one |
PATCH | /v1/customers/:customerId | Edit, or rebind the reference |
DELETE | /v1/customers/:customerId | Soft-delete. A deleted customer no longer appears, and cannot be used for payouts or declarations |
The routes need the Beneficiary permission, shown in the dashboard as Customer. A credential without it is 403 ABILITY_DENIED.
The earlier saved-payee routes are removed. Use these.
List
GET /v1/customers returns active customers, oldest first, paged: { "data", "meta": { "limit", "offset", "total" } }.
| Query | Default | Description |
|---|---|---|
limit | 10 | Page size (minimum 1, maximum 100) |
offset | 0 | Rows to skip |
Unknown query names are 400.
Identity
A customer is one rail, one account identifier and one currency. On swift that is the IBAN with whitespace removed and upper-cased. On local it is the account number and routing number (neither may contain :). Currency is USD, AED, EUR or GBP. Declarations and payouts reuse the oldest active customer with that identity, or create one. A create or identity edit that would duplicate an active customer is 409 CUSTOMER_EXISTS.
Your reference
customerReference is your own identifier (a CRM id, a supplier code). A customer holds at most one. The first declaration or payout that carries a reference for an unbound customer binds it. A different reference afterwards is 409 CUSTOMER_REFERENCE_CONFLICT. Change it on purpose with PATCH and a new customerReference. LEGACY_UNSET means the customer has no reference of yours yet; you can never send that value (400 RESERVED_CUSTOMER_REFERENCE).
Rebinding or deleting a customer expires its open declarations. You are told with deposit.expired and reason rebound or deleted.
What a customer reads as
customerId, customerReference, label, fullName, rail (swift or local), entityType, the identifiers of its rail, address lines, currency, source and whether it is payable. A customer a declaration or an incoming payment created is often not payable until you complete the blank entity type, address and SWIFT code with PATCH.
A customer outside your read scope is { "customerId": "…" } on a write response, and 403 CONDITION_FAILED on a direct read. A withheld field is absent.
Once strict mode is on, rail, IBAN, account number, routing number and a currency that is already set cannot be changed (400 IMMUTABLE_FIELD). Setting a missing currency once is still allowed.
Updated 4 days ago
