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

Update field

PATCH /v1/userfields/:entity/:id

Updates the properties of an existing user field of a CRM entity. 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
:entity (path) string yes Entity: deals, leads, contacts, companies, quotes, requisites
:id (path) number yes Numeric identifier of the field (from the response of GET /v1/userfields/:entity or POST /v1/userfields/:entity)

Request fields (body)

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

Field Type Description
label string Display label of the field. The value is automatically propagated to all Bitrix24 account languages
editFormLabel object Label in the edit form per 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 fill: "Y" or "N"
showFilter string Show in the 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
list array Options for an enumeration field. Pass all the options that should remain, with their ID, plus new ones without ID. An item without ID is created anew; an item with an ID 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/userfields/deals/7115" \
  -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/userfields/deals/7115" \
  -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/userfields/deals/7115', {
  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/userfields/deals/7115', {
  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 successful update

Response example

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

Error response example

404 — the field does not exist:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "The entity with ID '9999999' is not found."
  }
}

Errors

HTTP Code Description
400 INVALID_REQUEST The request body is not an object
400 UNKNOWN_ENTITY :entity is not in the list of supported entities
404 ENTITY_NOT_FOUND There is no field with this id
422 BITRIX_ERROR Bitrix24 errors: invalid field values, incompatible settings
403 SCOPE_DENIED The API key does not have the crm 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

Updating enumeration options. When the list field is passed for the enumeration type, you must include all options that should remain in the field. Existing options are passed with their ID from the response of GET /v1/userfields/:entity/:id — otherwise they will be deleted. New options are passed without ID.

See also