Лиды через API

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

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

Список

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. pool=true (только ключ агентства) - лиды в общем пуле агентства; личный ключ его игнорирует.

limit (1-50, по умолчанию 20) и page (с 1) вне диапазона приводятся к нему, а не отклоняются. Другие недопустимые значения известного параметра (неизвестное значение перечисления, нецелый page, неверная дата в from или to) отклоняются с 400 validation и названием поля.

Один лид

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

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

Форма лида

• id, status, type, priority, source, tags, isArchived; type - buy, rent, viewing, sell, contract, transfer или user
• createdAt, updatedAt, lastActivityAt
• customer - имя, страна, мессенджер и блок contact (phone, email, messengerHandle, profileUrl)
• budget - { value, currency }
• intent - город, районы, тип сделки и намерение клиента
• comments - отдельно комментарий клиента и ваш собственный
• object - объект, с которым связана заявка
• 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": "[email protected]" }
    },
    "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.

Флаг 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. Действуют правила кабинета: лид с объектом закрывается через финализацию в кабинете (code: finalize), лид, ждущий комиссии, сохраняет статус (fee_pending), закрытая сделка по договору меняется только в кабинете (closed) - 422 с причиной в code. Другие причины: sender (вы передали лид - его ведет получатель), module (лид Swipe Match, статус ведет модуль), agreement, network_readonly, forbidden.

Убрать лид

DELETE /leads/{id}

Это архивация, а не удаление: лид пропадает из обычного списка, но остается доступным по ?archived=true. Лид с действующим договором или соглашением о финализации, закрытый лид с объектом без финализации и лид, ждущий комиссии, не архивируются: 422 с code contract_active, agreement, finalize или fee_pending.

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

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

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

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

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

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

• Забрать лид: по умолчанию он назначается владельцу агентства; assignTo (id участника) могут передавать владелец или менеджер.
• Вернуть в пул: менеджер и выше или агент, на которого лид сейчас назначен. Тело необязательное: {"reason": "..."}. Лид, который архивировали правила пула, - 422 с code: pool_archived: сначала восстановите его в кабинете.
• Личный ключ или недостаточная роль - 403 с title: forbidden; попытка забрать лид, которого уже нет в пуле, - 404.
• Оба действия отправляют событие lead.updated.

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

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

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

• Объекты - каталог объявлений, на которые ссылаются лиды.
• Swipe Match - лиды модуля для брокеров-партнеров.
• Вебхуки - события о новых и измененных лидах.
• Ошибки - как читать отказы.