Поля контакта в REST 3.0

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

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

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

Поля контакта возвращают методы crm.contact.get и crm.contact.list, а принимают методы crm.contact.add и crm.contact.update. Значения множественных полей по одному добавляют и удаляют методы crm.contact.addfieldvalue и crm.contact.deletefieldvalue. Список полей с признаками возвращает метод crm.contact.field.list.

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

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

Метод	Принимает	Возвращает
crm.contact.add	Поля таблицы Объект контакта, которые можно изменять, и пользовательские поля. Обязательно хотя бы одно из полей `name` или `lastName`, иначе метод вернет ошибку «At least one of name or lastName is required.»	Идентификатор созданного контакта `id`
crm.contact.update	`id` контакта и те же поля, что `add`. Поля, которых нет в `fields`, сохраняют текущие значения	Признак успеха `true`
crm.contact.get	`id` контакта и `select`	Без `select` — только `id`. С `select` — только перечисленные поля, `id` не добавляется автоматически. Связанный объект целиком, например `assignedBy`, возвращает все свои поля, а путь через точку, например `assignedBy.firstName`, — только выбранные. Подробнее — в разделе Связанные объекты
crm.contact.list	`select`, `filter`, `order`, `pagination`	Без `select` — только `id` каждого контакта. Поля и связанные объекты запрашиваются в `select` так же, как в `get`
crm.contact.addfieldvalue, crm.contact.deletefieldvalue	`id` контакта, имя множественного поля `fieldName` и значение `value`. Подходят поля `phone`, `email`, `web`, `im`, `companiesId`, `observersId` и множественные пользовательские поля. Для других полей метод вернет ошибку «The field is not supported.»	Признак успеха `true`

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

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

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

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

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

Фильтр по полю companiesId сейчас не работает: метод crm.contact.list отвечает HTTP-статусом 500 и ошибкой INTERNAL_SERVER_ERROR. Чтобы найти контакты компании, фильтруйте по основной компании companyId или запросите поле contactsId у компании методом crm.company.get.

Объект контакта

