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 and card responses, and the declared types match the returned values: number fields return numbers, and boolean fields return true or false.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

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

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.

status values — the fields.status.enum field:

priority values — the fields.priority.enum field:

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 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:

{
  "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, while action, checklist, checkListTree and checkListCanAdd arrive only in the card. 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.

{
  "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:

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

Errors

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

See also

• Create task
• Update task
• List tasks
• Search tasks
• Aggregate tasks
• Entity API

Field schema IDs and enumeration variants: Task fields, GET /v1/userfields/tasks.