[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-userfields\u002Fusers":3,"docs-tabs-userfields\u002Fusers":6},{"content":4,"lastmod":5},"# Employee fields\n\nCreate, 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.\n\nBitrix24 API: `user.userfield.*`\nScope: `user.userfield`\n\n## Operations\n\n- [List employee fields](\u002Fdocs\u002Fuserfields\u002Fusers\u002Flist) — `GET \u002Fv1\u002Fuserfields\u002Fusers`\n- [Get employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fget) — `GET \u002Fv1\u002Fuserfields\u002Fusers\u002F:id`\n- [Create employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fcreate) — `POST \u002Fv1\u002Fuserfields\u002Fusers`\n- [Update employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fupdate) — `PATCH \u002Fv1\u002Fuserfields\u002Fusers\u002F:id`\n- [Delete employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fdelete) — `DELETE \u002Fv1\u002Fuserfields\u002Fusers\u002F:id`\n\nThis entity has no type catalog: the request `GET \u002Fv1\u002Fuserfields\u002Fusers\u002Ftypes` returns `400 UNSUPPORTED_ACTION`. The field type is set explicitly on creation — the allowed `userTypeId` values are listed in the \"Field types\" section below.\n\n## Key scope\n\nAll 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`.\n\n## Field name\n\n`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.\n\nThe field appears under the same name in the employee schema [`GET \u002Fv1\u002Fusers\u002Ffields`](\u002Fdocs\u002Fentities\u002Fusers\u002Ffields) and is accepted in employee requests — [`POST \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Fcreate), [`PATCH \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fupdate). 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)](\u002Fdocs\u002Fentity-api#user-fields-uf).\n\n## Field labels\n\nLabels — `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 \u002Fv1\u002Fusers\u002Ffields`](\u002Fdocs\u002Fentities\u002Fusers\u002Ffields) returns it in the `label` field.\n\nA `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\": { \"en\": \"Badge number\", \"de\": \"Personalnummer\" }`.\n\n## Which properties are applied\n\nBitrix24 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.\n\n| Property | Create | Update |\n|----------|----------|------------|\n| `sort`, `xmlId`, `settings` | applied | applied |\n| labels | accepted — not visible in the section's responses, check via `label` in the employee schema | accepted |\n| `showFilter` | applied | applied |\n| `list` — options of an `enumeration` field | applied | applied |\n| `multiple` | applied | not applied — multiplicity is set once, on creation |\n| `mandatory`, `isSearchable`, `showInList`, `editInList` | not applied | not applied |\n\nAn employee field always reads back with `mandatory: \"N\"`, `isSearchable: \"N\"`, `showInList: \"Y\"`, `editInList: \"Y\"` — whatever values were passed.\n\n## Field types\n\nAllowed `userTypeId` values — each verified by creating a field:\n\n`string`, `integer`, `double`, `boolean`, `date`, `datetime`, `enumeration`, `money`, `url`, `address`, `file`, `employee`, `crm`, `crm_status`, `iblock_section`, `iblock_element`.\n\nA 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](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fget) page.\n\n## Field name mapping\n\nIn 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.\n\n| API (camelCase) | Bitrix24 (UPPER_CASE) |\n|-----------------|------------------------|\n| `id` | `ID` |\n| `entityId` | `ENTITY_ID` |\n| `fieldName` | `FIELD_NAME` |\n| `userTypeId` | `USER_TYPE_ID` |\n| `xmlId` | `XML_ID` |\n| `sort` | `SORT` |\n| `multiple` | `MULTIPLE` |\n| `mandatory` | `MANDATORY` |\n| `showFilter` | `SHOW_FILTER` |\n| `showInList` | `SHOW_IN_LIST` |\n| `editInList` | `EDIT_IN_LIST` |\n| `isSearchable` | `IS_SEARCHABLE` |\n| `label` | `LABEL` |\n| `editFormLabel` | `EDIT_FORM_LABEL` |\n| `listColumnLabel` | `LIST_COLUMN_LABEL` |\n| `listFilterLabel` | `LIST_FILTER_LABEL` |\n| `errorMessage` | `ERROR_MESSAGE` |\n| `helpMessage` | `HELP_MESSAGE` |\n| `settings` | `SETTINGS` |\n| `list` | `LIST` |\n\n### Yes\u002Fno flags\n\nSend the `multiple` and `showFilter` properties as booleans (`true` \u002F `false`) or as the strings `\"Y\"` \u002F `\"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.\n\n## Typical scenario\n\n1. View the already created fields: [`GET \u002Fv1\u002Fuserfields\u002Fusers`](\u002Fdocs\u002Fuserfields\u002Fusers\u002Flist).\n2. Create a field with the required `userTypeId` and `fieldName`: [`POST \u002Fv1\u002Fuserfields\u002Fusers`](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fcreate).\n3. Read its definition — for `enumeration`, including the `list` options: [`GET \u002Fv1\u002Fuserfields\u002Fusers\u002F:id`](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fget).\n4. Make sure the field appeared in the employee schema [`GET \u002Fv1\u002Fusers\u002Ffields`](\u002Fdocs\u002Fentities\u002Fusers\u002Ffields), and write a value to an employee: [`PATCH \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fupdate).\n5. Update ([`PATCH`](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fupdate)) or delete ([`DELETE`](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fdelete)) the field by identifier.\n\n## See also\n\n- [CRM entity fields](\u002Fdocs\u002Fuserfields\u002Fcrm)\n- [Smart process fields](\u002Fdocs\u002Fuserfields\u002Fsmart-processes)\n- [Employees](\u002Fdocs\u002Fentities\u002Fusers)\n- [Employee fields](\u002Fdocs\u002Fentities\u002Fusers\u002Ffields)\n- [Scopes](\u002Fdocs\u002Fscopes)\n- [User fields](\u002Fdocs\u002Fuserfields)\n\n[Module field types](\u002Fdocs\u002Fuserfields\u002Ftypes) serve modules such as crm and do not provide types for employee fields.\n","2026-10-23",{},1794739617688]