Get a list of custom fields for deals crm.deal.userfield.list

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: crm

Who can execute the method: any user with "read" access permission for deals

DEPRECATED

The development of this method has been halted. Please use the REST 3.0 method crm.deal.field.custom.list.

The method crm.deal.userfield.list returns a list of custom fields for deals based on the filter: field names, types, and settings.

Method Parameters

Required parameters are marked with *

Name
type

Description

filter
object

Object format:

{
            field_1: value_1,
            field_2: value_2,
            ...,
            field_n: value_n,
        }

field_n — the field to filter by
value_n — the filter value

If filter is not provided, the method returns all custom deal fields.

All conditions for individual fields are combined using AND. Only exact match is supported: the method silently ignores conditions with the >, <, !, % prefixes and conditions with an array of values. See the list of available fields for filtering below.

order
object

Object format:

{
            field_1: value_1,
            field_2: value_2,
            ...,
            field_n: value_n,
        }

field_n — the field to sort by
value_n — a string value equal to:
- ASC — ascending sort
- DESC — descending sort

Available fields for sorting:

ID — identifier of the custom field
FIELD_NAME — field name with the UF_CRM_ prefix
USER_TYPE_ID — type of the custom field
XML_ID — external code
SORT — sort index

By default:

{
            "SORT": "ASC",
            "ID": "ASC"
        }

Available fields for filtering

Name `type`	Description
ID `integer`	Identifier of the custom field
FIELD_NAME `string`	Field name with the `UF_CRM_` prefix
USER_TYPE_ID `string`	Type of the custom field. Possible values: `string` — string `integer` — integer `double` — number `boolean` — yes/no `datetime` — date/time `date` — date `money` — money `url` — link `address` — address `enumeration` — list `file` — file `employee` — binding to an employee `crm_status` — binding to the CRM directory `iblock_section` — binding to information block sections `iblock_element` — binding to information block elements `crm` — binding to CRM elements custom field types The method crm.userfield.types returns the full list of types available in Bitrix24
XML_ID `string`	External code
SORT `integer`	Sort index
MULTIPLE `char`	Whether the custom field is multiple. Possible values: `Y` — yes `N` — no
MANDATORY `char`	Whether the custom field is mandatory. Possible values: `Y` — yes `N` — no
SHOW_FILTER `char`	Whether to show in the list filter. Possible values: `N` — do not show `I` — exact match `E` — mask `S` — substring
SHOW_IN_LIST `char`	Whether to show in the list. Possible values: `Y` — yes `N` — no
EDIT_IN_LIST `char`	Whether to allow user editing. Possible values: `Y` — yes `N` — no
IS_SEARCHABLE `char`	Whether the field values are searchable. Possible values: `Y` — yes `N` — no
LANG `string`	Language identifier. If you pass `LANG`, the method returns the field labels in this language: `EDIT_FORM_LABEL` — label in the edit form `LIST_COLUMN_LABEL` — header in the list `LIST_FILTER_LABEL` — filter label in the list `ERROR_MESSAGE` — error message `HELP_MESSAGE` — help

Code Examples

How to Use Examples in Documentation

Get a list of custom fields that:

are multiple
are mandatory
have custom field labels in German

