# Adding a user to an existing user group

The steps below explain how to list the existing user groups for a company, view the members of a specific group, and add a new user to that group.

| Step | Name | Endpoint | Details |
|  --- | --- | --- | --- |
| 1. 
 | [List user groups for company](/openapi/rbacapi/user-groups/listusergroupsforcompany) | `POST /v3/companies/{companyId}/user-groups/list` | List all available user groups for a company. You can use search text, filters, and sorting to narrow down results.**URL path requires:** `companyId`.**Request body requires:** `pagination` (with `offset` and `limit`). Optionally, provide `searchText` for case-insensitive search, `sortParams` to sort by `NAME` or `CREATED_AT`, and `filters` to filter by specific `userGroupIds`.**Response will contain:** `userGroups` (an array of user group objects each containing a unique `id`, `name`, and a `description`).**Other APIs will use:** `userGroups` > `id` (referred to as `groupId` in subsequent steps). |
| 1. 
 | [Get user group](/openapi/rbacapi/user-groups/getusergroup) | `GET /v3/companies/{companyId}/user-groups/{groupId}` | View the details of a specific user group selected from Step 1. This step is useful for confirming the group's name, description, and whether it is modifiable before proceeding.**URL path requires:** `companyId` and `groupId` (both as path parameters).**Response will contain:** the full user group object including `id`, `name`, `description`, `companyId`, `isUnmodifiable`, `createdAt`, `updatedAt`, `createdBy`, and `updatedBy`.**Note:** If `isUnmodifiable` is `true`, the group is platform-created and its name, description, and assigned roles cannot be changed. However, user members can still be added to it or removed from it.**Other APIs will use:** `groupId` from this response. |
| 1. 
 | [List user group members](/openapi/rbacapi/user-groups/listusergroupmembers) | `POST /v3/companies/{companyId}/user-groups/{groupId}/members` | View the current members of the user group selected in Step 2. Use this step to verify existing members before adding a new user.**URL path requires:** `companyId` and `groupId`.**Response will contain:** `members` (an array of member objects each containing `userId` and `addedAt`) and `pagination` with `totalNumResults`.**Note:** Use this response to confirm that the user you intend to add is not already a member of the group. |
| 1. 
 | [List user group roles](/openapi/rbacapi/roles/listusergrouprolesv3) (optional) | `POST /v3/companies/{companyId}/user-groups/{groupId}/roles` | View the roles currently assigned to the user group. This helps you understand what permissions the new user will inherit once added to the group.**URL path requires:** `companyId` and `groupId` from Step 1.**Response will contain:** `roles` (an array of role objects each containing role details with `id`, `name`, `description`, `isPlatformRole`, `permissions`, and associated scope information). |
| 1. 
 | [Update user group members](/openapi/rbacapi/user-groups/updateusergroupmembers) | `PATCH /v3/companies/{companyId}/user-groups/{groupId}/members` | Add the new user to the user group.**URL path requires:** `companyId` and `groupId`.**Request body requires:** `userIdsToAdd` (an array of user IDs to add to the group).**Note:** Users being added must belong to the same company as the user group. Once added, they will automatically inherit all roles and scopes assigned to the group.**Response will contain:** a `200` status code confirming the members were updated successfully. |
| 1. 
 | [List user groups for user](/openapi/rbacapi/user-groups/listusergroupsforuser) (optional) | `POST /v3/users/{userId}/user-groups` | Verify that the user was successfully added by listing all user groups the user belongs to.**URL path requires:** `userId`.**Response will contain:** `userGroups` (an array of user group objects that the user is a member of). The user group from Step 2 should now appear in this list, confirming the user has been successfully added and has inherited the group's roles and scopes. |