## 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 |
|----------|-----|:-----:|---------|
| `userTypeId` (query) | string | no | Filter by field type. Values come from the [type catalog](/docs/userfields/tasks/types). An unknown type returns an empty `data`. Example: `?userTypeId=enumeration` |
| `fieldName` (query) | string | no | Filter 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` |
| `lang` (query) | string | no | Language 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

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

### curl — OAuth application

```bash
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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of task fields. Element properties are the same as in the [field card](/docs/userfields/tasks/get): `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 |
| `meta.total` | number | Number 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 |
|------|-----|---------|
| 403 | `TASK_CUSTOM_FIELDS_UNAVAILABLE` | The portal plan does not include task user fields |
| 403 | `SCOPE_DENIED` | The API key does not have the `task` scope |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens. For an application key, the `Authorization: Bearer USER_SESSION_TOKEN` header was not passed |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |

Full list of common API errors — [Errors](/docs/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

- [Get field](/docs/userfields/tasks/get)
- [Create field](/docs/userfields/tasks/create)
- [Field types](/docs/userfields/tasks/types)
- [Task fields](/docs/userfields/tasks)
- [Tasks](/docs/entities/tasks)
- [User fields](/docs/userfields)