Employee fields

Create, read, update, and delete user fields of an employee — the users entity. A field is stored under a name with the UF_USR_ prefix and arrives under the same name in the employee card.

Bitrix24 API: user.userfield.* Scope: user.userfield

Operations

List employee fields — GET /v1/userfields/users
Get employee field — GET /v1/userfields/users/:id
Create employee field — POST /v1/userfields/users
Update employee field — PATCH /v1/userfields/users/:id
Delete employee field — DELETE /v1/userfields/users/:id

This entity has no type catalog: the request GET /v1/userfields/users/types returns 400 UNSUPPORTED_ACTION. The field type is set explicitly on creation — the allowed userTypeId values are listed in the "Field types" section below.

Key scope

All five operations require the user.userfield scope on the API key — a separate permission that is ticked when the key is issued. The user scope is not enough for these operations: a request without user.userfield returns 403 SCOPE_DENIED.

Field name

fieldName is required on creation. The name is stored in upper case with the UF_USR_ prefix: UF_USR_BADGE_NO is saved as is, while badge_no becomes UF_USR_BADGE_NO — Bitrix24 upper-cases the name and adds the prefix.

The field appears under the same name in the employee schema GET /v1/users/fields and is accepted in employee requests — POST /v1/users, PATCH /v1/users/:id. Unlike CRM fields, an employee field's definition name and working name are the same. For the value format by type, see User fields (UF).

Field labels

Labels — label, editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage — are accepted on creation and update but are not returned in the responses of this section: neither the list nor the field card contains them. To check a label, use the employee schema — GET /v1/users/fields returns it in the label field.

A label string without explicit editFormLabel, listColumnLabel and listFilterLabel is used for all three labels. To set different labels per Bitrix24 account language, pass an object: "editFormLabel": { "ru": "Badge number", "en": "Badge number" }.

Which properties are applied

Bitrix24 accepts the whole request body and returns success, but does not apply some employee field properties — the field reads back with its previous values. Verified with live calls on create and update.

Property	Create	Update
Property`sort`, `xmlId`, `settings`	Createapplied	Updateapplied
Propertylabels	Createaccepted — not visible in the section's responses, check via `label` in the employee schema	Updateaccepted
Property`showFilter`	Createapplied	Updateapplied
Property`list` — options of an `enumeration` field	Createapplied	Updateapplied
Property`multiple`	Createapplied	Updatenot applied — multiplicity is set once, on creation
Property`mandatory`, `isSearchable`, `showInList`, `editInList`	Createnot applied	Updatenot applied

An employee field always reads back with mandatory: "N", isSearchable: "N", showInList: "Y", editInList: "Y" — whatever values were passed.

Field types

Allowed userTypeId values — each verified by creating a field:

string, integer, double, boolean, date, datetime, enumeration, money, url, address, file, employee, crm, crm_status, iblock_section, iblock_element.

A value outside this list returns 422 BITRIX_ERROR. The structure of the settings object depends on the type — the key sets for the main types are listed on the Get employee field page.

Field name mapping

In the request body and in the response, field properties use camelCase names, while Bitrix24 stores them in UPPER_CASE. The table helps you read the nested structures — settings and the items of the list array — that Bitrix24 returns as-is.

API (camelCase)	Bitrix24 (UPPER_CASE)
API (camelCase)`id`	Bitrix24 (UPPER_CASE)`ID`
API (camelCase)`entityId`	Bitrix24 (UPPER_CASE)`ENTITY_ID`
API (camelCase)`fieldName`	Bitrix24 (UPPER_CASE)`FIELD_NAME`
API (camelCase)`userTypeId`	Bitrix24 (UPPER_CASE)`USER_TYPE_ID`
API (camelCase)`xmlId`	Bitrix24 (UPPER_CASE)`XML_ID`
API (camelCase)`sort`	Bitrix24 (UPPER_CASE)`SORT`
API (camelCase)`multiple`	Bitrix24 (UPPER_CASE)`MULTIPLE`
API (camelCase)`mandatory`	Bitrix24 (UPPER_CASE)`MANDATORY`
API (camelCase)`showFilter`	Bitrix24 (UPPER_CASE)`SHOW_FILTER`
API (camelCase)`showInList`	Bitrix24 (UPPER_CASE)`SHOW_IN_LIST`
API (camelCase)`editInList`	Bitrix24 (UPPER_CASE)`EDIT_IN_LIST`
API (camelCase)`isSearchable`	Bitrix24 (UPPER_CASE)`IS_SEARCHABLE`
API (camelCase)`label`	Bitrix24 (UPPER_CASE)`LABEL`
API (camelCase)`editFormLabel`	Bitrix24 (UPPER_CASE)`EDIT_FORM_LABEL`
API (camelCase)`listColumnLabel`	Bitrix24 (UPPER_CASE)`LIST_COLUMN_LABEL`
API (camelCase)`listFilterLabel`	Bitrix24 (UPPER_CASE)`LIST_FILTER_LABEL`
API (camelCase)`errorMessage`	Bitrix24 (UPPER_CASE)`ERROR_MESSAGE`
API (camelCase)`helpMessage`	Bitrix24 (UPPER_CASE)`HELP_MESSAGE`
API (camelCase)`settings`	Bitrix24 (UPPER_CASE)`SETTINGS`
API (camelCase)`list`	Bitrix24 (UPPER_CASE)`LIST`

Yes/no flags

Send the multiple and showFilter properties as booleans (true / false) or as the strings "Y" / "N" — the platform accepts both forms. In the response, multiple reads as "Y" or "N", and an enabled showFilter reads as "E": this is Bitrix24's storage form. The "E" you read can be sent back as is — the platform treats it as "on", so a read-modify-write cycle does not switch the filter off.

Typical scenario

View the already created fields: GET /v1/userfields/users.
Create a field with the required userTypeId and fieldName: POST /v1/userfields/users.
Read its description — for enumeration, with the list options: GET /v1/userfields/users/:id.
Make sure the field appeared in the employee schema GET /v1/users/fields, and write a value to an employee: PATCH /v1/users/:id.
Update (PATCH) or delete (DELETE) the field by identifier.