# 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 fields](/docs/userfields/users/list) — `GET /v1/userfields/users`
- [Get field](/docs/userfields/users/get) — `GET /v1/userfields/users/:id`
- [Create field](/docs/userfields/users/create) — `POST /v1/userfields/users`
- [Update field](/docs/userfields/users/update) — `PATCH /v1/userfields/users/:id`
- [Delete field](/docs/userfields/users/delete) — `DELETE /v1/userfields/users/:id`

This entity has no type catalog: the request `GET /v1/userfields/users/types` answers `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` answers `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`](/docs/entities/users/fields) and is accepted in employee requests — [`POST /v1/users`](/docs/entities/users/create), [`PATCH /v1/users/:id`](/docs/entities/users/update). Unlike CRM fields, an employee field's definition name and working name are the same. The value format by type — [User fields (UF)](/docs/entity-api#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`](/docs/entities/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 answers with 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 |
|----------|----------|------------|
| `sort`, `xmlId`, `settings` | applied | applied |
| labels | accepted — not visible in the section's responses, check via `label` in the employee schema | accepted |
| `showFilter` | applied | applied |
| `list` — options of an `enumeration` field | applied | applied |
| `multiple` | applied | not applied — multiplicity is set once, on creation |
| `mandatory`, `isSearchable`, `showInList`, `editInList` | not applied | not 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 answers `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 field](/docs/userfields/users/get) 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) |
|-----------------|------------------------|
| `id` | `ID` |
| `entityId` | `ENTITY_ID` |
| `fieldName` | `FIELD_NAME` |
| `userTypeId` | `USER_TYPE_ID` |
| `xmlId` | `XML_ID` |
| `sort` | `SORT` |
| `multiple` | `MULTIPLE` |
| `mandatory` | `MANDATORY` |
| `showFilter` | `SHOW_FILTER` |
| `showInList` | `SHOW_IN_LIST` |
| `editInList` | `EDIT_IN_LIST` |
| `isSearchable` | `IS_SEARCHABLE` |
| `label` | `LABEL` |
| `editFormLabel` | `EDIT_FORM_LABEL` |
| `listColumnLabel` | `LIST_COLUMN_LABEL` |
| `listFilterLabel` | `LIST_FILTER_LABEL` |
| `errorMessage` | `ERROR_MESSAGE` |
| `helpMessage` | `HELP_MESSAGE` |
| `settings` | `SETTINGS` |
| `list` | `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

1. View the already created fields: [`GET /v1/userfields/users`](/docs/userfields/users/list).
2. Create a field with the required `userTypeId` and `fieldName`: [`POST /v1/userfields/users`](/docs/userfields/users/create).
3. Read its description — for `enumeration`, with the `list` options: [`GET /v1/userfields/users/:id`](/docs/userfields/users/get).
4. Make sure the field appeared in the employee schema [`GET /v1/users/fields`](/docs/entities/users/fields), and write a value to an employee: [`PATCH /v1/users/:id`](/docs/entities/users/update).
5. Update ([`PATCH`](/docs/userfields/users/update)) or delete ([`DELETE`](/docs/userfields/users/delete)) the field by identifier.

## See also

- [CRM entity fields](/docs/userfields/crm)
- [Smart process fields](/docs/userfields/smart-processes)
- [Employees](/docs/entities/users)
- [Employee fields](/docs/entities/users/fields)
- [Scopes](/docs/scopes)
- [User fields](/docs/userfields)