## 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 here are the same ones the [list](./list.md) and [card](./get.md) responses carry, and the types match the values that arrive: a field declared `number` arrives as a number, `boolean` as `true`/`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.

| 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). While there are no such entries, it 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 \| array |  | | Task tags. For a task WITH tags — a dictionary object `{ "<id>": { "id": <id>, "title": "<tag>" } }`. For a task WITHOUT tags an empty array `[]` is returned (not an empty object) — the type depends on the data, check `Array.isArray()` before accessing by key. 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 |
| `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. Records — `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 the units of `durationType` |
| `durationFact` | `DURATION_FACT` | number | yes | yes | Actual effort in the units of `durationType` |
| `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. Management — `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. Management — `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 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 of the 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. 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. Management — `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 is present" — 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 |

The full list of common API errors — [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)