# Workgroup members

Change the membership of a workgroup: add and remove members, assign moderators, send invitations and transfer ownership. Bitrix24 checks the permissions for each action against the user the key acts on behalf of.

Bitrix24 API: `sonet_group.user.*`, `sonet_group.setowner`
Scope: `sonet_group`

## Operations

- [Add members](./members/add.md) — `POST /v1/workgroups/:groupId/users`
- [Remove members](./members/remove.md) — `DELETE /v1/workgroups/:groupId/users`
- [Change member role](./members/role.md) — `PATCH /v1/workgroups/:groupId/users`
- [Invite members](./members/invite.md) — `POST /v1/workgroups/:groupId/invitations`
- [Transfer group ownership](./members/owner.md) — `PUT /v1/workgroups/:groupId/owner`
- [My workgroups](/docs/me/workgroups) — `GET /v1/me/workgroups`

## Partial result

The add, remove, change-role and invite operations take a `userIds` array and respond the same way:

- All users processed — `200` with `data.processedUserIds` and an empty `data.skippedUserIds`.
- Not all processed — `422 BITRIX_ERROR`, with both arrays returned in `error.processedUserIds` and `error.skippedUserIds`.
- Bitrix24 refused the call — also `422 BITRIX_ERROR`, but `error` carries no arrays, only Bitrix24's own reason for the refusal. Check that the arrays are present before reading them.

Changes for the users in `processedUserIds` of a `422` response are already applied and are not rolled back. The response does not name the reason each user was skipped: the user is already in the group or already invited, already has this role, is the group owner or the scrum master of a scrum project, or does not exist. Before retrying, re-read the membership with [`GET /v1/workgroups/:groupId/users`](/docs/entities/workgroups/users) and send only the users that really need processing. Do not retry invitations blindly: each one reaches a real person.

## Typical scenario

1. Find the group: [`GET /v1/workgroups`](/docs/entities/workgroups/list).
2. Check the membership: [`GET /v1/workgroups/:groupId/users`](/docs/entities/workgroups/users).
3. Add employees right away — [`POST /v1/workgroups/:groupId/users`](./members/add.md), or invite them — [`POST /v1/workgroups/:groupId/invitations`](./members/invite.md).
4. Assign a moderator: [`PATCH /v1/workgroups/:groupId/users`](./members/role.md) with `role: "moderator"`.

These operations are not available through [`POST /v1/batch`](/docs/batch): a batch call addresses only entities from the [entity reference](/docs/entity-api).

## See also

- [Workgroups](/docs/entities/workgroups)
- [List workgroup members](/docs/entities/workgroups/users)