API передачи лидов.

01Ключ доступа

Ключ выпускается в личном кабинете: Интеграции → API → Выпустить ключ. Он показывается один раз, поэтому сохраните его сразу. Ключ действует на весь аккаунт и открывает доступ к лидам всех ваших проектов.

Если ключ утерян или скомпрометирован — перевыпустите его в кабинете: прежний перестанет работать немедленно.

02Базовый адрес и авторизация

Базовый адрес: https://www.kukuruza.tech/api/v1. Ключ передаётся в заголовке Authorization:

curl -s "https://www.kukuruza.tech/api/v1/leads?limit=100" \
  -H "Authorization: Bearer kuku_live_ваш_ключ"

03GET /leads

Возвращает страницу лидов, отсортированных по времени создания — от старых к новым. Все параметры необязательны.

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

{
  "data": [
    {
      "id": "clz3f9k2h0001s6a1b2c3d4e5",
      "status": "qualified",
      "phone": "79991234567",
      "comment": "Просил перезвонить после 18:00",
      "transcription": null,
      "project": { "id": "clz3f8x1a0000s6a1zzzz1111", "name": "Окна Москва" },
      "campaign": { "id": "clz3f8x1a0000s6a1yyyy2222", "number": 12, "name": "Конкуренты" },
      "source": {
        "kind": "calls_in",
        "direction": "incoming",
        "resultDate": "2026-07-19",
        "region": "Москва",
        "city": null,
        "timezoneUtcOffsetMinutes": 180
      },
      "createdAt": "2026-07-19T08:41:03.221Z",
      "updatedAt": "2026-07-19T10:02:55.010Z"
    }
  ],
  "nextCursor": "MjAyNi0wNy0xOVQwODo0MTowMy4yMjFafGNsejNmOWsyaDAwMDFzNmExYjJjM2Q0ZTU",
  "hasMore": true
}

Блок source описывает происхождение контакта: kind — тип источника (hosts, calls, calls_in, categories_v2), direction — направление звонка (incoming, outgoing, n_a), resultDate — дата исходных данных.

Поле phone содержит номер в формате 7XXXXXXXXXX. Поля comment и transcription заполняются оператором и могут быть пустыми. Записи разговоров через API пока не передаются.

04Постраничная выгрузка

За один запрос отдаётся не больше 100 лидов, но объём выгрузки этим не ограничен: чтобы получить всю базу, повторяйте запрос с курсором из поля nextCursor, пока hasMore не станет false. Порядок сортировки стабильный, поэтому записи не теряются и не дублируются, даже если между запросами появились новые лиды.

cursor=""
while :; do
  page=$(curl -s "https://www.kukuruza.tech/api/v1/leads?limit=100&cursor=$cursor" \
    -H "Authorization: Bearer $KUKURUZA_API_KEY")
  echo "$page" | jq -c '.data[]'
  [ "$(echo "$page" | jq -r '.hasMore')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.nextCursor')
done

Для регулярной синхронизации удобнее забирать только изменения: сохраните время последнего успешного запроса и передавайте его в updatedSince.

05GET /leads/{leadId}

Возвращает один лид в поле data. Лиды чужих проектов отдаются как not_found.

06GET /projects

Возвращает проекты, доступные ключу: id, name, status. Значения id используются в параметре projectId.

07Лимиты

По умолчанию действует ограничение 60 запросов в минуту на ключ и до 100 лидов в одном ответе. Лимиты повышаются индивидуально — напишите менеджеру, если нужен другой режим выгрузки.

Каждый ответ содержит текущее состояние счётчика:

• X-RateLimit-Limit — лимит запросов в минуту;
• X-RateLimit-Remaining — сколько запросов осталось в текущем окне;
• X-RateLimit-Reset — момент сброса окна (Unix-время в секундах).

При превышении лимита возвращается код 429 с заголовком Retry-After — повторите запрос через указанное число секунд.

08Ошибки

Ошибки приходят в едином формате:

{ "error": { "code": "rate_limited", "message": "Превышен лимит 60 запросов в минуту" } }

09Статусы лида

10Поддержка

Вопросы по интеграции — на profit@kukuruza.tech. Если нужен не опрос по расписанию, а доставка лидов сразу в вашу CRM, в кабинете есть готовые интеграции с Битрикс24 и amoCRM.