Создать новый лид crm.lead.add

Scope: crm

Кто может выполнять метод: любой пользователь с правом на создание лидов

DEPRECATED

Развитие метода остановлено. Используйте crm.item.add.

Метод crm.lead.add создает новый лид.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

fields
object

Объект формата:

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

где:

field_n — название поля
value_n — значение поля

Список доступных полей описан ниже

params
object

Необязательный массив опций ("optionName"=>"value"[, ...]). Перечень возможных полей описан ниже

Параметр fields

Название
тип

Описание

ADDRESS
string

Адрес

ADDRESS_2
string

Вторая страница адреса. В некоторых странах принято разбивать адрес на 2 части

ADDRESS_CITY
string

Город

ADDRESS_COUNTRY
string

Страна

ADDRESS_COUNTRY_CODE
string

Код страны

ADDRESS_POSTAL_CODE
string

Почтовый индекс

ADDRESS_PROVINCE
string

Область

ADDRESS_REGION
string

Район

ASSIGNED_BY_ID
user

Ответственный

BIRTHDATE
date

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

COMMENTS
string

Комментарии

COMPANY_ID
crm_company

Привязка лида к компании

COMPANY_TITLE
string

Название компании, указанное в соответствующем поле лида. Для привязки существующей компании стоит передавать её id в поле COMPANY_ID

CONTACT_ID
crm_contact

Привязка лида к контакту

CONTACT_IDS
crm_contact

Список привязанных к лиду контактов.

Контакты можно добавлять или удалять группой методов crm.lead.contact.*

CURRENCY_ID
crm_currency

Идентификатор валюты

EMAIL
crm_multifield

Адрес электронной почты. Множественное

HONORIFIC
crm_status

Вид обращения

IM
crm_multifield

Мессенджер. Множественное

LINK
crm_multifield

ID пользователя, привязанного через открытую линию. Множественное

LAST_NAME
string

Фамилия

NAME
string

Имя

SECOND_NAME
string

Отчество

OPENED
char

Признак доступности лида для всех. Допустимые значения Y или N.

OPPORTUNITY
double

Сумма

IS_MANUAL_OPPORTUNITY
char

Признак ручного режима расчёта суммы. Допустимые значения Y или N

ORIGINATOR_ID
string

Идентификатор источника данных.

Используется только для привязки к внешнему источнику

ORIGIN_ID
string

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

PHONE
crm_multifield

Телефон. Множественное

POST
string

Должность

SOURCE_DESCRIPTION
string

Описание источника

SOURCE_ID
crm_status

Идентификатор источника.
Значения по умолчанию:

SOURCE_ID	Название
CALL	Звонок
EMAIL	Электронная почта
WEB	Веб-сайт
ADVERTISING	Реклама
PARTNER	Существующий клиент
RECOMMENDATION	По рекомендации
TRADE_SHOW	Выставка
WEBFORM	CRM-форма
CALLBACK	Обратный звонок
RC_GENERATOR	Генератор продаж
STORE	Интернет-магазин
OTHER	Другое

Список всех возможных идентификаторов из справочника можно получить методом crm.status.list с фильтром filter[ENTITY_ID]=SOURCE

STATUS_DESCRIPTION
string

Дополнительно о стадии

STATUS_ID
crm_status

Идентификатор стадии лида. Стадии по умолчанию:

STATUS_ID	Название
NEW	Не обработан
IN_PROCESS	В работе
PROCESSED	Обработан
JUNK	Некачественный лид
CONVERTED	Качественный лид

Список всех возможных стадий из справочника можно получить методом crm.status.list с фильтром filter[ENTITY_ID]=STATUS

TITLE
string

Название лида

UTM_CAMPAIGN
string

Обозначение рекламной кампании

UTM_CONTENT
string

Содержание кампании. Например, для контекстных объявлений

UTM_MEDIUM
string

Тип трафика. CPC (объявления), CPM (баннеры)

UTM_SOURCE
string

Рекламная система. Yandex-Direct, Google-Adwords и другие

UTM_TERM
string

Условие поиска кампании. Например, ключевые слова контекстной рекламы

