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

Create field

POST /v1/items/:entityTypeId/userfields

Creates a new user field for smart process items. Returns HTTP 201 Created with the id of the new field. Fields are passed flat at the JSON root — without a fields wrapper.

Parameters

Parameter Type Required Description
Parameter:entityTypeId (path) Typenumber Requiredyes DescriptionSmart process type identifier. Source: GET /v1/smart-processes — the entityTypeId field on each element of the data array

Request fields (body)

Field Type Required Description
FielduserTypeId Typestring Requiredyes DescriptionField type. List of allowed values — GET /v1/items/:entityTypeId/userfields/types. Examples: string, enumeration, integer, double, datetime
FieldfieldName Typestring Requiredyes DescriptionFull system name: the prefix UF_ + entityId + _, followed by a suffix. For a regular smart process, entityId is CRM_<typeId>, so the name has the UF_CRM_<typeId>_<suffix> format. Here typeId is the id field (the type's internal ID) from the GET /v1/smart-processes response, not the entityTypeId from the request path: the values differ. The id field is always available, even when the smart process has no fields yet. For the built-in smart invoice (entityTypeId=31), including the /v1/userfields/invoices path, entityId is CRM_SMART_INVOICE, so the name has the UF_CRM_SMART_INVOICE_<suffix> format. The complete entityId is returned in every element of the GET /v1/items/:entityTypeId/userfields response when the entity already has fields. Auto-generation is not supported: the backend does not add the prefix, so an incomplete name returns 422 BITRIX_ERROR
Fieldlabel Typestring Requiredno DescriptionDisplay label. Fills each of editFormLabel, listColumnLabel, listFilterLabel unless that label is explicitly provided. A string is converted to { "ru": "value" }. For other languages, provide labels as objects keyed by language code
FieldeditFormLabel Typeobject Requiredno DescriptionEdit form label by language. Example: { "en": "Project", "de": "Projekt" }. Values are set for the specified languages. The remaining locales are filled in according to Bitrix24 rules
FieldlistColumnLabel Typeobject Requiredno DescriptionList column header by language. An explicit value takes precedence over label
FieldlistFilterLabel Typeobject Requiredno DescriptionFilter label by language. An explicit value takes precedence over label
Fieldsort Typestring Requiredno DescriptionSort order in the Bitrix24 interface. Defaults to "100"
Fieldmultiple Typestring Requiredno DescriptionAllow multiple values: "Y" or "N". Defaults to "N"
Fieldmandatory Typestring Requiredno DescriptionRequired field: "Y" or "N". Defaults to "N"
FieldshowFilter Typestring Requiredno DescriptionShow in filter: "N" — no, "I" — exact value, "E" — mask, "S" — range
FieldshowInList Typestring Requiredno DescriptionShow in the record list: "Y" or "N"
FieldeditInList Typestring Requiredno DescriptionAllow editing directly from the list: "Y" or "N"
FieldisSearchable Typestring Requiredno DescriptionParticipates in full-text search: "Y" or "N"
FieldxmlId Typestring Requiredno DescriptionExternal identifier for integrations
Fieldsettings Typeobject Requiredno DescriptionField settings specific to userTypeId. For string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE. The set depends on the type
Fieldenum Typearray Requiredno DescriptionOptions for an enumeration field. Each element: { "value": "Name", "sort": 10 } (optionally "def": "Y" — the default value). The same array is also accepted under the list key — the element format is identical. When the field is read, the options are returned in the enum block

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/items/174/userfields" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "UF_CRM_3_PROJECT_STATUS",
    "label": "Project status",
    "sort": "200",
    "showFilter": "I",
    "showInList": "Y",
    "enum": [
      { "value": "New", "sort": 10 },
      { "value": "In progress", "sort": 20 },
      { "value": "Done", "sort": 30 }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/items/174/userfields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "UF_CRM_3_PROJECT_STATUS",
    "label": "Project status",
    "sort": "200",
    "showFilter": "I",
    "showInList": "Y",
    "enum": [
      { "value": "New", "sort": 10 },
      { "value": "In progress", "sort": 20 },
      { "value": "Done", "sort": 30 }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/items/174/userfields', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userTypeId: 'enumeration',
    fieldName: 'UF_CRM_3_PROJECT_STATUS',
    label: 'Project status',
    sort: '200',
    showFilter: 'I',
    showInList: 'Y',
    enum: [
      { value: 'New', sort: 10 },
      { value: 'In progress', sort: 20 },
      { value: 'Done', 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/items/174/userfields', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userTypeId: 'enumeration',
    fieldName: 'UF_CRM_3_PROJECT_STATUS',
    label: 'Project status',
    sort: '200',
    showFilter: 'I',
    showInList: 'Y',
    enum: [
      { value: 'New', sort: 10 },
      { value: 'In progress', sort: 20 },
      { value: 'Done', sort: 30 },
    ],
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionCreation result
Fielddata.id Typestring DescriptionIdentifier of the created field. Returned as a string. When read via Get field, the same value is returned as a number

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "7119"
  }
}

Error response example

422 — invalid field name: it does not start with UF_ + entityId + _:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Invalid field code"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_FIELD DescriptionThe required userTypeId parameter was not passed
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP400 CodeINVALID_ENTITY_TYPE_ID Description:entityTypeId is not a positive integer
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key has no userfieldconfig scope — reissue the key with this scope
HTTP403 CodeSCOPE_DENIED DescriptionThe API key has no crm scope
HTTP404 CodeSMART_PROCESS_NOT_FOUND DescriptionA smart process with the given entityTypeId was not found on the portal
HTTP422 CodeBITRIX_ERROR DescriptionInvalid field code — fieldName does not start with UF_ + entityId + _
HTTP422 CodeBITRIX_ERROR DescriptionUnknown userTypeId (not from the /types catalog), duplicate field name, or invalid settings
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

The smart invoice field name prefix is accepted only in full. When you create a field for the built-in smart invoice via POST /v1/userfields/invoices (entityId is CRM_SMART_INVOICE), a name with a partial prefix is rejected:

fieldName Response
fieldNameUF_CRM_VFY_A Response422 "Invalid field code"
fieldNameUF_CRM_TESTPREFIX253906 Response422 "Invalid field code" — UF_CRM_ alone is not enough
fieldNameUF_SMART_INVOICE_X253906 Response422 "Invalid field code" — CRM_ is required
fieldNameUF_CRM_SMART_INVOICE_VFYA Response201 Created

The name must start with UF_ + the entity's entityId + _. A POST /v1/userfields/invoices request body with a valid name:

JSON 
{
  "userTypeId": "string",
  "fieldName": "UF_CRM_SMART_INVOICE_VFYA"
}

See also