User types
A user has atype, which is set when the user is created and decides how they’re onboarded:
individual: A person, onboarded through the KYC processes.business: A company or another legal entity, onboarded through the KYB processes.
Creating a user
Only an organization-wide client, acting as theclient subject, can create a user:
- The user must agree with the general terms of service of their country of residence, which you send in
termsOfService. Terms that don’t match the country fail withterms_of_service_mismatch. - The
X-Uphold-User-Ipuser context header is required, to record the IP the user accepted the terms from. - For individual users, you can also send KYC data such as
fullName,birthdateandaddresswhen creating the user, to fill in the KYC profile process upfront. Depending on the jurisdiction, the process may need more data, which you then submit through Update profile.
core.user.created webhook is sent once the user is created.
Acting on behalf of a user
Once created, the user is the subject of the other user endpoints, which act on the current user at/core/users/me, such as Get user.
A client bound to a single user acts on that user directly. An organization-wide client needs the core.users:act-on-behalf-of scope and sends the X-On-Behalf-Of header to pick the user. See Subjects.
What a user can do
A user has no single status. What a user can do, such as depositing, trading or withdrawing, is described by their capabilities, which depend on the KYC or KYB processes they completed and the terms they accepted. If a user is blocked, every request that isn’t aGET fails with a 409 error. See User blocked.
Deleting a user
Delete user needs areview.reason for the deletion, and fails with user_has_balance or user_has_pending_transactions while the user still has funds or pending transactions. Ask the user to withdraw their funds first.
A deletion can only be reversed through a manual process, and deposits received by a deleted user are held until they are manually released. The core.user.deleted webhook is sent once the user is deleted.
Metadata
Users support metadata, so you can attach your own data to a user, such as their id in your system or when you onboarded them, and map it to the records of your own system. Sendmetadata when you create the user, or manage it later with the metadata endpoints, using users as the entity and me as the id.
Without the write scope, a create request that includes
metadata is rejected with token_insufficient_scopes, and the user is not created.