Docs

Лиды через API

Последнее обновление: 2026-09-073 мин чтения

Раздел даёт программный доступ к вашим собственным лидам в CRM: сайт или внешняя форма может передавать заявки прямо в кабинет, а ваша система - читать их и двигать по статусам.

Базовый URL: https://developers.grem.capital/api/v1.

Лиды приватны. В отличие от публичного каталога объектов, здесь нет доступа без scope: чтение требует leads:read, изменения - leads:write. Вы видите только те лиды, где вы отправитель или получатель.

Список

GET /leads?status=new&type=buy&priority=hot&page=1&limit=20
Authorization: Bearer gsk_live_...

Параметры фильтра: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Архивные лиды в обычную выдачу не попадают - добавьте archived=true.

Один лид

GET /leads/{id}?expand=history,documents

expand добавляет к ответу историю статусов и действий (history) и перечень прикреплённых документов (documents).

Форма лида

  • id, status, type, priority, source, tags, isArchived
  • createdAt, updatedAt, lastActivityAt
  • customer - имя, страна, мессенджер и блок contact (phone, email, messengerHandle, profileUrl)
  • budget - { value, currency }
  • intent - город, районы, тип сделки и намерение клиента
  • comments - отдельно комментарий клиента и ваш собственный
  • object - объект, с которым связана заявка
  • deadline, reminder
  • agency - появляется только у лидов агентства: идентификатор агентства и признак, лежит ли лид в общем пуле

Контакты других брокеров, внутренние оценки и служебные пометки не отдаются никому.

Передать заявку извне

curl -X POST https://developers.grem.capital/api/v1/leads \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-2026-09-07-0001" \
  -d '{
    "customer": {
      "name": "Елена Ковальчук",
      "country": "UA",
      "contact": { "phone": "+380971234567", "email": "olena@example.com" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Интересует двухкомнатная рядом с метро",
    "priority": "warm",
    "consent": true
  }'

Обязательные поля: customer.name и хотя бы один способ связи в customer.contact. type - buy (по умолчанию) или rent. priority - hot, warm или cold. Можно добавить objectId, если заявка касается конкретного объявления, и до десяти своих меток в tags.

Заголовок Idempotency-Key спасает от дублей: если ваша форма повторила запрос из-за таймаута, лид не создастся второй раз. См. Идемпотентность.

Флаг pool: true отправляет заявку в общий пул на распределение вместо вашей CRM. По умолчанию лид попадает именно к вам.

Каждый лид, созданный через API, в кабинете помечен источником «API», поэтому его видно отдельно от остальных.

Изменить лид

PATCH /leads/{id}
{ "status": "in progress", "priority": "hot", "tags": ["ipoteka"], "brokerComments": "…" }

Менять можно статус, приоритет, метки и свой комментарий. Достаточно одного поля. Доступные статусы: new, in progress, processing, agreement, closed, not target, failed.

Убрать лид

DELETE /leads/{id}

Это архивация, а не удаление: лид исчезает из обычного списка, но остаётся доступен по ?archived=true.

Подбор объектов под лид

GET /leads/{id}/matches?page=1&limit=20

Возвращает объекты, отвечающие запросу клиента: тип, город и бюджет берутся из самого лида или из привязанного объявления. Вызов бесплатный.

Пул агентства

Для ключей агентства доступны два действия с пулом:

POST /leads/{id}/claim               забрать лид из пула себе
POST /leads/{id}/claim?assignTo=…    назначить лид участнику команды
POST /leads/{id}/return-to-pool      вернуть лид в пул

Оба действия требуют роли в агентстве, которая разрешает распределение лидов. Личный ключ получит отказ в доступе, а попытка забрать уже занятый лид вернёт 409.

Следить за изменениями

Вместо регулярного опроса списка подпишитесь на события lead.created и lead.updated - см. Вебхуки. В самом событии персональных данных нет: оно лишь указывает, какой лид изменился, а карточку вы читаете отдельным запросом.

Связанные статьи

Эта статья была полезной?