Workgroups

Manage Bitrix24 account workgroups and projects: create, get, update, delete, search. A workgroup brings employees together around a shared topic or project — it has an owner, a subject, openness and archiving flags, and a member count.

Bitrix24 API: sonet_group.* Scope: sonet_group

Create a workgroup

POST /v1/workgroups

Creates a new workgroup in the Bitrix24 account. Returns the full object of the created group. There is one required field — name; the rest of the parameters are optional.

Request fields (body)

isExtranet is read-only and derived from the group's site bindings in Bitrix24. Passing isExtranet, IS_EXTRANET, is_extranet or isextranet returns 400 READONLY_FIELD before creating a group: both false and true are rejected, including the current value. Remove this field from write bodies; reads still return the actual flag.

In POST /v1/workgroups/batch with action: create or action: update, this field causes 400 BATCH_ITEM_VALIDATION before the entire batch is sent. In POST /v1/batch, the rejected operation receives READONLY_FIELD in data.errors.<id>; the HTTP status is 400 if all operations are rejected, or 200 for a mixed result, with valid sibling operations executed.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/workgroups" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing 2026",
    "description": "Coordinating ad campaigns",
    "opened": true,
    "isProject": true
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/workgroups" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing 2026",
    "description": "Coordinating ad campaigns",
    "opened": true,
    "isProject": true
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Marketing 2026',
    description: 'Coordinating ad campaigns',
    opened: true,
    isProject: true,
  }),
})

const { success, data } = await res.json()
console.log('Workgroup ID:', data.id)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Marketing 2026',
    description: 'Coordinating ad campaigns',
    opened: true,
    isProject: true,
  }),
})

const { success, data } = await res.json()

Response fields

Returns the full object of the created workgroup.

Response example

{
  "success": true,
  "data": {
    "id": 201,
    "siteId": "ex",
    "name": "Marketing 2026",
    "description": "Coordinating ad campaigns",
    "dateCreate": "2026-10-20T06:48:43.000Z",
    "dateUpdate": "2026-10-20T06:48:43.000Z",
    "active": true,
    "visible": false,
    "opened": false,
    "archived": false,
    "subjectId": 1,
    "ownerId": 1317,
    "keywords": null,
    "membersCount": 1,
    "dateActivity": "2026-10-20T06:48:43.000Z",
    "subjectName": "Workgroups",
    "isProject": true,
    "isExtranet": true
  }
}

Error response example

422 — the required name field was not passed:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Title not specified"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

The group is created as a collab. On the Bitrix24 accounts we checked, a new group is created as a collab regardless of the request body. The response carries isProject: true, siteId: "ex", isExtranet: true, visible: false and opened: false, even when the request passed isProject: false or opened: true. The project flag cannot be cleared on such a group: PATCH /v1/workgroups/:id with isProject: false answers 422 BITRIX_ERROR with the text Field 'PROJECT' can not be updated from 'Y' for collab. Read the actual field values from the create response.

Keywords are not saved on create. Bitrix24 does not save keywords passed when the group is created: the create response and later reads return keywords: null. The same applies to action: create in POST /v1/workgroups/batch and POST /v1/batch. To set keywords, send PATCH /v1/workgroups/:id with the keywords field after the group is created — the update saves the value.

The group chat is created together with the group. Right after creation the group has one chat, a collab chat. Its card has type set to collab, entityType set to SONET_GROUP and entityId set to the group id. There is no separate main chat. Dialog ID by external ID returns this chat's dialogId for an externalId of the form sgN, where N is the id from the response. You do not need to create a chat for the group with POST /v1/chats: type: "COLLAB" with its entityId creates a second collab chat.

The avatar and permissions of the group chat cannot be set through the API. The avatar, message permissions and the v2-mode update answer 403 BITRIX_ACCESS_DENIED for a collab chat, including for its owner. The workgroup imageUrl field is read-only: PATCH /v1/workgroups/:id with it returns 400 READONLY_FIELD. No other API method sets the avatar of this chat.

See also

• List workgroups
• Get a workgroup
• Update a workgroup
• Workgroup fields