## Task fields

`GET /v1/tasks/fields`

Returns the task field schema: types, read-only flags, the `nullable` marker, human-readable `label` and `description`, value enumerations for `status`, `priority`, `mark` and `durationType`, and — for the fields the Bitrix24 account serves dynamically — the dictionary of accepted values `values` plus the default value `default`.

Field names match those in the [list](./list.md) and [card](./get.md) responses, and the declared types match the returned values: `number` fields return numbers, and `boolean` fields return `true` or `false`.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/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/tasks/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)
console.log('status values:', data.fields.status.enum)
```

### JavaScript — OAuth application

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

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

## Response fields

Every task field is described in camelCase — under the same name the response carries. Raw upper-case names are gone from the schema. There are two expected exceptions: the account's user fields (`UF_*`) and `CHECKLIST` — their set depends on the account, so they arrive dynamically (see [Account-specific fields](#account-specific-fields)).

The "Bitrix24" column gives the name the field is accepted under in `filter`, `sort` and `select`. The "null" column says whether the field can arrive empty.

The exception is `realStatus`: it is a filter-and-sort-only service name marked `notReturned: true`. An explicit `select=realStatus` returns an `UNKNOWN_SELECT_FIELD` warning, and no separate value is present in the response. Use `select=status` to read the actual status.

The `label` and `description` field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language. Enum values carry an English `label`.

| Field | Bitrix24 | Type | RO | null | Description |
|------|----------|-----|:--:|:--:|---------|
| `id` | `ID` | number | yes |  | Task identifier |
| `title` | `TITLE` | string | |  | Task title |
| `description` | `DESCRIPTION` | string | | yes | Description (supports BB-code) |
| `responsibleId` | `RESPONSIBLE_ID` | number | |  | Responsible person. List: `GET /v1/users` |
| `createdBy` | `CREATED_BY` | number | |  | Creator. Defaults to the key's user. Can be set both on create and in PATCH — Bitrix24 applies the value within the permissions of the calling user. Pass an existing employee only, otherwise the task stops being manageable through the API (see [PATCH /v1/tasks/:id](./update.md)). List: `GET /v1/users` |
| `status` | `STATUS` | number | |  | Task status. Allowed values in `fields.status.enum`. **`filter[status]` is a virtual (meta) filter**: here Bitrix24 expects `−1` (overdue), `−2` (unviewed), `−3` (almost overdue), not the number from the `status` field of the response — so `filter[status]=2` will NOT return all tasks with status `2`. To filter by the actual status use `realStatus` |
| `realStatus` | `REAL_STATUS` | number | yes |  | Real (actual stored) task status — matches the `status` field value in the response. `filter`/`sort` only: `?filter[realStatus]=2`, `?sort=realStatus` — unlike the virtual `filter[status]`, it filters by the stored status. Same values as `status` (see `fields.status.enum`). Not returned separately in the response body (the real status is already in `status`) — the schema marks this with `notReturned`. Change the status via `status` |
| `priority` | `PRIORITY` | number | |  | Task priority. Allowed values in `fields.priority.enum` |
| `groupId` | `GROUP_ID` | number | |  | Workgroup. List: `GET /v1/workgroups` |
| `parentId` | `PARENT_ID` | number | | yes | Parent task. List: `GET /v1/tasks` |
| `deadline` | `DEADLINE` | datetime | | yes | Deadline (ISO 8601) |
| `dateStart` | `DATE_START` | datetime | yes | yes | The actual date when work on the task started. Filterable: `?filter[>=dateStart]=2026-05-01T00:00:00` |
| `startDatePlan` | `START_DATE_PLAN` | datetime | | yes | Planned start date |
| `endDatePlan` | `END_DATE_PLAN` | datetime | | yes | Planned end date |
| `timeEstimate` | `TIME_ESTIMATE` | number | |  | Effort estimate in seconds |
| `timeSpentInLogs` | `TIME_SPENT_IN_LOGS` | number | yes | yes | Time actually spent, in seconds — the sum of the time-tracking entries, see [Task time tracking](./time.md). Until such entries exist, the field arrives as `null`. Selectable via `?select=timeSpentInLogs` and sortable via `?sort=-timeSpentInLogs`. A filter on this field is **silently ignored** — the request returns the same set as one without it. The sum over a selection comes from [aggregation](./aggregate.md) |
| `tags` | `TAGS` | object |  | | Task tags. A dictionary keyed by tag identifier: `{ "<id>": { "id": <id>, "title": "<tag>" } }`. With no tags — `{}`. Filter by a single tag: `?filter[tags]=tag` (translated to Bitrix24 `TAG`) |
| `accomplices` | `ACCOMPLICES` | array | |  | Participants. List: `GET /v1/users`. Filter by a single user: `?filter[accomplices]=25` (translated to Bitrix24 `ACCOMPLICE`) |
| `auditors` | `AUDITORS` | array | |  | Observers. List: `GET /v1/users`. Filter by a single user: `?filter[auditors]=25` (translated to Bitrix24 `AUDITOR`) |
| `closedDate` | `CLOSED_DATE` | datetime | | yes | Closing date (set on transition to status `5` or `6`). A service field, but accepted on writes — see [PATCH /v1/tasks/:id](./update.md) |
| `createdDate` | `CREATED_DATE` | datetime | |  | Creation date. A service field, but accepted on writes — see [PATCH /v1/tasks/:id](./update.md) |
| `changedDate` | `CHANGED_DATE` | datetime | |  | Date of the last change. A service field, but accepted on writes — the submitted value is stored instead of the current time, see [PATCH /v1/tasks/:id](./update.md) |
| `changedBy` | `CHANGED_BY` | number | |  | ID of the user who last modified the task. A service field, but accepted on writes — see [PATCH /v1/tasks/:id](./update.md). List: `GET /v1/users` |
| `closedBy` | `CLOSED_BY` | number | | yes | ID of the user who closed the task. A service field, but accepted on writes — see [PATCH /v1/tasks/:id](./update.md). List: `GET /v1/users` |
| `statusChangedBy` | `STATUS_CHANGED_BY` | number | | yes | ID of the user who last changed the task status. A service field, but accepted on writes — see [PATCH /v1/tasks/:id](./update.md). List: `GET /v1/users` |
| `activityDate` | `ACTIVITY_DATE` | datetime | yes |  | Date of the last activity (includes comments, unlike `changedDate`). Always returned and selectable via `?select=activityDate`. Important: not filterable on the Bitrix24 side — use `changedDate` for filtering |
| `mark` | `MARK` | string |  | yes | Supervisor rating of the task. Values live in `fields.mark.enum` (`P` — positive, `N` — negative). `null` until rated |
| `multitask` | `MULTITASK` | boolean |  |  | The task has several responsible users |
| `notViewed` | `NOT_VIEWED` | boolean | yes |  | The responsible user has not opened the task yet. Specific to the key's user |
| `replicate` | `REPLICATE` | boolean |  |  | The task is a recurring-task template |
| `stageId` | `STAGE_ID` | number |  |  | Kanban stage. `0` when the task is not on a board |
| `sprintId` | `SPRINT_ID` | number |  | yes | Scrum sprint |
| `backlogId` | `BACKLOG_ID` | number |  | yes | Scrum backlog |
| `statusChangedDate` | `STATUS_CHANGED_DATE` | datetime | yes |  | When the status last changed. Important: not filterable on the Bitrix24 side — use `changedDate` |
| `guid` | `GUID` | string | yes |  | Global identifier in braces, preserved across export and import. Use `id` for requests |
| `xmlId` | `XML_ID` | string |  | yes | Arbitrary code for matching with an external system, up to 50 characters. A longer value is not rejected on write — only the first 50 characters are stored, and `filter[xmlId]` with the original value does not find the task |
| `commentsCount` | `COMMENTS_COUNT` | number | yes | yes | Total comments on the task |
| `serviceCommentsCount` | `SERVICE_COMMENTS_COUNT` | number | yes | yes | How many automatic comments Bitrix24 itself added — about a status change, for example |
| `newCommentsCount` | `NEW_COMMENTS_COUNT` | number | yes |  | Unread comments. Specific to the key's user |
| `allowChangeDeadline` | `ALLOW_CHANGE_DEADLINE` | boolean |  |  | The responsible user may move `deadline` themselves |
| `allowTimeTracking` | `ALLOW_TIME_TRACKING` | boolean |  |  | Time tracking is enabled. Entries — `GET /v1/tasks/{taskId}/time` |
| `chatId` | `CHAT_ID` | number | yes | yes | Task discussion chat. Messages — `GET /v1/tasks/{taskId}/chat/messages` |
| `durationPlan` | `DURATION_PLAN` | number |  | yes | Planned effort in `durationType` units |
| `durationFact` | `DURATION_FACT` | number | yes | yes | Actual effort in `durationType` units |
| `durationType` | `DURATION_TYPE` | string |  |  | The unit of measure for `durationPlan` and `durationFact`. Values live in `fields.durationType.enum` |
| `favorite` | `FAVORITE` | boolean | yes |  | In favorites. Specific to the key's user. Manage via `POST/DELETE /v1/tasks/{taskId}/favorite` |
| `sorting` | `SORTING` | number | yes | yes | Manual sort weight inside a list |
| `isMuted` | `IS_MUTED` | boolean | yes |  | Notifications muted. Specific to the key's user |
| `isPinned` | `IS_PINNED` | boolean | yes |  | Pinned in the task list. Specific to the key's user. Manage via `POST/DELETE /v1/tasks/{taskId}/pin` |
| `isPinnedInGroup` | `IS_PINNED_IN_GROUP` | boolean | yes |  | Pinned inside its workgroup list |
| `flowId` | `FLOW_ID` | number | yes | yes | Flow the task was created in |
| `siteId` | `SITE_ID` | string | yes |  | The Bitrix24 account site the task belongs to |
| `forumId` | `FORUM_ID` | number | yes | yes | Internal comment storage |
| `forumTopicId` | `FORUM_TOPIC_ID` | number | yes | yes | Internal comment storage |
| `exchangeId` | `EXCHANGE_ID` | number | yes | yes | Microsoft Exchange identifier. Populated only on Bitrix24 accounts with synchronization |
| `exchangeModified` | `EXCHANGE_MODIFIED` | datetime | yes | yes | When the task last changed on the Microsoft Exchange side |
| `outlookVersion` | `OUTLOOK_VERSION` | number | yes |  | Revision counter for Microsoft Outlook synchronization |
| `viewedDate` | `VIEWED_DATE` | datetime | yes | yes | When the key's user last opened the task |
| `subordinate` | `SUBORDINATE` | boolean | yes |  | The task belongs to a subordinate of the key's user |
| `taskControl` | `TASK_CONTROL` | boolean |  |  | Once completed, the task returns to the creator for approval |
| `addInReport` | `ADD_IN_REPORT` | boolean |  |  | The task is counted in efficiency reports |
| `matchWorkTime` | `MATCH_WORK_TIME` | boolean |  |  | Deadline calculation skips weekends and holidays |
| `forkedByTemplateId` | `FORKED_BY_TEMPLATE_ID` | number | yes | yes | Template the task was created from. `null` when created manually |
| `descriptionInBbcode` | `DESCRIPTION_IN_BBCODE` | boolean | yes |  | The `description` field holds BB-code rather than plain text |
| `creator` | — | object | yes |  | Creator card: name, link, avatar. Not filterable and not selectable via `select` |
| `responsible` | — | object | yes |  | Responsible user card. Not filterable and not selectable via `select` |
| `accomplicesData` | — | object | yes |  | Participant cards keyed by user ID. With no participants — `{}` |
| `auditorsData` | — | object | yes |  | Observer cards keyed by user ID. With no observers — `{}` |
| `group` | — | object | yes |  | Workgroup card: name, image. With no group — `{}` |

**`status` values** — the `fields.status.enum` field:

| Value | Label | Description |
|----------|-------|----------|
| `1` | New | Initial state. New tasks are created with status `2`. The value `1` is found in tasks imported from external systems or migrated from older Bitrix24 versions |
| `2` | Pending | Pending. The default status for new tasks |
| `3` | In Progress | In progress |
| `4` | Awaiting Control | Awaiting control. The responsible user marked the task as done. The creator must confirm |
| `5` | Completed | Completed |
| `6` | Deferred | Deferred |
| `7` | Declined | Declined |

**`priority` values** — the `fields.priority.enum` field:

| Value | Label |
|----------|-------|
| `0` | Low |
| `1` | Normal |
| `2` | High |

**User fields (`UF_*`)** are accepted on create/update and in filters in both spellings — `ufCrmTask` and `UF_CRM_TASK` (camelCase is converted automatically). Important: `UF_CRM_TASK` (the CRM binding) accepts an **array** of binding identifiers — `["D_123"]` (deal), `["C_45"]` (contact), `["CO_7"]` (company), `["L_9"]` (lead). A string instead of an array (`"D_123"`) is silently ignored by Bitrix24 — the value will not be saved (verified on a live Bitrix24 account).

**File fields** accept an array of strings shaped as `n<id>`, where `id` is the file identifier from the [`POST /v1/files/upload`](../files/upload.md) response. A task has one standard file field — `ufTaskWebdavFiles` — plus any user fields of the file type created by the Bitrix24 account administrator. A sample value is `["n9759"]`. Any other shape — a number, a string without the prefix, a single string instead of an array — is rejected with `400 INVALID_DISK_ATTACHMENT_VALUE`, and no attachment is created.

A write replaces the whole attachment list of the task. An empty array `[]` removes every attachment. Clearing with an empty array works on `POST /v1/tasks` and `PATCH /v1/tasks/:id`; in a batch request (`POST /v1/batch`, `POST /v1/tasks/batch`) an empty array does not reach the wire and the attachments stay in place, so send the clear as a single request. On read the field returns numbers other than the ones sent on write: these are attachment identifiers that change on every rewrite of the field and do not match the file identifiers in Drive. To address the file itself, store the `id` from the upload response.

## Account-specific fields

Beyond the declared fields above, `GET /v1/tasks/fields` returns the fields that depend on the particular Bitrix24 account and therefore cannot be described in advance:

- **user fields** (`UF_*` / `uf*`) — their set is defined by the Bitrix24 account administrator.
- **`CHECKLIST`** — checklist items, read-only here. Manage via `GET/POST /v1/tasks/{taskId}/checklist`.

For such fields `type` comes from the account, and with it the dictionary of accepted values `values` and the default value `default`:

```json
{
  "CHECKLIST": {
    "type": "enum",
    "readonly": false,
    "label": "Checklist",
    "description": "Checklist items of the task. Read-only here — items are created and changed through the task checklist endpoints.",
    "values": [
      { "value": "Y", "label": "Yes" },
      { "value": "N", "label": "No" }
    ],
    "default": "N"
  }
}
```

The `label` of a dictionary entry comes from the account and is localized according to the account's settings. Where the account serves bare codes with no captions, the entry has no `label`.

**Six fields are per-user, not properties of the task.** `favorite`, `isMuted`, `isPinned`, `newCommentsCount`, `notViewed` and `viewedDate` describe how the task relates to the user the API key acts on behalf of — a different key on the same Bitrix24 account will see different values here. Do not cache them as task attributes.

**The `monts` typo in `durationType` comes from Bitrix24.** We pass the dictionary through as-is because that is the spelling the account accepts. A "corrected" `months` would not be understood.

**`values` and `items` are different keys with different shapes.** `values` is the normalized dictionary above. `items` is the raw Bitrix24 enumeration reference list for fields of type `enumeration`, passed through as-is: `[{ "ID": "1", "VALUE": "First" }]`. The guarantee is per key: each one always has its own shape. Read the one you need by name rather than "whichever dictionary you come across first" — on today's Bitrix24 accounts a field carries only one of the two, but we do not forbid both being present.

**Nullability.** Fields that really do arrive empty carry `nullable: true` in the schema and a mark in the "null" column above — 27 of them today. For type-safe clients (TS) declare such fields as `T | null`. Empty `accomplices` and `auditors` arrive as `[]` — they are lists. Empty `tags`, `group`, `accomplicesData` and `auditorsData` arrive as `{}` — they are dictionaries.

**Lists and cards differ in their key sets.** This is a property of Bitrix24 rather than of this wrapper, so those fields are deliberately absent from the schema: `subStatus` arrives only in the [list](./list.md), while `action`, `checklist`, `checkListTree` and `checkListCanAdd` arrive only in the [card](./get.md). They are still returned in the response.

## Response example

A few fields are shown as an example. The full response contains every declared field plus the account's user fields.

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "title": { "type": "string", "readonly": false },
      "description": { "type": "string", "readonly": false },
      "responsibleId": { "type": "number", "readonly": false },
      "createdBy": { "type": "number", "readonly": false },
      "status": {
        "type": "number",
        "readonly": false,
        "enum": [
          { "value": 1, "label": "New" },
          { "value": 2, "label": "Pending" },
          { "value": 3, "label": "In Progress" },
          { "value": 4, "label": "Awaiting Control" },
          { "value": 5, "label": "Completed" },
          { "value": 6, "label": "Deferred" },
          { "value": 7, "label": "Declined" }
        ]
      },
      "priority": {
        "type": "number",
        "readonly": false,
        "enum": [
          { "value": 0, "label": "Low" },
          { "value": 1, "label": "Normal" },
          { "value": 2, "label": "High" }
        ]
      },
      "deadline": { "type": "datetime", "readonly": false },
      "createdDate": { "type": "datetime", "readonly": false },
      "changedDate": { "type": "datetime", "readonly": false }
    }
  }
}
```

## Error response example

403 — no scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'tasks' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `tasks` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 429 | `RATE_LIMITED` | Rate 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](/docs/errors).

## See also

- [Create task](./create.md)
- [Update task](./update.md)
- [List tasks](./list.md)
- [Search tasks](./search.md)
- [Aggregate tasks](./aggregate.md)
- [Entity API](/docs/entity-api)


Field schema IDs and enumeration variants: [Task fields](/docs/userfields/tasks), `GET /v1/userfields/tasks`.