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

Workgroup fields

GET /v1/workgroups/fields

Returns the workgroup field schema and the list of operations available in batch requests.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/workgroups/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workgroups/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)
console.log('Available batch operations:', data.batch)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

The label and description field captions are returned in English. Request headers do not switch the language.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields Typeobject DescriptionWorkgroup field schema object
Fielddata.fields.<name> Typeobject DescriptionDescription of a single field
Fielddata.fields.<name>.type Typestring DescriptionValue type: number, string, boolean or datetime
Fielddata.fields.<name>.readonly Typeboolean Descriptiontrue — the field is filled in by the system and is not passed in write requests
Fielddata.fields.<name>.nullable Typeboolean Descriptiontrue — the field can come back as null. The key is present only on such fields
Fielddata.batch Typearray DescriptionList of entity operations available in POST /v1/batch: create, update, delete

Workgroup fields

Field Type Read-only Description
Fieldid Typenumber Read-onlyyes DescriptionWorkgroup identifier
Fieldname Typestring Read-only DescriptionName
Fielddescription Typestring Read-only DescriptionDescription
Fieldactive Typeboolean Read-only DescriptionWhether the group is active
Fieldvisible Typeboolean Read-only DescriptionWhether it is visible in general lists
Fieldopened Typeboolean Read-only DescriptionWhether it is open for joining without an invitation
FieldownerId Typenumber Read-only DescriptionOwner (responsible person). List: GET /v1/users
FieldsubjectId Typenumber Read-only DescriptionSubject identifier
FieldsubjectName Typestring Read-onlyyes DescriptionSubject name
FieldmembersCount Typenumber Read-onlyyes DescriptionNumber of members
FielddateCreate Typedatetime Read-onlyyes DescriptionCreation date
FielddateUpdate Typedatetime Read-onlyyes DescriptionLast update date
FielddateActivity Typedatetime Read-onlyyes DescriptionLast activity date
Fieldarchived Typeboolean Read-only DescriptionWhether it is archived
FieldisProject Typeboolean Read-only DescriptionWhether it is a project with tasks and deadlines
FieldisExtranet Typeboolean Read-onlyyes DescriptionExtranet group
Fieldkeywords Typestring Read-only DescriptionKeywords. Not saved on create — set via PATCH
FieldsiteId Typestring Read-onlyyes DescriptionBitrix24 account site identifier
FieldimageUrl Typestring Read-onlyyes DescriptionGroup avatar URL

Available includes

The GET /v1/workgroups/fields endpoint returns the list of available includes: owner.

Usage example: Get a workgroup.

More on includes: Related data.

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Identifier of the workgroup." },
      "name": { "type": "string", "readonly": false, "label": "Name", "description": "Name of the workgroup." },
      "description": { "type": "string", "readonly": false, "label": "Description", "description": "Text description of the workgroup." },
      "active": { "type": "boolean", "readonly": false, "label": "Active", "description": "Indicates that the group is active." },
      "visible": { "type": "boolean", "readonly": false, "label": "Visible in lists", "description": "Indicates that the group is shown in general lists." },
      "opened": { "type": "boolean", "readonly": false, "label": "Open group", "description": "Indicates that joining the group is possible without an invitation." },
      "ownerId": { "type": "number", "readonly": false, "label": "Owner", "description": "Identifier of the user responsible for the group." },
      "subjectId": { "type": "number", "readonly": false, "label": "Subject ID", "description": "Identifier of the subject (area of activity) of the workgroup." },
      "subjectName": { "type": "string", "readonly": true, "label": "Subject name", "description": "Name of the subject the workgroup belongs to." },
      "membersCount": { "type": "number", "readonly": true, "label": "Member count", "description": "Number of members in the workgroup." },
      "dateCreate": { "type": "datetime", "readonly": true, "label": "Created at", "description": "Date and time the workgroup was created." },
      "dateUpdate": { "type": "datetime", "readonly": true, "label": "Updated at", "description": "Date and time the workgroup was last updated." },
      "dateActivity": { "type": "datetime", "readonly": true, "label": "Last activity date", "description": "Date and time of the last activity in the workgroup." },
      "archived": { "type": "boolean", "readonly": false, "label": "Archived", "description": "Indicates that the group has been placed in the archive." },
      "isProject": { "type": "boolean", "readonly": false, "label": "Project", "description": "Indicates that the group is a project with tasks and deadlines." },
      "isExtranet": { "type": "boolean", "readonly": true, "label": "Extranet group", "description": "Read-only flag derived from the group's site bindings in Bitrix24. Cannot be set directly." },
      "keywords": { "type": "string", "readonly": false, "nullable": true, "label": "Keywords", "description": "Keywords associated with the workgroup. Bitrix24 does not save a value passed on create — the group is created with keywords null. Set keywords with PATCH /v1/workgroups/:id after the group is created." },
      "siteId": { "type": "string", "readonly": true, "label": "Site ID", "description": "Identifier of the portal site the group belongs to." },
      "imageUrl": { "type": "string", "readonly": true, "label": "Avatar URL", "description": "Link to the workgroup's avatar image." }
    },
    "batch": ["create", "update", "delete"]
  }
}

Error response example

401 — no authorization key:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required"
  }
}

Errors

HTTP Code Description
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sonet_group scope
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

  • The field list does not depend on the permissions of the key's user — the full entity schema is returned.
  • Besides the operations listed in data.batch, POST /v1/batch also accepts get, list and fields for workgroups.

See also