# 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.

[All task field operations](/docs/userfields/tasks)

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.