Leads API
Читайте лиды и обновляйте их статус из собственных систем с помощью ключа API с ограниченными правами.
Эта страница переведена с английского. При любых расхождениях действует английская версия. Читать на английском
Leads API позволяет вашей CRM, хранилищу данных или инструменту автоматизации читать ваши лиды и обновлять их статус.
Создавайте ключи в Studio в разделе Integrations → Leads API → New key. У каждого ключа есть:
- название;
- права:
leads:read(Read leads) и, по желанию,leads:write-status(Change lead status); - срок действия: 30, 90, 180 дней или 1 год.
Ключи выглядят как atl_lead_ и 43 символа после него. Они показываются один раз, хранятся только в виде отпечатка, проверяются при каждом запросе и могут быть отозваны в любой момент (Revoke key). У окружения сайта может быть до 20 активных ключей. Для создания ключа может потребоваться второе подтверждение на вашем телефоне.
Базовый URL и аутентификация
Заголовок раздела «Базовый URL и аутентификация»https://<delivery host>/v1/leads-api/environments/{environmentId}Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXОтветы приходят с Cache-Control: private, no-store. Ошибки используют формат RFC 9457 application/problem+json.
Список лидов
Заголовок раздела «Список лидов»GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…
| Параметр | Примечания |
|---|---|
since |
Только лиды, обновлённые в это время или позже. ISO 8601 с часовым поясом |
limit |
От 1 до 200, по умолчанию 50 |
cursor |
nextCursor из предыдущего ответа |
Лиды идут от самого раннего изменения. Ответ имеет вид { "leads": [ … ], "nextCursor": "…" | null }. Продолжайте постраничное чтение, пока nextCursor не станет null, и сохраняйте последнее значение updatedAt, чтобы в следующий раз получать только изменения.
Список включает объединённые, анонимизированные и тестовые лиды. Проверяйте mergedInto, anonymisedAt и isTest.
Получение одного лида
Заголовок раздела «Получение одного лида»GET /leads/{leadId}
| Поле | Примечания |
|---|---|
id, source |
Источник — форма или чат-бот, из которых пришёл лид |
form |
{ key, name } или null для лидов из чат-бота |
name, email, phone, company, message |
Пусты, если хранение удалило персональные данные |
details |
Любые другие ответы |
status |
new, contacted, qualified, won, lost или spam |
isTest |
Тестовые отправки из Studio |
version |
Отправьте его обратно при смене статуса |
mergedInto, anonymisedAt |
Заданы, если лид был объединён или анонимизирован |
createdAt, updatedAt |
Временные метки ISO 8601 |
Смена статуса лида
Заголовок раздела «Смена статуса лида»PATCH /leads/{leadId}/status с { "status": "qualified", "expectedVersion": 4 }. Требуется право Change lead status. Изменение появляется в истории лида как сделанное ключом.
Ошибки и лимиты
Заголовок раздела «Ошибки и лимиты»| Статус | Код | Значение |
|---|---|---|
| 401 | CP_UNAUTHENTICATED |
Ключ отсутствует, неверен, просрочен или отозван |
| 403 | CP_FORBIDDEN |
У ключа нет права на этот запрос |
| 404 | CP_NOT_FOUND |
В этом окружении нет такого лида |
| 409 | CP_VERSION_CONFLICT |
Лид изменился с момента чтения. Прочитайте его заново |
| 422 | REQUEST_SCHEMA_INVALID |
Тело запроса или параметр недопустимы |
| 422 | CURSOR_INVALID |
Не удалось прочитать курсор |
| 429 | RATE_LIMITED |
Более 300 запросов в минуту. Подождите и повторите |
Ограничение частоты применяется отдельно на каждом сервере API Atlas, поэтому считайте 300 запросов в минуту потолком, а не гарантией.