Поля моей компании в REST 3.0

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

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

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

Моя компания — компания из справочника «Мои компании», от имени которой вы работаете с клиентами. Ее выбирают в сделках, счетах, предложениях и смарт-процессах, например в поле myCompanyId счета.

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

Моя компания устроена как обычная компания CRM, но методы crm.mycompany.* и crm.company.* не пересекаются. crm.mycompany.get по идентификатору компании клиента вернет ошибку «Запись с ID = … не найдена», а crm.mycompany.list компании клиентов не покажет. Поля компаний клиентов описаны в статье Поля компании в REST 3.0.

У моей компании нет методов пользовательских полей crm.mycompany.field.custom.* и обязательности полей crm.mycompany.field.required.*. Пользовательские поля у моих компаний общие с компаниями клиентов, подробнее — в разделе Пользовательские поля.

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

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

Метод

Принимает

Возвращает

crm.mycompany.add

Поля таблицы Объект моей компании, которые можно изменять, и пользовательские поля. Обязательно поле title, иначе метод вернет ошибку «Не заполнено обязательное поле "title"»

Идентификатор созданной компании id

crm.mycompany.update

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

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

crm.mycompany.get

id компании и select

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

crm.mycompany.list

select, filter, order, pagination

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

crm.mycompany.addfieldvalue, crm.mycompany.deletefieldvalue

id компании, имя множественного поля fieldName и значение value. Подходят поля phone, email, web, im, contactsId, observersId и множественные пользовательские поля. Для других полей метод вернет ошибку «The field is not supported.»

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

crm.mycompany.basic.get, crm.mycompany.basic.list

basic.get — id и select, basic.list — select, filter, order, pagination

Сокращенный набор данных: id, title, phone, email, реквизиты requisites и банковские реквизиты bankRequisites. Без select — id и title. Подробнее — на страницах методов

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

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

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

Поля типа datetime возвращаются в формате ISO 8601, например 2026-11-03T14:42:01+03:00. В фильтре по полю datetime тоже передавайте дату со временем.

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

Ответ crm.mycompany.field.list отличается от фактического формата полей. У createdTime, updatedTime и lastActivityTime указан тип object, а приходят строки datetime. У phone, email, web и im указано multiple: false, а приходят массивы. У observersId и contactsId тип элементов указан как object, а передаются и приходят целые числа. Правила проверки validationRules приходят пустыми объектами {}. Ориентируйтесь на таблицу Объект моей компании.

Объект моей компании

Название
тип

Описание

id
integer

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

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

title
string

Название компании, до 255 символов. Обязательное поле при создании компании. Пустую строку crm.mycompany.update не записывает: название не меняется. Это же название показывается в поле myCompany.title сделок, счетов и других элементов.

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

typeId
string | null

Идентификатор типа компании, например CUSTOMER. Значения возвращает метод crm.dictionary.companytype.list.

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

type
object | null

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

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

industryId
string | null

Идентификатор сферы деятельности, например IT. Значения возвращает метод crm.dictionary.industry.list.

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

industry
object | null

Сфера деятельности. Объект типа значение справочника.

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

employeesId
string | null

Идентификатор диапазона количества сотрудников, например EMPLOYEES_2. Значения возвращает метод crm.dictionary.employees.list.

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

employees
object | null

Количество сотрудников. Объект типа значение справочника.

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

revenue
double | null

Годовой оборот, например 1500000.5. Валюту оборота задает поле currencyId.

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

currencyId
string | null

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

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

currency
object | null

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

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

logo
object | null

Логотип компании. Объект типа файл. Чтобы удалить логотип, передайте null.

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

contactsId
integer[]

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

Можно изменять и фильтровать, сортировать нельзя. В фильтре ["contactsId", "=", 3211] находит мои компании, к которым привязан контакт 3211

contacts
object[]

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

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

contactId
integer | null

Идентификатор контакта, для которого эта компания основная. Если компания не основная ни для одного из своих контактов — null. Основную компанию контакта задает порядок в поле companiesId контакта, подробнее — в статье Поля контакта в REST 3.0. Полный список контактов компании — в поле contactsId.

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

contact
object | null

Контакт, для которого эта компания основная. Объект типа элемент CRM.

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

leadId
integer | null

Идентификатор лида, из которого создана компания. Если компания создана не из лида — null.

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

lead
object | null

Лид, из которого создана компания. Объект типа элемент CRM.

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

phone
object[]

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

Можно изменять. Фильтровать можно по полям значения через точку, например ["phone.value", "=", "+79990000001"]. Сортировать нельзя

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 — нет.

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

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"]. Сортировать нельзя

originatorId
string | null

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

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

originId
string | null

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

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

originVersion
string | null

Версия записи во внешней системе.

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

createdTime
datetime

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

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

createdById
integer

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

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

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

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

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

canRead
boolean

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

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

url
string

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

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

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

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

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

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

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

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

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

Поля 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": 8861,
            "valueTypeId": "WORK",
            "valueType": {
                "id": "WORK",
                "name": "Рабочий телефон",
                "nameShort": "Рабочий"
            },
            "value": "+79990000001"
        }
    ]
}

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

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

Объект файла

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

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

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

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

Название
тип

Описание

id
string

Идентификатор файла, например "39935"

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

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

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

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

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

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

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

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

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

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

Поля 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

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

Название
тип

Описание

id
integer

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

entityTypeId
integer

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

canRead
boolean

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

title
string

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

url
string

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

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

Поля type, industry, employees.

Название
тип

Описание

id
string

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

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

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

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

Пользовательские поля у моих компаний и компаний клиентов общие: это одни и те же поля UF_CRM_<код>, например UF_CRM_1687188367. Их передают и запрашивают по имени так же, как стандартные поля. Своих методов пользовательских полей у моей компании нет: crm.mycompany.field.custom.list вернет ошибку BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION. Список полей возвращает метод crm.company.field.custom.list, создают и изменяют их методы crm.company.field.custom.*.

Значение поля типа «Деньги» передается объектом {"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 — массив таких объектов.

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

Предыдущая
Поля смарт-процесса
Следующая
Обзор методов