> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users API overview

> Create and manage the individual and business users you onboard to the Uphold platform, act on their behalf, and attach your own metadata to them.

The users group of endpoints allows you to create and manage the users you onboard to the platform.

Every other Core entity, such as accounts, external accounts, transactions and files, belongs to a user. Creating the user is the first step of any integration.

## User types

A user has a `type`, which is set when the user is created and decides how they're onboarded:

* `individual`: A person, onboarded through the [KYC](https://developer.uphold.com/rest-apis/core-api/kyc/overview.md) processes.
* `business`: A company or another legal entity, onboarded through the [KYB](https://developer.uphold.com/rest-apis/core-api/kyb/overview.md) processes.

See the [user onboarding guide](https://developer.uphold.com/developer-guides/user-onboarding/introduction.md) for an end-to-end walkthrough of each type.

## Creating a user

Only an organization-wide client, acting as the `client` [subject](https://developer.uphold.com/rest-apis/authentication.md#subjects), can [create a user](https://developer.uphold.com/rest-apis/core-api/users/create-user.md):

* The user must agree with the [general terms of service](https://developer.uphold.com/rest-apis/core-api/terms-of-service/overview.md#general-terms) of their country of residence, which you send in `termsOfService`. Terms that don't match the country fail with `terms_of_service_mismatch`.
* The `X-Uphold-User-Ip` [user context](https://developer.uphold.com/rest-apis/headers.md#user-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`, `birthdate` and `address` when creating the user, to fill in the KYC [profile](https://developer.uphold.com/rest-apis/core-api/kyc/update-profile.md) process upfront. Depending on the jurisdiction, the process may need more data, which you then submit through [Update profile](https://developer.uphold.com/rest-apis/core-api/kyc/update-profile.md).

The [`core.user.created`](https://developer.uphold.com/rest-apis/core-api/users/webhooks/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](https://developer.uphold.com/rest-apis/core-api/users/get-user.md).

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](https://developer.uphold.com/rest-apis/authentication.md#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](https://developer.uphold.com/rest-apis/core-api/capabilities/overview.md), 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 a `GET` fails with a `409` error. See [User blocked](https://developer.uphold.com/rest-apis/authentication.md#user-blocked).

## Deleting a user

[Delete user](https://developer.uphold.com/rest-apis/core-api/users/delete-user.md) needs a `review.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`](https://developer.uphold.com/rest-apis/core-api/users/webhooks/user-deleted) webhook is sent once the user is deleted.

## Metadata

Users support [metadata](https://developer.uphold.com/rest-apis/entity-metadata.md), 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.

Send `metadata` when you [create the user](https://developer.uphold.com/rest-apis/core-api/users/create-user.md), or manage it later with the [metadata endpoints](https://developer.uphold.com/rest-apis/core-api/metadata/set-metadata.md), using `users` as the entity and `me` as the id.

| Operation | Scope |
| - | - |
| [Get metadata](https://developer.uphold.com/rest-apis/core-api/metadata/get-metadata.md) | `core.users.metadata:read` |
| [Set metadata](https://developer.uphold.com/rest-apis/core-api/metadata/set-metadata.md), [Update metadata](https://developer.uphold.com/rest-apis/core-api/metadata/update-metadata.md), [Delete metadata](https://developer.uphold.com/rest-apis/core-api/metadata/delete-metadata.md) | `core.users.metadata:write` |
| [Create user](https://developer.uphold.com/rest-apis/core-api/users/create-user.md) with `metadata` | `core.users.metadata:write`, in addition to `core.users:create` |

Without the write scope, a create request that includes `metadata` is rejected with `token_insufficient_scopes`, and the user is not created.
