Creating user roles

Both Business accounts and Child accounts require clients to set up users with specific roles. To help facilitate this, Upvest provides the /roles API.

Prerequisites

Prior to adding a user role, you must first create both the user and either a child account group or business entity.

In addition you must work with Upvest to enable the roles:admin and roles:read scopes for authentication.

Setting the user’s role

You can set a user’s role for both child accounts and business account users as follows:

POST /roles

Field	Required	Description
`user_id`	Required	The user’s unique identifier.
`entity_type`	Required	Sets whether the `entity_id` parameter equals the `id` of a child account group or business entity. Accepts the following values: `ACCOUNT_GROUP`: Used for child accounts groups. `BUSINESS`: Used for business entities.
`entity_id`	Required	Unique identifier for either the child account group or the business entity depending on the value of the `entity_type` parameter.
`role_type`	Required	Sets the specific role to map to the user. For child accounts: GUARDIAN: The user is a legal custodian for the child account group. CHILD: The actual child beneficiary for a child account. The owner of the child account group is automatically set to the child. For business accounts: - `LEGAL_REPRESENTATIVE`: a designated individual that serves as an official legal representative for the business. - `AUTHORISED_SIGNATORY`: an individual that is given the legal right to sign documents/make commitments on behalf of a business. - `ULTIMATE_BENEFICIAL_OWNER`: individual who ultimately owns or controls the business. - `CONTRACTING_EXECUTIVE`: an individual that is able to enter contracts on behalf of a business. - `TRADER`: an individual that is permitted to trade on behalf of a business. NOTE: Business accounts must assign at least one (1) Ultimate beneficial owner and at least one (1) Legal representative and one Contracting Executive to the business.
`status`	Required	Unique identifier of the transfer. Useful for API consumers to build special logic on their side
Additional parameter for child accounts
`custody_type`		Sets whether a single or multiple guardian roles are required for the child account group. - `SOLE_CUSTODY` - Single guardian - `JOINT_CUSTODY` - Multiple guardians required

Examples request and response for child accounts

Example Account Group role request

{
  "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab",
  "entity_type": "ACCOUNT_GROUP",
  "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c",
  "role_type": "GUARDIAN"
}

Example Business role request

{
  "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0",
  "entity_type": "BUSINESS",
  "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712",
  "role_type": "LEGAL_REPRESENTATIVE"
}

Listing roles

You can retrieve a list of all created roles by submitting the following GET request:

GET /roles

You can also retrieve details for a specific /role using the following:

GET /roles/{role_id}

User roles status

When assigning or retrieving users’ roles, the following statuses appear in the response message.

Status	Description
PENDING	The role is not yet activated. This may occur if the account group requirements are not met. For example: A child account does not have at least two guardians assigned when `custody_type=JOINT_CUSTODY`. A business account does not have at least one legal representative and one ultimate business owner assigned.
ACTIVE	The role is active and mapped to the user and account group/business.
DEACTIVATED	The role is deactivated. For example, a guardian’s role deactivates when the child user comes of age.

Roles event webhooks

You can use the Roles event webhook to track the status of the roles creation. Both the account group role and business role events use the following statuses:

Status	Description
ROLE.CREATED	The role is added to the system but not yet activated. This may occur if the account group requirements are not met.
ROLE.ACTIVATED	The role is active and mapped to the user and account group/business.
ROLE.DEACTIVATED	The role is deactivated. For example, a guardian’s role deactivates when the child user comes of age.

Example response account group role creation

{  
  "id": "2df83681-6a42-4837-a554-a8197335bcfa",  
  "created_at": "2021-11-22T09:04:42Z",  
  "type": "ROLE.CREATED",  
  "object": {  
    "id": "baf05386-0459-4e8c-9ac9-cd6442f194dd",  
    "created_at": "2025-04-01T10:11:40Z",  
    "updated_at": "2025-04-01T10:11:40Z",  
    "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab",  
    "entity_type": "ACCOUNT_GROUP",  
    "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c",  
    "role_type": "GUARDIAN",  
    "custody_type": "JOINT_CUSTODY",  
    "status": "PENDING"  
  },  
  "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b"  
}

Example response business role activation

{  
  "id": "2df83681-6a42-4837-a554-a8197335bcfa",  
  "created_at": "2021-11-22T09:04:42Z",  
  "type": "ROLE.ACTIVATED",  
  "object": {  
    "id": "e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f",  
    "created_at": "2025-04-01T10:11:40Z",  
    "updated_at": "2025-04-01T10:11:40Z",  
    "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0",  
    "entity_type": "BUSINESS",  
    "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712",  
    "role_type": "LEGAL_REPRESENTATIVE",  
    "status": "ACTIVE"  
  },  
  "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b"  
}