Add Custom Field userfieldconfig.add
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
userfieldconfig, module scope frommoduleId(for example,crm)Who can execute the method: a user with permission to modify object settings in the
moduleIdmodule (forcrm— permission "Allow to modify settings")
The userfieldconfig.add method adds a new custom field.
Method Parameters
Required parameters are marked with *
|
Name |
Description |
|
moduleId* |
Module identifier where the field is created |
|
field* |
Object with custom field settings (detailed description) |
Parameter field
|
Name |
Description |
|
entityId* |
Identifier of the object for which the field is created. The format depends on the module, for example, |
|
fieldName* |
Field code in the format |
|
userTypeId* |
Identifier of the field type. The list of available types is returned by the userfieldconfig.getTypes method |
|
xmlId |
External identifier of the field |
|
sort |
Sort index. Default is |
|
multiple |
Whether the field is multiple. Possible values: |
|
mandatory |
Whether the field is mandatory. Possible values: |
|
showFilter |
Whether to show the field in the filter. Possible values: |
|
editInList |
Whether to allow editing the value in the list. Possible values: |
|
isSearchable |
Whether the field values participate in the search. Possible values: |
|
settings |
Additional field settings. The set of keys depends on |
|
Label in the edit form. When a string is passed, it is used as a general value; when a |
|
|
Help text. When a string is passed, it is used as a general value; when a |
|
|
enum |
Value options for fields of type |
The method uses a fixed set of keys in field (see the table above).
Incorrect and unsupported keys in field are ignored.
Keys showInList, listColumnLabel, listFilterLabel, errorMessage, label are not processed by the userfieldconfig.add method, even if passed in field.
Parameter settings
Each field type has its own set of keys in settings.
|
Name |
Description |
|
DEFAULT_VALUE |
Default value |
|
ROWS |
Number of rows in the input field, must be greater than 0 |
|
SIZE |
Width of the input field |
|
REGEXP |
Regular expression for validation |
|
MIN_LENGTH |
Minimum string length |
|
MAX_LENGTH |
Maximum string length |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value |
|
SIZE |
Width of the input field |
|
MIN_VALUE |
Minimum value |
|
MAX_VALUE |
Maximum value |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value |
|
PRECISION |
Number precision, must be greater than or equal to 0 |
|
SIZE |
Width of the input field |
|
MIN_VALUE |
Minimum value |
|
MAX_VALUE |
Maximum value |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value, where |
|
DISPLAY |
Appearance, possible values: |
|
LABEL |
Label for the Yes value |
|
LABEL_CHECKBOX |
Label for |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value in the format |
|
USE_SECOND |
Use seconds in the |
|
USE_TIMEZONE |
Use timezone in the |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value in the format |
|
Name |
Description |
|
POPUP |
Open link in a new window |
|
SIZE |
Width of the input field |
|
MIN_LENGTH |
Minimum length of the value |
|
MAX_LENGTH |
Maximum length of the value |
|
DEFAULT_VALUE |
Default value |
|
ROWS |
Number of rows in the input field |
|
Name |
Description |
|
SHOW_MAP |
Show map for the address |
|
Name |
Description |
|
SIZE |
Width of the input field |
|
LIST_WIDTH |
Width of the preview in the list |
|
LIST_HEIGHT |
Height of the preview in the list |
|
MAX_SHOW_SIZE |
Maximum file size for display |
|
MAX_ALLOWED_SIZE |
Maximum allowable file size |
|
EXTENSIONS |
List of allowed extensions |
|
TARGET_BLANK |
Open file in a new tab |
|
Name |
Description |
|
DISPLAY |
Appearance, possible values: |
|
LIST_HEIGHT |
Height of the list, must be greater than 0 |
|
CAPTION_NO_VALUE |
Label for empty value |
|
SHOW_NO_VALUE |
Show empty value |
|
Name |
Description |
|
DISPLAY |
Appearance, possible values: |
|
LIST_HEIGHT |
Height of the list, must be greater than 0 |
|
IBLOCK_ID |
Identifier of the information block |
|
DEFAULT_VALUE |
Default value |
|
ACTIVE_FILTER |
Use only active elements |
|
Name |
Description |
|
ENTITY_TYPE |
Identifier of the CRM reference type. Possible values can be obtained using the |
|
Name |
Description |
|
LEAD |
Enable binding to leads |
|
CONTACT |
Enable binding to contacts |
|
COMPANY |
Enable binding to companies |
|
DEAL |
Enable binding to deals |
|
QUOTE |
Enable binding to estimates |
|
ORDER |
Enable binding to orders |
|
SMART_INVOICE |
Enable binding to invoices |
|
DYNAMIC_* |
Enable binding to SPA with a specific |
Separate settings in settings for the employee type are not used.
Settings are defined by the custom field type handler.
Type uf_enum_element
|
Name |
Description |
|
value* |
Value of the list option |
|
def |
Default value flag ( |
|
sort |
Sort index of the option |
|
xmlId |
External identifier of the option |
Code Examples
How to Use Examples in Documentation
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"moduleId": "crm",
"field": {
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": {
"en": "List of characteristics"
},
"enum": [
{ "value": "Characteristic 1", "def": "N", "sort": 100 },
{ "value": "Characteristic 2", "def": "Y", "sort": 200 }
]
}
}' \
"https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/userfieldconfig.add"
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"moduleId": "crm",
"field": {
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": {
"en": "List of characteristics"
},
"enum": [
{ "value": "Characteristic 1", "def": "N", "sort": 100 },
{ "value": "Characteristic 2", "def": "Y", "sort": 200 }
]
},
"auth": "**put_access_token_here**"
}' \
"https://**put_your_bitrix24_address**/rest/userfieldconfig.add"
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
// Shape of the payload returned in result (match the "response handling" section of the page)
type UserfieldconfigAddResult = {
field: {
id: string
entityId: string
fieldName: string
userTypeId: string
xmlId: string | null
sort: string
multiple: string
mandatory: string
showFilter: string
showInList: string
editInList: string
isSearchable: string
settings: Record<string, unknown>
languageId: Record<string, string>
editFormLabel: Record<string, string | null>
listColumnLabel: Record<string, string | null>
listFilterLabel: Record<string, string | null>
errorMessage: Record<string, string | null>
helpMessage: Record<string, string | null>
enum?: Array<{
id: string
userFieldId: string
value: string
def: string
sort: string
xmlId: string
}>
}
}
try {
const response = await $b24.actions.v2.call.make<UserfieldconfigAddResult>({
method: 'userfieldconfig.add',
params: {
moduleId: 'crm',
field: {
entityId: 'CRM_7',
fieldName: 'UF_CRM_7_NEW_REST_LIST_2026',
userTypeId: 'enumeration',
multiple: 'Y',
editFormLabel: {
en: 'List of characteristics',
},
enum: [
{ value: 'Characteristic 1', def: 'N', sort: 100 },
{ value: 'Characteristic 2', def: 'Y', sort: 200 },
],
},
},
requestId: Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Created field:', result.field.id, result.field.fieldName)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function addUserfield() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'userfieldconfig.add',
params: {
moduleId: 'crm',
field: {
entityId: 'CRM_7',
fieldName: 'UF_CRM_7_NEW_REST_LIST_2026',
userTypeId: 'enumeration',
multiple: 'Y',
editFormLabel: {
en: 'List of characteristics',
},
enum: [
{ value: 'Characteristic 1', def: 'N', sort: 100 },
{ value: 'Characteristic 2', def: 'Y', sort: 200 },
],
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Created field:', result.field.id, result.field.fieldName)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', addUserfield)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.userfieldconfig.add(
module_id="crm",
field={
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": {
"ru": "List of characteristics",
"en": "List of characteristics",
},
"listColumnLabel": {
"ru": "Characteristics",
"en": "Characteristics",
},
"listFilterLabel": {
"ru": "Characteristics",
"en": "Characteristics",
},
"settings": {
"DISPLAY": "LIST",
"LIST_HEIGHT": 1,
},
"enum": [
{
"value": "Characteristic 1",
"def": "N",
"sort": 100,
},
{
"value": "Characteristic 2",
"def": "Y",
"sort": 200,
},
],
},
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Bitrix API error",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
$payload = [
'auth' => '**put_access_token_here**',
'moduleId' => 'crm',
'field' => [
'entityId' => 'CRM_7',
'fieldName' => 'UF_CRM_7_NEW_REST_LIST_2026',
'userTypeId' => 'enumeration',
'multiple' => 'Y',
'editFormLabel' => [
'en' => 'List of characteristics',
],
'enum' => [
['value' => 'Characteristic 1', 'def' => 'N', 'sort' => 100],
['value' => 'Characteristic 2', 'def' => 'Y', 'sort' => 200],
],
],
];
$curl = curl_init('https://**put_your_bitrix24_address**/rest/userfieldconfig.add.json');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = curl_exec($curl);
curl_close($curl);
print_r($result);
BX24.callMethod(
"userfieldconfig.add",
{
moduleId: "crm",
field: {
entityId: "CRM_7",
fieldName: "UF_CRM_7_NEW_REST_LIST_2026",
userTypeId: "enumeration",
multiple: "Y",
editFormLabel: {
en: "List of characteristics",
},
enum: [
{ value: "Characteristic 1", def: "N", sort: 100 },
{ value: "Characteristic 2", def: "Y", sort: 200 },
],
},
},
(result) => {
if (result.error()) {
console.error(result.error());
} else {
console.info(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'userfieldconfig.add',
[
'moduleId' => 'crm',
'field' => [
'entityId' => 'CRM_7',
'fieldName' => 'UF_CRM_7_NEW_REST_LIST_2026',
'userTypeId' => 'enumeration',
'multiple' => 'Y',
'editFormLabel' => [
'en' => 'List of characteristics',
],
'enum' => [
['value' => 'Characteristic 1', 'def' => 'N', 'sort' => 100],
['value' => 'Characteristic 2', 'def' => 'Y', 'sort' => 200],
],
],
]
);
echo '<pre>';
print_r($result);
echo '</pre>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "userfieldconfig.add", b24.Params{
"moduleId": "crm",
"field": b24.Params{
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": b24.Params{
"en": "List of characteristics",
},
"enum": []b24.Params{
{
"value": "Characteristic 1",
"def": "N",
"sort": 100,
},
{
"value": "Characteristic 2",
"def": "Y",
"sort": 200,
},
},
},
})
if err != nil {
return fmt.Errorf("userfieldconfig.add: %w", err)
}
// The method wraps the response in an object with the "field" key.
raw, ok := b24.Unwrap(res.Result, "field")
if !ok {
return fmt.Errorf("no field key in the response")
}
var item struct {
ID b24.ID `json:"id"`
EntityID string `json:"entityId"`
FieldName string `json:"fieldName"`
UserTypeID string `json:"userTypeId"`
Sort string `json:"sort"`
Multiple string `json:"multiple"`
}
if err := json.Unmarshal(raw, &item); err != nil {
return fmt.Errorf("parse response: %w", err)
}
fmt.Println(item.ID, item.EntityID)
Response Handling
HTTP Status: 200
{
"result": {
"field": {
"id": "6953",
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"xmlId": null,
"sort": "100",
"multiple": "Y",
"mandatory": "N",
"showFilter": "N",
"showInList": "Y",
"editInList": "Y",
"isSearchable": "N",
"settings": {
"DISPLAY": "LIST",
"LIST_HEIGHT": 1,
"CAPTION_NO_VALUE": "",
"SHOW_NO_VALUE": "Y"
},
"languageId": {
"en": "en",
"ru": "ru"
},
"editFormLabel": {
"en": "List of characteristics"
},
"listColumnLabel": {
"en": null,
"ru": null
},
"listFilterLabel": {
"en": null,
"ru": null
},
"errorMessage": {
"en": null,
"ru": null
},
"helpMessage": {
"en": null,
"ru": null
},
"enum": [
{
"id": "3363",
"userFieldId": "6953",
"value": "Characteristic 1",
"def": "N",
"sort": "100",
"xmlId": "56dff18efcfe25f3bae0117a6b372567"
},
{
"id": "3365",
"userFieldId": "6953",
"value": "Characteristic 2",
"def": "Y",
"sort": "200",
"xmlId": "42e3ebcf5506a65283bf3bf510d8f05a"
}
]
}
},
"time": {
"start": 1724239307.903115,
"finish": 1724239308.567422,
"duration": 0.6643068790435791,
"processing": 0.20090818405151367,
"date_start": "2024-08-21T13:21:47+02:00",
"date_finish": "2024-08-21T13:21:48+02:00",
"operating": 0
}
}
Returned Data
|
Name |
Description |
|
result |
Root element of the response (detailed description) |
|
time |
Information about the request execution time |
Object result
|
Name |
Description |
|
field |
Settings of the created custom field (detailed description) |
Object field
|
Name |
Description |
|
id |
Identifier of the field settings |
|
entityId |
Identifier of the object |
|
fieldName |
Field code |
|
userTypeId |
Identifier of the field type |
|
xmlId |
External identifier of the field |
|
sort |
Sort index |
|
multiple |
Flag for multiple values ( |
|
mandatory |
Flag for mandatory field ( |
|
showFilter |
Flag for showing the field in the filter |
|
showInList |
Flag for showing the field in the list |
|
editInList |
Flag for editing in the list |
|
isSearchable |
Flag for participation in search |
|
settings |
Additional field settings (detailed description). The set of keys depends on |
|
languageId |
Languages for which field labels are set |
|
editFormLabel |
Labels in the edit form |
|
listColumnLabel |
Column labels in the list |
|
listFilterLabel |
Filter labels |
|
errorMessage |
Error message text |
|
helpMessage |
Help text for the field |
|
enum |
Value options. This field is returned only for |
Error Handling
HTTP Status: 400
{
"error": "",
"error_description": "The 'FIELD_NAME' field is not found."
}
|
Name |
Description |
|
error |
String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only |
|
error_description |
Error message for the developer. Do not show it to the end user without processing |
Possible Error Codes
|
Code |
Description |
Value |
|
Empty value |
Access denied |
Insufficient permissions to create a custom field |
|
Empty value |
You cannot create custom fields |
This error may occur if |
|
Empty value |
The 'USER_TYPE_ID' field is not found |
Mandatory |
|
Empty value |
The 'FIELD_NAME' field is not found |
Mandatory |
|
Empty value |
Field ... already exists |
The provided |
|
Empty value |
Fail to create new user field |
Error creating the field on the server side |
|
Empty value |
Fail to save enumeration field values |
Error saving list values for type |
Statuses and System Error Codes
HTTP Status: 4xx, 5xx
The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit |
|
|
|
The request contains no authorization data: neither an access token nor a webhook code was passed |
|
|
|
Methods are called over the HTTPS protocol only |
|
|
|
The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support |
|
|
|
REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — |
|
|
|
No active webhook with the specified user identifier and secret code was found |
|
|
|
No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope |
|
|
|
The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with |
|
|
|
The access token has expired |
|
|
|
The application is installed, but the Bitrix24 administrator has granted access to it only to specific users |
|
|
|
The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site |