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
Parameter:entity (path) Typestring Requiredyes DescriptionEntity: deals, leads, contacts, companies, quotes, requisites
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric 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
Fieldlabel Typestring DescriptionDisplay label of the field. The value is automatically propagated to all Bitrix24 account languages
FieldeditFormLabel Typeobject DescriptionLabel in the edit form per language. Example: { "en": "Project", "de": "Projekt" }
Fieldsort Typenumber | string DescriptionSort order in the Bitrix24 interface. Accepted as a number or a string, read back as a string
Fieldmultiple Typeboolean DescriptionAllow multiple values: true / false or "Y" / "N"
Fieldmandatory Typeboolean DescriptionRequired when filling in a record: true / false or "Y" / "N"
FieldshowFilter Typeboolean DescriptionShow in the filter: true or "Y" — yes, false or "N" — no. On write, the letters "I" and "S" switch the filter off. An enabled filter reads back as "E"; sending that "E" back is safe — the platform reads it as "on"
FieldshowInList Typeboolean DescriptionShow in the record list: true / false or "Y" / "N"
FieldeditInList Typeboolean DescriptionAllow editing directly from the list: true / false or "Y" / "N"
FieldisSearchable Typeboolean DescriptionIncluded in the full-text search of the Bitrix24 account: true / false or "Y" / "N"
FieldxmlId Typestring DescriptionExternal identifier for integrations
Fieldsettings Typeobject DescriptionField settings specific to the type. The structure depends on userTypeId. For the crm type, these are the LEAD, CONTACT, COMPANY, and DEAL keys set to "Y" or "N", as when creating a field
Fieldlist Typearray DescriptionOptions for an enumeration field. Pass all the options that should remain, with their ID, plus new ones without an ID. An item without an ID is created as a new option; an existing item whose ID 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/userfields/deals/7115" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mandatory": "Y",
    "showFilter": true
  }'

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": true
  }'

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: true,
  }),
})

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: true,
  }),
})

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 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
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP400 CodeUNKNOWN_ENTITY Description:entity is not in the list of supported entities
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no field with this id
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 errors: invalid field values, incompatible settings
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
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

Updating enumeration options. When you pass list for an enumeration field, 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 an ID.

settings keys of a crm field are updated individually. The keys you pass change their values, and the keys you omit keep theirs. For example, for a crm field that links to deals and contacts, the body { "settings": { "COMPANY": "Y" } } adds companies, while deals and contacts remain. To remove a link, pass the key set to "N". The DYNAMIC_<entityTypeId> key for a smart process link is not saved, even though the response comes back with "updated": true.

See also