Add Custom Field userfieldconfig.add

Scope: userfieldconfig, module scope from moduleId (for example, crm)

Who can execute the method: a user with permission to modify object settings in the moduleId (for crm — permission "Allow to modify settings")

The method userfieldconfig.add adds a new custom field.

Method Parameters

Required parameters are marked with *

Name `type`	Description
moduleId* `string`	Identifier of the module where the field is created
field* `object`	Object with custom field settings (detailed description)

Parameter field

Name `type`	Description
entityId* `string`	Identifier of the object for which the field is created. The format depends on the module, for example, `CRM_7` for SPA
fieldName* `string`	Field code in the format `UF_{OBJECT_IDENTIFIER}_{POSTFIX}`. The code must be unique within the object. Allowed characters are `A-Z`, `0-9`, `_`. Maximum length of the code is 50 characters
userTypeId* `string`	Identifier of the field type. The list of available types is returned by the method userfieldconfig.getTypes
xmlId `string`	External identifier of the field
sort `integer`	Sort index. Default is `100`
multiple `boolean`	Indicates whether the field is multiple. Possible values: `Y` or `N`. Default is `N`
mandatory `boolean`	Indicates whether the field is mandatory. Possible values: `Y` or `N`. Default is `N`
showFilter `boolean`	Whether to show the field in the filter. Possible values: `Y` or `N`. Default is `N`
editInList `boolean`	Whether to allow editing the value in the list. Possible values: `Y` or `N`
isSearchable `boolean`	Whether the field values are included in the search. Possible values: `Y` or `N`
settings `object`	Additional settings for the field. The set of keys depends on `userTypeId` (detailed description)
editFormLabel `string`\|`lang_map`	Label in the edit form. When a string is passed, it is used as a general value; when `lang_map` is passed, labels can be specified by languages
helpMessage `string`\|`lang_map`	Help text. When a string is passed, it is used as a general value; when `lang_map` is passed, help messages can be specified by languages
enum `uf_enum_element[]`	Value options for fields of type `enumeration`

The method uses a fixed set of keys in field (see the table above).

Incorrect and unsupported keys in field are ignored.

The keys showInList, listColumnLabel, listFilterLabel, errorMessage, label are not processed by the method userfieldconfig.add, even if passed in field.

Parameter settings

Each field type has its own set of keys in settings.

string

integer

double

boolean

date|datetime

money

url

address

file

enumeration

iblock_section|iblock_element

crm_status

crm

employee

rest_*

Name `type`	Description
DEFAULT_VALUE `string`	Default value
ROWS `integer`	Number of rows in the input field, must be greater than 0
SIZE `integer`	Width of the input field
REGEXP `string`	Regular expression for validation
MIN_LENGTH `integer`	Minimum length of the string
MAX_LENGTH `integer`	Maximum length of the string

Name `type`	Description
DEFAULT_VALUE `integer`	Default value
SIZE `integer`	Width of the input field
MIN_VALUE `integer`	Minimum value
MAX_VALUE `integer`	Maximum value

Name `type`	Description
DEFAULT_VALUE `double`	Default value
PRECISION `integer`	Precision of the number, must be greater than or equal to 0
SIZE `integer`	Width of the input field
MIN_VALUE `double`	Minimum value
MAX_VALUE `double`	Maximum value

Name `type`	Description
DEFAULT_VALUE `integer`	Default value, where `1` = yes and `0` = no
DISPLAY `string`	Appearance, possible values: `CHECKBOX`, `RADIO`, `DROPDOWN`
LABEL `string`	Label for the Yes value
LABEL_CHECKBOX `string`	Label for `CHECKBOX` mode

Name `type`	Description
DEFAULT_VALUE `object`	Default value in the format `{VALUE, TYPE}`, where `TYPE`: `NONE`, `NOW`, `FIXED`
USE_SECOND `boolean`	Use seconds in the `datetime` field
USE_TIMEZONE `boolean`	Use timezone in the `datetime` field

Name `type`	Description
DEFAULT_VALUE `string`	Default value in the format `	{CURRENCY}`

Name `type`	Description
POPUP `boolean`	Open link in a new window
SIZE `integer`	Width of the input field
MIN_LENGTH `integer`	Minimum length of the value
MAX_LENGTH `integer`	Maximum length of the value
DEFAULT_VALUE `string`	Default value
ROWS `integer`	Number of rows in the input field

Name `type`	Description
SHOW_MAP `boolean`	Show map for the address

Name `type`	Description
SIZE `integer`	Width of the input field
LIST_WIDTH `integer`	Width of the preview in the list
LIST_HEIGHT `integer`	Height of the preview in the list
MAX_SHOW_SIZE `integer`	Maximum file size for display
MAX_ALLOWED_SIZE `integer`	Maximum allowed file size
EXTENSIONS `string[]`	List of allowed extensions
TARGET_BLANK `boolean`	Open file in a new tab

Name `type`	Description
DISPLAY `string`	Appearance, possible values: `LIST`, `UI`, `CHECKBOX`, `DIALOG`
LIST_HEIGHT `integer`	Height of the list, must be greater than 0
CAPTION_NO_VALUE `string`	Label for empty value
SHOW_NO_VALUE `boolean`	Show empty value

Name `type`	Description
DISPLAY `string`	Appearance, possible values: `DIALOG`, `UI`, `LIST`, `CHECKBOX`
LIST_HEIGHT `integer`	Height of the list, must be greater than 0
IBLOCK_ID `integer`	Identifier of the information block
DEFAULT_VALUE `string`	Default value
ACTIVE_FILTER `boolean`	Use only active elements

Name `type`	Description
ENTITY_TYPE `string`	Identifier of the CRM reference type. Possible values can be obtained by the method `crm.status.entity.types`

Name `type`	Description
LEAD `boolean`	Enable binding to leads
CONTACT `boolean`	Enable binding to contacts
COMPANY `boolean`	Enable binding to companies
DEAL `boolean`	Enable binding to deals
QUOTE `boolean`	Enable binding to estimates
ORDER `boolean`	Enable binding to orders
SMART_INVOICE `boolean`	Enable binding to invoices
DYNAMIC_* `boolean`	Enable binding to SPA with a specific `typeId`

Separate settings in settings for the employee type are not used.

Settings are defined by the handler of the custom field type.

Type uf_enum_element

Name `type`	Description
value* `string`	Value of the list option
def `boolean`	Default value flag (`Y`/`N`)
sort `integer`	Sort index of the option
xmlId `string`	External identifier of the option

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

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"

const endpoint = "https://**put_your_bitrix24_address**/rest/userfieldconfig.add.json";
        
        fetch(endpoint, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                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 },
                    ],
                },
            }),
        })
            .then((response) => response.json())
            .then((data) => console.log(data))
            .catch((error) => console.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>';

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"
                    },
                    "editFormLabel": {
                        "en": "List of characteristics"
                    },
                    "listColumnLabel": {
                        "en": null
                    },
                    "listFilterLabel": {
                        "en": null
                    },
                    "errorMessage": {
                        "en": null
                    },
                    "helpMessage": {
                        "en": 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 `type`	Description
result `object`	Root element of the response (detailed description)
time `time`	Information about the request execution time

Object result

Name `type`	Description
field `object`	Settings of the created custom field (detailed description)

Object field

Name `type`	Description
id `integer`	Identifier of the field settings
entityId `string`	Identifier of the object
fieldName `string`	Field code
userTypeId `string`	Identifier of the field type
xmlId `string`	External identifier of the field
sort `integer`	Sort index
multiple `boolean`	Multiple value flag (`Y`/`N`)
mandatory `boolean`	Mandatory field flag (`Y`/`N`)
showFilter `boolean`	Flag to show the field in the filter
showInList `boolean`	Flag to show the field in the list
editInList `boolean`	Flag for editing in the list
isSearchable `boolean`	Flag for participation in search
settings `object`	Additional settings for the field (detailed description). The set of keys depends on `userTypeId`
languageId `object`	Languages for which field labels are set
editFormLabel `lang_map`	Labels in the edit form
listColumnLabel `lang_map`	Column labels in the list
listFilterLabel `lang_map`	Filter labels
errorMessage `lang_map`	Error message text
helpMessage `lang_map`	Help text for the field
enum `object[]`	Value options. This field is returned only for `userTypeId = enumeration`

Error Handling

HTTP Status: 400

{
            "error": "",
            "error_description": "The 'FIELD_NAME' field is not found."
        }

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

Possible Error Codes

Code	Description	Value
`-`	Access denied	Insufficient permissions to create a custom field
`-`	You cannot create custom fields	This error may occur if `field.fieldName` does not start with `UF_{entityId}_`
`-`	The 'USER_TYPE_ID' field is not found	Required `field.userTypeId` is not provided
`-`	The 'FIELD_NAME' field is not found	Required `field.fieldName` is not provided
`-`	Field ... already exists	The provided `field.fieldName` is already in use for this object
`-`	Fail to create new user field	Error creating the field on the server side
`-`	Fail to save enumeration field values	Error saving list values for type `enumeration`

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not permitted for calls using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The HTTPS protocol is required for method calls
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block; please contact Bitrix24 technical support to lift it
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is only available on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user associated with the access token or webhook used to call the method lacks the necessary permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the portal administrator has restricted access to this application to specific users only
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site 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

Continue Learning

Working with Custom Fields

Delete Custom Field Settings

Add Custom Field userfieldconfig.add

Method ParametersMethod Parameters

Parameter fieldParameter field

Parameter settingsParameter settings

Type uf_enum_elementType uf_enum_element

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Object resultObject result

Object fieldObject field

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning