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

Create field

POST /v1/userfields/:entity

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

Parameters

Parameter	Type	Required	Description
`:entity` (path)	string	yes	Entity: `deals`, `leads`, `contacts`, `companies`, `quotes`, `requisites`

Request fields (body)

Field	Type	Required	Description
`userTypeId`	string	yes	Field type. The list of allowed values — `GET /v1/userfields/:entity/types`. Examples: `string`, `enumeration`, `integer`, `double`, `datetime`
`fieldName`	string	no	Suffix of the system name. The final name is formed as `UF_CRM_<FIELD_NAME>`. If omitted, Bitrix24 generates the name automatically. The name used to pass the field in entity record requests is different — User fields (UF)
`label`	string	no	Display label of the field. The value is automatically propagated to all Bitrix24 account languages in `editFormLabel`, `listColumnLabel`, `listFilterLabel`, `errorMessage`, `helpMessage`. To set different labels per language, use the `editFormLabel` object
`editFormLabel`	object	no	Label in the edit form per language. Example: `{ "en": "Project", "de": "Projekt" }`. Values are set for the specified languages; the remaining locales are filled per Bitrix24 rules
`sort`	string	no	Sort order in the Bitrix24 interface. Defaults to `"100"`
`multiple`	boolean	no	Allow multiple values: `true` / `false` or `"Y"` / `"N"`. Off by default
`mandatory`	boolean	no	Required when filling in a record: `true` / `false` or `"Y"` / `"N"`. Off by default
`showFilter`	boolean	no	Show in the filter: `true` or `"Y"` — yes, `false` or `"N"` — no. The letters `"I"` and `"S"` this page used to recommend are not accepted on write by `crm.<entity>.userfield.*` — they switch the filter off (measured on four field types). An enabled filter reads back as `"E"`; sending that `"E"` back is safe — the platform reads it as "on"
`showInList`	boolean	no	Show in the record list: `true` / `false` or `"Y"` / `"N"`
`editInList`	boolean	no	Allow editing directly from the list: `true` / `false` or `"Y"` / `"N"`
`isSearchable`	boolean	no	Participates in the account full-text search: `true` / `false` or `"Y"` / `"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`. For `double` — `PRECISION`, the number of decimal places, `0` by default. The available settings depend on the field type
`list`	array	no	Options for an `enumeration` field. Each item: `{ "VALUE": "Name", "SORT": 10 }`. Ignored for other types

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/userfields/deals" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "PROJECT_STATUS",
    "label": "Project status",
    "sort": "200",
    "showFilter": true,
    "showInList": "Y",
    "list": [
      { "VALUE": "New", "SORT": 10 },
      { "VALUE": "In progress", "SORT": 20 },
      { "VALUE": "Completed", "SORT": 30 }
    ]
  }'

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/userfields/deals" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "PROJECT_STATUS",
    "label": "Project status",
    "sort": "200",
    "showFilter": true,
    "showInList": "Y",
    "list": [
      { "VALUE": "New", "SORT": 10 },
      { "VALUE": "In progress", "SORT": 20 },
      { "VALUE": "Completed", "SORT": 30 }
    ]
  }'

JavaScript — personal key

javascript

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

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

Response fields

Field	Type	Description
`success`	boolean	Always `true` on success
`data.id`	number	Numeric identifier of the created field

Response example

JSON

{
  "success": true,
  "data": {
    "id": 7115
  }
}

Error response example

400 — the required parameter userTypeId is missing: