Поля лида в REST 3.0

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Поля относятся к методам REST 3.0. Особенности вызова и формат ответа новой версии API описаны в обзоре REST 3.0.

Поля лида возвращают методы crm.lead.get и crm.lead.list, а принимают методы crm.lead.add и crm.lead.update. Список полей с признаками возвращает метод crm.lead.field.list.

Часть полей существует в двух видах: как идентификатор и как связанный объект, например assignedById и assignedBy. Идентификатор можно передать при записи, а связанный объект — только запросить в select.

Какие поля принимают и возвращают методы

Метод

Принимает

Возвращает

crm.lead.add

Поля таблицы Объект лида, которые можно изменять, и пользовательские поля. Обязательное поле — title

Идентификатор созданного лида id

crm.lead.update

id лида и те же поля, что add. Поля, которых нет в fields, сохраняют текущие значения

Признак успеха true

crm.lead.get

id лида и select

Без select — только id. С select — только перечисленные поля, id не добавляется автоматически. Связанный объект целиком, например assignedBy, возвращает все свои поля, а путь через точку, например assignedBy.firstName, — только выбранные. Подробнее — в разделе Связанные объекты

crm.lead.list

select, filter, order, pagination

Без select — только id каждого лида. Поля и связанные объекты запрашиваются в select так же, как в get

Поля с пометкой «только чтение» методы add и update не принимают и возвращают ошибку BITRIX_REST_V3_EXCEPTION_VALIDATION_DTOVALIDATIONEXCEPTION с текстом «Поле "hasPhone" не доступно к заполнению». Связанные объекты, например company и stage, тоже только для чтения: для записи передавайте идентификатор — companyId, stageId.

Поля со значениями из справочников метод проверяет при записи. Если значения нет в справочнике, метод вернет ошибку «Значение поля не содержится в списке допустимых значений». Для стадии, обращения, источника и валюты в тексте ошибки перечислены допустимые значения.

Логические поля принимают и возвращают true или false. Значения Y, N, 1 и 0 не подходят: метод вернет ошибку «В поле opened требуется тип данных bool для такого запроса».

Поля типа date принимают и возвращают дату в формате YYYY-MM-DD, например 1990-05-15. Дату со временем или в формате 15.05.1990 такое поле не принимает. Поля типа datetime возвращаются в формате ISO 8601, например 2026-11-03T14:48:48+03:00. В фильтре по полю datetime тоже передавайте дату со временем: значение 2026-11-03 метод не примет.

Фильтровать и сортировать можно только по полям, у которых это указано в описании. На другие поля метод list вернет ошибку «требуется наличие атрибута Filterable» или «Sortable». Через точку можно фильтровать по полям связанных элементов CRM, значений телефона, почты, сайта и мессенджера, объектов lastCommunication и utm, например ["company.title", "=", "Ромашка"] или ["im.valueTypeId", "=", "IMOL"]. По полям сотрудников, стадии и источника, например assignedBy.id или stage.semanticId, фильтр не работает: метод вернет ошибку BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION. Формат фильтра описан на странице crm.<тип>.list и в статье Обзор REST API 3.0.

Поля closed и taxValue есть в ответе crm.lead.field.list, но методы get и list их не принимают. На такое поле в select, filter или order метод вернет ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION.

Объект лида

Название
тип

Описание

title
string

Название лида, до 255 символов. Обязательное поле для создания лида.

Можно изменять, фильтровать и сортировать

honorificId
string | null

Идентификатор обращения, например HNR_RU_1. Обращения возвращает метод crm.dictionary.honorific.list.

Можно изменять, фильтровать и сортировать

honorific
object | null

Обращение. Объект типа значение справочника.

Только чтение. Запрашивается в select

name
string | null

Имя, до 50 символов.

Можно изменять, фильтровать и сортировать

secondName
string | null

Отчество, до 50 символов.

Можно изменять, фильтровать и сортировать

lastName
string | null

Фамилия, до 50 символов.

Можно изменять, фильтровать и сортировать

post
string | null

Должность, до 255 символов.

Можно изменять, фильтровать и сортировать

companyTitle
string | null

