Для AI-агентов: markdown этой страницы — /docs-content/entities/leads/move.md индекс документации — /llms.txt
Перевести лид на другой статус
POST /v1/leads/:id/move
Переводит лид на другой статус — например, из новой заявки в работу.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Параметрid (path) |
Типnumber | Обяз.да | ОписаниеID лида. Список: GET /v1/leads |
Поля запроса (body)
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
ПолеstatusId |
Типstring | Обяз.нет | ОписаниеИдентификатор целевого статуса. Список: GET /v1/statuses?filter[entityId]=STATUS |
ПолеstageId |
Типstring | Обяз.нет | ОписаниеВторое имя того же поля. Принимается наравне со statusId и означает тот же статус |
Поля вне таблицы игнорируются.
Примеры
curl — личный ключ
curl -X POST "https://vibecode.bitrix24.tech/v1/leads/42/move" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"statusId": "IN_PROCESS"
}'
curl — OAuth-приложение
curl -X POST "https://vibecode.bitrix24.tech/v1/leads/42/move" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"statusId": "IN_PROCESS"
}'
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/leads/42/move', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
statusId: 'IN_PROCESS',
}),
})
const { success, data } = await res.json()
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/leads/42/move', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
statusId: 'IN_PROCESS',
}),
})
const { success, data } = await res.json()
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | Описаниеtrue при успешном вызове |
Полеdata |
Типobject | ОписаниеЛид после вызова, все поля — см. Поля лида |
Полеdata.stageId |
Типstring | ОписаниеСтатус лида после вызова. Значение приходит в этом поле независимо от того, каким именем оно было передано в теле запроса |
Полеdata.movedTime |
Типstring | ОписаниеМомент последней смены статуса в формате ISO 8601 |
Пример ответа
Показаны основные поля.
{
"success": true,
"data": {
"id": 42,
"title": "Заявка с сайта",
"name": "Мария",
"stageId": "IN_PROCESS",
"stageSemanticId": "P",
"assignedById": 1,
"movedBy": 1,
"movedTime": "2026-08-25T13:47:20+03:00",
"updatedTime": "2026-08-25T10:47:20.000Z",
"entityTypeId": 1
}
}
Пример ответа при ошибке
404 — лида с таким id нет:
{
"success": false,
"error": {
"code": "ENTITY_NOT_FOUND",
"message": "Элемент не найден"
}
}
422 — переданный статус не применился (например, значение, которого нет в справочнике). Запись к этому моменту уже прошла в Битрикс24 и перечитана, поэтому отказ несёт перечитанный лид в data, а error.details — список неприменившихся полей и их текущие значения:
{
"success": false,
"error": {
"code": "STAGE_NOT_APPLIED",
"message": "Bitrix24 accepted the write but did not apply it: stageId requested \"BOGUS_STATUS\", still \"NEW\" after re-read. The value is likely not a valid id for this lead — check GET /v1/statuses?filter[entityId]=... (or GET /v1/deal-categories for a pipeline id) for the valid set before retrying. The record was already written and re-read: any OTHER field in the same request may have been applied, so correct the value and send only what still needs changing rather than repeating the whole body.",
"details": {
"unappliedFields": ["stageId"],
"currentValues": {
"stageId": "NEW"
}
}
},
"data": {
"id": 42,
"title": "Заявка с сайта",
"name": "Мария",
"stageId": "NEW",
"entityTypeId": 1
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP404 | КодENTITY_NOT_FOUND |
ОписаниеЛида с указанным id нет |
| HTTP422 | КодSTAGE_NOT_APPLIED |
ОписаниеПереданный statusId или stageId не применился: после вызова статус остался прежним, например при значении, которого нет в справочнике. Подробности — в error.message и error.details, перечитанный лид — в data |
| HTTP422 | КодBITRIX_ERROR |
ОписаниеБитрикс24 отклонил сам вызов (не конкретно значение статуса) — например неверный формат поля. Текст причины приходит в error.message, машиночитаемый код Битрикс24 — в error.b24Code |
| HTTP403 | КодBITRIX_ACCESS_DENIED |
ОписаниеБитрикс24 отказал в доступе к лиду |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа crm |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
ОписаниеКлюч в режиме «только чтение» вызвал метод записи |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеУ ключа нет настроенных токенов авторизации |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов. В ответе приходит заголовок Retry-After с рекомендованной паузой |
Полный список общих ошибок API — Ошибки.
Известные особенности
- Пустое тело — не ошибка. Вызов без
statusId/stageIdв теле отвечает200, и лид остаётся на прежнем статусе: сверять нечего, поэтому это неSTAGE_NOT_APPLIED— платформа проверяет только те поля, что реально были переданы.