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

Update field

PATCH /v1/items/:entityTypeId/userfields/:id

Updates the properties of an existing smart process user field. The field type (userTypeId) cannot be changed — to change the type, delete the field and create a new one. Pass only the fields you want to change.

Parameters

Parameter Type Required Description
Parameter:entityTypeId (path) Typenumber Requiredyes DescriptionSmart process type identifier. Source: GET /v1/smart-processes — the entityTypeId field on each element of the data array
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric field identifier (from the response of GET /v1/items/:entityTypeId/userfields or POST /v1/items/:entityTypeId/userfields)

Request fields (body)

The fields are the same as on creation. Pass only the ones you want to change.

Field Type Description
Fieldlabel Typestring DescriptionDisplay label. Fills each of editFormLabel, listColumnLabel, listFilterLabel unless that label is explicitly provided. A string is converted to { "ru": "value" }. For other languages, provide labels as objects keyed by language code
FieldeditFormLabel Typeobject DescriptionEdit form label by language. Example: { "en": "Project", "de": "Projekt" }
FieldlistColumnLabel Typeobject DescriptionList column header by language. An explicit value takes precedence over label
FieldlistFilterLabel Typeobject DescriptionFilter label by language. An explicit value takes precedence over label
Fieldsort Typestring DescriptionSort order in the Bitrix24 interface
Fieldmultiple Typestring DescriptionAllow multiple values: "Y" or "N"
Fieldmandatory Typestring DescriptionWhether the field is required: "Y" or "N"
FieldshowFilter Typestring DescriptionShow in filter: "N" — no, "I" — exact value, "E" — mask, "S" — range
FieldshowInList Typestring DescriptionShow in the record list: "Y" or "N"
FieldeditInList Typestring DescriptionAllow editing directly from the list: "Y" or "N"
FieldisSearchable Typestring DescriptionIncluded in full-text search: "Y" or "N"
FieldxmlId Typestring DescriptionExternal identifier for integrations
Fieldsettings Typeobject DescriptionType-specific field settings. The structure depends on userTypeId
Fieldenum Typearray DescriptionOptions for an enumeration field. Pass all options that should remain, with their id, plus new ones without id. An element without id is created as new; an element with id that is not passed in the array is deleted

Read-only fields (id, entityId, fieldName, userTypeId) are ignored when passed.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/items/174/userfields/8210" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mandatory": "Y",
    "showFilter": "I"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/items/174/userfields/8210" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mandatory": "Y",
    "showFilter": "I"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/items/174/userfields/8210', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mandatory: 'Y',
    showFilter: 'I',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/items/174/userfields/8210', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mandatory: 'Y',
    showFilter: 'I',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionUpdate result
Fielddata.updated Typeboolean Descriptiontrue on a successful update

Response example

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

Error response example

403 — the key has no userfieldconfig scope:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "The request requires higher privileges than provided by the webhook token"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP400 CodeINVALID_ENTITY_TYPE_ID Description:entityTypeId is not a positive integer
HTTP400 CodeINVALID_PARAMS Description:id is not a positive integer or exceeds 9007199254740991. The value must contain digits only, with no leading zero, sign, fractional part, exponent or spaces. The field is not changed
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key has no userfieldconfig scope — reissue the key with this scope
HTTP403 CodeSCOPE_DENIED DescriptionThe API key has no crm scope
HTTP404 CodeSMART_PROCESS_NOT_FOUND DescriptionA smart process with the given entityTypeId was not found on the portal
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe smart process in the path has no field with the given id: the field was deleted or belongs to another entity. Nothing is changed
HTTP422 CodeBITRIX_ERROR DescriptionThe field was deleted between the check and the update — Bitrix24 responds "You cannot change the user field settings"
HTTP422 CodeBITRIX_ERROR DescriptionInvalid field values or incompatible settings
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

Only fields of the smart process in the path are updated. Field IDs are shared across all entities of the Bitrix24 account, so before updating, the platform checks that the smart process :entityTypeId has a field with this id. A field of another entity or a deleted field returns 404 ENTITY_NOT_FOUND, and nothing is changed.

Updating enumeration options. Options are passed as the enum array (not list). To keep an existing option, pass it with the id field from the response of GET /v1/items/:entityTypeId/userfields/:id — an option without id is created as new, and one omitted from the array is deleted.

See also