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

Update a list field value

PATCH /v1/userfields/:entity/enum-values/:id

Updates one option of a CRM custom list field. Send fields at the JSON root without a fields wrapper.

Availability. An administrator must enable this feature. It requires a CRM update after version 26.2200.0. The release version for that update has not yet been announced. If unavailable, the API returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

Alternative path for Smart Process Automation and invoices: PATCH /v1/items/:entityTypeId/userfields/enum-values/:id.

Parameters

Parameter Type Required Description
Parameterentity (path) Typestring Requiredyes Descriptiondeals, leads, contacts, companies, quotes, invoices
Parameterid (path) Typenumber Requiredyes DescriptionValue ID. Source: List field values
ParameterentityTypeId (path) Typenumber Requiredyes for the alternative path DescriptionFor the alternative path: a Smart Process Automation type ID, or 31 for invoices

Request body

Field Type Required Description
Fieldvalue Typestring Requiredno DescriptionOption label
FieldisDefault Typeboolean Requiredno DescriptionWhether this option is selected by default
Fieldsort Typeinteger Requiredno DescriptionSort order
FieldxmlId Typestring | null Requiredno DescriptionExternal identifier. null preserves the current value

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/userfields/deals/enum-values/4119" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "VIBE-PROBE changed"}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/userfields/deals/enum-values/4119" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "VIBE-PROBE changed"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/deals/enum-values/4119', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"value": "VIBE-PROBE changed"}),
})

const result = await res.json()
console.log(result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/deals/enum-values/4119', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"value": "VIBE-PROBE changed"}),
})

const result = await res.json()
console.log(result)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue
Fielddata Typeobject DescriptionThe updated option
Fielddata.id Typenumber DescriptionOption ID from List field values
Fielddata.fieldId Typenumber DescriptionCRM custom field ID or Smart Process Automation custom field ID
Fielddata.value Typestring DescriptionOption label
Fielddata.isDefault Typeboolean DescriptionWhether selected by default
Fielddata.sort Typeinteger DescriptionSort order
Fielddata.xmlId Typestring | null DescriptionExternal identifier

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 4119,
    "fieldId": 6008145,
    "value": "VIBE-PROBE changed",
    "isDefault": false,
    "sort": 500,
    "xmlId": "VIBE-PROBE-X"
  }
}

Error response example

400: attempting to pass id in the request body:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Use enum fields fieldId (add only), value, isDefault, sort and xmlId with their documented types"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionA parameter has an invalid type or shape
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionAn unknown or repeated query parameter
HTTP401 CodeMISSING_API_KEY DescriptionThe API key is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 credentials
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied permission for this operation
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key allows reads only
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe list value was not found
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe feature is disabled or unavailable on this portal. error.release identifies the required update
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the request. See error.message
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an invalid response

For shared API errors, see Errors.

See also