Название компании клиента, до 255 символов. Это текст в карточке лида, а не привязка к компании CRM — привязку задает поле companyId.

Можно изменять, фильтровать и сортировать

birthdayTime
date | null

Дата рождения.

Можно изменять, фильтровать и сортировать

statusDescription
string | null

Дополнительная информация о стадии лида.

Можно изменять, фильтровать и сортировать

id
integer

Идентификатор лида. Назначается при создании.

Только чтение. Можно фильтровать и сортировать

createdTime
datetime

Дата и время создания лида.

Только чтение. Можно фильтровать и сортировать

createdById
integer

Идентификатор пользователя, который создал лид.

Только чтение. Можно фильтровать и сортировать

createdBy
object

Пользователь, который создал лид. Объект типа сотрудник.

Только чтение. Запрашивается в select

updatedTime
datetime

Дата и время последнего изменения лида.

Только чтение. Можно фильтровать и сортировать

updatedById
integer

Идентификатор пользователя, который последним изменил лид.

Только чтение. Можно фильтровать и сортировать

updatedBy
object

Пользователь, который последним изменил лид. Объект типа сотрудник.

Только чтение. Запрашивается в select

lastActivityTime
datetime

Дата и время последней активности в таймлайне лида.

Только чтение. Можно фильтровать и сортировать

lastActivityById
integer

Идентификатор автора последней активности в таймлайне.

Только чтение. Можно фильтровать и сортировать

lastActivityBy
object

Автор последней активности в таймлайне. Объект типа сотрудник.

Только чтение. Запрашивается в select

assignedById
integer

Идентификатор ответственного за лид. Идентификаторы пользователей возвращает метод user.get. Если пользователя нет, метод вернет ошибку «Значение поля не содержится в списке допустимых значений».

Можно изменять, фильтровать и сортировать

assignedBy
object

Ответственный. Объект типа сотрудник.

Только чтение. Запрашивается в select

opened
boolean

Доступен ли лид всем пользователям: true — да, false — нет.

Можно изменять, фильтровать и сортировать

comments
string | null

Комментарий к лиду. Поддерживает BB-коды, например [b]текст[/b].

Можно изменять. Фильтровать и сортировать нельзя

originatorId
string | null

Идентификатор внешней системы, из которой пришел лид. Используйте вместе с originId для связи с внешним источником.

Можно изменять, фильтровать и сортировать

originId
string | null

Идентификатор лида во внешней системе.

Можно изменять, фильтровать и сортировать

webformId
integer | null

Идентификатор CRM-формы, через которую создан лид. Если лид создан не формой — null. Список форм возвращает метод crm.form.list.

Только чтение. Можно фильтровать и сортировать

webform
object | null

CRM-форма, через которую создан лид. Объект типа CRM-форма.

Только чтение. Запрашивается в select

lastCommunication
object

Даты последних коммуникаций с клиентом по лиду. Объект типа последняя коммуникация.

Только чтение. Запрашивается в select. Можно фильтровать по полям объекта через точку, например ["lastCommunication.imolTime", ">=", "2026-11-01T00:00:00+03:00"]

entityTypeId
integer

Идентификатор типа объекта. Для лида — 1.

Только чтение

canRead
boolean

Может ли текущий пользователь просматривать лид: true — да, false — нет.

Только чтение

url
string

Относительная ссылка на карточку лида, например /crm/lead/details/1001253/.

Только чтение

stageId
string

Идентификатор стадии лида, например NEW, IN_PROCESS, CONVERTED. У лидов одна воронка. Стадии лида возвращает метод crm.status.list с фильтром ENTITY_ID = STATUS.

Можно изменять, фильтровать и сортировать

stage
object

Стадия лида. Объект типа стадия.

Только чтение. Запрашивается в select

movedTime
datetime

Дата и время последней смены стадии.

Только чтение. Можно фильтровать и сортировать

movedById
integer

Идентификатор пользователя, который последним сменил стадию.

Только чтение. Можно фильтровать и сортировать

movedBy
object

Пользователь, который последним сменил стадию. Объект типа сотрудник.

Только чтение. Запрашивается в select

closed
boolean

Признак закрытого лида.

