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 employee user field by its numeric identifier.

Parameters

Parameter Type Required Description
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionField object
Fielddata.id Typenumber DescriptionNumeric identifier of the field
Fielddata.entityId Typestring DescriptionInternal entity identifier — always USER
Fielddata.fieldName Typestring DescriptionSystem field name in the UF_USR_* format. The field appears under the same name in the employee schema GET /v1/users/fields
Fielddata.userTypeId Typestring DescriptionField type. Allowed values — Field types
Fielddata.xmlId Typestring|null DescriptionExternal identifier for integrations. Set manually on creation or update
Fielddata.sort Typestring DescriptionSort order in the Bitrix24 interface
Fielddata.multiple Typestring DescriptionMultiple field: "Y" or "N"
Fielddata.mandatory Typestring DescriptionRequired field. Always "N" for employee fields — Which properties are applied
Fielddata.showFilter Typestring DescriptionShow in the filter. "N" — off; the enabled state comes back as "E" — Bitrix24's storage form. An "N" or an "E" you read can be sent back as is
Fielddata.showInList Typestring DescriptionShow in the employee list. Always "Y" for employee fields
Fielddata.editInList Typestring DescriptionAllow editing from the list. Always "Y" for employee fields
Fielddata.isSearchable Typestring DescriptionWhether it participates in full-text search. Always "N" for employee fields
Fielddata.settings Typeobject DescriptionField settings specific to userTypeId. For enumeration — DISPLAY, LIST_HEIGHT, CAPTION_NO_VALUE, SHOW_NO_VALUE. Key sets for other types — in "Known specifics"
Fielddata.list Typearray DescriptionOptions 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
HTTP400 CodeINVALID_ID Description:id is not a positive integer — the request is rejected before the portal is contacted
HTTP404 CodeNOT_FOUND DescriptionNo field with this id
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the user.userfield scope
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

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