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
userTypeId (query) string no Filter by field type. Allowed values — Field types. Example: ?userTypeId=enumeration
fieldName (query) string no Filter 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
success boolean Always true on success
data array Array 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
meta.total number Total 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
403 SCOPE_DENIED The API key does not have the user.userfield scope — the user scope is not enough
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The 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 and 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