# 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

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

Response
```json
{
  "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",
  "status": "INACTIVE"
}
```

### Example Business role request

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

Response
```json
{
  "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"
}
```

## 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

Response
```json
{  
  "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

Response
```json
{  
  "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"  
}
```