Role-based activation

This section explains the relationship between users and user roles. It also shows the requirements each account group type must meet before it can be funded and accept orders.

Users, roles, and entities

The /roles endpoint shows an end user's connection to a specific entity as listed in the entity_type field.

For personal, child, and joint accounts, the entity_type field equals ACCOUNT_GROUP. For business accounts, the entity_type field equals BUSINESS.

Two distinct sets of conditions govern activation:

Role activation: A role is created in PENDING and transitions to ACTIVE once the role's requirements, such as regulatory checks, are met. The required checks depend on the type of role.
Account group activation: An account group transitions from PENDING_APPROVAL to ACTIVE once all of its required roles are active and any entity-level checks have passed.

These statuses are otherwise independent. An end user can hold a PENDING role, and an account group remains in PENDING_APPROVAL until its required roles are active. An end user's role reaching the ACTIVE status means their own onboarding is complete, but they must still be mapped to a role to access an account group.

Assigning roles

The following table highlights whether you must directly assign the end user's role or if the role is automatically assigned.

For child accounts, you must assign the GUARDIAN roles for the account. For joint accounts, you must assign a second OWNER role. For business accounts, you must assign roles to all of the required users.

In addition, roles like the OWNER and CHILD roles are automatically assigned.

Role	Entity type	Assignment
`OWNER`	`ACCOUNT_GROUP`	Assigned by Upvest when a personal account group is created, and when a child account group converts to a personal account group.
`CHILD`	`ACCOUNT_GROUP`	Assigned by Upvest when a child account group is created.
`JOINT`	`ACCOUNT_GROUP`	First user automatically assigned an `OWNER` role by Upvest. You must assign the second end user an `OWNER` role via the `POST /roles` endpoint.
`GUARDIAN`	`ACCOUNT_GROUP`	Created by you with the `POST /roles` endpoint.
`LEGAL_REPRESENTATIVE` `AUTHORISED_SIGNATORY` `ULTIMATE_BENEFICIAL_OWNER` `CONTRACTING_EXECUTIVE` `TRADER` `SOLE_TRADER`	`BUSINESS`	Created by client via the `POST /roles` endpoint.

For account groups, GUARDIAN (for child accounts) and OWNER (for joint accounts) are the only two values accepted as role_type in a POST /roles request.

For more information, refer to Creating user roles.

Assigning multiple roles

Once configured, an end user's identity verification, compliance screening, and tax residency data can be referenced by every role that user takes on. After onboarding, you can assign as many roles as the end user needs:

For example, the same end user can be the OWNER of their own personal account group, a GUARDIAN on a child account group, and the ULTIMATE_BENEFICIAL_OWNER of a business.
Assign a separate role for each capacity, using one POST /roles request per role. Do not create duplicate users.
Regulatory checks are not repeated for subsequent roles for an end user.

For businesses, every assigned user is screened, not only those covering the minimum required roles. A business can carry additional ultimate beneficial owners, several legal representatives, or extra traders, and all of them are screened.

Activation requirements per account group type

An account group accepts neither funds nor orders until its required roles are active and any entity-level checks have passed.

Account group type	Roles required for activation
`PERSONAL`	Only one active `OWNER`
`CHILD`	Active `GUARDIAN` roles — one for `SOLE_CUSTODY`, two for `JOINT_CUSTODY`, plus one `CHILD` role
`JOINT`	Two active `OWNER` roles
`FRENCH_PEA`, `ISA`, `PENSION_DE`	Only one active `OWNER`
`BUSINESS`	Corporate entities: must have an active `ULTIMATE_BENEFICIAL_OWNER`, `LEGAL_REPRESENTATIVE`, and `CONTRACTING_EXECUTIVE`. Sole traders: one active `SOLE_TRADER`.

The required roles for business accounts depend on the legal structure.

For the requirements that apply to a specific legal type, refer to Creating a corporate business account or Creating a sole trader business account sections in the guide.

Tax-wrapped account groups

Tax wrappers carry their own activation requirements, and the account group and its accounts are activated automatically once the wrapper reaches ACTIVE.

For more details refer to the Tax wrappers guide.

Regulatory checks by operating model

Which regulatory checks gate role activation depends on your operating model, and is configured as part of your setup with Upvest:

Take our license - Single Accounts

Identity verification, compliance screening, and the relevant terms and conditions are required before a role activates.

An account group starts in PENDING_APPROVAL and transitions to ACTIVE once those checks clear, typically within seconds.

Bring your own license - Single Accounts

Typically only a user identifier (for transaction reporting) and tax residency (for tax handling) are required.

Because the role requirements are minimal, roles and the account group usually activate immediately on creation, and you may observe the account group moving directly to ACTIVE.

For more information, refer to Conducting regulatory checks.

Tracking activation

Tracking role activation

Activation is asynchronous and condition-driven. You can subscribe to the role webhook events to automatically receive notifications of a role’s activation status. Listen for ROLE.CREATED and ROLE.ACTIVATED webhook events.

Tracking account group and account activation

To detect readiness, listen for ACCOUNT_GROUP.ACTIVATED and ACCOUNT.ACTIVATED as well.

For more information, refer to User webhooks and Account and account group webhooks sections of the guides.

Role lifecycle

Account group roles and business roles behave differently over time.

Personal, joint, and child accounts

Account group roles, like OWNER, GUARDIAN, and CHILD, persist until the account group is closed. They define who the account group exists for, so you cannot deactivate them via the API.

A DELETE /roles/{role_id} request rejects the attempt with a 403 Forbidden error message.

For child accounts, roles are automatically updated when the child reaches the age at which they can manage the account themselves. When this occurs, the child account group converts to a personal account group and the following roles are updated:

Both GUARDIAN roles are deactivated.
The former CHILD role holder is assigned the OWNER role.

In addition, the account group retains its full transaction history.

You receive a ROLE.DEACTIVATED event for each guardian and a ROLE.CREATED and a ROLE.ACTIVATED event for the new owner.

Business accounts

Business roles can change over the lifetime of the entity, because they record who acts for the business in a given capacity rather than who the business exists for. You can deactivate a business role with the DELETE /roles/{role_id} endpoint:

Only roles whose entity_type is BUSINESS can be deactivated through this endpoint.
Deactivation is terminal. A deactivated role cannot be reactivated. To restore the capacity, create a new role for the same user and entity.
The role remains queryable with status DEACTIVATED.
The call is idempotent. Calling it on an already-deactivated role returns 202 Accepted with no side effects.
A ROLE.DEACTIVATED event is emitted on the first successful deactivation only.

Deactivating a role does not exempt the business from its minimum role requirements. For example, if you deactivate the only active LEGAL_REPRESENTATIVE on a corporate business, assign a replacement so the entity continues to meet the requirements described in Activation requirements per account group type.