Accounts

Accounts are the central resource in the Investment API and are needed to perform operations such as placing orders. This guide outlines the concept of accounts and walks you through the creation of account groups and accounts. Once you have completed the account creation process for a user, you can use the full functionality of the Investment API for them.

How accounts work

Account opening


Account levels

There are two levels of accounts - account groups and accounts.

  • Account groups do not hold any positions themselves but aggregate all accounts within the account group for tax calculation and regulatory reporting purposes. Therefore, we assign official security account numbers at the account group level.

  • Accounts cannot exist on the Investment API without being associated with an account group. Accounts can hold positions.

Account types

We currently support one type on the account group level, and two types on the account level:

Account level Account type Description
Account group PERSONAL Account group of an individual person holding securities on their own behalf.
Account TRADING Account allows orders to be placed at instrument level and positions to be queried in the account.
Account PORTFOLIO Account allows orders to be placed at a portfolio level and positions to be queried in the account.
COMING SOON

More types of account groups such as joint account groups or child account groups will follow soon.

Implementing account groups and accounts

Prerequisites

You will be able to create account groups and accounts as soon as you have created a user.

As a rule, the following steps are required to create an account:

  1. First create a user as decribed here.
  2. Then set up the parent account group.
  3. Create the account.
INFO

You can already create accounts while user onboarding and the associated checks are still in progress. The accounts remain in the status PENDING_APPROVAL until the onboarding process is completed.

1. Creating an account group

After you have created the user, you can set up the parent account group as follows:

POST /account_groups

Example request

{
  "user_id": "413715f2-5401-4b97-8055-034a6b879f8c",
  "type": "PERSONAL"
}
Parameter Description
user_id The ID of the user to be associated with this account group.
type Specify the type PERSONAL. Currently, we only support one PERSONAL account group per user.

You will receive an account group ID, which is needed to create an account.

Furthermore, you will receive a webhook with the respective account group created event. As soon as all requirements for activating the account group are met, you will also receive an account group activated event.

Account group status

The following status apply to an account group:

Status Description
PENDING_APPROVAL Account group approval is pending - the account group is visible via our API but cannot be acted on.
ACTIVE Account group is active - full functionality of the Investment API is accessible.
LOCKED Account group is locked for all actions.
CLOSING Account group is closing.
CLOSED Account group is closed.

2. Creating an account

After the creation of the account group, you can now setup an account with:

POST /accounts

Example request

{
  "user_id": "413715f2-5401-4b97-8055-034a6b879f8c",
  "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6",
  "type": "TRADING",
  "name": "Main account"
}

Parameter Description
user_id The ID of the user to be associated with this account.
account_group_id The ID of the account group to be associated with this account.
type Specify the type TRADING or PORTFOLIO for this account.
name Optionally, you can provide a nickname for the account that can be used for reporting purposes.

The account will be created with the PENDING_APPROVAL status and switches to ACTIVE as soon as the user onboarding process is completed.

Furthermore, you will receive a webhook with the respective account created event. As soon as all prerequisites for activating the account are passed, you also receive an account activated event.

Account status

The following status apply to an account:

Status Description
PENDING_APPROVAL Account approval is pending - the account is visible via our API but cannot be acted on.
ACTIVE Account is active - full functionality of the Investment API is accessible.
LOCKED Account is locked for all actions.
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 successfully.

3. Listing account groups and accounts

You can list all account groups and accounts of a specific user with

All account groups and accounts can be listed with

Next steps

You are all set now: a user is onboarded and an account group as well as an account have been created. Your user is now ready to fund the account and to place the first order. Follow the Payments guide.

Was this page helpful?