Accounts

Accounts are the central resource on the Investment API and are needed to carry out 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 account groups and accounts work

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.

We currently support one type on the account group level:

• Account group type: PERSONAL
  • Account group of an individual person holding securities on their own behalf.

And two types on the account level:

• Account type: TRADING
  • Account allows orders to be placed at instrument level and positions to be queried in the account.
• Account type: PORTFOLIO
  • Account allows orders to be placed at a portfolio level and positions to be queried in the account.

Implementing account groups and accounts

Prerequisites

You will be able to create account groups and accounts as soon as you have created a user. Accounts can already be created, while the user onboarding and the associated checks are still in progress. The accounts will remain in PENDING_APPROVAL until the onboarding process is completed.

Creating an account group

After creating the user, but before creating an account, the parent account group must exist. To create an account group, send POST /account_group with the type PERSONAL in the payload. 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.

The following status apply to an account group:

Example request

{
  "user_id": "413715f2-5401-4b97-8055-034a6b879f8c",
  "type": "PERSONAL"
}

Creating an account

To create an account, send POST /accounts including the information that you want to create an account of the type TRADING or PORTFOLIO and the parent account group ID in the payload.

You are free to provide a nickname for the account that can be used for reporting purposes. The account will be opened in a PENDING_APPROVAL state 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.

The following status apply to an account:

Example request

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

Listing account groups and accounts

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

• GET /users/{user_ID}/account_groups and
• GET/users/{user_ID}/accounts.

All account groups and accounts can be listed with

• GET /account_groups and
• GET /accounts.

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'.