Для 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" }
  ]
}

Поля ответа

Поле Тип Описание
id number ID созданного лида
title string Название
stageId string Статус (стадия) лида
assignedById number Ответственный
createdBy number Создатель
createdTime datetime Дата создания

Ответ содержит все поля лида.

URL карточки лида в Битрикс24 строится из 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 Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
400 INVALID_MULTIFIELD_SHAPE Неверная форма поля phone или email — нужен [{ "value", "typeId" }]
400 READONLY_FIELD Попытка записать read-only поле
400 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' } })

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