For AI agents: markdown of this page — /docs-content-en/userfields/tasks/create.md documentation index — /llms.txt
Create field
POST /v1/userfields/tasks
Bitrix24 method: task.item.userfield.add. Scope: task.
The field is shared by the entire account: it appears in every task for every employee.
Required: fieldName, userTypeId. Optional: label as a string or language map, boolean multiple and mandatory, integer sort, object settings, array items for enumeration variants. Bitrix24 normalizes the name to UF_<UPPER>. label is copied into three labels without changing error or help text. boolean with multiple:true is refused. REST task writes do not enforce mandatory: a task can be created without the field value. Response 201 {success:true,data:{id,fieldName,...}} contains the field read back after creation.
Example body: {"fieldName":"UF_VIBEPROBE_CLIENT","userTypeId":"enumeration","label":"Client","items":[{"value":"First","xmlId":"first"},{"value":"Second","xmlId":"second"}]}.
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.
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.