Только чтение. Поле есть в ответе field.list, но методы get и list его не принимают и возвращают ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION. Группу стадии лида возвращает поле stageSemanticId

stageSemanticId
string

Группа стадии. Возможные значения:

  • P — в работе
  • S — успех
  • F — провал

Только чтение. Можно фильтровать и сортировать

stageSemantic
object

Группа стадии с названием. Объект типа группа стадии.

Только чтение. Запрашивается в select

observersId
integer[]

Идентификаторы наблюдателей. Идентификаторы пользователей возвращает метод user.get.

Можно изменять и фильтровать, сортировать нельзя. В фильтре ["observersId", "=", 1] находит лиды, у которых среди наблюдателей есть пользователь 1

observers
object[]

Наблюдатели. Массив объектов типа сотрудник. Если наблюдателей нет — пустой массив.

Только чтение. Запрашивается в select

contactId
integer | null

Идентификатор основного контакта — первого в списке contactsId. Назначить основной контакт можно методом crm.lead.setprimarycontact.

Только чтение. Можно фильтровать, сортировать нельзя

contact
object | null

Основной контакт. Объект типа элемент CRM.

Только чтение. Запрашивается в select

contactsId
integer[]

Идентификаторы контактов, к которым привязан лид. Контакты возвращает метод crm.contact.list. Переданный массив заменяет текущий список контактов.

Можно изменять и фильтровать, сортировать нельзя

contacts
object[]

Контакты лида. Массив объектов типа элемент CRM. Если контактов нет — пустой массив.

Только чтение. Запрашивается в select

companyId
integer | null

Идентификатор компании CRM, к которой привязан лид. Компании возвращает метод crm.company.list.

Можно изменять, фильтровать и сортировать

company
object | null

Компания. Объект типа элемент CRM.

Только чтение. Запрашивается в select

sourceId
string | null

Идентификатор источника, например CALL. Источники возвращает метод crm.dictionary.source.list.

Можно изменять, фильтровать и сортировать

source
object | null

Источник. Объект типа значение справочника.

Только чтение. Запрашивается в select

sourceDescription
string | null

Дополнительная информация об источнике.

Можно изменять и фильтровать, сортировать нельзя

opportunity
double

Сумма лида, не меньше 0. Способ расчета суммы задает поле isManualOpportunity.

Можно изменять, фильтровать и сортировать

taxValue
double

Сумма налога.

Только чтение. Поле есть в ответе field.list, но методы get и list его не принимают и возвращают ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION

isManualOpportunity
boolean

Режим расчета суммы: true — сумма задается вручную, false — рассчитывается по товарным позициям.

Можно изменять, фильтровать и сортировать

currencyId
string

Идентификатор валюты, например RUB. Валюты возвращает метод crm.currency.list.

Можно изменять, фильтровать и сортировать

currency
object

Валюта. Объект типа валюта.

Только чтение. Запрашивается в select

phone
object[]

Телефоны. Массив объектов типа значение множественного поля. Типы телефонов возвращает метод crm.dictionary.phonetype.list.

Можно изменять: переданный массив заменяет все телефоны лида, например [{"valueTypeId": "WORK", "value": "+79990000001"}]. Можно фильтровать по полям объекта через точку, например ["phone.value", "=", "+79990000001"], сортировать нельзя

email
object[]

Адреса электронной почты. Массив объектов типа значение множественного поля. Типы адресов возвращает метод crm.dictionary.emailtype.list.

Можно изменять: переданный массив заменяет все адреса лида. Можно фильтровать по полям объекта через точку, сортировать нельзя

web
object[]

Сайты. Массив объектов типа значение множественного поля. Типы сайтов возвращает метод crm.dictionary.webtype.list.

Можно изменять: переданный массив заменяет все сайты лида. Можно фильтровать по полям объекта через точку, сортировать нельзя

im
object[]

Мессенджеры и открытые линии. Массив объектов типа значение множественного поля. Типы мессенджеров возвращает метод crm.dictionary.imtype.list.

Можно изменять: переданный массив заменяет все значения этого поля. Можно фильтровать по полям объекта через точку, например ["im.valueTypeId", "=", "IMOL"], сортировать нельзя

hasPhone
boolean

