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

Invite members

POST /v1/workgroups/:groupId/invitations

Sends users an invitation to join a workgroup. They become members only after they accept the invitation in Bitrix24 themselves.

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 IDs of the users to invite — positive integers. List: GET /v1/users
Fieldmessage Typestring Requiredno DescriptionInvitation text the user will see

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/workgroups/157/invitations" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93], "message": "Join the project group"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/workgroups/157/invitations" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93], "message": "Join the project group"}'

JavaScript — personal key

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

const body = await res.json()
if (!body.success && body.error.code === 'BITRIX_ERROR') {
  if (Array.isArray(body.error.processedUserIds)) {
    // Invitations to processedUserIds have already been sent — do not resend them
    console.log('Invited:', body.error.processedUserIds)
    console.log('Not invited:', 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/invitations', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93], message: 'Join the project group' }),
})

const body = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when invitations have been sent to all requested users
Fielddata.groupId Typenumber DescriptionWorkgroup ID
Fielddata.processedUserIds Typenumber[] DescriptionIDs of the users who were sent an invitation. Duplicates in userIds collapse into one
Fielddata.skippedUserIds Typenumber[] DescriptionAlways 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

Response example

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

Error response example

422 — the user has already been invited and has not responded yet:

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 CodeINVALID_PARAMS Descriptionmessage is sent but is not a string
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 invite users to 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 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
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: it does not say who did get an invitation — do not blindly repeat the call
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. The invitation may already have been sent — do not blindly repeat the call

Full list of common API errors — Errors.

Known specifics

See also