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
:entityTypeId (path) number yes Smart process type identifier. Source: GET /v1/smart-processes — the entityTypeId field on each element of the data array
:id (path) number yes Numeric 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
label string Field label for display. If explicit editFormLabel / listColumnLabel are not set, the value is copied into both labels — the edit form (editFormLabel) and the list column header (listColumnLabel)
editFormLabel object Edit form label by language. Example: { "en": "Project", "de": "Projekt" }
sort string Sort order in the Bitrix24 interface
multiple string Allow multiple values: "Y" or "N"
mandatory string Required on input: "Y" or "N"
showFilter string Show in filter: "N" — no, "I" — exact value, "E" — mask, "S" — range
showInList string Show in the record list: "Y" or "N"
editInList string Allow editing directly from the list: "Y" or "N"
isSearchable string Participates in full-text search: "Y" or "N"
xmlId string External identifier for integrations
settings object Field settings specific to the type. The structure depends on userTypeId
enum array Options for an enumeration field. Pass all options that should remain, with their id, plus new ones without id. An element without id is created anew; 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
success boolean Always true on success
data.updated boolean true 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
400 INVALID_REQUEST The request body is not an object
400 INVALID_ENTITY_TYPE_ID :entityTypeId is not a positive integer
403 BITRIX_ACCESS_DENIED The key has no userfieldconfig scope — reissue the key with this scope
403 SCOPE_DENIED The API key has no crm scope
404 SMART_PROCESS_NOT_FOUND A smart process with the given entityTypeId was not found on the portal
422 BITRIX_ERROR The field with the given id does not exist — Bitrix24 responds "You cannot change the user field settings"
422 BITRIX_ERROR Invalid field values or incompatible settings
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

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