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

Add members

POST /v1/workgroups/:groupId/users

Adds users to a workgroup right away, with no invitation and no confirmation on their side. Added users get the member role.

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. Strings such as "93" are not accepted. List: GET /v1/users

Examples

curl — personal key

Terminal 
curl -X POST "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 POST "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: 'POST',
  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 added — changes are not rolled back
    console.log('Added:', body.error.processedUserIds)
    console.log('Not added:', 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: 'POST',
  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 added
Fielddata.groupId Typenumber DescriptionWorkgroup ID
Fielddata.processedUserIds Typenumber[] DescriptionIDs of the added users. Duplicates in userIds collapse into one
Fielddata.skippedUserIds Typenumber[] DescriptionAlways 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

Response example

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

Error response example

422 — the user is already in the group, so there is no one to add:

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": [],
    "skippedUserIds": [93]
  }
}

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 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
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 addition may have gone through

Full list of common API errors — Errors.

Known specifics

  • 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 /v1/workgroups/:groupId/users and send only the missing users.
  • An invited user cannot be added this way. Until the invitation from POST /v1/workgroups/:groupId/invitations is accepted, the user lands in skippedUserIds. To add them right away, first cancel the invitation with DELETE /v1/workgroups/:groupId/users.
  • 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.
  • 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 /v1/users/:id.

See also