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
:entityTypeId (path) number yes Smart 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
userTypeId string yes Field type. List of allowed values — GET /v1/items/:entityTypeId/userfields/types. Examples: string, enumeration, integer, double, datetime
fieldName string yes Full system name in 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. Auto-generation is not supported: the backend does not add the prefix, an incomplete name yields 422 BITRIX_ERROR
label string no Field label for display. If explicit editFormLabel / listColumnLabel are not set, the value is copied into both labels — the edit form (editFormLabel) and the list column header (listColumnLabel). For per-language labels use the editFormLabel / listColumnLabel objects
editFormLabel object no Edit 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
sort string no Sort order in the Bitrix24 interface. Defaults to "100"
multiple string no Allow multiple values: "Y" or "N". Defaults to "N"
mandatory string no Required field: "Y" or "N". Defaults to "N"
showFilter string no Show in filter: "N" — no, "I" — exact value, "E" — mask, "S" — range
showInList string no Show in the record list: "Y" or "N"
editInList string no Allow editing directly from the list: "Y" or "N"
isSearchable string no Participates in full-text search: "Y" or "N"
xmlId string no External identifier for integrations
settings object no Field settings specific to userTypeId. For string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE. The set depends on the type
enum array no Options 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
success boolean Always true on success
data.id string Identifier 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 (not in the UF_CRM_<typeId>_<suffix> format):

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

Errors

HTTP Code Description
400 MISSING_FIELD The required userTypeId parameter was not passed
400 INVALID_REQUEST The request body is not an object
400 INVALID_ENTITY_TYPE_ID :entityTypeId is not a positive integer
403 BITRIX_ACCESS_DENIED The key has no userfieldconfig scope — reissue the key with this scope
403 SCOPE_DENIED The API key has no crm scope
404 SMART_PROCESS_NOT_FOUND A smart process with the given entityTypeId was not found on the portal
422 BITRIX_ERROR Invalid field code — fieldName is not in the UF_CRM_<typeId>_<suffix> format
422 BITRIX_ERROR Unknown userTypeId (not from the /types catalog), duplicate field name, or invalid settings
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY The X-Api-Key header is missing

Full list of common API errors — Errors.

See also