Название `тип`	Описание
id `integer`	Идентификатор контакта. Назначается при создании. Только чтение. Можно фильтровать и сортировать
name `string`	Имя, до 50 символов. При создании контакта обязательно `name` или `lastName`. Можно изменять, фильтровать и сортировать
secondName `string`	Отчество, до 50 символов. Можно изменять, фильтровать и сортировать
lastName `string`	Фамилия, до 50 символов. При создании контакта обязательно `name` или `lastName`. Можно изменять, фильтровать и сортировать
title `string`	Полное имя контакта, которое Битрикс24 собирает из фамилии, имени и отчества, например `Иванов Иван Иванович`. Чтобы изменить, передайте `name`, `secondName` или `lastName`. Только чтение. Фильтровать и сортировать нельзя
honorificId `string`	Идентификатор обращения, например `HNR_RU_1`. Значения возвращает метод crm.dictionary.honorific.list. Можно изменять, фильтровать и сортировать
honorific `object \| null`	Обращение. Объект типа значение справочника. Только чтение. Запрашивается в `select`
post `string`	Должность, до 255 символов. Можно изменять, фильтровать и сортировать
birthdayTime `date \| null`	Дата рождения в формате `YYYY-MM-DD`, например `1990-05-15`. Можно изменять, фильтровать и сортировать
typeId `string`	Идентификатор типа контакта, например `CLIENT`. Значения возвращает метод crm.dictionary.contacttype.list. Можно изменять, фильтровать и сортировать
type `object \| null`	Тип контакта. Объект типа значение справочника. Только чтение. Запрашивается в `select`
export `boolean`	Участвует ли контакт в экспорте контактов: `true` — да, `false` — нет. Можно изменять, фильтровать и сортировать
photo `object \| null`	Фотография контакта. Объект типа файл. Чтобы удалить фотографию, передайте `null`. Можно изменять. Фильтровать и сортировать нельзя
companiesId `integer[]`	Идентификаторы компаний контакта, до 50 значений. Компании возвращает метод crm.company.list. Переданный массив заменяет текущий список компаний. Первая компания массива становится основной и попадает в `companyId`. Можно изменять. Фильтр по полю сейчас возвращает ошибку `INTERNAL_SERVER_ERROR`, сортировать нельзя
companies `object[]`	Компании контакта. Массив объектов типа элемент CRM. Если компаний нет — пустой массив. Только чтение. Запрашивается в `select`
companyId `integer \| null`	Идентификатор основной компании контакта — первой в списке `companiesId`. Чтобы изменить основную компанию, передайте ее первой в `companiesId`. Только чтение. Можно фильтровать и сортировать
company `object \| null`	Основная компания контакта. Объект типа элемент CRM. Только чтение. Запрашивается в `select`
leadId `integer \| null`	Идентификатор лида, из которого создан контакт. Если контакт создан не из лида — `null`. Только чтение. Можно фильтровать и сортировать
lead `object \| null`	Лид, из которого создан контакт. Объект типа элемент CRM. Только чтение. Запрашивается в `select`
phone `object[]`	Телефоны контакта. Массив объектов типа значение множественного поля. Типы телефонов возвращает метод crm.dictionary.phonetype.list. Можно изменять. Фильтровать можно по полям значения через точку, например `["phone.value", "=", "+79990000003"]`. Сортировать нельзя
email `object[]`	Адреса электронной почты. Массив объектов типа значение множественного поля. Типы адресов возвращает метод crm.dictionary.emailtype.list. Метод проверяет формат адреса и на некорректный адрес возвращает ошибку «Поле "Рабочий e-mail" содержит некорректный адрес». Можно изменять. Фильтровать можно по полям значения через точку, например `email.value`. Сортировать нельзя
web `object[]`	Сайты и страницы в соцсетях. Массив объектов типа значение множественного поля. Типы сайтов возвращает метод crm.dictionary.webtype.list. Можно изменять. Фильтровать можно по полям значения через точку, например `web.value`. Сортировать нельзя
im `object[]`	Мессенджеры и открытые линии. Массив объектов типа значение множественного поля. Типы мессенджеров возвращает метод crm.dictionary.imtype.list. Можно изменять. Фильтровать можно по полям значения через точку, например `im.value`. Сортировать нельзя
hasPhone `boolean`	Есть ли у контакта хотя бы один телефон: `true` — да, `false` — нет. Только чтение. Фильтровать и сортировать нельзя
hasEmail `boolean`	Есть ли у контакта хотя бы один адрес почты: `true` — да, `false` — нет. Только чтение. Фильтровать и сортировать нельзя
hasWeb `boolean`	Есть ли у контакта хотя бы один сайт: `true` — да, `false` — нет. Только чтение. Фильтровать и сортировать нельзя
hasIm `boolean`	Есть ли у контакта хотя бы одно значение в поле `im`: `true` — да, `false` — нет. Только чтение. Фильтровать и сортировать нельзя
sourceId `string \| null`	Идентификатор источника, например `WEB`. Источники возвращает метод crm.dictionary.source.list. Можно изменять, фильтровать и сортировать
source `object \| null`	Источник. Объект типа значение справочника. Только чтение. Запрашивается в `select`
sourceDescription `string \| null`	Дополнительная информация об источнике. Можно изменять и фильтровать, сортировать нельзя
assignedById `integer`	Идентификатор ответственного за контакт. Идентификаторы пользователей возвращает метод user.get. Если пользователя нет, метод вернет ошибку «Значение поля не содержится в списке допустимых значений». Можно изменять, фильтровать и сортировать
assignedBy `object`	Ответственный. Объект типа сотрудник. Только чтение. Запрашивается в `select`
observersId `integer[]`	Идентификаторы наблюдателей. Идентификаторы пользователей возвращает метод user.get. Переданный массив заменяет текущий список наблюдателей. Можно изменять и фильтровать, сортировать нельзя. В фильтре `["observersId", "=", 1]` находит контакты, у которых среди наблюдателей есть пользователь `1`
observers `object[]`	Наблюдатели. Массив объектов типа сотрудник. Если наблюдателей нет — пустой массив. Только чтение. Запрашивается в `select`
opened `boolean`	Доступен ли контакт всем пользователям: `true` — да, `false` — нет. Можно изменять, фильтровать и сортировать
comments `string \| null`	Комментарий к контакту. Можно изменять. Фильтровать и сортировать нельзя
utm `object`	UTM-метки контакта. Объект типа UTM-метки. Можно изменять. Фильтровать можно по полям объекта через точку, например `["utm.source", "=", "google"]`. Сортировать нельзя
trackingSourceId `integer \| null`	Идентификатор источника сквозной аналитики. Если источника нет или он в архиве, метод вернет ошибку «Источник сквозной аналитики не найден или находится в архиве». Можно изменять и фильтровать, сортировать нельзя
originatorId `string \| null`	Идентификатор внешней системы, из которой загружен контакт. Используйте вместе с `originId` для связи с записью во внешней системе. Можно изменять, фильтровать и сортировать
originId `string \| null`	Идентификатор контакта во внешней системе. Можно изменять, фильтровать и сортировать
originVersion `string \| null`	Версия записи во внешней системе. Можно изменять. Фильтровать и сортировать нельзя
createdTime `datetime`	Дата и время создания контакта. Только чтение. Можно фильтровать и сортировать
createdById `integer`	Идентификатор пользователя, который создал контакт. Данные пользователя — в объекте `createdBy`. Только чтение. Можно фильтровать и сортировать
createdBy `object`	Пользователь, который создал контакт. Объект типа сотрудник. Только чтение. Запрашивается в `select`
updatedTime `datetime`	Дата и время последнего изменения контакта. Только чтение. Можно фильтровать и сортировать
updatedById `integer`	Идентификатор пользователя, который последним изменил контакт. Только чтение. Можно фильтровать и сортировать
updatedBy `object`	Пользователь, который последним изменил контакт. Объект типа сотрудник. Только чтение. Запрашивается в `select`
lastActivityTime `datetime`	Дата и время последней активности в таймлайне контакта. Только чтение. Можно фильтровать и сортировать
lastActivityById `integer`	Идентификатор автора последней активности в таймлайне. Только чтение. Можно фильтровать и сортировать
lastActivityBy `object`	Автор последней активности в таймлайне. Объект типа сотрудник. Только чтение. Запрашивается в `select`
webformId `integer \| null`	Идентификатор CRM-формы, через которую создан контакт. Если контакт создан не формой — `null`. Список форм возвращает метод crm.form.list. Только чтение. Можно фильтровать и сортировать
webform `object \| null`	CRM-форма, через которую создан контакт. Объект типа CRM-форма. Только чтение. Запрашивается в `select`
lastCommunication `object`	Даты последних коммуникаций с контактом. Объект типа последняя коммуникация. Только чтение. Запрашивается в `select`. Можно фильтровать по полям объекта через точку, например `["lastCommunication.callTime", ">=", "2026-11-01T00:00:00+03:00"]`
entityTypeId `integer`	Идентификатор типа объекта. Для контакта — `3`. Только чтение
canRead `boolean`	Может ли текущий пользователь просматривать контакт: `true` — да, `false` — нет. Только чтение
url `string`	Относительная ссылка на карточку контакта, например `/crm/contact/details/3211/`. Только чтение

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

