Создать новый контакт crm.contact.add
Если вы разрабатываете интеграции для Битрикс24 с помощью AI-инструментов (Codex, Claude Code, Cursor), подключите MCP-сервер, чтобы ассистент использовал официальную REST-документацию.
Scope:
crmКто может выполнять метод: любой пользователь с правом «добавления|импорта» контакта
DEPRECATED
Развитие метода остановлено. Используйте crm.item.add.
Метод crm.contact.add создает новый контакт.
Параметры метода
|
Название |
Описание |
|
fields |
Объект формата: где:
Список доступных полей описан ниже. Некорректное поле в |
|
params |
Объект, содержащий набор дополнительных параметров. Структура и возможные значения описана ниже |
Параметр fields
|
Название |
Описание |
|
HONORIFIC |
Обращение. Список доступных типов обращений можно узнать с помощью метода По умолчанию — первый доступный тип обращения |
|
NAME |
Имя |
|
SECOND_NAME |
Отчество |
|
LAST_NAME |
Фамилия |
|
PHOTO |
Фотография |
|
BIRTHDATE |
Дата рождения |
|
TYPE_ID |
Тип контакта. Список доступных типов контакта можно узнать с помощью метода По умолчанию — первый доступный тип контакта |
|
SOURCE_ID |
Источник. Список доступных типов источника можно узнать с помощью метода По умолчанию — первый доступный тип источника |
|
SOURCE_DESCRIPTION |
Дополнительно об источнике |
|
POST |
Должность |
|
COMMENTS |
Комментарий. Поддерживает bb-коды |
|
OPENED |
Доступен ли для всех. Возможные значения:
По умолчанию |
|
EXPORT |
Участвует ли контакт в экспорте. Возможные значения:
По умолчанию |
|
ASSIGNED_BY_ID |
Идентификатор пользователя, ответственного за элемент. По умолчанию — идентификатор пользователя, который вызывает метод |
|
COMPANY_ID |
Идентификатор основной компании для контакта. Список компаний можно получить с помощью метода |
|
COMPANY_IDS |
Массив идентификаторов компаний, к которым привязан контакт. Список компаний можно получить с помощью метода |
|
UTM_SOURCE |
Рекламная система (Yandex-Direct, Google-Adwords и другие) |
|
UTM_MEDIUM |
Тип трафика. Возможные значения:
|
|
UTM_CAMPAIGN |
Обозначение рекламной кампании |
|
UTM_CONTENT |
Содержание кампании. Например, для контекстных объявлений |
|
UTM_TERM |
Условие поиска кампании. Например, ключевые слова контекстной рекламы |
|
TRACE |
Информация для сквозной аналитики |
|
PHONE |
Телефон |
|
EMAIL |
|
|
WEB |
Сайт |
|
Мессенджер |
|
|
LINK |
Ссылки. Служебное поле |
|
UF_... |
Пользовательские поля. Например, В зависимости от настроек портала у контактов может быть набор пользовательских полей определенных типов. Добавить пользовательское поле в контакт можно с помощью метода crm.contact.userfield.add |
|
PARENT_ID_... |
Поля связей. Если на портале есть смарт-процессы, связанные с контактами, для каждого такого смарт-процесса существует поле, хранящее связь между этим смарт-процессом и контактом. Само поле хранит идентификатор элемента такого смарт-процесса. Например, поле |
Поля связи с внешними источниками данных
Если контакт создан внешней системой, то:
- поле
ORIGINATOR_IDхранит строковый идентификатор этой системы - поле
ORIGIN_IDхранит строковый идентификатор контакта в этой внешней системе - поле
ORIGIN_VERSIONхранит версию данных контакта в этой внешней системе
|
Название |
Описание |
|
ORIGINATOR_ID |
Идентификатор внешней системы, являющейся источником данных об этом контакте |
|
ORIGIN_ID |
Версия данных о контакте во внешней системе. Используется для защиты данных от случайного перетирания внешней системой. Если данные были импортированы и не изменялись во внешней системе, то такие данные могут быть редактированы в CRM без опасения, что следующая выгрузка приведет к перетиранию данных |
|
ORIGIN_VERSION |
Версия оригинала |
Импорт
Данные поля доступны для заполнения при передаче параметра IMPORT = 'Y' в параметр params.
|
Название |
Описание |
|
DATE_CREATE |
Дата создания. Доступен при передаче Не может быть меньше, чем дата создания последнего созданного контакта |
|
DATE_MODIFY |
Дата изменения. Доступен при передаче |
|
CREATED_BY_ID |
Кем создан. Доступен при передаче |
|
MODIFY_BY_ID |
Кем изменен. |
Устаревшие поля
Поля адреса в контакте являются устаревшими и используются только в режиме совместимости. Для работы с адресом используйте реквизиты.
|
Название |
Описание |
|
ADDRESS |
Адрес |
|
ADDRESS_2 |
Вторая строка адреса |
|
ADDRESS_CITY |
Город |
|
ADDRESS_POSTAL_CODE |
Почтовый индекс |
|
ADDRESS_REGION |
Район |
|
ADDRESS_PROVINCE |
Область |
|
ADDRESS_COUNTRY |
Страна |
|
ADDRESS_COUNTRY_CODE |
Код страны |
|
ADDRESS_LOC_ADDR_ID |
Идентификатор адреса местоположения |
Параметр params
|
Название |
Описание |
|
REGISTER_SONET_EVENT |
Производить ли регистрацию события добавления контакта в живой ленте. Возможные значения:
По умолчанию |
|
IMPORT |
Включен ли режим импорта. Возможные значения:
Чтобы передать значение По умолчанию |
Примеры кода
Как использовать примеры в документации
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"FIELDS":{"HONORIFIC":"HNR_RU_1","NAME":"Иван","SECOND_NAME":"Иванович","LAST_NAME":"Иванов","PHOTO":{"fileData":"**put_photo_data_here**"},"BIRTHDATE":"11.11.2001","TYPE_ID":"PARTNER","SOURCE_ID":"WEB","SOURCE_DESCRIPTION":"*Дополнительно об источнике*","POST":"Администратор","COMMENTS":"**put_comment_here**","OPENED":"Y","EXPORT":"N","ASSIGNED_BY_ID":6,"COMPANY_ID":12,"COMPANY_IDS":[12,13,15],"UTM_SOURCE":"yandex","UTM_MEDIUM":"CPC","UTM_CAMPAIGN":"summer_sale","UTM_CONTENT":"header_banner","UTM_TERM":"discount","PHONE":[{"VALUE":"+7333333555","VALUE_TYPE":"WORK"},{"VALUE":"+35599888666","VALUE_TYPE":"HOME"}],"EMAIL":[{"VALUE":"ivanov@example.mailing","VALUE_TYPE":"MAILING"},{"VALUE":"ivanov@example.work","VALUE_TYPE":"WORK"}],"UF_CRM_1720697698689":"Пример значения пользовательского поля с типом \"Строка\"","PARENT_ID_1224":12}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.contact.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"FIELDS":{"HONORIFIC":"HNR_RU_1","NAME":"Иван","SECOND_NAME":"Иванович","LAST_NAME":"Иванов","PHOTO":{"fileData":"**put_photo_data_here**"},"BIRTHDATE":"11.11.2001","TYPE_ID":"PARTNER","SOURCE_ID":"WEB","SOURCE_DESCRIPTION":"*Дополнительно об источнике*","POST":"Администратор","COMMENTS":"**put_comment_here**","OPENED":"Y","EXPORT":"N","ASSIGNED_BY_ID":6,"COMPANY_ID":12,"COMPANY_IDS":[12,13,15],"UTM_SOURCE":"yandex","UTM_MEDIUM":"CPC","UTM_CAMPAIGN":"summer_sale","UTM_CONTENT":"header_banner","UTM_TERM":"discount","PHONE":[{"VALUE":"+7333333555","VALUE_TYPE":"WORK"},{"VALUE":"+35599888666","VALUE_TYPE":"HOME"}],"EMAIL":[{"VALUE":"ivanov@example.mailing","VALUE_TYPE":"MAILING"},{"VALUE":"ivanov@example.work","VALUE_TYPE":"WORK"}],"UF_CRM_1720697698689":"Пример значения пользовательского поля с типом \"Строка\"","PARENT_ID_1224":12},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.contact.add
try
{
const response = await $b24.callMethod(
'crm.contact.add',
{
fields: {
HONORIFIC: "HNR_RU_1",
NAME: "Иван",
SECOND_NAME: "Иванович",
LAST_NAME: "Иванов",
PHOTO: {
fileData: document.getElementById('photo'),
},
BIRTHDATE: '11.11.2001',
TYPE_ID: "PARTNER",
SOURCE_ID: "WEB",
SOURCE_DESCRIPTION: "*Дополнительно об источнике*",
POST: "Администратор",
COMMENTS: `
Пример комментария внутри контакта
[B]Жирный текст[/B]
[I]Курсив[/I]
[U]Подчеркнутый[/U]
[S]Зачеркнутый[/S]
[B][I][U][S]Микс[/S][/U][/I][/B]
[LIST]
[*]Элемент списка #1
[*]Элемент списка #2
[*]Элемент списка #3
[/LIST]
[LIST=1]
[*]Нумерованный элемент списка #1
[*]Нумерованный элемент списка #2
[*]Нумерованный элемент списка #3
[/LIST]
`,
OPENED: "Y",
EXPORT: "N",
ASSIGNED_BY_ID: 6,
COMPANY_ID: 12,
COMPANY_IDS: [12, 13, 15],
UTM_SOURCE: "yandex",
UTM_MEDIUM: "CPC",
UTM_CAMPAIGN: "summer_sale",
UTM_CONTENT: "header_banner",
UTM_TERM: "discount",
PHONE: [
{
VALUE: "+7333333555",
VALUE_TYPE: "WORK",
},
{
VALUE: "+35599888666",
VALUE_TYPE: "HOME",
}
],
EMAIL: [
{
VALUE: "ivanov@example.mailing",
VALUE_TYPE: "MAILING",
},
{
VALUE: "ivanov@example.work",
VALUE_TYPE: "WORK",
}
],
UF_CRM_1720697698689: "Пример значения пользовательского поля с типом \"Строка\"",
PARENT_ID_1224: 12,
},
}
);
const result = response.getData().result;
result.error()
? console.error(result.error())
: console.info(result)
;
}
catch( error )
{
console.error(error);
}
try {
$response = $b24Service
->core
->call(
'crm.contact.add',
[
'fields' => [
'HONORIFIC' => 'HNR_RU_1',
'NAME' => 'Иван',
'SECOND_NAME' => 'Иванович',
'LAST_NAME' => 'Иванов',
'PHOTO' => [
'fileData' => document.getElementById('photo'),
],
'BIRTHDATE' => '11.11.2001',
'TYPE_ID' => 'PARTNER',
'SOURCE_ID' => 'WEB',
'SOURCE_DESCRIPTION' => '*Дополнительно об источнике*',
'POST' => 'Администратор',
'COMMENTS' => '
Пример комментария внутри контакта
[B]Жирный текст[/B]
[I]Курсив[/I]
[U]Подчеркнутый[/U]
[S]Зачеркнутый[/S]
[B][I][U][S]Микс[/S][/U][/I][/B]
[LIST]
[*]Элемент списка #1
[*]Элемент списка #2
[*]Элемент списка #3
[/LIST]
[LIST=1]
[*]Нумерованный элемент списка #1
[*]Нумерованный элемент списка #2
[*]Нумерованный элемент списка #3
[/LIST]
',
'OPENED' => 'Y',
'EXPORT' => 'N',
'ASSIGNED_BY_ID' => 6,
'COMPANY_ID' => 12,
'COMPANY_IDS' => [12, 13, 15],
'UTM_SOURCE' => 'yandex',
'UTM_MEDIUM' => 'CPC',
'UTM_CAMPAIGN' => 'summer_sale',
'UTM_CONTENT' => 'header_banner',
'UTM_TERM' => 'discount',
'PHONE' => [
[
'VALUE' => '+7333333555',
'VALUE_TYPE' => 'WORK',
],
[
'VALUE' => '+35599888666',
'VALUE_TYPE' => 'HOME',
]
],
'EMAIL' => [
[
'VALUE' => 'ivanov@example.mailing',
'VALUE_TYPE' => 'MAILING',
],
[
'VALUE' => 'ivanov@example.work',
'VALUE_TYPE' => 'WORK',
]
],
'UF_CRM_1720697698689' => 'Пример значения пользовательского поля с типом "Строка"',
'PARENT_ID_1224' => 12,
]
]
);
$result = $response
->getResponseData()
->getResult();
echo 'Success: ' . print_r($result, true);
processData($result);
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error adding contact: ' . $e->getMessage();
}
BX24.callMethod(
'crm.contact.add',
{
fields: {
HONORIFIC: "HNR_RU_1",
NAME: "Иван",
SECOND_NAME: "Иванович",
LAST_NAME: "Иванов",
PHOTO: {
fileData: document.getElementById('photo'),
},
BIRTHDATE: '11.11.2001',
TYPE_ID: "PARTNER",
SOURCE_ID: "WEB",
SOURCE_DESCRIPTION: "*Дополнительно об источнике*",
POST: "Администратор",
COMMENTS: `
Пример комментария внутри контакта
[B]Жирный текст[/B]
[I]Курсив[/I]
[U]Подчеркнутый[/U]
[S]Зачеркнутый[/S]
[B][I][U][S]Микс[/S][/U][/I][/B]
[LIST]
[*]Элемент списка #1
[*]Элемент списка #2
[*]Элемент списка #3
[/LIST]
[LIST=1]
[*]Нумерованный элемент списка #1
[*]Нумерованный элемент списка #2
[*]Нумерованный элемент списка #3
[/LIST]
`,
OPENED: "Y",
EXPORT: "N",
ASSIGNED_BY_ID: 6,
COMPANY_ID: 12,
COMPANY_IDS: [12, 13, 15],
UTM_SOURCE: "yandex",
UTM_MEDIUM: "CPC",
UTM_CAMPAIGN: "summer_sale",
UTM_CONTENT: "header_banner",
UTM_TERM: "discount",
PHONE: [
{
VALUE: "+7333333555",
VALUE_TYPE: "WORK",
},
{
VALUE: "+35599888666",
VALUE_TYPE: "HOME",
}
],
EMAIL: [
{
VALUE: "ivanov@example.mailing",
VALUE_TYPE: "MAILING",
},
{
VALUE: "ivanov@example.work",
VALUE_TYPE: "WORK",
}
],
UF_CRM_1720697698689: "Пример значения пользовательского поля с типом \"Строка\"",
PARENT_ID_1224: 12,
},
},
(result) => {
result.error()
? console.error(result.error())
: console.info(result.data())
;
},
);
require_once('crest.php');
$result = CRest::call(
'crm.contact.add',
[
'fields' => [
'HONORIFIC' => 'HNR_RU_1',
'NAME' => 'Иван',
'SECOND_NAME' => 'Иванович',
'LAST_NAME' => 'Иванов',
'PHOTO' => [
'fileData' => document.getElementById('photo'),
],
'BIRTHDATE' => '11.11.2001',
'TYPE_ID' => 'PARTNER',
'SOURCE_ID' => 'WEB',
'SOURCE_DESCRIPTION' => '*Дополнительно об источнике*',
'POST' => 'Администратор',
'COMMENTS' => '
Пример комментария внутри контакта
[B]Жирный текст[/B]
[I]Курсив[/I]
[U]Подчеркнутый[/U]
[S]Зачеркнутый[/S]
[B][I][U][S]Микс[/S][/U][/I][/B]
[LIST]
[*]Элемент списка #1
[*]Элемент списка #2
[*]Элемент списка #3
[/LIST]
[LIST=1]
[*]Нумерованный элемент списка #1
[*]Нумерованный элемент списка #2
[*]Нумерованный элемент списка #3
[/LIST]
',
'OPENED' => 'Y',
'EXPORT' => 'N',
'ASSIGNED_BY_ID' => 6,
'COMPANY_ID' => 12,
'COMPANY_IDS' => [12, 13, 15],
'UTM_SOURCE' => 'yandex',
'UTM_MEDIUM' => 'CPC',
'UTM_CAMPAIGN' => 'summer_sale',
'UTM_CONTENT' => 'header_banner',
'UTM_TERM' => 'discount',
'PHONE' => [
[
'VALUE' => '+7333333555',
'VALUE_TYPE' => 'WORK',
],
[
'VALUE' => '+35599888666',
'VALUE_TYPE' => 'HOME',
]
],
'EMAIL' => [
[
'VALUE' => 'ivanov@example.mailing',
'VALUE_TYPE' => 'MAILING',
],
[
'VALUE' => 'ivanov@example.work',
'VALUE_TYPE' => 'WORK',
]
],
'UF_CRM_1720697698689' => 'Пример значения пользовательского поля с типом "Строка"',
'PARENT_ID_1224' => 12,
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
Обработка ответа
HTTP-статус: 200
{
"result": 46,
"time": {
"start": 1723713732.235658,
"finish": 1723713733.742049,
"duration": 1.5063910484313965,
"processing": 1.1416668891906738,
"date_start": "2024-08-15T11:22:12+02:00",
"date_finish": "2024-08-15T11:22:13+02:00"
}
}
Возвращаемые данные
|
Название |
Описание |
|
result |
Корневой элемент ответа, содержит идентификатор созданного контакта |
|
time |
Информация о времени выполнения запроса |
Обработка ошибок
HTTP-статус: 400
{
"error": "",
"error_description": "Parameter 'fields' must be array."
}
|
Название |
Описание |
|
error |
Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания |
|
error_description |
Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде |
Возможные коды ошибок
|
Код |
Описание |
Значение |
|
|
|
В параметр |
|
|
|
В параметр |
|
|
|
У пользователя нет прав на «Добавление» или «Импорт» контактов |
|
|
Исчерпан выделенный дисковый ресурс |
|
|
|
Поле |
Статусы и коды системных ошибок
HTTP-статус: 20x, 40x, 50x
Описанные ниже ошибки могут возникнуть при вызове любого метода
|
Статус |
Код |
Описание |
|
|
|
Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Превышен лимит на интенсивность запросов |
|
|
|
Текущий метод не разрешен для вызова с помощью batch |
|
|
|
Превышена максимальная длина параметров, переданных в метод batch |
|
|
|
Неверный access-токен или код вебхука |
|
|
|
Для вызовов методов требуется использовать протокол HTTPS |
|
|
|
REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24 |
|
|
|
REST API доступен только на коммерческих планах |
|
|
|
У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав |
|
|
|
Манифест недоступен |
|
|
|
Запрос требует более высоких привилегий, чем предоставляет токен вебхука |
|
|
|
Предоставленный access-токен доступа истек |
|
|
|
Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям |
|
|
|
Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта |
Продолжите изучение
- Изменить контакт crm.contact.update
- Получить контакт по Id crm.contact.get
- Получить список контактов crm.contact.list
- Удалить контакт crm.contact.delete
- Получить поля контакта crm.contact.fields
- Добавить контакт через веб-форму
- Добавить контакт с реквизитами через веб-форму
- Как изменить или удалить номера телефонов и email