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> (for requisites — UF_REQUISITE_<FIELD_NAME>). If omitted, Bitrix24 generates the name automatically
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 string no Allow multiple values: "Y" or "N". Defaults to "N"
mandatory string no Required on fill: "Y" or "N". Defaults to "N"
showFilter string no Show in the 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 composition depends on the 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": "I",
    "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": "I",
    "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: 'I',
    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: 'I',
    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:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_FIELD",
    "message": "userTypeId is required (e.g. \"string\", \"enumeration\", \"integer\", \"double\", \"datetime\")"
  }
}

Errors

HTTP Code Description
400 MISSING_FIELD The required parameter userTypeId is missing
400 INVALID_REQUEST The request body is not an object
400 UNKNOWN_ENTITY :entity is not in the list of supported entities
422 BITRIX_ERROR An unknown userTypeId was passed — not from the /types catalog
422 BITRIX_ERROR Other Bitrix24 errors: duplicate field name, invalid settings
403 SCOPE_DENIED The API key does not have the crm scope
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.

Known specifics

Auto-propagation of label. When a label string is passed, the value automatically appears in all language fields: editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage. To set different labels for different languages, pass the editFormLabel object: { "en": "Project", "de": "Projekt" }.

See also