Поля phone, email, web и im — массивы значений. Каждое значение — объект с полями:

Название `тип`	Описание
id `integer`	Идентификатор значения. Назначается при записи, передавать его нельзя: метод вернет ошибку «Поле "id" не доступно к заполнению»
valueTypeId `string`	Тип значения, например `WORK` или `MOBILE`. Обязательное поле при записи. Допустимые типы для каждого поля возвращают методы crm.dictionary.phonetype.list, crm.dictionary.emailtype.list, crm.dictionary.webtype.list и crm.dictionary.imtype.list
valueType `object`	Тип значения с названием: `id`, `name` — полное название, например `Мобильный телефон`, `nameShort` — краткое, например `Мобильный`. Только чтение
value `string`	Значение: номер телефона, адрес почты, адрес сайта или идентификатор в мессенджере. Обязательное поле при записи

При записи передавайте массив объектов с полями valueTypeId и value:

{
    "phone": [
        {"valueTypeId": "WORK", "value": "+79990000001"},
        {"valueTypeId": "MOBILE", "value": "+79990000002"}
    ]
}

В ответе каждое значение приходит с id и объектом valueType:

{
    "phone": [
        {
            "id": 8871,
            "valueTypeId": "MOBILE",
            "valueType": {
                "id": "MOBILE",
                "name": "Мобильный телефон",
                "nameShort": "Мобильный"
            },
            "value": "+79990000003"
        }
    ]
}

