Update field

PATCH /v1/userfields/tasks/:id

Bitrix24 method: task.item.userfield.update. Scope: task.

Only label, mandatory, sort, settings, items are accepted. fieldName, userTypeId, multiple return 400 IMMUTABLE_FIELD; unknown properties and an empty object return 400 INVALID_PARAMS. label is a string or language map, mandatory is boolean, sort is an integer.

An item with id must include a nonempty value; to delete it, send del:true. Otherwise Bitrix24 would silently delete the variant. Unmentioned variants stay. When xmlId is omitted, the wrapper preserves its current value; a new item without id is added. Example: {"items":[{"id":8,"value":"New name"},{"id":9,"del":true}]}.

The field is read before writing; system fields return 403 SYSTEM_FIELD_PROTECTED. Response contains the field read back after writing. Bitrix24 may normalize settings and labels of uninstalled languages on any update.

Errors and access

Missing scope: 403 SCOPE_DENIED. Portal plan without TASK_CUSTOM_FIELDS: 403 TASK_CUSTOM_FIELDS_UNAVAILABLE, including reads. Nonexistent fields: 404 ENTITY_NOT_FOUND. Invalid input: 400; Bitrix24 business refusals: 422. Bitrix24 write permission refusals: 403. Reads accept READONLY keys; writes require READWRITE and portal administrator rights. Writes are never retried automatically. After a timeout, the outcome is unknown: reread the field before another write.

All task field operations

List item items.sort must be positive: Bitrix24 ignores zero. To clear a single-list default, select another item with def:true in the same PATCH; otherwise the response is 400 INVALID_PARAMS. If reading fails after a confirmed write, 502 TASK_USERFIELD_READBACK_FAILED includes error.fieldId and error.writeConfirmed:true: repeat GET, not the write.