Skip to content

user-userfield-add.md

Latest commit

 

History

History
793 lines (673 loc) · 22.3 KB

user-userfield-add.md

File metadata and controls

793 lines (673 loc) · 22.3 KB
Raw

Add custom field user.userfield.add

{% note tip "" %}

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

{% endnote %}

Scope: user.userfield

Who can execute the method: administrator

The user.userfield.add method adds a custom field.

Method Parameters

{% include Note on required parameters %}

#| || Name type | Description || || fields* object| Field values for adding a new custom field || |#

Parameter fields

{% include Note on required parameters %}

#| || Name type | Description || || FIELD_NAME* string| Field name (code). Bitrix24 converts it to uppercase and supplements it with the UF_USR_ prefix:

  • DEALS and UF_DEALS become UF_USR_DEALS
  • UF_USR_DEALS remains unchanged

The resulting field code is returned by the user.userfield.list method || || USER_TYPE_ID* string| Custom field type. Possible values:

  • string — string
  • integer — integer
  • double — number
  • date — date
  • datetime — date with time
  • boolean — Yes / No
  • file — file
  • enumeration — list
  • url — link
  • address — Google Maps address
  • money — money
  • iblock_section — Link to infoblock section
  • iblock_element — Link to infoblock item
  • employee — Link to user
  • crm — Link to CRM item
  • crm_status — Link to CRM directory || || XML_ID string| External code || || SORT integer| Sort order || || MULTIPLE boolean| Whether the field is multiple. Possible values:
  • Y — yes
  • N — no || || MANDATORY boolean| Whether the custom field is required. Possible values:
  • Y — yes
  • N — no || || SHOW_FILTER boolean| Whether to show the field in the list filter. Possible values:
  • Y — yes
  • N — no || || SHOW_IN_LIST boolean| Whether to show the field in the list. Possible values:
  • Y — yes
  • N — no ||
  • || EDIT_IN_LIST boolean| Whether to edit the field in the list. Possible values:
  • Y — yes
  • N — no ||
  • || IS_SEARCHABLE boolean| Whether the field is included in search. Possible values:
  • Y — yes
  • N — no || || SETTINGS object| An object in {"field_1": "value_1", ... "field_N": "value_N"} format to pass additional custom field settings. Settings are described below || || EDIT_FORM_LABEL string| Label in the editing form. You can pass a string or an object with labels by language in {"de": "...", "en": "..."} format. If a string is passed, the value will be set for all languages || || LIST_COLUMN_LABEL string| Column header in the list. You can pass a string or an object with labels by language in {"de": "...", "en": "..."} format. If a string is passed, the value will be set for all languages || || LIST_FILTER_LABEL string| Filter header in the list. You can pass a string or an object with labels by language in {"de": "...", "en": "..."} format. If a string is passed, the value will be set for all languages || || ERROR_MESSAGE string| Error message for invalid input. You can pass a string or an object with texts by language in {"de": "...", "en": "..."} format. If a string is passed, the value will be set for all languages || || HELP_MESSAGE string| Tooltip text for the field. You can pass a string or an object with texts by language in {"de": "...", "en": "..."} format. If a string is passed, the value will be set for all languages || || LABEL string| Default custom field name.

The value will be set in fields LIST_FILTER_LABEL, LIST_COLUMN_LABEL, EDIT_FORM_LABEL, ERROR_MESSAGE, HELP_MESSAGE if no value is provided in them || |#

