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 - див. Вебхуки. У самій події персональних даних немає: вона лише вказує, який лід змінився, а картку ви читаєте окремим запитом.

Пов'язані статті

Ця стаття була корисною?