For AI agents: markdown of this page — /docs-content-en/workgroups/members/remove.md documentation index — /llms.txt

Remove members

DELETE /v1/workgroups/:groupId/users

Removes users from a workgroup. The same call cancels an invitation the user has not answered yet.

Parameters

Parameter Type Required Description
ParametergroupId (path) Typenumber Requiredyes DescriptionWorkgroup ID — a positive integer. List: GET /v1/workgroups

Request fields (body)

Field Type Required Description
FielduserIds Typenumber[] Requiredyes DescriptionNon-empty array of user IDs — positive integers. Group membership: GET /v1/workgroups/:groupId/users

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/workgroups/157/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93]}'

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/workgroups/157/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93]}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/157/users', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93] }),
})

const body = await res.json()
if (!body.success && body.error.code === 'BITRIX_ERROR') {
  if (Array.isArray(body.error.processedUserIds)) {
    // Some users may already be removed — changes are not rolled back
    console.log('Removed:', body.error.processedUserIds)
    console.log('Not removed:', body.error.skippedUserIds)
  } else {
    // The other 422: Bitrix24 refused the call, so the response has no arrays
    console.log('Bitrix24 refused:', body.error.message)
  }
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/157/users', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93] }),
})

const body = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when all requested users are removed
Fielddata.groupId Typenumber DescriptionWorkgroup ID
Fielddata.processedUserIds Typenumber[] DescriptionIDs of the removed users and of those whose invitation is cancelled. Duplicates in userIds collapse into one
Fielddata.skippedUserIds Typenumber[] DescriptionAlways 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

Response example

JSON 
{
  "success": true,
  "data": {
    "groupId": 157,
    "processedUserIds": [93],
    "skippedUserIds": []
  }
}

Error response example

422 — member 93 is removed, group owner 1 is skipped:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "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.",
    "processedUserIds": [93],
    "skippedUserIds": [1]
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiongroupId is not a positive integer, for example 15.7
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionuserIds is missing, empty or contains something other than positive integers
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not sent
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the sonet_group scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key works in read-only mode
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user the key acts on behalf of has no permission to change the membership of this group
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe group does not exist or is not visible to the user the key acts on behalf of
HTTP422 CodeBITRIX_ERROR DescriptionNot 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
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 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
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded. Retry after the delay in the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response the endpoint cannot parse
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 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

Full list of common API errors — Errors.

Known specifics

  • 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.
  • The owner cannot be removed with this call. First transfer ownership to another user with PUT /v1/workgroups/:groupId/owner — after that, the previous owner stays in the group with the member role.
  • 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.
  • An invited user does not appear in the member list but can be removed. GET /v1/workgroups/:groupId/users does not show users with an unanswered invitation, while this call cancels their invitation and returns them in processedUserIds.

See also