For AI agents: markdown of this page — /docs-content-en/userfields/tasks/list.md documentation index — /llms.txt

List fields

GET /v1/userfields/tasks

Returns the user and system task fields of the Bitrix24 account. Supports filtering by field type and field name, and choosing the label language.

Parameters

Parameter Type Required Description
ParameteruserTypeId (query) Typestring Requiredno DescriptionFilter by field type. Values come from the type catalog. An unknown type returns an empty data. Example: ?userTypeId=enumeration
ParameterfieldName (query) Typestring Requiredno DescriptionFilter by the full field name with the UF_ prefix. A name without the prefix matches nothing and returns an empty data. Example: ?fieldName=UF_CRM_TASK
Parameterlang (query) Typestring Requiredno DescriptionLanguage code for field labels, for example en. Defaults to the key owner's language

Results are sorted by the sort field in ascending order. There is no pagination: all fields come in a single response, and meta.total equals the length of data.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/userfields/tasks?userTypeId=enumeration" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/userfields/tasks?userTypeId=enumeration" \
  -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/userfields/tasks?userTypeId=enumeration',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data, meta } = await res.json()
console.log(`Enumeration fields: ${meta.total}`)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/userfields/tasks?userTypeId=enumeration',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data, meta } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of task fields. Element properties are the same as in the field card: id, fieldName, userTypeId, flags, settings, labels, system, and for an enumeration field, items with its options. The labels editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage come as a string in the lang language, not as an object keyed by language
Fieldmeta.total Typenumber DescriptionNumber of fields in the response

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 6007969,
      "entityId": "TASKS_TASK",
      "fieldName": "UF_REVIEW_STAGE",
      "userTypeId": "enumeration",
      "xmlId": null,
      "sort": "100",
      "multiple": "N",
      "mandatory": "N",
      "showFilter": "N",
      "showInList": "Y",
      "editInList": "Y",
      "isSearchable": "N",
      "settings": {
        "DISPLAY": "LIST",
        "LIST_HEIGHT": 1,
        "CAPTION_NO_VALUE": "",
        "SHOW_NO_VALUE": "Y"
      },
      "editFormLabel": "Review stage",
      "listColumnLabel": "Review stage",
      "listFilterLabel": "Review stage",
      "errorMessage": "UF_REVIEW_STAGE",
      "helpMessage": "UF_REVIEW_STAGE",
      "system": false,
      "items": [
        {
          "id": 4057,
          "value": "Accepted",
          "sort": "500",
          "def": "N",
          "xmlId": "accepted"
        },
        {
          "id": 4053,
          "value": "New",
          "sort": "500",
          "def": "Y",
          "xmlId": "new"
        },
        {
          "id": 4055,
          "value": "In review",
          "sort": "500",
          "def": "N",
          "xmlId": "review"
        }
      ]
    },
    {
      "id": 6007971,
      "entityId": "TASKS_TASK",
      "fieldName": "UF_REQUEST_CHANNEL",
      "userTypeId": "enumeration",
      "xmlId": null,
      "sort": "200",
      "multiple": "N",
      "mandatory": "N",
      "showFilter": "N",
      "showInList": "Y",
      "editInList": "Y",
      "isSearchable": "N",
      "settings": {
        "DISPLAY": "LIST",
        "LIST_HEIGHT": 1,
        "CAPTION_NO_VALUE": "",
        "SHOW_NO_VALUE": "Y"
      },
      "editFormLabel": "Request channel",
      "listColumnLabel": "Request channel",
      "listFilterLabel": "Request channel",
      "errorMessage": "UF_REQUEST_CHANNEL",
      "helpMessage": "UF_REQUEST_CHANNEL",
      "system": false,
      "items": [
        {
          "id": 4059,
          "value": "Email",
          "sort": "10",
          "def": "N",
          "xmlId": "7245a0bf104971496996a5fbf538e9da"
        },
        {
          "id": 4061,
          "value": "Phone",
          "sort": "20",
          "def": "N",
          "xmlId": "fcdd8897d6d423b186180bba744d3d54"
        }
      ]
    }
  ],
  "meta": {
    "total": 2
  }
}

Error response example

401 — the X-Api-Key header was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
HTTP403 CodeTASK_CUSTOM_FIELDS_UNAVAILABLE DescriptionThe portal plan does not include task user fields
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the task scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens. For an application key, the Authorization: Bearer USER_SESSION_TOKEN header was not passed
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

System fields are returned along with user fields. The list includes UF_CRM_TASK, UF_TASK_WEBDAV_FILES, and UF_MAIL_MESSAGE with system: true. They cannot be changed or deleted — write requests return 403 SYSTEM_FIELD_PROTECTED.

Option order is set by sort. Options created without sort default to 500 and do not come back in the order they were passed at creation — as with the UF_REVIEW_STAGE field in the example above.

See also