Для AI-агентов: markdown этой страницы — /docs-content/userfields/users/update.md индекс документации — /llms.txt
Обновить поле сотрудника
PATCH /v1/userfields/users/:id
Обновляет свойства существующего пользовательского поля сотрудника. Тип поля userTypeId и множественность multiple изменить нельзя — для смены типа удалите поле и создайте новое. Передавайте только те свойства, которые хотите изменить.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Параметр:id (path) |
Типnumber | Обяз.да | ОписаниеЧисловой идентификатор поля (из ответа GET /v1/userfields/users или POST /v1/userfields/users) |
Поля запроса (body)
| Поле | Тип | Описание |
|---|---|---|
Полеlabel |
Типstring | ОписаниеПодпись поля. Подставляется в editFormLabel, listColumnLabel и listFilterLabel, если они не переданы явно. В ответах раздела подписи не возвращаются — Подписи поля |
ПолеeditFormLabel |
Типobject | ОписаниеПодпись в форме редактирования по языкам портала. Пример: { "ru": "Табельный номер", "en": "Badge number" }. Именно эта подпись приходит в схеме сотрудника как label |
Полеsort |
Типstring | ОписаниеПорядок сортировки в интерфейсе Битрикс24 |
ПолеshowFilter |
Типboolean | ОписаниеПоказывать в фильтре: true или "Y" — да, false или "N" — нет. Прочитанное "E" можно отправить обратно как есть — платформа понимает его как «включён» |
ПолеxmlId |
Типstring | ОписаниеВнешний идентификатор для интеграций |
Полеsettings |
Типobject | ОписаниеНастройки поля, специфичные для типа. Структура зависит от userTypeId — Получить поле сотрудника |
Полеlist |
Типarray | ОписаниеВарианты поля типа enumeration. Элемент без ID добавляется как новый вариант, элемент с ID и новым VALUE переименовывает существующий, элемент { "ID": 3967, "DEL": "Y" } удаляет вариант. Варианты, не упомянутые в массиве, остаются без изменений |
Полеmandatory, isSearchable, showInList, editInList, multiple |
Типboolean | ОписаниеПринимаются, но к полю сотрудника при обновлении не применяются — Какие свойства применяются |
Свойства только для чтения — id, entityId, fieldName, userTypeId — при передаче игнорируются: идентификатор поля берётся только из пути.
Примеры
curl — личный ключ
curl -X PATCH "https://vibecode.bitrix24.tech/v1/userfields/users/6007923" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sort": "300",
"list": [
{ "VALUE": "Сутки", "SORT": 40 }
]
}'
curl — OAuth-приложение
curl -X PATCH "https://vibecode.bitrix24.tech/v1/userfields/users/6007923" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sort": "300",
"list": [
{ "VALUE": "Сутки", "SORT": 40 }
]
}'
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/userfields/users/6007923', {
method: 'PATCH',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
sort: '300',
list: [
{ VALUE: 'Сутки', SORT: 40 },
],
}),
})
const { success, data } = await res.json()
console.log('Обновлено:', data.updated)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/userfields/users/6007923', {
method: 'PATCH',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
sort: '300',
list: [
{ VALUE: 'Сутки', SORT: 40 },
],
}),
})
const { success, data } = await res.json()
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типobject | ОписаниеРезультат обновления |
Полеdata.updated |
Типboolean | Описаниеtrue при успешном обновлении |
Пример ответа
{
"success": true,
"data": {
"updated": true
}
}
Пример ответа при ошибке
404 — поля с таким id нет:
{
"success": false,
"error": {
"code": "ENTITY_NOT_FOUND",
"message": "User field 999999999 not found"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_ID |
Описание:id не является положительным целым числом — запрос отклонён до обращения к порталу |
| HTTP400 | КодINVALID_REQUEST |
ОписаниеТело запроса не является объектом |
| HTTP404 | КодENTITY_NOT_FOUND |
ОписаниеПоля с таким id нет. Существование проверяется до правки, поэтому изменение на портал не уходит |
| HTTP422 | КодBITRIX_ERROR |
ОписаниеВладелец ключа не является администратором портала — Битрикс24 отвечает сообщением Access denied. |
| HTTP422 | КодBITRIX_ERROR |
ОписаниеДругие отказы Битрикс24 — в том числе поле удалили между проверкой существования и самой правкой. Текст приходит в error.message дословно |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеAPI-ключ не имеет скоупа user.userfield |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеAPI-ключ не имеет настроенных токенов |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеОтсутствует заголовок X-Api-Key |
Полный список общих ошибок API — Ошибки.
Известные особенности
Ответ не подтверждает применение свойств. updated: true означает, что Битрикс24 принял запрос, а не то, что каждое переданное свойство изменилось: свойства, помеченные в таблице Какие свойства применяются как не применяемые, остаются прежними при успешном ответе. После обновления перечитайте поле — GET /v1/userfields/users/:id.
Варианты enumeration правятся адресно. Массив list не заменяет набор вариантов целиком: не упомянутые в нём варианты сохраняются. Идентификаторы ID существующих вариантов берутся из ответа GET /v1/userfields/users/:id. В примере выше к трём вариантам поля добавляется четвёртый — «Сутки».