WEB
crm_multifield

Сайт. Множественное

UF_...

Пользовательские поля. Например, UF_CRM_25534736.

В зависимости от настроек портала у лидов может быть набор пользовательских полей определенных типов.

Для создания, изменения или удаления пользовательских полей в лидах используйте методы crm.lead.userfield.*

Примечание

Так же, чтобы узнать требуемый формат полей, можно выполнить метод crm.lead.fields и посмотреть формат пришедших значений этих полей.

Примечание

При добавлении лида нельзя явно установить признак повторного лида (поле IS_RETURN_CUSTOMER), однако, это поле автоматически принимает значение Y, если при добавлении лида указать значение для COMPANY_ID или CONTACT_ID

Параметр params

Название `тип`	Описание
REGISTER_SONET_EVENT `boolean`	Флаг `Y`/`N` - произвести регистрацию события добавления лида. Дополнительно будет отправлено уведомление ответственному за лид

Примеры кода

Как использовать примеры в документации

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"TITLE":"ИП Титов","NAME":"Глеб","SECOND_NAME":"Егорович","LAST_NAME":"Титов","STATUS_ID":"NEW","OPENED":"Y","ASSIGNED_BY_ID":1,"CURRENCY_ID":"USD","OPPORTUNITY":12500,"PHONE":[{"VALUE":"555888","VALUE_TYPE":"WORK"}],"WEB":[{"VALUE":"www.mysite.com","VALUE_TYPE":"WORK"}]},"params":{"REGISTER_SONET_EVENT":"Y"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.lead.add

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"TITLE":"ИП Титов","NAME":"Глеб","SECOND_NAME":"Егорович","LAST_NAME":"Титов","STATUS_ID":"NEW","OPENED":"Y","ASSIGNED_BY_ID":1,"CURRENCY_ID":"USD","OPPORTUNITY":12500,"PHONE":[{"VALUE":"555888","VALUE_TYPE":"WORK"}],"WEB":[{"VALUE":"www.mysite.com","VALUE_TYPE":"WORK"}]},"params":{"REGISTER_SONET_EVENT":"Y"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.lead.add

try
        {
        	const response = await $b24.callMethod(
        		'crm.lead.add',
        		{
        			fields:
        			{
        				TITLE: 'ИП Титов',
        				NAME: 'Глеб',
        				SECOND_NAME: 'Егорович',
        				LAST_NAME: 'Титов',
        				STATUS_ID: 'NEW',
        				OPENED: 'Y',
        				ASSIGNED_BY_ID: 1,
        				CURRENCY_ID: 'USD',
        				OPPORTUNITY: 12500,
        				PHONE: [
        					{ 
        						VALUE: '555888',
        						VALUE_TYPE: 'WORK',
        					},
        				],
        				WEB: [
        					{
        						VALUE: 'www.mysite.com',
        						VALUE_TYPE: 'WORK',
        					}
        				],
        			},
        			params: {
        				REGISTER_SONET_EVENT: 'Y',
        			}
        		}
        	);
        	
        	const result = response.getData().result;
        	console.info(`Создан лид с ID ${result}`);
        }
        catch( error )
        {
        	console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.lead.add',
                    [
                        'fields' => [
                            'TITLE'          => 'ИП Титов',
                            'NAME'           => 'Глеб',
                            'SECOND_NAME'    => 'Егорович',
                            'LAST_NAME'      => 'Титов',
                            'STATUS_ID'      => 'NEW',
                            'OPENED'         => 'Y',
                            'ASSIGNED_BY_ID' => 1,
                            'CURRENCY_ID'    => 'USD',
                            'OPPORTUNITY'    => 12500,
                            'PHONE'          => [
                                [
                                    'VALUE'      => '555888',
                                    'VALUE_TYPE' => 'WORK',
                                ],
                            ],
                            'WEB'            => [
                                [
                                    'VALUE'      => 'www.mysite.com',
                                    'VALUE_TYPE' => 'WORK',
                                ],
                            ],
                        ],
                        'params' => [
                            'REGISTER_SONET_EVENT' => 'Y',
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Создан лид с ID ' . $result;
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Ошибка при создании лида: ' . $e->getMessage();
        }

BX24.callMethod(
            "crm.lead.add",
            {
                fields:
                {
                    TITLE: "ИП Титов",
                    NAME: "Глеб",
                    SECOND_NAME: "Егорович",
                    LAST_NAME: "Титов",
                    STATUS_ID: "NEW",
                    OPENED: "Y",
                    ASSIGNED_BY_ID: 1,
                    CURRENCY_ID: "USD",
                    OPPORTUNITY: 12500,
                    PHONE: [
                        { 
                            VALUE: "555888",
                            VALUE_TYPE: "WORK",
                        },
                    ] ,
                    WEB: [
                            {
                            VALUE: "www.mysite.com",
                            VALUE_TYPE: "WORK",
                            }
                    ],
                },
                params: {
                    REGISTER_SONET_EVENT: "Y",
                }
            },
            (result) => {
                if (result.error())
                {
                    console.error(result.error());
                    
                    return;
                }
                
                console.info(`Создан лид с ID ${result.data()}`);
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'crm.lead.add',
            [
                'fields' => [
                    'TITLE' => 'ИП Титов',
                    'NAME' => 'Глеб',
                    'SECOND_NAME' => 'Егорович',
                    'LAST_NAME' => 'Титов',
                    'STATUS_ID' => 'NEW',
                    'OPENED' => 'Y',
                    'ASSIGNED_BY_ID' => 1,
                    'CURRENCY_ID' => 'USD',
                    'OPPORTUNITY' => 12500,
                    'PHONE' => [
                        [
                            'VALUE' => '555888',
                            'VALUE_TYPE' => 'WORK',
                        ],
                    ],
                    'WEB' => [
                        [
                            'VALUE' => 'www.mysite.com',
                            'VALUE_TYPE' => 'WORK',
                        ],
                    ],
                ],
                'params' => [
                    'REGISTER_SONET_EVENT' => 'Y',
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Обработка ответа

HTTP-статус: 200

{
            "result": 3465,
            "time": {
                "start": 1705764932.998683,
                "finish": 1705764937.173995,
                "duration": 4.1753120422363281,
                "processing": 3.3076529502868652,
                "date_start": "2024-01-20T18:35:32+03:00",
                "date_finish": "2024-01-20T18:35:37+03:00",
                "operating_reset_at": 1705765533,
                "operating": 3.3076241016387939
            }
        }

Возвращаемые данные

Название `тип`	Описание
result `integer`	Корневой элемент ответа, содержит идентификатор созданного лида
time `time`	Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 40x, 50x Error

{
            "error": "",
            "error_description": "Access denied."
        }

Название `тип`	Описание
error `string`	Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания
error_description `error_description`	Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные ошибки

Код	Текст ошибки	Описание
Пустое значение	Access denied.	У пользователя нет прав на добавление лида

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	Текущий метод не разрешен для вызова с помощью batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	Превышена максимальная длина параметров, переданных в метод batch
`401`	`NO_AUTH_FOUND` Wrong authorization data	Неверный access-токен или код вебхука
`400`	`INVALID_REQUEST` Https required	Для вызовов методов требуется использовать протокол HTTPS
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	REST API доступен только на коммерческих планах
`403`	`INVALID_CREDENTIALS` Invalid request credentials	У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	Манифест недоступен
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более высоких привилегий, чем предоставляет токен вебхука
`401`	`expired_token` The access token provided has expired	Предоставленный access-токен доступа истек
`403`	`user_access_error` The user does not have access to the application	Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям
`500`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Обзор методов

Изменить лид

Создать новый лид crm.lead.add

Параметры методаПараметры метода

Параметр fieldsПараметр fields

Параметр paramsПараметр params

Примеры кодаПримеры кода

Обработка ответаОбработка ответа

Возвращаемые данныеВозвращаемые данные

Обработка ошибокОбработка ошибок

Возможные ошибкиВозможные ошибки

Статусы и коды системных ошибокСтатусы и коды системных ошибок

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