Есть ли у лида хотя бы один телефон: true — да, false — нет.

Только чтение. Фильтровать и сортировать нельзя

hasEmail
boolean

Есть ли у лида хотя бы один адрес почты: true — да, false — нет.

Только чтение. Фильтровать и сортировать нельзя

hasWeb
boolean

Есть ли у лида хотя бы один сайт: true — да, false — нет.

Только чтение. Фильтровать и сортировать нельзя

hasIm
boolean

Есть ли у лида хотя бы одно значение в поле im: true — да, false — нет.

Только чтение. Фильтровать и сортировать нельзя

utm
object | null

UTM-метки лида. Объект типа UTM-метки. Если меток нет — null.

Можно изменять: передайте объект с нужными метками, например {"source": "google", "medium": "cpc"}. Можно фильтровать по полям объекта через точку, например ["utm.source", "=", "google"], сортировать нельзя

trackingSourceId
integer | null

Идентификатор источника сквозной аналитики.

Можно изменять и фильтровать, сортировать нельзя

related<Код типа>Id
integer | null

Идентификатор родительского элемента другого типа объекта, например relatedSmartProcess177Id. Подробнее — в разделе Поля связей с другими типами.

Можно изменять и фильтровать, сортировать нельзя

related<Код типа>
object | null

Родительский элемент другого типа объекта, например relatedSmartProcess177. Объект типа элемент CRM.

Только чтение. Запрашивается в select

Поля related<Код типа>Id и related<Код типа> появляются, когда в Битрикс24 настроена связь, в которой лид подчинен другому типу объекта, например смарт-процессу. Для каждого родительского типа у лида есть пара полей:

  • related<Код типа>Id — идентификатор родительского элемента, например relatedSmartProcess177Id для смарт-процесса с entityTypeId = 177
  • related<Код типа> — родительский элемент как объект типа элемент CRM, например relatedSmartProcess177

Название поля в ответе crm.lead.field.list совпадает с названием родительского типа, например «Закупка оборудования». Метод проверяет, что элемент с переданным идентификатором существует. Если элемента нет, метод вернет ошибку «Значение поля не содержится в списке допустимых значений».

Состав этих полей зависит от связей, настроенных в Битрикс24. Актуальный список возвращает метод crm.lead.field.list.

Связанные объекты

Связанный объект запрашивается в select по имени поля без суффикса Id: assignedBy, stage, honorific. Имя объекта целиком возвращает все его поля, путь через точку — только выбранные, например ["stage.name", "assignedBy.firstName"]. Путь поддерживает один уровень вложенности.

Связанный элемент CRM — contact, company, related<Код типа> — по имени целиком возвращает только id. Остальные поля элемента запрашивайте через точку, например ["company.title", "company.url"].

Если связь не заполнена, объект приходит как null, а массив объектов, например observers, contacts или phone, — как пустой массив.

Объект сотрудника

Поля createdBy, updatedBy, lastActivityBy, assignedBy, movedBy, observers.

Название
тип

Описание

id
integer

Идентификатор пользователя

firstName
string

Имя

lastName
string

Фамилия

personalGender
string | null

Пол: M — мужской, F — женский. Если пол не указан — null

url
string

Относительная ссылка на профиль пользователя, например /company/personal/user/1/

personalPhoto
string | null

Ссылка на фотографию пользователя. Если фотографии нет — null

Объект элемента CRM

Поля contact, contacts, company, related<Код типа>.

Название
тип

Описание

id
integer

Идентификатор элемента

entityTypeId
integer

Идентификатор типа объекта, например 3 — контакт, 4 — компания

canRead
boolean

Может ли текущий пользователь просматривать элемент

title
string

Название элемента. У контакта — фамилия, имя и отчество

url
string

Относительная ссылка на карточку элемента, например /crm/company/details/3/

Телефоны, почта, сайты и мессенджеры

Поля phone, email, web, im. При записи передавайте valueTypeId и value, оба обязательны. Если типа значения нет в справочнике, метод вернет ошибку «Значение поля не содержится в списке допустимых значений».

Название
тип

Описание

id
integer

Идентификатор значения. Назначается при записи, при замене списка значения получают новые идентификаторы

valueTypeId
string

