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

List employee fields

GET /v1/userfields/users

Returns the list of employee user fields. Supports filtering by field type and by name.

Parameters

Parameter Type Required Description
ParameteruserTypeId (query) Typestring Requiredno DescriptionFilter by field type. Allowed values — Field types. Example: ?userTypeId=enumeration
ParameterfieldName (query) Typestring Requiredno DescriptionFilter by the full field name with the UF_USR_ prefix. A name without the prefix matches nothing — the response comes back with an empty data. Example: ?fieldName=UF_USR_BADGE_NO

The result is ordered by the sort field ascending. A sort parameter is not accepted.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/userfields/users?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 employee fields. An item's property set matches the field card: id, entityId, fieldName, userTypeId, xmlId, sort, flags, settings, and for an enumeration field — list with the options
Fieldmeta.total Typenumber DescriptionTotal number of fields matching the filter

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 4925,
      "entityId": "USER",
      "fieldName": "UF_USR_1685540881093",
      "userTypeId": "enumeration",
      "xmlId": null,
      "sort": "100",
      "multiple": "N",
      "mandatory": "N",
      "showFilter": "E",
      "showInList": "Y",
      "editInList": "Y",
      "isSearchable": "N",
      "settings": {
        "DISPLAY": "UI",
        "LIST_HEIGHT": 1,
        "CAPTION_NO_VALUE": "",
        "SHOW_NO_VALUE": "Y"
      },
      "list": [
        {
          "ID": "1669",
          "SORT": "0",
          "VALUE": "First",
          "DEF": "N",
          "XML_ID": "be318f13536d5268018638e2520a4684"
        },
        {
          "ID": "1671",
          "SORT": "100",
          "VALUE": "Second",
          "DEF": "N",
          "XML_ID": "8b24b8eca61a98bf8e240a26f943d839"
        },
        {
          "ID": "1673",
          "SORT": "200",
          "VALUE": "Third",
          "DEF": "N",
          "XML_ID": "b49345c332ddd62d584f8d0fb4aebcec"
        }
      ]
    },
    {
      "id": 6007923,
      "entityId": "USER",
      "fieldName": "UF_USR_SHIFT",
      "userTypeId": "enumeration",
      "xmlId": null,
      "sort": "200",
      "multiple": "N",
      "mandatory": "N",
      "showFilter": "E",
      "showInList": "Y",
      "editInList": "Y",
      "isSearchable": "N",
      "settings": {
        "DISPLAY": "LIST",
        "LIST_HEIGHT": 1,
        "CAPTION_NO_VALUE": "",
        "SHOW_NO_VALUE": "Y"
      },
      "list": [
        {
          "ID": "3967",
          "SORT": "10",
          "VALUE": "Morning",
          "DEF": "N",
          "XML_ID": "46e4bae66329c39fafcbaef4262d490b"
        },
        {
          "ID": "3969",
          "SORT": "20",
          "VALUE": "Evening",
          "DEF": "N",
          "XML_ID": "3351c3d103ce376358db5c39019af5c4"
        },
        {
          "ID": "3971",
          "SORT": "30",
          "VALUE": "Night",
          "DEF": "N",
          "XML_ID": "160aa32209dc24bfb699010bf2df174a"
        }
      ]
    }
  ],
  "meta": {
    "total": 2
  }
}

Error response example

403 — the key lacks the user.userfield scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'user.userfield' scope"
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the user.userfield scope — the user scope is not enough
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Labels are absent from the list. A list item does not contain editFormLabel, listColumnLabel, listFilterLabel, errorMessage or helpMessage — and the field card does not return them either. Read the field label from the label field of the employee schema GET /v1/users/fields.

No pagination. The endpoint returns all employee fields without splitting them into pages. meta.total reflects the total number of fields in the response.

An enabled filter reads as "E". In the example above, showFilter comes back as "E" rather than "Y" — this is how Bitrix24 stores the value. A disabled filter arrives as "N".

See also