For AI agents: markdown of this page — /docs-content-en/userfields/users/update.md documentation index — /llms.txt

Update employee field

PATCH /v1/userfields/users/:id

Updates the properties of an existing employee user field. The field type userTypeId and the multiple flag cannot be changed — to change the type, delete the field and create a new one. Pass only the properties you want to change.

Parameters

Parameter Type Required Description
:id (path) number yes Numeric identifier of the field (from the response of GET /v1/userfields/users or POST /v1/userfields/users)

Request fields (body)

Field Type Description
label string Field label. Substituted into editFormLabel, listColumnLabel and listFilterLabel when they are not passed explicitly. Responses in this section do not return labels — Field labels
editFormLabel object Label in the edit form, keyed by Bitrix24 account language. Example: { "ru": "Badge number", "en": "Badge number" }. This is the label returned in the employee schema as label
sort string Sort order in the Bitrix24 interface
showFilter boolean Show in the filter: true or "Y" — yes, false or "N" — no. The "E" you read can be sent back as is — the platform treats it as "on"
xmlId string External identifier for integrations
settings object Type-specific field settings. The structure depends on userTypeId — Get field
list array Options of an enumeration field. An item without ID is added as a new option; an item with ID and a new VALUE renames an existing one; an item { "ID": 3967, "DEL": "Y" } deletes the option. Options not mentioned in the array remain unchanged
mandatory, isSearchable, showInList, editInList, multiple boolean Accepted, but not applied to an employee field on update — Which properties are applied

Read-only properties — id, entityId, fieldName, userTypeId — are ignored when passed: the field identifier is taken only from the path.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/userfields/users/6007923" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": "300",
    "list": [
      { "VALUE": "24-hour", "SORT": 40 }
    ]
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/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": "24-hour", "SORT": 40 }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users/6007923', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sort: '300',
    list: [
      { VALUE: '24-hour', SORT: 40 },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Updated:', data.updated)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: '24-hour', SORT: 40 },
    ],
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data.updated boolean true on successful update

Response example

JSON 
{
  "success": true,
  "data": {
    "updated": true
  }
}

Error response example

404 — there is no field with this id:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "User field 999999999 not found"
  }
}

Errors

HTTP Code Description
400 INVALID_ID :id is not a positive integer — the request is rejected before the portal is contacted
400 INVALID_REQUEST The request body is not an object
404 ENTITY_NOT_FOUND There is no field with this id. Existence is checked before the update, so no change reaches the portal
422 BITRIX_ERROR The key owner is not a Bitrix24 account administrator — Bitrix24 responds with the message Access denied.
422 BITRIX_ERROR Other Bitrix24 rejections — including a field removed between the existence check and the update itself. The text is returned verbatim in error.message
403 SCOPE_DENIED The API key does not have the user.userfield scope
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY The X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

The response does not confirm that properties were applied. updated: true means that Bitrix24 accepted the request, not that every passed property changed: the properties the Which properties are applied table marks as not applied keep their previous values even when the response is successful. After an update, re-read the field — GET /v1/userfields/users/:id.

enumeration options are edited individually. The list array does not replace the option set as a whole: options not mentioned in it are kept. The IDs of existing options are taken from the response of GET /v1/userfields/users/:id. In the example above a fourth option — "24-hour" — is added to the field's three options.

See also