Thanks to the filter by the LANG parameter, we will additionally receive field names in the response.

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"filter":{"MULTIPLE":"Y","MANDATORY":"Y","LANG":"de"},"order":{"USER_TYPE_ID":"ASC","SORT":"ASC"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.userfield.list

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"filter":{"MULTIPLE":"Y","MANDATORY":"Y","LANG":"de"},"order":{"USER_TYPE_ID":"ASC","SORT":"ASC"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.deal.userfield.list

// 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 each userfield returned in result[]
        type CrmDealUserfieldListItem = {
          ID: string
          ENTITY_ID: string
          FIELD_NAME: string
          USER_TYPE_ID: string
          XML_ID: string | null
          SORT: string
          MULTIPLE: string
          MANDATORY: string
          SHOW_FILTER: string
          SHOW_IN_LIST: string
          EDIT_IN_LIST: string
          IS_SEARCHABLE: string
        }
        
        try {
          // crm.deal.userfield.list has no pagination: all matching fields come in one response
          const response = await $b24.actions.v2.call.make<CrmDealUserfieldListItem[]>({
            method: 'crm.deal.userfield.list',
            params: {
              filter: {
                MULTIPLE: 'Y',
                MANDATORY: 'Y',
                LANG: 'ru',
              },
              order: {
                USER_TYPE_ID: 'ASC',
                SORT: 'ASC',
              },
            },
            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('Userfields found:', result.length, 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 listDealUserfields() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              // crm.deal.userfield.list has no pagination: all matching fields come in one response
              const response = await $b24.actions.v2.call.make({
                method: 'crm.deal.userfield.list',
                params: {
                  filter: {
                    MULTIPLE: 'Y',
                    MANDATORY: 'Y',
                    LANG: 'ru',
                  },
                  order: {
                    USER_TYPE_ID: 'ASC',
                    SORT: 'ASC',
                  },
                },
                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('Userfields found:', result.length, result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', listDealUserfields)
        </script>


        from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.crm.deal.userfield.list(
                filter={"MULTIPLE": "Y", "MANDATORY": "Y", "LANG": "de"},
                order={"USER_TYPE_ID": "ASC", "SORT": "ASC"},
            ).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 {
            $response = $b24Service
                ->core
                ->call(
                    'crm.deal.userfield.list',
                    [
                        'filter' => [
                            'MULTIPLE' => 'Y',
                            'MANDATORY' => 'Y',
                            'LANG' => 'de',
                        ],
                        'order' => [
                            'USER_TYPE_ID' => 'ASC',
                            'SORT' => 'ASC',
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            print_r($result);
        } catch (Throwable $e) {
            echo $e->getMessage();
        }

BX24.callMethod(
            'crm.deal.userfield.list',
            {
                filter: {
                    MULTIPLE: "Y",
                    MANDATORY: "Y",
                    LANG: "de",
                },
                order: {
                    USER_TYPE_ID: "ASC",
                    SORT: "ASC",
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data())
                ;
            },
        );

require_once('crest.php');
        
        $result = CRest::call(
            'crm.deal.userfield.list',
            [
                'filter' => [
                    'MULTIPLE' => "Y",
                    'MANDATORY' => "Y",
                    'LANG' => "de",
                ],
                'order' => [
                    'USER_TYPE_ID' => "ASC",
                    'SORT' => "ASC",
                ]
            ]
        );
        
        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.deal.userfield.list", b24.Params{
        	"filter": b24.Params{
        		"MULTIPLE":  "Y",
        		"MANDATORY": "Y",
        		"LANG":      "ru",
        	},
        	"order": b24.Params{
        		"USER_TYPE_ID": "ASC",
        		"SORT":         "ASC",
        	},
        }, b24.WithIdempotent())
        if err != nil {
        	return fmt.Errorf("crm.deal.userfield.list: %w", err)
        }
        
        var items []struct {
        	ID         b24.ID `json:"ID"`
        	EntityID   string `json:"ENTITY_ID"`
        	FieldName  string `json:"FIELD_NAME"`
        	UserTypeID string `json:"USER_TYPE_ID"`
        	Sort       string `json:"SORT"`
        	Multiple   string `json:"MULTIPLE"`
        }
        if err := json.Unmarshal(res.Result, &items); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        for _, it := range items {
        	fmt.Println(it.ID, it.EntityID)
        }
        
        // The method returns all fields in one response; Total equals their count.
        if res.Total != nil {
        	fmt.Println("total:", *res.Total)
        }

Response Handling

HTTP status: 200

{
            "result": [
                {
                    "ID": "5815",
                    "ENTITY_ID": "CRM_DEAL",
                    "FIELD_NAME": "UF_CRM_1713790573",
                    "USER_TYPE_ID": "crm_status",
                    "XML_ID": null,
                    "SORT": "100",
                    "MULTIPLE": "Y",
                    "MANDATORY": "Y",
                    "SHOW_FILTER": "I",
                    "SHOW_IN_LIST": "Y",
                    "EDIT_IN_LIST": "Y",
                    "IS_SEARCHABLE": "N",
                    "SETTINGS": {
                        "ENTITY_TYPE": "INDUSTRY"
                    },
                    "EDIT_FORM_LABEL": "Directory",
                    "LIST_COLUMN_LABEL": "Directory",
                    "LIST_FILTER_LABEL": "Directory",
                    "ERROR_MESSAGE": null,
                    "HELP_MESSAGE": null
                },
                {
                    "ID": "6799",
                    "ENTITY_ID": "CRM_DEAL",
                    "FIELD_NAME": "UF_CRM_1724077760",
                    "USER_TYPE_ID": "enumeration",
                    "XML_ID": null,
                    "SORT": "150",
                    "MULTIPLE": "Y",
                    "MANDATORY": "Y",
                    "SHOW_FILTER": "E",
                    "SHOW_IN_LIST": "Y",
                    "EDIT_IN_LIST": "Y",
                    "IS_SEARCHABLE": "N",
                    "SETTINGS": {
                        "DISPLAY": "LIST",
                        "LIST_HEIGHT": 1,
                        "CAPTION_NO_VALUE": "",
                        "SHOW_NO_VALUE": "Y"
                    },
                    "EDIT_FORM_LABEL": "Radio",
                    "LIST_COLUMN_LABEL": "Radio",
                    "LIST_FILTER_LABEL": "Radio",
                    "ERROR_MESSAGE": null,
                    "HELP_MESSAGE": null,
                    "LIST": [
                        {
                            "ID": "3157",
                            "SORT": "10",
                            "VALUE": "Children's Radio",
                            "DEF": "N",
                            "XML_ID": "79b4c576f96e65eb40f390e45c0dc802"
                        },
                        {
                            "ID": "3159",
                            "SORT": "20",
                            "VALUE": "Shanson Radio",
                            "DEF": "N",
                            "XML_ID": "d3ffd89a825f218f5efd79dffd38fbbf"
                        },
                        {
                            "ID": "3161",
                            "SORT": "30",
                            "VALUE": "Love Radio",
                            "DEF": "N",
                            "XML_ID": "dff769fa19d7d7ce8d0677341d221161"
                        },
                        {
                            "ID": "3163",
                            "SORT": "40",
                            "VALUE": "Monte Carlo Radio",
                            "DEF": "N",
                            "XML_ID": "1f22e5c818ce336a42bd0ec94eb69b9e"
                        },
                        {
                            "ID": "3181",
                            "SORT": "130",
                            "VALUE": "DFM Yuriev-Polsky",
                            "DEF": "N",
                            "XML_ID": "fc1c5e6b4a9fd20b4749240b8dbac41a"
                        }
                    ]
                },
                {
                    "ID": "6791",
                    "ENTITY_ID": "CRM_DEAL",
                    "FIELD_NAME": "UF_CRM_1722578010",
                    "USER_TYPE_ID": "file",
                    "XML_ID": null,
                    "SORT": "150",
                    "MULTIPLE": "Y",
                    "MANDATORY": "Y",
                    "SHOW_FILTER": "E",
                    "SHOW_IN_LIST": "Y",
                    "EDIT_IN_LIST": "Y",
                    "IS_SEARCHABLE": "N",
                    "SETTINGS": {
                        "SIZE": 20,
                        "LIST_WIDTH": 0,
                        "LIST_HEIGHT": 0,
                        "MAX_SHOW_SIZE": 0,
                        "MAX_ALLOWED_SIZE": 0,
                        "EXTENSIONS": [],
                        "TARGET_BLANK": "Y"
                    },
                    "EDIT_FORM_LABEL": "Estimate (files)",
                    "LIST_COLUMN_LABEL": "Estimate (files)",
                    "LIST_FILTER_LABEL": "Estimate (files)",
                    "ERROR_MESSAGE": null,
                    "HELP_MESSAGE": null
                },
                {
                    "ID": "5567",
                    "ENTITY_ID": "CRM_DEAL",
                    "FIELD_NAME": "UF_CRM_1709565075",
                    "USER_TYPE_ID": "resourcebooking",
                    "XML_ID": null,
                    "SORT": "1",
                    "MULTIPLE": "Y",
                    "MANDATORY": "Y",
                    "SHOW_FILTER": "N",
                    "SHOW_IN_LIST": "Y",
                    "EDIT_IN_LIST": "Y",
                    "IS_SEARCHABLE": "N",
                    "SETTINGS": {
                        "USE_USERS": "N",
                        "USE_RESOURCES": "Y",
                        "RESOURCES": {
                            "resource": {
                                "XML_ID": "resource",
                                "NAME": "resource",
                                "SECTIONS": [
                                    {
                                        "ID": "7",
                                        "CAL_TYPE": "resource",
                                        "NAME": "Museum Hall"
                                    },
                                    {
                                        "ID": "49",
                                        "CAL_TYPE": "resource",
                                        "NAME": "resource 1"
                                    },
                                    {
                                        "ID": "51",
                                        "CAL_TYPE": "resource",
                                        "NAME": "resource 2"
                                    },
                                    {
                                        "ID": "53",
                                        "CAL_TYPE": "resource",
                                        "NAME": "1"
                                    },
                                    {
                                        "ID": "57",
                                        "CAL_TYPE": "resource",
                                        "NAME": "Resource"
                                    },
                                    {
                                        "ID": "59",
                                        "CAL_TYPE": "resource",
                                        "NAME": "Resource 2"
                                    }
                                ]
                            }
                        },
                        "SELECTED_RESOURCES": [
                            {
                                "type": "resource",
                                "id": "7",
                                "title": "Museum Hall"
                            }
                        ],
                        "SELECTED_USERS": [],
                        "FULL_DAY": "N",
                        "ALLOW_OVERBOOKING": "Y",
                        "USE_SERVICES": "N",
                        "SERVICE_LIST": [
                            {
                                "name": "",
                                "duration": "60"
                            }
                        ],
                        "RESOURCE_LIMIT": -1,
                        "TIMEZONE": "Europe/Berlin",
                        "USE_USER_TIMEZONE": "N"
                    },
                    "EDIT_FORM_LABEL": "MEETING ROOM BOOKING",
                    "LIST_COLUMN_LABEL": "MEETING ROOM BOOKING",
                    "LIST_FILTER_LABEL": "MEETING ROOM BOOKING",
                    "ERROR_MESSAGE": null,
                    "HELP_MESSAGE": null
                }
            ],
            "total": 4,
            "time": {
                "start": 1753793143.219832,
                "finish": 1753793143.529472,
                "duration": 0.30964016914367676,
                "processing": 0.06361007690429688,
                "date_start": "2025-07-29T15:45:43+02:00",
                "date_finish": "2025-07-29T15:45:43+02:00",
                "operating_reset_at": 1753793743,
                "operating": 0
            }
        }

Returned Data

Name `type`	Description
result `object[]`	Array of custom deal fields (detailed description). If no fields match, an empty array `[]`. The method has no pagination: all matching fields come in one response, and the `start` parameter is ignored
total `integer`	The number of found custom fields. Equals the length of the `result` array
time `time`	Information about the execution time of the request

result Array Element

Numeric values of ID and SORT are returned as strings.

Name `type`	Description
ID `string`	Custom field identifier. Used in the methods crm.deal.userfield.get, crm.deal.userfield.update, and crm.deal.userfield.delete
ENTITY_ID `string`	The object the field belongs to. For deals, always `CRM_DEAL`
FIELD_NAME `string`	Field name with the `UF_CRM_` prefix. Deal methods use this name to write and read the field value, for example, crm.deal.update and crm.deal.get. The method itself does not return field values in deals
USER_TYPE_ID `string`	Field type; for values, see the list of fields for filtering
USER_TYPE_OWNER `string`	Identifier of the application that registered the custom field type. Returned only for fields of a custom type
XML_ID `string`	External code. If not set, `null`
SORT `string`	Sort index
MULTIPLE, MANDATORY, SHOW_IN_LIST, EDIT_IN_LIST, IS_SEARCHABLE `char`	Field flags with the values `Y` or `N`; for their meaning, see the list of fields for filtering
SHOW_FILTER `char`	Filter mode: `N`, `I`, `E`, or `S`; for the decoding, see the list of fields for filtering
SETTINGS `object`	Field type settings, for example, `DEFAULT_VALUE` or `PRECISION`. The set of keys depends on `USER_TYPE_ID`. The method crm.userfield.settings.fields returns the list of keys for a type. The default value of `datetime` fields is returned in ISO 8601 format
EDIT_FORM_LABEL, LIST_COLUMN_LABEL, LIST_FILTER_LABEL, ERROR_MESSAGE, HELP_MESSAGE `string`	Field labels in the language from `filter.LANG`. Returned only if `LANG` is passed in the filter. If there is no label in this language, `null`. The method crm.deal.userfield.get returns labels in all languages at once
LIST `object[]`	List items. Returned only for `enumeration` fields, sorted by `SORT`. Each item contains: `ID` — item identifier; pass it as the field value when writing to a deal `SORT` — sort index `VALUE` — item value `DEF` — whether the item is the default: `Y` or `N` `XML_ID` — item external code

Error Handling

HTTP status: 400

{
            "error": "",
            "error_description": "Parameter 'filter' must be array."
        }

Name `type`	Description
error `string`	String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only `error_description` shows the reason
error_description `string`	Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Status	Code	Description	Value
`400`	Empty value	`Parameter 'order' must be array.`	The provided `order` is not an object
`400`	Empty value	`Parameter 'filter' must be array.`	The provided `filter` is not an object
`400`	Empty value	`Access denied.`	The user does not have "read" access permission for deals

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 Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	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
`401`	`NO_AUTH_FOUND` Wrong authorization data	The request contains no authorization data: neither an access token nor a webhook code was passed
`401`	`INVALID_REQUEST` Https required	Methods are called over the HTTPS protocol only
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support
`401`	`ACCESS_DENIED` REST is available only on commercial plans	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 — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	No active webhook with the specified user identifier and secret code was found
`404`	`ERROR_METHOD_NOT_FOUND` Method not 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
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	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 `provided by the access token`
`401`	`expired_token` The access token provided has expired	The access token has expired
`401`	`user_access_error` The user does not have access to the application	The application is installed, but the Bitrix24 administrator has granted access to it only to specific users
`403`	`PORTAL_DELETED` Portal was deleted	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

Continue Learning

Was the article helpful?

Get Deal Custom Field by Id

Delete Deal Custom Field

Get a list of custom fields for deals crm.deal.userfield.list

Method ParametersMethod Parameters

Available fields for filteringAvailable fields for filtering

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

result Array Elementresult Array Element

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning