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

Update field

PATCH /v1/userfields/tasks/:id

Changes the label, required flag, sort order, settings, and list options of a task user field. The name, type, and multiplicity of a field cannot be changed after creation.

Parameters

Parameter Type Required Description
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric identifier of the field from the response of GET /v1/userfields/tasks or POST /v1/userfields/tasks

Request fields (body)

Pass at least one property. Properties are passed flat at the JSON root — without a fields wrapper.

Field Type Required Description
Fieldlabel Typestring | object Requiredno DescriptionField label. A string is written to editFormLabel, listColumnLabel, and listFilterLabel in all languages. An object sets labels per language — { "ru": "Approval stage", "en": "Approval stage" }; labels in the other languages become empty
Fieldmandatory Typeboolean Requiredno DescriptionRequired field
Fieldsort Typeinteger Requiredno DescriptionField order — a non-negative integer
Fieldsettings Typeobject Requiredno DescriptionField settings; the set of keys depends on the type — Get field
Fielditems Typearray Requiredno DescriptionChanges to the options of an enumeration field
Fielditems[].id Typenumber Requiredno DescriptionIdentifier of an existing option from GET /v1/userfields/tasks/:id. An element without id adds a new option
Fielditems[].value Typestring Requiredyes DescriptionOption name — a non-empty string. Can be omitted only in an element with del: true
Fielditems[].del Typeboolean Requiredno Descriptiontrue — delete the option with the specified id
Fielditems[].sort Typeinteger Requiredno DescriptionOption order — an integer greater than 0
Fielditems[].def Typeboolean Requiredno DescriptionDefault option. To clear it on a field without multiple, mark another option with def: true in the same request
Fielditems[].xmlId Typestring Requiredno DescriptionExternal identifier of the option. If omitted, an existing option keeps its current value

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/userfields/tasks/6007967" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": { "ru": "Approval stage", "en": "Approval stage" },
    "items": [
      { "id": 4047, "value": "Pending approval" },
      { "id": 4049, "del": true },
      { "value": "Approved", "xmlId": "approved", "sort": 40 }
    ]
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/userfields/tasks/6007967" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": { "ru": "Approval stage", "en": "Approval stage" },
    "items": [
      { "id": 4047, "value": "Pending approval" },
      { "id": 4049, "del": true },
      { "value": "Approved", "xmlId": "approved", "sort": 40 }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/tasks/6007967', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: { ru: 'Approval stage', en: 'Approval stage' },
    items: [
      { id: 4047, value: 'Pending approval' },
      { id: 4049, del: true },
      { value: 'Approved', xmlId: 'approved', sort: 40 },
    ],
  }),
})

const { success, data } = await res.json()
console.log(data.items.map((item) => item.value))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/tasks/6007967', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: { ru: 'Approval stage', en: 'Approval stage' },
    items: [
      { id: 4047, value: 'Pending approval' },
      { id: 4049, del: true },
      { value: 'Approved', xmlId: 'approved', sort: 40 },
    ],
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe whole field after the change — in the same shape as in the Get field response
Fielddata.items Typearray DescriptionAll options of the field after the change, including those not mentioned in the request

Response example

Labels in the example are shortened to two languages — en and ru. In the other languages, the editFormLabel, listColumnLabel, and listFilterLabel labels in this response are empty: the label object in the request set only two languages.

JSON 
{
  "success": true,
  "data": {
    "id": 6007967,
    "entityId": "TASKS_TASK",
    "fieldName": "UF_REVIEW_STAGE",
    "userTypeId": "enumeration",
    "xmlId": null,
    "sort": "500",
    "multiple": "N",
    "mandatory": "Y",
    "showFilter": "N",
    "showInList": "Y",
    "editInList": "Y",
    "isSearchable": "N",
    "settings": {
      "DISPLAY": "LIST",
      "LIST_HEIGHT": 1,
      "CAPTION_NO_VALUE": "",
      "SHOW_NO_VALUE": "Y"
    },
    "editFormLabel": {
      "en": "Approval stage",
      "ru": "Approval stage"
    },
    "listColumnLabel": {
      "en": "Approval stage",
      "ru": "Approval stage"
    },
    "listFilterLabel": {
      "en": "Approval stage",
      "ru": "Approval stage"
    },
    "errorMessage": {
      "en": "UF_REVIEW_STAGE",
      "ru": "UF_REVIEW_STAGE"
    },
    "helpMessage": {
      "en": "UF_REVIEW_STAGE",
      "ru": "UF_REVIEW_STAGE"
    },
    "system": false,
    "items": [
      {
        "id": 4045,
        "value": "New",
        "sort": "10",
        "def": "Y",
        "xmlId": "new"
      },
      {
        "id": 4047,
        "value": "Pending approval",
        "sort": "20",
        "def": "N",
        "xmlId": "review"
      },
      {
        "id": 4051,
        "value": "Approved",
        "sort": "40",
        "def": "N",
        "xmlId": "approved"
      }
    ]
  }
}

Error response example

400 — the body contains the immutable property fieldName:

JSON 
{
  "success": false,
  "error": {
    "code": "IMMUTABLE_FIELD",
    "message": "fieldName, userTypeId and multiple cannot be changed"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID Description:id is not a positive integer — the request is rejected before it reaches Bitrix24
HTTP400 CodeIMMUTABLE_FIELD DescriptionThe body contains fieldName, userTypeId, or multiple
HTTP400 CodeINVALID_PARAMS DescriptionEmpty body, an unknown key, or a value of the wrong type
HTTP400 CodeINVALID_PARAMS DescriptionAn items element without value and without del: true, or an option sort less than 1
HTTP400 CodeINVALID_PARAMS DescriptionThe option id belongs to another field
HTTP400 CodeINVALID_PARAMS DescriptionOn a field without multiple, def is cleared from the default option and no other option is marked, or more than one option is marked
HTTP400 CodeINVALID_PARAMS Descriptionitems is passed for a field whose type is not enumeration
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no field with this id, or it belongs to another entity
HTTP403 CodeSYSTEM_FIELD_PROTECTED DescriptionSystem field UF_CRM_TASK, UF_TASK_WEBDAV_FILES, or UF_MAIL_MESSAGE
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key owner is not a Bitrix24 account administrator
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeTASK_CUSTOM_FIELDS_UNAVAILABLE DescriptionThe portal plan does not include task user fields
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the task scope
HTTP502 CodeTASK_USERFIELD_OUTCOME_UNKNOWN DescriptionThe connection to Bitrix24 dropped, or Bitrix24 returned a server error during the write — whether the change was applied is unknown. The request was not retried automatically: read the field before changing it again
HTTP502 CodeTASK_USERFIELD_READBACK_FAILED DescriptionThe change was written, but the field could not be read after the write. The response contains error.fieldId — the field ID — and error.writeConfirmed: true. Retry the read, not the update
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens. For an application key, the Authorization: Bearer USER_SESSION_TOKEN header was not passed
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

items describes only the changes. An option that is not in the array stays unchanged. In the example, the "New" option was kept, "Accepted" was deleted, "In review" was renamed and kept its xmlId, and "Approved" was added.

See also