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

Get employee field

GET /v1/userfields/users/:id

Returns the description of a single user field of an employee by its numeric identifier.

Parameters

Parameter Type Required Description
:id (path) number yes Numeric identifier of the field (from the response of GET /v1/userfields/users or POST /v1/userfields/users). Leading zeros are ignored — 007 reads as 7

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/userfields/users/6007923" \
  -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/6007923',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(data.fieldName, data.userTypeId)

JavaScript — OAuth application

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

Response fields

Field Type Description
success boolean Always true on success
data object Field object
data.id number Numeric identifier of the field
data.entityId string Internal entity identifier — always USER
data.fieldName string System field name in the UF_USR_* format. The field appears under the same name in the employee schema GET /v1/users/fields
data.userTypeId string Field type. Allowed values — Field types
data.xmlId string|null External identifier for integrations. Set manually on creation or update
data.sort string Sort order in the Bitrix24 interface
data.multiple string Multiple field: "Y" or "N"
data.mandatory string Required field. Always "N" for employee fields — Which properties are applied
data.showFilter string Show in the filter. "N" — off; an enabled filter comes back as "E" — Bitrix24's storage form. An "N" or an "E" you read can be sent back as is
data.showInList string Show in the employee list. Always "Y" for employee fields
data.editInList string Allow editing from the list. Always "Y" for employee fields
data.isSearchable string Whether it participates in full-text search. Always "N" for employee fields
data.settings object Field settings specific to userTypeId. For enumeration — DISPLAY, LIST_HEIGHT, CAPTION_NO_VALUE, SHOW_NO_VALUE. Key sets for other types — in "Known specifics"
data.list array Options of an enumeration field. Absent for other types. Each item contains ID, SORT, VALUE, DEF and XML_ID — all values are strings; Bitrix24 generates XML_ID itself when it is not passed

Field labels — editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage — are absent from the response: only the employee schema GET /v1/users/fields returns them, in the label field.

Response example

JSON 
{
  "success": true,
  "data": {
    "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"
      }
    ]
  }
}

Error response example

404 — the field does not exist:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "User field 999999999 not found"
  }
}

Errors

HTTP Code Description
400 INVALID_ID :id is not a positive integer — the request is rejected before the portal is contacted
404 NOT_FOUND No field with this id
403 SCOPE_DENIED The API key does not have the user.userfield scope
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

The card is assembled from the list. The response is the list item selected by id: the property set is the same as that of a list item; the card carries no additional data. So when you need several fields at once, one list request is cheaper than a card per field.

The settings field. The structure of the settings object depends on the userTypeId value. Key sets taken from live fields:

  • string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE
  • integer — SIZE, MIN_VALUE, MAX_VALUE, DEFAULT_VALUE
  • double — PRECISION, SIZE, MIN_VALUE, MAX_VALUE, DEFAULT_VALUE
  • date — DEFAULT_VALUE as an object { "TYPE": "NONE", "VALUE": "" }
  • datetime — DEFAULT_VALUE as the same object, USE_SECOND, USE_TIMEZONE
  • boolean — DEFAULT_VALUE, DISPLAY, LABEL, LABEL_CHECKBOX
  • enumeration — DISPLAY, LIST_HEIGHT, CAPTION_NO_VALUE, SHOW_NO_VALUE
  • file — SIZE, LIST_WIDTH, LIST_HEIGHT, MAX_SHOW_SIZE, MAX_ALLOWED_SIZE, EXTENSIONS, TARGET_BLANK, DEFAULT_VIEW
  • employee — DEFAULT_VALUE as an empty array
  • crm — binding flags LEAD, CONTACT, COMPANY, DEAL with "Y" / "N" values

The type of the nested DEFAULT_VALUE key also depends on userTypeId: an empty string for string and money, null for integer and double, the number 0 for boolean, an object for date and datetime, an empty array for employee. Rely on the specific userTypeId, not on a single set.

See also