[{"data":1,"prerenderedAt":12},["ShallowReactive",2],{"docs-workgroups\u002Fmembers":3,"docs-tabs-workgroups\u002Fmembers":6},{"content":4,"lastmod":5},"# Workgroup members\n\nChange 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.\n\nBitrix24 API: `sonet_group.user.*`, `sonet_group.setowner`\nScope: `sonet_group`\n\n## Operations\n\n- [Add members](.\u002Fmembers\u002Fadd.md) — `POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`\n- [Remove members](.\u002Fmembers\u002Fremove.md) — `DELETE \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`\n- [Change member role](.\u002Fmembers\u002Frole.md) — `PATCH \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`\n- [Invite members](.\u002Fmembers\u002Finvite.md) — `POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Finvitations`\n- [Transfer group ownership](.\u002Fmembers\u002Fowner.md) — `PUT \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fowner`\n- [My workgroups](\u002Fdocs\u002Fme\u002Fworkgroups) — `GET \u002Fv1\u002Fme\u002Fworkgroups`\n\n## Partial result\n\nThe add, remove, change-role and invite operations take a `userIds` array and respond the same way:\n\n- All users processed — `200` with `data.processedUserIds` and an empty `data.skippedUserIds`.\n- Not all processed — `422 BITRIX_ERROR`, with both arrays returned in `error.processedUserIds` and `error.skippedUserIds`.\n- 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.\n\nChanges 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 \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers) and send only the users that really need processing. Do not retry invitations blindly: each one reaches a real person.\n\n## Typical scenario\n\n1. Find the group: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist).\n2. Check the membership: [`GET \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers).\n3. Add employees right away — [`POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](.\u002Fmembers\u002Fadd.md), or invite them — [`POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Finvitations`](.\u002Fmembers\u002Finvite.md).\n4. Assign a moderator: [`PATCH \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](.\u002Fmembers\u002Frole.md) with `role: \"moderator\"`.\n\nThese operations are not available through [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch): a batch call addresses only entities from the [entity reference](\u002Fdocs\u002Fentity-api).\n\n## See also\n\n- [Workgroups](\u002Fdocs\u002Fentities\u002Fworkgroups)\n- [List workgroup members](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers)\n","2026-10-15",{"members\u002Fadd.md":7,"members\u002Fremove.md":8,"members\u002Frole.md":9,"members\u002Finvite.md":10,"members\u002Fowner.md":11},"## Add members\n\n`POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`\n\nAdds users to a workgroup right away, with no invitation and no confirmation on their side. Added users get the member role.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `groupId` (path) | number | yes | Workgroup ID — a positive integer. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|-------|------|:--------:|-------------|\n| `userIds` | number[] | yes | Non-empty array of user IDs — positive integers. Strings such as `\"93\"` are not accepted. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93]}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93]}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93] }),\n})\n\nconst body = await res.json()\nif (!body.success && body.error.code === 'BITRIX_ERROR') {\n  if (Array.isArray(body.error.processedUserIds)) {\n    \u002F\u002F Some users may already be added — changes are not rolled back\n    console.log('Added:', body.error.processedUserIds)\n    console.log('Not added:', body.error.skippedUserIds)\n  } else {\n    \u002F\u002F The other 422: Bitrix24 refused the call, so the response has no arrays\n    console.log('Bitrix24 refused:', body.error.message)\n  }\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93] }),\n})\n\nconst body = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `success` | boolean | `true` when all requested users are added |\n| `data.groupId` | number | Workgroup ID |\n| `data.processedUserIds` | number[] | IDs of the added users. Duplicates in `userIds` collapse into one |\n| `data.skippedUserIds` | number[] | Always an empty array in a successful response. If not everyone could be added, the response is `422 BITRIX_ERROR` and both arrays move into `error`. That is the only response that carries them: the other `422 BITRIX_ERROR` — a refusal from Bitrix24 itself — carries only its own message in `error`, with no `processedUserIds` and no `skippedUserIds` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"groupId\": 157,\n    \"processedUserIds\": [93],\n    \"skippedUserIds\": []\n  }\n}\n```\n\n## Error response example\n\n422 — the user is already in the group, so there is no one to add:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Bitrix24 did not change every requested user: existing membership or role, owner, scrum master, missing user or permissions may prevent the action. Do not blindly retry invitations.\",\n    \"processedUserIds\": [],\n    \"skippedUserIds\": [93]\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|------|-------------|\n| 400 | `INVALID_PARAMS` | `groupId` is not a positive integer, for example `15.7` |\n| 400 | `MISSING_REQUIRED_FIELDS` | `userIds` is missing, empty or contains something other than positive integers |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not sent |\n| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `sonet_group` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key works in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | The user the key acts on behalf of has no permission to change the membership of this group |\n| 404 | `ENTITY_NOT_FOUND` | The group does not exist or is not visible to the user the key acts on behalf of |\n| 422 | `BITRIX_ERROR` | Not all users were added. `error.processedUserIds` and `error.skippedUserIds` list who was added and who was not. A user is skipped if they are already in the group, have a pending invitation to it, or do not exist |\n| 422 | `BITRIX_ERROR` | Bitrix24 refused the call and returned its own reason in `error.message`. This response carries no `error.processedUserIds` and no `error.skippedUserIds` — check that they are present before reading them, and re-read the membership before retrying |\n| 429 | `RATE_LIMITED` | Request limit exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response the endpoint cannot parse |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond in time. The response includes a `Retry-After` header. Re-read the membership before retrying: the addition may have gone through |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **A partial result is not rolled back.** If `userIds` holds several users and some of them are skipped, the response is `422`, but the users in `error.processedUserIds` are already added. Before retrying, re-read the membership with [`GET \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers) and send only the missing users.\n- **An invited user cannot be added this way.** Until the invitation from [`POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Finvitations`](.\u002Finvite.md) is accepted, the user lands in `skippedUserIds`. To add them right away, first cancel the invitation with [`DELETE \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](.\u002Fremove.md).\n- **Every addition shows up in the group chat.** For each added user, a system message announcing that they joined is posted to the group chat.\n- **`422` does not name the reason for each skipped user.** A user who is already a member, a user with an unanswered invitation and a non-existent ID are skipped the same way. To find the reason, check the group membership and call [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget).\n\n## See also\n\n- [Remove members](.\u002Fremove.md)\n- [Change member role](.\u002Frole.md)\n- [Invite members](.\u002Finvite.md)\n- [List workgroup members](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers)\n- [Workgroup members](\u002Fdocs\u002Fworkgroups\u002Fmembers)\n","## Remove members\n\n`DELETE \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`\n\nRemoves users from a workgroup. The same call cancels an invitation the user has not answered yet.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `groupId` (path) | number | yes | Workgroup ID — a positive integer. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|-------|------|:--------:|-------------|\n| `userIds` | number[] | yes | Non-empty array of user IDs — positive integers. Group membership: [`GET \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93]}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93]}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93] }),\n})\n\nconst body = await res.json()\nif (!body.success && body.error.code === 'BITRIX_ERROR') {\n  if (Array.isArray(body.error.processedUserIds)) {\n    \u002F\u002F Some users may already be removed — changes are not rolled back\n    console.log('Removed:', body.error.processedUserIds)\n    console.log('Not removed:', body.error.skippedUserIds)\n  } else {\n    \u002F\u002F The other 422: Bitrix24 refused the call, so the response has no arrays\n    console.log('Bitrix24 refused:', body.error.message)\n  }\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93] }),\n})\n\nconst body = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `success` | boolean | `true` when all requested users are removed |\n| `data.groupId` | number | Workgroup ID |\n| `data.processedUserIds` | number[] | IDs of the removed users and of those whose invitation is cancelled. Duplicates in `userIds` collapse into one |\n| `data.skippedUserIds` | number[] | Always an empty array in a successful response. If not everyone could be removed, the response is `422 BITRIX_ERROR` and both arrays move into `error`. That is the only response that carries them: the other `422 BITRIX_ERROR` — a refusal from Bitrix24 itself — carries only its own message in `error`, with no `processedUserIds` and no `skippedUserIds` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"groupId\": 157,\n    \"processedUserIds\": [93],\n    \"skippedUserIds\": []\n  }\n}\n```\n\n## Error response example\n\n422 — member `93` is removed, group owner `1` is skipped:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Bitrix24 did not change every requested user: existing membership or role, owner, scrum master, missing user or permissions may prevent the action. Do not blindly retry invitations.\",\n    \"processedUserIds\": [93],\n    \"skippedUserIds\": [1]\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|------|-------------|\n| 400 | `INVALID_PARAMS` | `groupId` is not a positive integer, for example `15.7` |\n| 400 | `MISSING_REQUIRED_FIELDS` | `userIds` is missing, empty or contains something other than positive integers |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not sent |\n| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `sonet_group` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key works in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | The user the key acts on behalf of has no permission to change the membership of this group |\n| 404 | `ENTITY_NOT_FOUND` | The group does not exist or is not visible to the user the key acts on behalf of |\n| 422 | `BITRIX_ERROR` | Not all users were removed. `error.processedUserIds` lists the removed users, `error.skippedUserIds` the skipped ones. A user is skipped if they are neither in the group nor invited to it, are the group owner, or are the scrum master of a scrum project |\n| 422 | `BITRIX_ERROR` | Bitrix24 refused the call and returned its own reason in `error.message`. This response carries no `error.processedUserIds` and no `error.skippedUserIds` — check that they are present before reading them, and re-read the membership before retrying |\n| 429 | `RATE_LIMITED` | Request limit exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response the endpoint cannot parse |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond in time. The response includes a `Retry-After` header. Re-read the membership before retrying: the users may already be removed |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **A partial result is not rolled back.** If some users are skipped, the response is `422`, but the users in `error.processedUserIds` are already removed from the group. Repeating the request with the same body is pointless: they will land in `skippedUserIds`.\n- **The owner cannot be removed with this call.** First transfer ownership to another user with [`PUT \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fowner`](.\u002Fowner.md) — after that, the previous owner stays in the group with the member role.\n- **The scrum master of a scrum project cannot be removed with this call.** In the member list the scrum master appears as moderator `E`, but unlike a regular moderator, they land in `skippedUserIds`.\n- **An invited user does not appear in the member list but can be removed.** [`GET \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers) does not show users with an unanswered invitation, while this call cancels their invitation and returns them in `processedUserIds`.\n\n## See also\n\n- [Add members](.\u002Fadd.md)\n- [Invite members](.\u002Finvite.md)\n- [Transfer group ownership](.\u002Fowner.md)\n- [List workgroup members](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers)\n- [Workgroup members](\u002Fdocs\u002Fworkgroups\u002Fmembers)\n","## Change member role\n\n`PATCH \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`\n\nAssigns the moderator role to workgroup members or returns them to the member role. One role applies to all users in `userIds` at once.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `groupId` (path) | number | yes | Workgroup ID — a positive integer. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|-------|------|:--------:|-------------|\n| `userIds` | number[] | yes | Non-empty array of group member IDs — positive integers. Group membership: [`GET \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers) |\n| `role` | string | yes | New role: `moderator` or `member`. In the group membership they appear as `E` and `K`, respectively |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93], \"role\": \"moderator\"}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93], \"role\": \"moderator\"}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93], role: 'moderator' }),\n})\n\nconst body = await res.json()\nif (!body.success && body.error.code === 'BITRIX_ERROR') {\n  if (Array.isArray(body.error.processedUserIds)) {\n    \u002F\u002F Some roles may have already changed — changes are not rolled back\n    console.log('Role changed:', body.error.processedUserIds)\n    console.log('Role not changed:', body.error.skippedUserIds)\n  } else {\n    \u002F\u002F The other 422: Bitrix24 refused the call, so the response has no arrays\n    console.log('Bitrix24 refused:', body.error.message)\n  }\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fusers', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93], role: 'moderator' }),\n})\n\nconst body = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `success` | boolean | `true` when the role is changed for all requested users |\n| `data.groupId` | number | Workgroup ID |\n| `data.processedUserIds` | number[] | IDs of the users who got the new role. Duplicates in `userIds` collapse into one |\n| `data.skippedUserIds` | number[] | Always an empty array in a successful response. If the role did not change for everyone, the response is `422 BITRIX_ERROR` and both arrays move into `error`. That is the only response that carries them: the other `422 BITRIX_ERROR` — a refusal from Bitrix24 itself — carries only its own message in `error`, with no `processedUserIds` and no `skippedUserIds` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"groupId\": 157,\n    \"processedUserIds\": [93],\n    \"skippedUserIds\": []\n  }\n}\n```\n\n## Error response example\n\n422 — role `member` requested: it changed for user `93` but not for the group owner `1`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Bitrix24 did not change every requested user: existing membership or role, owner, scrum master, missing user or permissions may prevent the action. Do not blindly retry invitations.\",\n    \"processedUserIds\": [93],\n    \"skippedUserIds\": [1]\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|------|-------------|\n| 400 | `INVALID_PARAMS` | `groupId` is not a positive integer, for example `15.7` |\n| 400 | `INVALID_PARAMS` | `role` is missing or is neither `moderator` nor `member` |\n| 400 | `MISSING_REQUIRED_FIELDS` | `userIds` is missing, empty or contains something other than positive integers |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not sent |\n| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `sonet_group` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key works in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | The user the key acts on behalf of has no permission to change roles in this group |\n| 404 | `ENTITY_NOT_FOUND` | The group does not exist or is not visible to the user the key acts on behalf of |\n| 422 | `BITRIX_ERROR` | The role did not change for every user. `error.processedUserIds` lists the users whose role changed, `error.skippedUserIds` those whose role did not. A user is skipped if they already have this role or are the group owner |\n| 422 | `BITRIX_ERROR` | Bitrix24 refused the call and returned its own reason in `error.message` — for example, a role code it does not accept. This response carries no `error.processedUserIds` and no `error.skippedUserIds` — check that they are present before reading them, and re-read the membership before retrying |\n| 429 | `RATE_LIMITED` | Request limit exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response the endpoint cannot parse |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond in time. The response includes a `Retry-After` header. Re-read the group membership before retrying: the role may have already changed |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **A partial result is not rolled back.** If some users are skipped, the response is `422`, but the users in `error.processedUserIds` already have the new role. Check the outcome with [`GET \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers).\n- **Repeating the call with the same role returns `422`, not success.** A user whose role already matches the requested one lands in `skippedUserIds`. To keep a repeated call from looking like an error, compare the roles in the group membership before the call.\n- **This call does not change the owner's role.** The owner is assigned by [`PUT \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fowner`](.\u002Fowner.md).\n\n## See also\n\n- [Add members](.\u002Fadd.md)\n- [Transfer group ownership](.\u002Fowner.md)\n- [List workgroup members](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers)\n- [Workgroup members](\u002Fdocs\u002Fworkgroups\u002Fmembers)\n","## Invite members\n\n`POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Finvitations`\n\nSends users an invitation to join a workgroup. They become members only after they accept the invitation in Bitrix24 themselves.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `groupId` (path) | number | yes | Workgroup ID — a positive integer. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|-------|------|:--------:|-------------|\n| `userIds` | number[] | yes | Non-empty array of IDs of the users to invite — positive integers. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `message` | string | no | Invitation text the user will see |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Finvitations\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93], \"message\": \"Join the project group\"}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Finvitations\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userIds\": [93], \"message\": \"Join the project group\"}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Finvitations', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93], message: 'Join the project group' }),\n})\n\nconst body = await res.json()\nif (!body.success && body.error.code === 'BITRIX_ERROR') {\n  if (Array.isArray(body.error.processedUserIds)) {\n    \u002F\u002F Invitations to processedUserIds have already been sent — do not resend them\n    console.log('Invited:', body.error.processedUserIds)\n    console.log('Not invited:', body.error.skippedUserIds)\n  } else {\n    \u002F\u002F The other 422: Bitrix24 refused the call, so the response has no arrays\n    console.log('Bitrix24 refused:', body.error.message)\n  }\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Finvitations', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userIds: [93], message: 'Join the project group' }),\n})\n\nconst body = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `success` | boolean | `true` when invitations have been sent to all requested users |\n| `data.groupId` | number | Workgroup ID |\n| `data.processedUserIds` | number[] | IDs of the users who were sent an invitation. Duplicates in `userIds` collapse into one |\n| `data.skippedUserIds` | number[] | Always an empty array in a successful response. If not everyone could be invited, the response is `422 BITRIX_ERROR` and both arrays move into `error`. That is the only response that carries them: the other `422 BITRIX_ERROR` — a refusal from Bitrix24 itself — carries only its own message in `error`, with no `processedUserIds` and no `skippedUserIds` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"groupId\": 157,\n    \"processedUserIds\": [93],\n    \"skippedUserIds\": []\n  }\n}\n```\n\n## Error response example\n\n422 — the user has already been invited and has not responded yet:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Bitrix24 did not change every requested user: existing membership or role, owner, scrum master, missing user or permissions may prevent the action. Do not blindly retry invitations.\",\n    \"processedUserIds\": [],\n    \"skippedUserIds\": [93]\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|------|-------------|\n| 400 | `INVALID_PARAMS` | `groupId` is not a positive integer, for example `15.7` |\n| 400 | `INVALID_PARAMS` | `message` is sent but is not a string |\n| 400 | `MISSING_REQUIRED_FIELDS` | `userIds` is missing, empty or contains something other than positive integers |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not sent |\n| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `sonet_group` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key works in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | The user the key acts on behalf of has no permission to invite users to this group |\n| 404 | `ENTITY_NOT_FOUND` | The group does not exist or is not visible to the user the key acts on behalf of |\n| 422 | `BITRIX_ERROR` | Not every user was invited. `error.processedUserIds` and `error.skippedUserIds` list who received an invitation and who did not. Reasons for skipping: the user has already been invited and has not responded, or the user is already a group member |\n| 422 | `BITRIX_ERROR` | Bitrix24 refused the call and returned its own reason in `error.message`. This response carries no `error.processedUserIds` and no `error.skippedUserIds`: it does not say who did get an invitation — do not blindly repeat the call |\n| 429 | `RATE_LIMITED` | Request limit exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response the endpoint cannot parse |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond in time. The response includes a `Retry-After` header. The invitation may already have been sent — do not blindly repeat the call |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **An invitation reaches a real person.** Every successful call sends the user a real invitation. A retry after `422` or `503` does not cancel invitations already sent: the users in `error.processedUserIds` have received theirs.\n- **An invited user is not visible in the group membership.** Until the invitation is accepted, [`GET \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers) does not show this user, and [`POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](.\u002Fadd.md) skips them with `422`.\n- **An invitation is cancelled by removal.** [`DELETE \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](.\u002Fremove.md) with the invited user's ID withdraws the invitation. After that, the user can be added to the group right away with [`POST \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](.\u002Fadd.md).\n\n## See also\n\n- [Add members](.\u002Fadd.md)\n- [Remove members](.\u002Fremove.md)\n- [List workgroup members](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers)\n- [Workgroup members](\u002Fdocs\u002Fworkgroups\u002Fmembers)\n","## Transfer group ownership\n\n`PUT \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fowner`\n\nAssigns a new owner to a workgroup. The new owner can also be a user who is not in the group: they are added to it right away with the owner role.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|:--------:|-------------|\n| `groupId` (path) | number | yes | Workgroup ID — a positive integer. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|-------|------|:--------:|-------------|\n| `userId` | number | yes | ID of the new owner — a positive integer. One user, not an array. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fowner\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userId\": 93}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fowner\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userId\": 93}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fowner', {\n  method: 'PUT',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userId: 93 }),\n})\n\nconst body = await res.json()\nconsole.log('Group owner:', body.data.ownerId)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkgroups\u002F157\u002Fowner', {\n  method: 'PUT',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ userId: 93 }),\n})\n\nconst body = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `success` | boolean | `true` when the new owner is assigned and this is confirmed by re-reading the group |\n| `data.groupId` | number | Workgroup ID |\n| `data.ownerId` | number | ID of the group owner after the call. Matches the `userId` sent |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"groupId\": 157,\n    \"ownerId\": 93\n  }\n}\n```\n\n## Error response example\n\n403 — after the transfer, the previous owner tries to change the owner again:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ACCESS_DENIED\",\n    \"message\": \"Insufficient permissions for the operation\",\n    \"hint\": \"Bitrix24 reports an access-rights refusal for sonet_group.setowner, not a scope error. The Bitrix24 user this call runs as lacks access; ask a portal admin to grant it, or call under a user who has it.\",\n    \"cause\": \"b24_permission\",\n    \"method\": \"sonet_group.setowner\",\n    \"fix\": {\n      \"action\": \"grant_b24_rights\",\n      \"via\": \"portal_admin\"\n    }\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|------|-------------|\n| 400 | `INVALID_PARAMS` | `groupId` is not a positive integer, for example `15.7` |\n| 400 | `MISSING_REQUIRED_FIELDS` | `userId` is missing or is not a positive integer. A `userIds` array instead of `userId` also returns this code |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not sent |\n| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `sonet_group` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key works in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | The user the key acts on behalf of has no permission to change the owner of this group |\n| 404 | `ENTITY_NOT_FOUND` | The group does not exist or is not visible to the user the key acts on behalf of |\n| 422 | `BITRIX_ERROR` | Bitrix24 did not confirm the owner change |\n| 422 | `BITRIX_ERROR` | Bitrix24 responded with success, but re-reading the group showed a different owner. Re-read the group before retrying |\n| 422 | `BITRIX_ERROR` | Bitrix24 refused the owner change, or the group re-read, and returned its own reason in `error.message`. Re-read the group before retrying: the owner may have already changed |\n| 429 | `RATE_LIMITED` | Request limit exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response the endpoint cannot parse |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond in time. The response includes a `Retry-After` header. Re-read the group before retrying: the owner may have already changed |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **The transfer may be irreversible for the caller.** After the call, the previous owner stays in the group with the member role `K` and loses the right to change the owner — even if they are a Bitrix24 account administrator. A repeat call on their behalf, including one to take ownership back, gets `403 BITRIX_ACCESS_DENIED`. Before transferring ownership, make sure your choice of new owner is final.\n- **A successful response means a confirmed change.** Before responding, the platform re-reads the group and compares `ownerId` with the `userId` sent, so `200` is returned only when the new owner is already saved.\n- **The owner change shows up in the group chat as a join.** The group chat receives a system message that the new owner joined the group, even if they were already a member. There is no separate message about the owner change.\n- **The previous owner keeps the right to change the membership.** They can still add and remove members with [`POST`](.\u002Fadd.md) and [`DELETE \u002Fv1\u002Fworkgroups\u002F:groupId\u002Fusers`](.\u002Fremove.md) after the transfer, if their Bitrix24 account permissions allow it.\n\n## See also\n\n- [Get a workgroup](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fget)\n- [Change member role](.\u002Frole.md)\n- [Remove members](.\u002Fremove.md)\n- [List workgroup members](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fusers)\n- [Workgroup members](\u002Fdocs\u002Fworkgroups\u002Fmembers)\n",1795000595257]