Как работает запись:

crm.contact.update заменяет все значения поля переданным массивом. Значения, которых нет в массиве, удаляются. Другие множественные поля, которых нет в fields, не меняются
пустой массив, например "phone": [], удаляет все значения поля
одно значение добавляет метод crm.contact.addfieldvalue, удаляет — crm.contact.deletefieldvalue. В value передайте объект {"valueTypeId": "MOBILE", "value": "+79990000008"}. Если такое значение уже есть, addfieldvalue вернет ошибку «The field value already exists.»
в одном поле может быть до 50 значений, во всех четырех полях вместе — до 100. При превышении метод вернет ошибку «Too many phone multifields.»

Объект файла

Поле photo. Чтобы загрузить фотографию, передайте объект upload с именем файла и содержимым в Base64 или ссылкой на файл:

{
    "photo": {
        "upload": {
            "name": "photo.png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
        }
    }
}

Вместо data можно передать url — адрес файла. Одновременно передавать data и url нельзя.

В ответе поле содержит данные загруженного файла:

Название `тип`	Описание
id `string`	Идентификатор файла, например `"39933"`
name `string`	Имя файла
url `string`	Адрес для просмотра файла в Битрикс24
downloadUrl `string`	Адрес для скачивания файла через REST. В адресе есть данные авторизации вебхука, не публикуйте его

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

Поле utm. При записи передавайте только нужные метки: при создании остальные получат значение null, при изменении сохранят текущие значения. Каждая метка — строка до 255 символов.

Название `тип`	Описание
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`

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

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

Связанный элемент CRM — company, companies, lead — по имени целиком возвращает только id. Остальные поля элемента запрашивайте через точку. Через точку доступны поля из объекта элемента CRM и любые поля типа связанного элемента, например ["company.title", "company.phone", "company.industryId"]. Поля компании описаны в статье Поля компании в REST 3.0.

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

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

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

Название `тип`	Описание
id `integer`	Идентификатор пользователя
firstName `string`	Имя
lastName `string`	Фамилия
personalGender `string \| null`	Пол: `M` — мужской, `F` — женский. Если пол не указан — `null`
url `string`	Относительная ссылка на профиль пользователя, например `/company/personal/user/1/`
personalPhoto `string \| null`	Ссылка на фотографию пользователя. Если фотографии нет — `null`

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

Поля company, companies, lead.

Название `тип`	Описание
id `integer`	Идентификатор элемента
entityTypeId `integer`	Идентификатор типа объекта: `4` — компания, `1` — лид
canRead `boolean`	Может ли текущий пользователь просматривать элемент
title `string`	Название элемента
url `string`	Относительная ссылка на карточку элемента, например `/crm/company/details/3159/`

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

Поля honorific, type, source.

Название `тип`	Описание
id `string`	Идентификатор значения, например `CLIENT`
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-формы

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

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

Значение поля типа «Деньги» передается объектом {"sum": 150.5, "currencyId": "RUB"}. Строка вида 150.5|RUB не подходит: метод вернет ошибку «В поле UF_CRM_… требуется тип данных MoneyDto для такого запроса».

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

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

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

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

Была ли статья полезна?

Поля лида

Поля компании

Поля контакта в REST 3.0

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

Объект контактаОбъект контакта

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

Объект файлаОбъект файла

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

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

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

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

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

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

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

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

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