Для AI-агентов: markdown этой страницы — /docs-content/entities/leads/create.md индекс документации — /llms.txt

Создать лид

POST /v1/leads

Создаёт новый лид в CRM.

Поля запроса (body)

Параметр Тип Описание
Параметрtitle Типstring ОписаниеНазвание лида
Параметрname Типstring ОписаниеИмя контакта
ПараметрlastName Типstring ОписаниеФамилия контакта
ПараметрsecondName Типstring ОписаниеОтчество
ПараметрstageId Типstring ОписаниеСтатус лида — каноническое имя, принимается и алиас statusId. Стандартные: NEW, IN_PROCESS, PROCESSED. Портал может иметь свои — список: GET /v1/statuses?filter[entityId]=STATUS. В ответе значение возвращается в поле stageId. Перед записью сверяется со справочником буквально — статус, которого нет, отклоняется кодом UNKNOWN_STAGE, запись не создаётся. Пустое значение не проверяется: лид ложится на статус по умолчанию
Параметрopportunity Типnumber ОписаниеСумма — каноническое имя, принимается и алиас amount. Важно: чтобы значение сохранилось, передайте в том же запросе isManualOpportunity: true — иначе Битрикс24 пересчитает сумму по товарным позициям
ПараметрisManualOpportunity Типboolean ОписаниеРучной режим суммы (см. opportunity)
Параметрcurrency Типstring ОписаниеВалюта (алиас currencyId). Список: GET /v1/currencies
ПараметрcompanyTitle Типstring ОписаниеНазвание компании (текст, не ID)
Параметрphone Типstring | string[] | object[] ОписаниеТелефон. Принимает три формы: строка "+7...", массив строк ["+7...", "+7..."], или массив объектов [{ "value": "+7...", "typeId": "WORK" }, …]. typeId: WORK | HOME | MOBILE | OTHER (по умолчанию WORK). Важно: UPPER-форма [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] не принимается — вернёт 400 INVALID_MULTIFIELD_SHAPE. Используйте camelCase: [{ "value": "...", "typeId": "WORK" }]
Параметрemail Типstring | string[] | object[] ОписаниеEmail. Принимает три формы: строка "a@b.com", массив строк ["a@b.com", "b@c.com"], или массив объектов [{ "value": "a@b.com", "typeId": "WORK" }, …]. typeId: WORK | HOME | MAILING | OTHER (по умолчанию WORK). Важно: UPPER-форма [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] не принимается — вернёт 400 INVALID_MULTIFIELD_SHAPE. Используйте camelCase: [{ "value": "...", "typeId": "WORK" }]
Параметрpost Типstring ОписаниеДолжность
Параметрcomments Типstring ОписаниеКомментарий
ПараметрsourceId Типstring ОписаниеИсточник. Список: GET /v1/statuses?filter[entityId]=SOURCE
ПараметрsourceDescription Типstring ОписаниеОписание источника
ПараметрassignedById Типnumber ОписаниеОтветственный. Список: GET /v1/users
Параметрopened Типboolean ОписаниеДоступен для всех
ПараметрufCrm* Типпо схеме поля ОписаниеПользовательское поле портала, например ufCrmProjectCode. Рабочее имя и тип — в схеме GET /v1/leads/fields, формат значения по типам — Пользовательские поля (UF). В поле типа enumeration записывается ID варианта из массива items этого поля в схеме, в множественное поле — массив таких ID. Подпись VALUE на месте ID теряется: поле с одним значением получает 0. Число, которого нет среди вариантов, сохраняется как есть. Ни подпись, ни несуществующий ID не дают ошибки, ответ приходит с кодом 201, поэтому сопоставляйте подпись с ID на своей стороне и сверяйте сохранённое значение по этому полю в data ответа

Полный список полей: GET /v1/leads/fields.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/leads \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Заявка с сайта",
    "name": "Мария",
    "lastName": "Сидорова",
    "phone": "+79161234567",
    "sourceId": "WEB",
    "stageId": "NEW"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/leads \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Заявка с сайта",
    "name": "Мария",
    "lastName": "Сидорова",
    "phone": "+79161234567",
    "sourceId": "WEB",
    "stageId": "NEW"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/leads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Заявка с сайта',
    name: 'Мария',
    lastName: 'Сидорова',
    phone: '+79161234567',
    sourceId: 'WEB',
    stageId: 'NEW',
  }),
})

