Update Existing Custom Field for Leads crm.lead.userfield.update
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:
crmWho can execute the method: CRM administrator
DEPRECATED
The development of this method has been halted. Please use the REST 3.0 method crm.lead.field.custom.update.
The method crm.lead.userfield.update updates an existing custom field for leads.
Method Parameters
Required parameters are marked with *
|
Name |
Description |
|
id* |
Identifier of the custom field. The identifier can be obtained using the methods crm.lead.userfield.add and crm.lead.userfield.list |
|
fields* |
Object in the format:
The list of available fields is described below. An incorrect field in Only those fields that need to be changed should be passed in |
Parameter fields
Required parameters are marked with *
|
Parameter |
Description |
|
MANDATORY |
Is the field mandatory? Possible values:
|
|
SHOW_FILTER |
Should the field be shown in the filter? Possible values:
|
|
XML_ID |
External code |
|
SETTINGS |
Additional parameters for the field. Each field type The field only overwrites the values that are passed |
|
LIST |
List of possible values for the custom field of type |
|
SORT |
Sort index. Must be greater than zero |
|
SHOW_IN_LIST |
Should the custom field be shown in the list? This parameter does not affect anything within Possible values:
|
|
EDIT_IN_LIST |
Allow user editing? Possible values:
|
|
IS_SEARCHABLE |
Are the field values searchable? This parameter does not affect anything within Possible values:
|
|
Filter label in the list. When passing a string, it is set for each language. For languages where no value is explicitly specified, it will be recorded as The field completely overwrites the previous value |
|
|
Header in the list. When passing a string, it is set for each language. For languages where no value is explicitly specified, it will be recorded as The field completely overwrites the previous value |
|
|
Label in the edit form. When passing a string, it is set for each language. For languages where no value is explicitly specified, it will be recorded as The field completely overwrites the previous value |
|
|
Error message |
|
|
Help |
Parameter SETTINGS
Each type of custom field has its own set of additional settings. This method only supports those described below.
|
Name |
Description |
|
DEFAULT_VALUE |
Default value |
|
ROWS |
Number of rows in the input field. Must be greater than 0 |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value |
|
PRECISION |
Number precision. Must be greater than or equal to 0 |
|
Name |
Description |
|
DEFAULT_VALUE |
Default value, where Possible values:
|
|
DISPLAY |
Appearance. Possible values:
|
|
Name |
Description |
|
DEFAULT_VALUE |
Default value.
where:
|
|
Name |
Description |
|
DISPLAY |
Appearance. Possible values:
|
|
LIST_HEIGHT |
Height of the list. Must be greater than 0. Available only when |
|
Name |
Description |
|
IBLOCK_TYPE_ID |
Identifier of the information block type |
|
IBLOCK_ID |
Identifier of the information block |
|
DEFAULT_VALUE |
Default value |
|
DISPLAY |
Appearance. Possible values:
|
|
LIST_HEIGHT |
Height of the list. Must be greater than 0 |
|
ACTIVE_FILTER |
Should elements with the active flag be shown? Possible values:
|
|
Name |
Description |
|
ENTITY_TYPE |
Identifier of the reference type. Use |
|
Name |
Description |
|
LEAD |
Is the binding to Leads enabled? Possible values:
|
|
CONTACT |
Is the binding to Contacts enabled? Possible values:
|
|
COMPANY |
Is the binding to Companies enabled? Possible values:
|
|
DEAL |
Is the binding to Deals enabled? Possible values:
|
Parameter LIST
|
Name |
Description |
|
VALUE |
Value of the list element. List elements with an empty or missing |
|
SORT |
Sort index. Must be greater than or equal to 0 |
|
DEF |
Is the list element the default value? Possible values:
For multiple fields, multiple |
|
XML_ID |
External code of the value. Must be unique within the elements of the custom field |
Code Examples
How to Use Examples in Documentation
Example of Updating a String Type Custom Field
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":536,"fields":{"MANDATORY":"N","SHOW_FILTER":"N","SETTINGS":{"DEFAULT_VALUE":"Hello, World! Default value (changed)","ROWS":10},"SORT":2000,"EDIT_IN_LIST":"N","LIST_FILTER_LABEL":"Hello, World! Filter (changed)","LIST_COLUMN_LABEL":{"en":"Hello, World! Column (changed)","de":"Hallo, Welt! Spalte (geändert)"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit (changed)","de":"Hallo, Welt! Bearbeiten (geändert)"},"ERROR_MESSAGE":{"en":"Hello, World! Error (changed)","de":"Hallo, Welt! Fehler (geändert)"},"HELP_MESSAGE":{"en":"Hello, World! Help (changed)","de":"Hallo, Welt! Hilfe (geändert)"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.lead.userfield.update
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":536,"fields":{"MANDATORY":"N","SHOW_FILTER":"N","SETTINGS":{"DEFAULT_VALUE":"Hello, World! Default value (changed)","ROWS":10},"SORT":2000,"EDIT_IN_LIST":"N","LIST_FILTER_LABEL":"Hello, World! Filter (changed)","LIST_COLUMN_LABEL":{"en":"Hello, World! Column (changed)","de":"Hallo, Welt! Spalte (geändert)"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit (changed)","de":"Hallo, Welt! Bearbeiten (geändert)"},"ERROR_MESSAGE":{"en":"Hello, World! Error (changed)","de":"Hallo, Welt! Fehler (geändert)"},"HELP_MESSAGE":{"en":"Hello, World! Help (changed)","de":"Hallo, Welt! Hilfe (geändert)"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.lead.userfield.update
// 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
try {
const response = await $b24.actions.v2.call.make<boolean>({
method: 'crm.lead.userfield.update',
params: {
id: 536,
fields: {
MANDATORY: 'N',
SHOW_FILTER: 'N',
SETTINGS: {
DEFAULT_VALUE: 'Hello, World! Default value (changed)',
ROWS: 10,
},
SORT: 2000,
EDIT_IN_LIST: 'N',
LIST_FILTER_LABEL: 'Hello, World! Filter (changed)',
LIST_COLUMN_LABEL: {
en: 'Hello, World! Column (changed)',
de: 'Hallo, Welt! Spalte (geändert)',
},
EDIT_FORM_LABEL: {
en: 'Hello, World! Edit (changed)',
de: 'Hallo, Welt! Bearbeiten (geändert)',
},
ERROR_MESSAGE: {
en: 'Hello, World! Error (changed)',
de: 'Hallo, Welt! Fehler (geändert)',
},
HELP_MESSAGE: {
en: 'Hello, World! Help (changed)',
de: 'Hallo, Welt! Hilfe (geändert)',
},
},
},
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('User field updated:', result)
}
} 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 updateLeadUserField() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'crm.lead.userfield.update',
params: {
id: 536,
fields: {
MANDATORY: 'N',
SHOW_FILTER: 'N',
SETTINGS: {
DEFAULT_VALUE: 'Hello, World! Default value (changed)',
ROWS: 10,
},
SORT: 2000,
EDIT_IN_LIST: 'N',
LIST_FILTER_LABEL: 'Hello, World! Filter (changed)',
LIST_COLUMN_LABEL: {
en: 'Hello, World! Column (changed)',
de: 'Hallo, Welt! Spalte (geändert)',
},
EDIT_FORM_LABEL: {
en: 'Hello, World! Edit (changed)',
de: 'Hallo, Welt! Bearbeiten (geändert)',
},
ERROR_MESSAGE: {
en: 'Hello, World! Error (changed)',
de: 'Hallo, Welt! Fehler (geändert)',
},
HELP_MESSAGE: {
en: 'Hello, World! Help (changed)',
de: 'Hallo, Welt! Hilfe (geändert)',
},
},
},
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('User field updated:', result)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', updateLeadUserField)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.crm.lead.userfield.update(
bitrix_id=536,
fields={
"MANDATORY": "N",
"SHOW_FILTER": "N",
"SETTINGS": {
"DEFAULT_VALUE": "Hello, World! Default value (changed)",
"ROWS": 10,
},
"SORT": 2000,
"EDIT_IN_LIST": "N",
"LIST_FILTER_LABEL": "Hello, World! Filter (changed)",
"LIST_COLUMN_LABEL": {
"en": "Hello, World! Column (changed)",
"de": "Hallo, Welt! Spalte (geändert)",
},
"EDIT_FORM_LABEL": {
"en": "Hello, World! Edit (changed)",
"de": "Hallo, Welt! Bearbeiten (geändert)",
},
"ERROR_MESSAGE": {
"en": "Hello, World! Error (changed)",
"de": "Hallo, Welt! Fehler (geändert)",
},
"HELP_MESSAGE": {
"en": "Hello, World! Help (changed)",
"de": "Hallo, Welt! Hilfe (geändert)",
},
},
).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}")
try {
$result = $serviceBuilder
->getCRMScope()
->leadUserfield()
->update(
536,
[
'MANDATORY' => 'N',
'SHOW_FILTER' => 'N',
'SETTINGS' => [
'DEFAULT_VALUE' => 'Hello, World! Default value (changed)',
'ROWS' => 10,
],
'SORT' => 2000,
'EDIT_IN_LIST' => 'N',
'LIST_FILTER_LABEL' => 'Hello, World! Filter (changed)',
]
);
print($result->isSuccess() ? 'Updated' : 'Failed');
} catch (Throwable $e) {
print('Error: ' . $e->getMessage());
}
BX24.callMethod(
'crm.lead.userfield.update',
{
id: 536,
fields: {
MANDATORY: 'N',
SHOW_FILTER: 'N',
SETTINGS: {
DEFAULT_VALUE: 'Hello, World! Default value (changed)',
ROWS: 10,
},
SORT: 2000,
EDIT_IN_LIST: 'N',
LIST_FILTER_LABEL: 'Hello, World! Filter (changed)',
},
},
(result) => {
result.error()
? console.error(result.error())
: console.info(result.data());
}
);
require_once('crest.php');
$result = CRest::call(
'crm.lead.userfield.update',
[
'id' => 536,
'fields' => [
'MANDATORY' => 'N',
'SHOW_FILTER' => 'N',
'SETTINGS' => [
'DEFAULT_VALUE' => 'Hello, World! Default value (changed)',
'ROWS' => 10,
],
'SORT' => 2000,
'EDIT_IN_LIST' => 'N',
'LIST_FILTER_LABEL' => 'Hello, World! Filter (changed)',
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "crm.lead.userfield.update", b24.Params{
"id": 536,
"fields": b24.Params{
"MANDATORY": "N",
"SHOW_FILTER": "N",
"SETTINGS": b24.Params{
"DEFAULT_VALUE": "Hello, World! Default value (changed)",
"ROWS": 10,
},
"SORT": 2000,
"EDIT_IN_LIST": "N",
"LIST_FILTER_LABEL": "Hello, World! Filter (changed)",
"LIST_COLUMN_LABEL": b24.Params{
"en": "Hello, World! Column (changed)",
"de": "Hallo, Welt! Spalte (geändert)",
},
"EDIT_FORM_LABEL": b24.Params{
"en": "Hello, World! Edit (changed)",
"de": "Hallo, Welt! Bearbeiten (geändert)",
},
"ERROR_MESSAGE": b24.Params{
"en": "Hello, World! Error (changed)",
"de": "Hallo, Welt! Fehler (geändert)",
},
"HELP_MESSAGE": b24.Params{
"en": "Hello, World! Help (changed)",
"de": "Hallo, Welt! Hilfe (geändert)",
},
},
})
if err != nil {
return fmt.Errorf("crm.lead.userfield.update: %w", err)
}
var ok bool
if err := json.Unmarshal(res.Result, &ok); err != nil {
return fmt.Errorf("parse response: %w", err)
}
fmt.Println("done:", ok)
Response Handling
HTTP Status: 200
{
"result": true,
"time": {
"start": 1753790234.592207,
"finish": 1753790234.762644,
"duration": 0.17043709754943848,
"processing": 0.11566615104675293,
"date_start": "2025-07-29T14:57:14+02:00",
"date_finish": "2025-07-29T14:57:14+02:00",
"operating_reset_at": 1753790834,
"operating": 0.11564803123474121
}
}
Returned Data
|
Name |
Description |
|
result |
Root element of the response, contains |
|
time |
Information about the request execution time |
Error Handling
HTTP Status: 400
{
"error": "",
"error_description": "Access denied."
}
|
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 |
|
|
Parameter 'fields' must be array |
The passed |
|
|
ID is not defined or invalid |
The passed |
|
|
Access denied |
Occurs when:
|
|
|
The entity with ID 'id' is not found |
The custom field with the passed |
|
|
List item with value XML_ID='XML_ID' already exists |
The passed |