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

Create field

POST /v1/userfields/tasks

Creates a task user field. The field is shared across the whole Bitrix24 account: it appears right away in every task for all employees.

Pass the field properties flat at the JSON root — without a fields wrapper.

Request fields (body)

Field Type Required Description
FieldfieldName Typestring Requiredyes DescriptionSystem field name. Stored in upper case with the UF_ prefix: UF_REVIEW_STAGE is saved as is, request_channel becomes UF_REQUEST_CHANNEL
FielduserTypeId Typestring Requiredyes DescriptionField type from the type catalog, for example string, enumeration, double
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": "Request channel", "en": "Request channel" }; in the remaining languages the field name becomes the label. The label does not go into errorMessage and helpMessage: those hold the field name
Fieldmultiple Typeboolean Requiredno DescriptionMultiple values in one task. Defaults to false. Can be set only at creation. A boolean field cannot be multiple
Fieldmandatory Typeboolean Requiredno DescriptionRequired field. Defaults to false
Fieldsort Typeinteger Requiredno DescriptionField order — a non-negative integer. Defaults to 100
Fieldsettings Typeobject Requiredno DescriptionField settings; the set of keys depends on userTypeId. Keys that are not passed get default values — the sets for string and enumeration are listed on the Get field page
Fielditems Typearray Requiredno DescriptionOptions of an enumeration field. Not accepted for other types
Fielditems[].value Typestring Requiredyes DescriptionOption name — a non-empty string
Fielditems[].sort Typeinteger Requiredno DescriptionOption order — an integer greater than 0. Without sort the option gets 500, and the order of options in the response no longer matches the order you passed
Fielditems[].def Typeboolean Requiredno DescriptionDefault option. A field without multiple can have only one such option
Fielditems[].xmlId Typestring Requiredno DescriptionExternal option ID. Generated automatically if not passed

The method accepts no other properties: an unknown key, such as xmlId of the field itself, is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/tasks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "UF_REVIEW_STAGE",
    "userTypeId": "enumeration",
    "label": "Review stage",
    "mandatory": true,
    "sort": 500,
    "items": [
      { "value": "New", "xmlId": "new", "sort": 10, "def": true },
      { "value": "Under review", "xmlId": "review", "sort": 20 },
      { "value": "Accepted", "xmlId": "accepted", "sort": 30 }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/tasks" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "UF_REVIEW_STAGE",
    "userTypeId": "enumeration",
    "label": "Review stage",
    "mandatory": true,
    "sort": 500,
    "items": [
      { "value": "New", "xmlId": "new", "sort": 10, "def": true },
      { "value": "Under review", "xmlId": "review", "sort": 20 },
      { "value": "Accepted", "xmlId": "accepted", "sort": 30 }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/tasks', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fieldName: 'UF_REVIEW_STAGE',
    userTypeId: 'enumeration',
    label: 'Review stage',
    mandatory: true,
    sort: 500,
    items: [
      { value: 'New', xmlId: 'new', sort: 10, def: true },
      { value: 'Under review', xmlId: 'review', sort: 20 },
      { value: 'Accepted', xmlId: 'accepted', sort: 30 },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Created field with id:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/tasks', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fieldName: 'UF_REVIEW_STAGE',
    userTypeId: 'enumeration',
    label: 'Review stage',
    mandatory: true,
    sort: 500,
    items: [
      { value: 'New', xmlId: 'new', sort: 10, def: true },
      { value: 'Under review', xmlId: 'review', sort: 20 },
      { value: 'Accepted', xmlId: 'accepted', sort: 30 },
    ],
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe whole created field — in the same shape as in the Get field response
Fielddata.id Typenumber DescriptionNumeric ID of the created field
Fielddata.fieldName Typestring DescriptionFinal field name in the UF_* format

The response comes with HTTP status 201 Created.

Response example

The labels in the example are trimmed to two languages — en and ru. The response has more keys: one per language.

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": "Review stage",
      "ru": "Review stage"
    },
    "listColumnLabel": {
      "en": "Review stage",
      "ru": "Review stage"
    },
    "listFilterLabel": {
      "en": "Review stage",
      "ru": "Review 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": "Under review",
        "sort": "20",
        "def": "N",
        "xmlId": "review"
      },
      {
        "id": 4049,
        "value": "Accepted",
        "sort": "30",
        "def": "N",
        "xmlId": "accepted"
      }
    ]
  }
}

Error response example

400 — the required fieldName was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "fieldName and userTypeId are required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionfieldName or userTypeId was not passed
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not an object, an unknown key was passed, or a value has the wrong type — for example, sort as a string
HTTP400 CodeINVALID_PARAMS DescriptionA boolean field with multiple: true
HTTP400 CodeINVALID_PARAMS Descriptionitems for a field whose type is not enumeration
HTTP400 CodeINVALID_PARAMS DescriptionAn option without value or with sort less than 1
HTTP400 CodeINVALID_PARAMS DescriptionMore than one option with def: true for a field without multiple
HTTP422 CodeBITRIX_ERROR DescriptionUnknown userTypeId — the message is The custom type is invalid.
HTTP422 CodeBITRIX_ERROR DescriptionA field with this name already exists — the message is The field UF_REVIEW_STAGE for entity TASKS_TASK already exists.
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 field was created is unknown. The request was not retried automatically: find the field in the list by fieldName before creating it again
HTTP502 CodeTASK_USERFIELD_READBACK_FAILED DescriptionThe field was created, but reading it back after the write failed. The response contains error.fieldId — the field ID — and error.writeConfirmed: true. Retry the read by fieldId, not the creation
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

The API creates a task even without a value for a required field. POST /v1/tasks creates a task without the field value even when the field has mandatory: true. In that task the field value is null, even if a list option has def: true.

A new field is visible in tasks immediately. After creation the field arrives in GET /v1/tasks/:id under its camelCase name — ufReviewStage for UF_REVIEW_STAGE.

See also