const { success, data } = await res.json()
console.log('Lead ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/leads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Заявка с сайта',
    name: 'Мария',
    lastName: 'Сидорова',
    phone: '+79161234567',
    sourceId: 'WEB',
    stageId: 'NEW',
  }),
})

const { success, data } = await res.json()

Альтернативная форма — массив объектов с явным `typeId`

Если нужно указать несколько значений или явный тип (HOME, MOBILE):

JSON 
{
  "phone": [
    { "value": "+79161234567", "typeId": "WORK" },
    { "value": "+79161112233", "typeId": "MOBILE" }
  ],
  "email": [
    { "value": "work@company.ru", "typeId": "WORK" },
    { "value": "personal@me.ru", "typeId": "HOME" }
  ]
}

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном создании
Полеdata Типobject ОписаниеСозданный лид. Полный список полей — Поля лида
Полеdata.id Типnumber ОписаниеID созданного лида
Полеdata.title Типstring ОписаниеНазвание
Полеdata.stageId Типstring ОписаниеСтатус лида
Полеdata.assignedById Типnumber ОписаниеОтветственный
Полеdata.createdBy Типnumber ОписаниеСоздатель
Полеdata.createdTime Типdatetime ОписаниеДата создания

URL карточки лида в Битрикс24 строится из data.id:

https://<portal>.bitrix24.ru/crm/lead/details/<id>/

<portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": 5001,
    "title": "Заявка с сайта",
    "stageId": "NEW",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T13:00:00+03:00",
    "updatedTime": "2026-04-15T13:00:00+03:00",
    "opened": true,
    "sourceId": "WEB"
  }
}

Пример ответа при ошибке

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Ошибки

HTTP Код Описание
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов
HTTP400 КодINVALID_MULTIFIELD_SHAPE ОписаниеНеверная форма поля phone или email — нужен [{ "value", "typeId" }]. Тот же код, если в phone или email передан объект без value, например пустой или с ключами вроде n0, 0, 011, либо число или true/false — сам по себе или элементом массива, — или если сырой fm передан не массивом, например строкой, числом, пустым объектом или объектом с ключами типов вида PHONE: fm принимается только массивом [{ "typeId", "valueType", "value" }]. Запрос отклоняется, ничего не записывается
HTTP400 КодMULTIFIELD_ID_NOT_SUPPORTED ОписаниеВ phone, email или в сыром fm[] передан объект с полем id. При создании адресовать нечего: Битрикс24 назначает идентификаторы записей мультиполя сам, поэтому запрос отклоняется и ничего не записывается. Тот же отказ, если fm, phone или email передан объектом, где ключи — id записей ({"fm": {"11": {…}}})
HTTP400 КодREADONLY_FIELD ОписаниеПопытка записать read-only поле
HTTP400 КодUNKNOWN_STAGE ОписаниеstageId / statusId не из справочника статусов лидов (STATUS): опечатка, другой регистр, стадия сделки вместо статуса лида. Запись не создаётся; message подсказывает точное написание, details.knownStages перечисляет статусы справочника

Полный список общих ошибок API — Ошибки.

Известные особенности

Простой режим CRM (без лидов): если портал работает в простом режиме, Битрикс24 конвертирует лид сразу при создании — он приходит CONVERTED и закрытым, а из него создаются контакт и сделка, которых в запросе не было. Запрошенная стадия при этом не сохраняется. Вайбкод ничего не меняет в запросе: так ведёт себя сам портал, и переключить режим через API нельзя — только в настройках CRM. Ответ остаётся 201, а в meta.warnings добавляется предупреждение LEAD_AUTO_CONVERTED с номерами созданных порталом контакта (contactId) и сделки (dealId); null — если сущность не создана или не найдена: контакт, который вы привязали сами через contactId, портал переиспользует и создание не считается. Предупреждения нет, если CONVERTED запрошен явно. На таком портале заводите сделки и контакты напрямую.

Конвертация лида: Битрикс24 REST не имеет отдельного метода конвертации. Чтобы «конвертировать» лид, создайте сделку/контакт/компанию с leadId и обновите статус лида:

javascript 
// 1. Создать сделку из лида
await fetch('/v1/deals', { body: { title: 'Из лида', leadId: 5001 } })
// 2. Закрыть лид
await fetch('/v1/leads/5001', { method: 'PATCH', body: { statusId: 'CONVERTED' } })

Смотрите также