Parameter SETTINGS {#settings}

Each custom field type has its own set of additional configurations.

{% list tabs %}

  • string

    #| || Name type | Description || || DEFAULT_VALUE string | Default value.

    Default '' || || ROWS integer | Number of lines in the input field. Must be greater than 0.

    Default 1 || |#

  • integer

    #| || Name type | Description || || DEFAULT_VALUE integer | Default value || |#

  • double

    #| || Name type | Description || || DEFAULT_VALUE double | Default value || || PRECISION integer | Number precision. Must be greater than or equal to 0.

    Default 2 || |#

  • boolean

    #| || Name type | Description || || DEFAULT_VALUE integer | Default value, where 1 is yes, 0 is no.

    Possible values:

    • >= 1 -> 1
    • <= 0 -> 0

    Default 0 || || DISPLAY string | Appearance. Possible values:

    • CHECKBOX — checkbox
    • RADIO — radio buttons
    • DROPDOWN — dropdown list

    Default CHECKBOX || |#

  • date|datetime

    #| || Name type | Description || || DEFAULT_VALUE object | Default value.

    Object format:

    {
    VALUE: datetime|date,
    TYPE: 'NONE'|'NOW'|'FIXED',
}

    where:

    • VALUE — default value of type datetime or date
    • TYPE — type of the default value:
      • NONE — do not set a default value
      • NOW — use current time/date
      • FIXED — use time/date from VALUE

    Default value:

    {
    VALUE: '',
    TYPE: 'NONE',
}

    || |#

  • enumeration

    #| || Name type | Description || || DISPLAY string | Appearance. Possible values:

    • LIST — list
    • UI — editable list
    • CHECKBOX — checkboxes
    • DIALOG — entity selection dialog

    Default LIST || || LIST_HEIGHT | List height. Must be greater than 0.

    Available only when DISPLAY = LIST or DISPLAY = UI.

    Default 1 || |#

  • iblock_section|iblock_element

    #| || Name type | Description || || IBLOCK_TYPE_ID string | Infoblock type identifier.

    Default '' || || IBLOCK_ID string | Information block identifier.

    Default 0 || || DEFAULT_VALUE string | Default value.

    Default '' || || DISPLAY string | Appearance. Possible values:

    • DIALOG — dialog
    • UI — editable list
    • LIST — list
    • CHECKBOX — checkboxes

    Default LIST || || LIST_HEIGHT integer | List height. Must be greater than 0.

    Default 1 || || ACTIVE_FILTER boolean | Whether to show items with the activity flag enabled. Possible values:

    • Y — yes
    • N — no

    Default is N || |#

  • crm_status

    #| || Name type | Description || || ENTITY_TYPE string | Directory type identifier.

    Use crm.status.entity.types to find possible values.

    Default '' || |#

  • crm

    If none of the following options are passed, linking to leads (LEAD = Y) will be enabled by default.

    #| || Name type | Description || || LEAD boolean | Whether binding to Leads is enabled. Possible values:

    • Y — yes
    • N — no

    Default is N || || CONTACT boolean | Whether binding to Contacts is enabled. Possible values:

    • Y — yes
    • N — no

    Default is N || || COMPANY boolean | Whether binding to Companies is enabled. Possible values:

    • Y — yes
    • N — no

    Default is N || || DEAL boolean | Whether binding to Deals is enabled. Possible values:

    • Y — yes
    • N — no

    Default is N || |#

  • Python

    from b24pysdk.errors import BitrixAPIError, BitrixSDKException

fields = {
    "FIELD_NAME": "UF_USR_SKILLS_PROFILE",
    "USER_TYPE_ID": "string",
    "XML_ID": "UF_USR_SKILLS_PROFILE",
    "SORT": 150,
    "MULTIPLE": "N",
    "MANDATORY": "N",
    "SHOW_FILTER": "Y",
    "SHOW_IN_LIST": "Y",
    "EDIT_IN_LIST": "Y",
    "IS_SEARCHABLE": "Y",
    "SETTINGS": {
        "DEFAULT_VALUE": "Python integration engineer",
        "ROWS": 3,
    },
    "EDIT_FORM_LABEL": {
        "en": "Skills profile",
    },
    "LIST_COLUMN_LABEL": {
        "en": "Skills profile",
    },
    "LIST_FILTER_LABEL": {
        "en": "Skills profile",
    },
    "ERROR_MESSAGE": {
        "en": "Skills profile is invalid",
    },
    "HELP_MESSAGE": {
        "en": "Store a short integration skills summary.",
    },
    "LABEL": "Skills profile",
}

try:
    bitrix_response = client.user.userfield.add(
        fields=fields,
    ).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("Bitrix SDK error", error.message, sep="\n")
except Exception as error:
    print("Unexpected error", error, sep="\n")

{% endlist %}

{% note info "" %}

If it is necessary to create a custom field with an added custom type via the API, you must specify rest_<app_number>_<added_type_USER_TYPE_ID> in the USER_TYPE_ID field. For example, rest_436278_test_type.

{% endnote %}

Code Examples

{% include Note on examples %}

{% list tabs %}

  • cURL (Webhook)

    curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields": {
        "FIELD_NAME": "UF_USR_DEALS",
        "USER_TYPE_ID": "crm",
        "XML_ID": "UF_CRM_DEALS",
        "SORT": 100,
        "MULTIPLE": "Y",
        "MANDATORY": "N",
        "SHOW_FILTER": "N",
        "SHOW_IN_LIST": "Y",
        "EDIT_IN_LIST": "Y",
        "SETTINGS": {
            "DEAL": "Y"
        },
        "LABEL": "CRM Deal Linking",
        "EDIT_FORM_LABEL": {
            "de": "CRM Deal Linking"
        }
    }
}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/user.userfield.add

  • cURL (OAuth)

    curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields": {
        "FIELD_NAME": "UF_USR_DEALS",
        "USER_TYPE_ID": "crm",
        "XML_ID": "UF_CRM_DEALS",
        "SORT": 100,
        "MULTIPLE": "Y",
        "MANDATORY": "N",
        "SHOW_FILTER": "N",
        "SHOW_IN_LIST": "Y",
        "EDIT_IN_LIST": "Y",
        "SETTINGS": {
            "DEAL": "Y"
        },
        "LABEL": "CRM Deal Linking",
        "EDIT_FORM_LABEL": {
            "de": "CRM Deal Linking"
        }
    },
    "auth": "**put_access_token_here**"
}' \
https://**put_your_bitrix24_address**/rest/user.userfield.add

  • JS (TS)

    // 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 AddUserFieldResult = number

