#Task fields

GET /v1/tasks/fields

Returns the task field schema: types, read-only flags, static value enumerations for status and priority.

#Examples

#curl — personal key

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

#curl — OAuth application

Terminal 
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

Below are the main fields documented in the API. The response also returns their Bitrix24 UPPER_SNAKE_CASE equivalents (TITLE, RESPONSIBLE_ID, CREATED_DATE, etc.) — kept for backward compatibility.

Field Bitrix24 Type RO Description
id ID number yes Task identifier
title TITLE string Task title
description DESCRIPTION string Description (supports BB-code)
responsibleId RESPONSIBLE_ID number Responsible person. List: GET /v1/users
createdBy CREATED_BY number Creator. Set on create only (defaults to the key's user); rejected on PATCH. List: GET /v1/users
status STATUS number Task status. Allowed values in fields.status.enum
priority PRIORITY number Task priority. Allowed values in fields.priority.enum
groupId GROUP_ID number Workgroup. List: GET /v1/workgroups
parentId PARENT_ID number Parent task. List: GET /v1/tasks
deadline DEADLINE datetime Deadline (ISO 8601)
dateStart DATE_START datetime yes Actual date work on the task started. Filterable: ?filter[>=dateStart]=2026-05-01T00:00:00
startDatePlan START_DATE_PLAN datetime Planned start date
endDatePlan END_DATE_PLAN datetime Planned end date
timeEstimate TIME_ESTIMATE number Effort estimate in seconds
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 [] comes (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 B24 TAG)
accomplices ACCOMPLICES array Collaborators. List: GET /v1/users. Filter by a single user: ?filter[accomplices]=25 (translated to B24 ACCOMPLICE)
auditors AUDITORS array Watchers. List: GET /v1/users. Filter by a single user: ?filter[auditors]=25 (translated to B24 AUDITOR)
closedDate CLOSED_DATE datetime yes Closing date (set on transition to status 5 or 6)
createdDate CREATED_DATE datetime yes Creation date
changedDate CHANGED_DATE datetime yes Date of the last change

Decoding status — the fields.status.enum field:

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

Decoding priority — 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). ⚠ 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 portal).

Nullability. Many optional fields come as null when not filled: parentId, dateStart, startDatePlan, endDatePlan, deadline, closedBy, closedDate, mark, sprintId, backlogId, durationFact, durationPlan, timeSpentInLogs, sorting, flowId, xmlId, ufCrmTask, ufMailMessage, and others. For type-safe clients (TS), declare such fields as T | null. The documented empty cases accomplices/auditors/checklist come as []; tags is the exception: without tags it comes as [], with tags — an object (see above).

#Response example

The main fields are shown. The full response additionally contains UPPER_SNAKE equivalents and system service 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, "createOnly": true },
      "status": {
        "type": "number",
        "readonly": false,
        "enum": [
          { "value": 1, "label": "New", "labelRu": "New" },
          { "value": 2, "label": "Pending", "labelRu": "Pending" },
          { "value": 3, "label": "In Progress", "labelRu": "In Progress" },
          { "value": 4, "label": "Awaiting Control", "labelRu": "Awaiting Control" },
          { "value": 5, "label": "Completed", "labelRu": "Completed" },
          { "value": 6, "label": "Deferred", "labelRu": "Deferred" },
          { "value": 7, "label": "Declined", "labelRu": "Declined" }
        ]
      },
      "priority": {
        "type": "number",
        "readonly": false,
        "enum": [
          { "value": 0, "label": "Low", "labelRu": "Low" },
          { "value": 1, "label": "Normal", "labelRu": "Normal" },
          { "value": 2, "label": "High", "labelRu": "High" }
        ]
      },
      "deadline": { "type": "datetime", "readonly": false },
      "createdDate": { "type": "datetime", "readonly": true },
      "changedDate": { "type": "datetime", "readonly": true }
    }
  }
}

#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.

#See also