Creating an account group

Prerequisites

Authentication scopes — accounts:admin
For more information, refer to Authentication scopes.
Webhook handler ready — Set up a webhook endpoint to listen for account group lifecycle events.
- Subscribe to ACCOUNT_GROUP.* events.
For more information, refer to Implementing webhooks.

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 (unless providing a `business_id`): The ID of the user to be associated with this account group.
`business_id`	Required (unless providing a `user_id`): The ID of the business entity to be associated with this account group.
`type`	Required: Possible values are - `PERSONAL`: Account group of a person who holds assets in their own name. - `LEGAL_ENTITY`: Account group of a legal entity that holds assets in the name of its users. - `BUSINESS`: Account group of a business holding assets. - `FRENCH_PEA`: Account group of a person who holds assets in their own name in the Plan d'Épargne en Actions, a tax-efficient investment wrapper for residents of France. We support one FRENCH_PEA account group per user. - `ISA`: Account group for UK residents holding assets in an Individual Savings Account (ISA).Visit the ISA Integration Guide for more information. - `Child`: Account group for a child user holding assets in a child account. Visit the Child Accounts Guide for more information.

Example

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

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.

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.

Recommended: Use webhooks to track account group status

To check if the account group is activated, set up a webhook listener for ACCOUNT_GROUP.ACTIVATED. You'll receive automatic notification when the account group becomes active and ready for operations.

For more information, refer to Account and account group webhooks

Initially this will be the PENDING APPROVAL status.

As soon as all requirements for activating the account group are met, its status will transition to ACTIVE.

Our flexible regulatory checks ensure that the onboarding process only takes a few seconds instead of days.

Webhooks

You will receive webhooks notifying you of key events in account group creation and activation:

For full documentation of all account group and account webhook events, refer to Account and account group webhooks.

Listing account groups

You can list all account groups of a specific user with

GET /users/{user_id}/account_groups

All account groups can be listed with

GET /account_groups

Next steps

After successfully creating the account group, you can now dedicate yourself to creating an account.