Skip to main content
Use these routes to provision card holders, search your user base, move users between sub-accounts, and remove users when they should no longer have access.

​
Before you start

  • The common prerequisites
  • Active Authorized User Terms accepted by the end user (GET /users/terms)
  • A strong password collected from the end user
Fetch the current Authorized User Terms before user creation (same agreement as business team enrollment):
GET /users/terms

​
Create a user

Create a user with identity, date of birth, phone, password, and termsPolicy: true. birthDate is required (YYYY-MM-DD, age 18+). You can optionally supply firstName and lastName to record distinct legal names for KYC verification and cardholder identity; if omitted, name is used as the profile name. If you omit subAccountId, the user is assigned to your business default sub-account. Optional physicalAddress is the residential address. Omit it on create if you do not have one yet. You will need a stored address later when issuing a virtual card (see Virtual and physical cards).
POST /users
physicalAddress fields when provided: line1, city, postalCode, and a 2-letter countryCode are required; line2, region, and country are optional. Partial addresses are rejected.
Response
Send verificationUrl to the end user to complete hosted KYC. See Check KYC approval.

​
List users

Use GET /users for paginated user management screens and reconciliation jobs.
GET /users
Useful query parameters: Users with kycStatus new or pending include verificationUrl when a hosted KYC link is available.

​
Get one user

Use GET /users/{userId} when you need the latest KYC status, phone, sub-account summary, legal names, or hosted verification link for one user.
GET /users/USER_ID

​
Update a user

PATCH /users/{userId} supports updating name, firstName, lastName, birthDate, email, phone, physicalAddress, and subAccountId. Password changes use a separate endpoint. When the user is already enrolled for cards, name, physicalAddress, and phone changes are also synced to the card issuer. birthDate updates are stored locally only (the issuer does not accept date of birth on user update). Updating phone replaces the stored number, clears phone.network (MNO), and sets phone verification to unverified.
PATCH /users/USER_ID

​
Delete a user

DELETE /users/{userId} removes the user from your business. Active cards linked to the user are terminated first.
DELETE /users/USER_ID