Creating account groups and accounts
Creating accounts is a key step that must be completed before operations, such as placing orders, can be performed.
This guide will lead you through the creation of account groups and accounts.
Prerequisites
Before attempting this guide you must understand the roles of account groups and accounts within the Upvest Investment API.
Please read the Account Groups and Accounts overview before continuing.
You must be able to create a user.
Overview
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:
First create a user as decribed here.
Then set up the parent account group.
Create the account.
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.
→ Creating an account group
After you have created the user, you can set up the parent account group as follows:
POST /account_groups
This request accepts two parameters in its body:
Parameter | Description |
---|---|
user_id | Required: The ID of the user to be associated with this account group. |
type | Required: Possible values are - PERSONAL : Account group of a person who holds assets in his own name. We support one PERSONAL account group per user. - LEGAL_ENTITY : Account group of a legal entity that holds assets in the name of its users. |
Example request
{
"user_id": "413715f2-5401-4b97-8055-034a6b879f8c",
"type": "PERSONAL"
}
In the response to this request, you will receive an account group ID, which is needed to create an account and to take further actions on the account group itself.
→ Monitoring account group status
The response to the request to create an account group, contains status field.
The following statuses can 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. |
Initially this will be the PENDING APPROVAL
status. You can check the current status of an account group by inspecting it directly using the account_group_id
:
GET /account_groups/{account_group_id}
As soon as all requirements for activating the account group are met, its status will transition to ACTIVE
.
You will also receive the following webooks notifying you of the key events in account group creation and acitivation:
→ Create 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.
Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.
Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.
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. |
→ 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
- GET
/account_groups
and - GET
/accounts
.
✔ Creating accounts and account groups complete!
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.