--- title: "Create an account" method: POST path: "/accounts" tags: ["Accounts"] --- # Create an account `POST /accounts` ## Request - Base URL: `https://sandbox.upvest.co` - URL: `https://sandbox.upvest.co/accounts` - Auth: OAuth 2 (client credentials, token URL `https://sandbox.upvest.co/auth/token`, scopes: `accounts:admin`) Creates an account for a user or a business within an existing account group. The account is created with status `PENDING_APPROVAL` and switches to `ACTIVE` once the owner's onboarding is complete; subscribe to the `ACCOUNT.ACTIVATED` webhook event to be notified. An account cannot exist without an account group and holds positions in the form of units. For a `JOINT` account group, `user_id` must be one of its 2 owners; either owner can be used. The account is shared by both owners and its `users` list both of them with type `OWNER`. A second owner whose `OWNER` role is still `PENDING` is not yet a member of the account group, and the request returns `404`. See the Creating accounts guide ([TOL](https://docs.upvest.co/products/tol/guides/accounts/accounts_create_accounts) / [BYOL](https://docs.upvest.co/products/byol/guides/accounts/accounts_create_accounts)) for implementation details. ## Headers - `idempotency-key` string, uuid, required ## Request body - union: Request to create an account for either a user or a business, within an existing account group. - object: Request to create an account for a user within an existing account group. - `user_id` string, uuid, required: Unique identifier of the user, as a UUID. - `account_group_id` string, uuid, required: Universally Unique Identifier (UUID) of the account group. - `type` 'TRADING' | 'PORTFOLIO', required: Account type. * TRADING - Orders in accounts of this type are created on a specific instrument basis. * PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available. - `name` string: The name of the account. - object: Request to create an account for a business within an existing account group. - `business_id` string, uuid, required: Unique identifier for the business. - `account_group_id` string, uuid, required: Universally Unique Identifier (UUID) of the account group. - `type` 'TRADING' | 'PORTFOLIO', required: Account type. * TRADING - Orders in accounts of this type are created on a specific instrument basis. * PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available. - `name` string: The name of the account. ## Response `200` Account created. - union: The newly created account — either a user account or a business account. - object: An account held by a user. Accounts belong to an account group and hold positions in the form of units. - `id` string, uuid, required: Universally Unique Identifier (UUID) of the account. - `created_at` string, date-time, required: Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `updated_at` string, date-time, required: Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `account_group_id` string, uuid, required: Universally Unique Identifier (UUID) of the account group. - `type` 'TRADING' | 'PORTFOLIO', required: Account type. * TRADING - Orders in accounts of this type are created on a specific instrument basis. * PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available. - `users` object[], required: The users associated with the account, each with their relation type. - `id` string, uuid: Unique identifier of the user, as a UUID. - `type` 'OWNER' | 'GUARDIAN' | 'CHILD': Relation of the user to the account group. * `OWNER` — The user owns the account group. A `JOINT` account group has exactly 2 `OWNER` users. * `CHILD` — The user is the child in a child account group. * `GUARDIAN` — The user is a guardian of a child account group. - `account_number` integer, required: The serial account number of the account in the account group. - `name` string, required: The name of the account. - `status` 'PENDING_APPROVAL' | 'ACTIVE' | 'CLOSING' | 'CLOSED' | 'LOCKED', required: The status of the account. * `PENDING_APPROVAL` — Account approval is pending — the account is visible through our API but cannot be acted on. * `ACTIVE` — Account is active — full functionality of the Investment API is accessible. * `CLOSING` — Account is closing — only sell orders or the transfer of positions out are permissible before the account is closed. * `CLOSED` — Account is closed with zero balance. * `LOCKED` — Account is locked for all actions. - object: An account held by a business. Accounts belong to an account group and hold positions in the form of units. - `id` string, uuid, required: Universally Unique Identifier (UUID) of the account. - `created_at` string, date-time, required: Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `updated_at` string, date-time, required: Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `account_group_id` string, uuid, required: Universally Unique Identifier (UUID) of the account group. - `type` 'TRADING' | 'PORTFOLIO', required: Account type. * TRADING - Orders in accounts of this type are created on a specific instrument basis. * PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available. - `business_id` string, uuid, required: Unique identifier for the business. - `account_number` integer, required: The serial account number of the account in the account group. - `name` string, required: The name of the account. - `status` 'PENDING_APPROVAL' | 'ACTIVE' | 'CLOSING' | 'CLOSED' | 'LOCKED', required: The status of the account. * `PENDING_APPROVAL` — Account approval is pending — the account is visible through our API but cannot be acted on. * `ACTIVE` — Account is active — full functionality of the Investment API is accessible. * `CLOSING` — Account is closing — only sell orders or the transfer of positions out are permissible before the account is closed. * `CLOSED` — Account is closed with zero balance. * `LOCKED` — Account is locked for all actions. ## Other responses - `400`: Bad Request. The incoming request had a malformed parameter/object. - `401`: Unauthorized. The caller has not been authenticated. - `403`: Forbidden. The caller has been authenticated but is not allowed to take the requested action. - `404`: Not Found. The requested resource could not be found. - `406`: Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value. - `429`: Too Many Requests. The caller has exceeded their quota for the time period and has been throttled. - `500`: Internal Server Error. The service encountered an unexpected error. - `503`: Service Unavailable. The service handling for this request cannot be reached at this time. - `504`: Gateway Timeout. The service gateway has reached its internal timeout. --- [API](https://skmtc.dev/upvest/apis/upvest-investment-api.md) · [All operations](https://skmtc.dev/upvest/apis/upvest-investment-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upvest/apis/upvest-investment-api/revisions/ca69534b631d?raw)