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
Parameter:entity (path) Typestring Requiredyes DescriptionEntity: deals, leads, contacts, companies, quotes, requisites

Request fields (body)

Field Type Required Description
FielduserTypeId Typestring Requiredyes DescriptionField type. For the list of allowed values, see GET /v1/userfields/:entity/types. Examples: string, enumeration, integer, double, datetime
FieldfieldName Typestring Requiredno DescriptionSuffix of the system name. The final name is formed as UF_CRM_<FIELD_NAME>. If you do not pass it, Bitrix24 generates the name automatically — leave the key out entirely; an empty string or null is not accepted. The name used to pass the field in entity record requests is different — User fields (UF)
Fieldlabel Typestring Requiredno DescriptionDisplay 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
FieldeditFormLabel Typeobject Requiredno DescriptionLabel in the edit form per language. Example: { "en": "Project", "de": "Projekt" }. Values are set for the specified languages; the remaining locales are filled in according to Bitrix24 rules
Fieldsort Typenumber | string Requiredno DescriptionSort order in the Bitrix24 interface. Accepted as a number or a string, read back as a string. Defaults to "100"
Fieldmultiple Typeboolean Requiredno DescriptionAllow multiple values: true / false or "Y" / "N". Off by default
Fieldmandatory Typeboolean Requiredno DescriptionRequired when filling in a record: true / false or "Y" / "N". Off by default
FieldshowFilter Typeboolean Requiredno DescriptionShow in the filter: true or "Y" — yes, false or "N" — no. On write, the letters "I" and "S" switch the filter off. An enabled filter reads back as "E"; sending that "E" back is safe — the platform reads it as "on"
FieldshowInList Typeboolean Requiredno DescriptionShow in the record list: true / false or "Y" / "N"
FieldeditInList Typeboolean Requiredno DescriptionAllow editing directly from the list: true / false or "Y" / "N"
FieldisSearchable Typeboolean Requiredno DescriptionIncluded in the Bitrix24 account's full-text search: true / false or "Y" / "N"
FieldxmlId Typestring Requiredno DescriptionExternal identifier for integrations
Fieldsettings Typeobject Requiredno DescriptionField settings specific to userTypeId. For string, double, and crm, the keys in the rows below are saved
Fieldsettings.ROWS Typenumber Requiredno DescriptionFor the string type: height of the input field in lines
Fieldsettings.DEFAULT_VALUE Typestring Requiredno DescriptionFor the string type: default value
Fieldsettings.PRECISION Typenumber Requiredno DescriptionFor the double type: number of decimal places. Defaults to 0
Fieldsettings.LEAD Typestring Requiredno DescriptionFor the crm type: the field links to leads when the value is "Y"
Fieldsettings.CONTACT Typestring Requiredno DescriptionFor the crm type: the field links to contacts when the value is "Y"
Fieldsettings.COMPANY Typestring Requiredno DescriptionFor the crm type: the field links to companies when the value is "Y"
Fieldsettings.DEAL Typestring Requiredno DescriptionFor the crm type: the field links to deals when the value is "Y"
Fieldlist Typearray Requiredno DescriptionOptions 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionCreation result
Fielddata.id Typenumber DescriptionNumeric 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
HTTP400 CodeMISSING_FIELD DescriptionThe required parameter userTypeId is missing
HTTP400 CodeINVALID_FIELD_NAME DescriptionThe fieldName key was passed, but its value is not a string or consists of whitespace only
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP400 CodeUNKNOWN_ENTITY Description:entity is not in the list of supported entities
HTTP422 CodeBITRIX_ERROR DescriptionAn unknown userTypeId was passed — not from the /types catalog
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 errors: duplicate field name, invalid settings
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
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

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" }.

Linking a crm field. The field links to records of the entities whose key in settings equals the string "Y". A boolean true and lowercase keys are not saved. If no key equals "Y", or settings is omitted, the field links to leads. Example body for a field that links to contacts and companies: { "userTypeId": "crm", "settings": { "CONTACT": "Y", "COMPANY": "Y" } }.

A link to a smart process is not saved. This method does not save the DYNAMIC_<entityTypeId> key in the settings of a crm field: the response comes back with 201, but the key is missing when you read the field. If the request has no other key set to "Y", the field links to leads.

See also