try {
  const response = await $b24.actions.v2.call.make<AddUserFieldResult>({
    method: 'user.userfield.add',
    params: {
      fields: {
        FIELD_NAME: 'UF_USR_DEALS',
        USER_TYPE_ID: 'crm',
        XML_ID: 'UF_CRM_DEALS',
        SORT: 100,
        MULTIPLE: 'Y',
        MANDATORY: 'N',
        SHOW_FILTER: 'N',
        SHOW_IN_LIST: 'Y',
        EDIT_IN_LIST: 'Y',
        SETTINGS: {
          DEAL: 'Y',
        },
        LABEL: 'CRM deals binding',
        EDIT_FORM_LABEL: {
          ru: 'CRM deals binding',
        },
      },
    },
    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 user field with ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

  • JS (UMD)

    <!-- 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: 'user.userfield.add',
        params: {
          fields: {
            FIELD_NAME: 'UF_USR_DEALS',
            USER_TYPE_ID: 'crm',
            XML_ID: 'UF_CRM_DEALS',
            SORT: 100,
            MULTIPLE: 'Y',
            MANDATORY: 'N',
            SHOW_FILTER: 'N',
            SHOW_IN_LIST: 'Y',
            EDIT_IN_LIST: 'Y',
            SETTINGS: {
              DEAL: 'Y',
            },
            LABEL: 'CRM deals binding',
            EDIT_FORM_LABEL: {
              ru: 'CRM deals binding',
            },
          },
        },
        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 user field with ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addUserField)
</script>

  • Python

    from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.user.userfield.add(
        fields={
            "FIELD_NAME": "UF_USER_DEALS",
            "USER_TYPE_ID": "crm",
            "XML_ID": "UF_CRM_DEALS",
            "SORT": 100,
            "MULTIPLE": "Y",
            "MANDATORY": "N",
            "SHOW_FILTER": "N",
            "SHOW_IN_LIST": "Y",
            "EDIT_IN_LIST": "Y",
            "SETTINGS": {
                "DEAL": "Y",
            },
            "LABEL": "Linking to CRM deals",
            "EDIT_FORM_LABEL": {
                "ru": "Linking to CRM deals",
            },
        },
    ).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}")

  • PHP

    try {
    $response = $b24Service
        ->core
        ->call(
            'user.userfield.add',
            [
                'fields' => [
                    'FIELD_NAME' => 'UF_USR_DEALS',
                    'USER_TYPE_ID' => 'crm',
                    'XML_ID' => 'UF_CRM_DEALS',
                    'SORT' => 100,
                    'MULTIPLE' => 'Y',
                    'MANDATORY' => 'N',
                    'SHOW_FILTER' => 'N',
                    'SHOW_IN_LIST' => 'Y',
                    'EDIT_IN_LIST' => 'Y',
                    'SETTINGS' => [
                        'DEAL' => 'Y',
                    ],
                    'LABEL' => 'CRM Deal Linking',
                    'EDIT_FORM_LABEL' => [
                        'de' => 'CRM Deal Linking'
                    ],
                ]
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
    processData($result);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding user field: ' . $e->getMessage();
}

  • BX24.js

    BX24.callMethod(
    'user.userfield.add', 
    {
        fields: {
            FIELD_NAME: "UF_USR_DEALS",
            USER_TYPE_ID: "crm",
            XML_ID: "UF_CRM_DEALS",
            SORT: 100,
            MULTIPLE: "Y",
            MANDATORY: "N",
            SHOW_FILTER: "N",
            SHOW_IN_LIST: "Y",
            EDIT_IN_LIST: "Y",
            SETTINGS: {
                DEAL: "Y",
            },
            LABEL: "CRM Deal Linking",
            EDIT_FORM_LABEL: {
                ru: "CRM Deal Linking"
            },
        },
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
            console.log(result.data());
    }
);

  • PHP CRest

    require_once('crest.php');

$result = CRest::call(
    'user.userfield.add',
    [
        'fields' => [
            'FIELD_NAME' => 'UF_USR_DEALS',
            'USER_TYPE_ID' => 'crm',
            'XML_ID' => 'UF_CRM_DEALS',
            'SORT' => 100,
            'MULTIPLE' => 'Y',
            'MANDATORY' => 'N',
            'SHOW_FILTER' => 'N',
            'SHOW_IN_LIST' => 'Y',
            'EDIT_IN_LIST' => 'Y',
            'SETTINGS' => [
                'DEAL' => 'Y',
            ],
            'LABEL' => 'CRM Deal Linking',
            'EDIT_FORM_LABEL' => [
                'de' => 'CRM Deal Linking'
            ],
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

  • Go

    // client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "user.userfield.add", b24.Params{
	"fields": b24.Params{
		"FIELD_NAME":   "UF_USR_DEALS",
		"USER_TYPE_ID": "crm",
		"XML_ID":       "UF_CRM_DEALS",
		"SORT":         100,
		"MULTIPLE":     "Y",
		"MANDATORY":    "N",
		"SHOW_FILTER":  "N",
		"SHOW_IN_LIST": "Y",
		"EDIT_IN_LIST": "Y",
		"SETTINGS": b24.Params{
			"DEAL": "Y",
		},
		"LABEL": "CRM Deal Linking",
		"EDIT_FORM_LABEL": b24.Params{
		},
	},
})
if err != nil {
	return fmt.Errorf("user.userfield.add: %w", err)
}

var newID b24.ID
if err := json.Unmarshal(res.Result, &newID); err != nil {
	return fmt.Errorf("parse response: %w", err)
}
fmt.Println("id:", newID)

{% endlist %}

Response Handling

HTTP status: 200

{
    "result":177,
    "time":{
        "start":1747301035.550121,
        "finish":1747301037.514112,
        "duration":1.9639909267425537,
        "processing":0.5865437984466553,
        "date_start":"2025-05-15T11:23:55+02:00",
        "date_finish":"2025-05-15T11:23:57+02:00",
        "operating":0
    }
}

Returned Data

#| || Name type | Description || || result integer | Identifier of the created custom field || || time time | Request execution time information || |#

Error Handling

HTTP status: 400

{
   "error":"",
   "error_description":"The \u0027FIELD_NAME\u0027 field is not found."
}

{% include notitle Error handling %}

Possible Error Codes

#| || Code | Description | Value || || ERROR_ARGUMENT | Argument 'USER_TYPE_ID' is null or empty | Not specified USER_TYPE_ID || || ERROR_ARGUMENT | Argument 'HANDLER' is null or empty | Not specified HANDLER || || ERROR_CORE | Field *** for USER object already exists | Field *** for USER object already exists || || ERROR_CORE | Fail to create new user field | Error while creating field || || Empty string | The \u0027FIELD_NAME\u0027 field is not found. | Mandatory field FIELD_NAME is not specified || || Empty string | The \u0027USER_TYPE_ID\u0027 field is not found. | Mandatory field USER_TYPE_ID is not specified || |#

{% include System errors %}

Continue Learning