Тип значения, например WORK или MOBILE для телефона

valueType
object

Тип значения с названием: id, name — полное название, nameShort — краткое. Только чтение

value
string

Значение: номер телефона, адрес почты, адрес сайта или идентификатор в мессенджере

Объект стадии

Поле stage.

Название
тип

Описание

id
string

Идентификатор стадии, например NEW

name
string

Название стадии

sort
integer

Порядок стадии

color
string

Цвет стадии в формате #RRGGBB

semanticId
string

Группа стадии: P — в работе, S — успех, F — провал

Объект группы стадии

Поле stageSemantic. Справочник групп возвращает метод crm.dictionary.stagesemantic.list.

Название
тип

Описание

id
string

Идентификатор группы: P, S или F

name
string

Название группы, например Группа стадий "Лид в работе"

Объект значения справочника

Поля honorific и source.

Название
тип

Описание

id
string

Идентификатор значения, например CALL

name
string

Название значения, например Звонок

sort
integer

Порядок сортировки

Объект CRM-формы

Поле webform.

Название
тип

Описание

id
integer

Идентификатор CRM-формы

name
string

Название CRM-формы

Объект последней коммуникации

Поле lastCommunication. Если коммуникации такого вида не было, поле равно null.

Название
тип

Описание

communicationTime
datetime | null

Дата и время последней коммуникации любого вида

callTime
datetime | null

Дата и время последнего звонка

emailTime
datetime | null

Дата и время последнего письма

imolTime
datetime | null

Дата и время последнего сообщения в открытой линии

webformTime
datetime | null

Дата и время последнего заполнения CRM-формы

Объект валюты

Поле currency.

Название
тип

Описание

id
string

Код валюты, например RUB

fullName
string

Название валюты

formatString
string

Шаблон вывода суммы. Символ # заменяется суммой. Знак валюты приходит HTML-сущностью, например # &#8381;

decPoint
string

Десятичный разделитель

thousandsSep
string

Разделитель разрядов. Может приходить HTML-сущностью, например &nbsp;

decimals
integer

Количество знаков после запятой

hideZero
boolean

Скрывать ли незначащие нули в дробной части

amount
double

Курс валюты относительно базовой

amountCount
integer

Количество единиц валюты, к которому относится курс

base
boolean

Базовая валюта: true — да, false — нет

sort
integer

Порядок сортировки

numericCode
string

Цифровой код валюты, например 643

languageId
string

Язык, для которого заданы название и формат

createdTime
datetime | null

Дата и время создания валюты

updatedTime
datetime | null

Дата и время изменения валюты

createdById
integer | null

Идентификатор пользователя, который создал валюту

updatedById
integer | null

Идентификатор пользователя, который изменил валюту

Объект UTM-меток

Поле utm. Каждая метка — строка до 255 символов. Метки, которые не переданы, приходят как null.

Название
тип

Описание

source
string | null

Рекламная система, метка utm_source, например google

medium
string | null

Тип трафика, метка utm_medium, например cpc

campaign
string | null

Рекламная кампания, метка utm_campaign

content
string | null

Содержание объявления, метка utm_content

term
string | null

Ключевая фраза, метка utm_term

Пользовательские поля

Пользовательские поля лида называются UF_CRM_<код>, например UF_CRM_1687961618. Их передают и запрашивают по имени так же, как стандартные поля. Список пользовательских полей возвращает метод crm.lead.field.custom.list.

У каждого пользовательского поля есть парное поле UF_CRM_…_data — только для чтения, запрашивается в select. Оно содержит значение в нескольких представлениях:

  • value — значение в том же формате, что в самом поле
  • rawValue — значение в формате хранения, например 100.5|RUB для поля «Деньги»
  • formattedValue — значение для показа пользователю: 100.50 ₽ для денег, имя сотрудника для поля «Привязка к сотруднику», текст варианта для списка
  • extra — дополнительные данные: для денег — amount, currencyId и currencyFullName, для сотрудника — поля объекта сотрудника. Для строки, даты и списка — null

У множественного пользовательского поля UF_CRM_…_data — массив таких объектов.

Продолжите изучение

Предыдущая
Поля сделки
Следующая
Поля контакта