ADS Beast — універсальна інтеграція якості лідів

Ця сторінка — технічна документація для будь-якого бізнесу, який використовує ADS Beast для реклами. Вона пояснює, як ваш сайт/CRM має передавати дані про лідів і їхні статуси, щоб ADS Beast могла автоматично оптимізувати рекламні кампанії на реєстрації, оплати та інші цільові події.

Коротко: ADS Beast веде рекламу → користувач переходить по оголошенню → ви зберігаєте UTM і click ID → користувач реєструється/платить → ви повідомляєте ADS Beast про результат → ADS Beast оптимізує кампанії за реальною якістю лідів.

1. Що таке «якість ліда» в ADS Beast

ADS Beast оптимізує не тільки кількість лідів, а й їхню якість. Для цього CRM або сайт клієнта має повертати статус кожного ліда:

На основі цих статусів система:

2. Що зберігати при першому переході на сайт

Коли користувач клікає оголошення, ADS Beast додає до URL рекламні параметри. Ви маєте зберегти їх у сесії / cookie / профілі користувача і передати в CRM разом із лідом:

ПолеОписПриклад
utm_sourceДжерело трафікуadsbeast
utm_mediumТип трафікуpaid, cpc
utm_campaignНазва кампаніїmanaro_meta_ua
utm_contentКреатив / аудиторіяfeed_beauty
utm_termКлючове слово (Google)crm+для+салона
fbclidMeta click IDIwAR2ABCD...
gclidGoogle click IDCjwKCAjw...
gbraid, wbraidGoogle iOS / web-to-app ID—
ttclidTikTok click ID—
click_idУніверсальний click ID—
campaign_nameНазва кампанії з ADS BeastManaro CRM — Lead Gen UA
platform_campaign_idID кампанії в рекламному кабінеті1234567890
Важливо: click IDs (fbclid, gclid, ttclid) мають термін життя. Meta — до 7 днів, Google — до 90 днів для offline conversions. Передавайте статус якомога швидше після події.

3. Передача статусів лідів (основний метод)

Один endpoint для будь-якого сайту або CRM. Надсилайте рядок щоразу, коли змінюється статус ліда чи користувача.

POST https://adsbeast.pro/api/integrations/quality-outcomes/{org_slug}/sync
Content-Type: application/json
X-API-Key: absk_...

{
  "client_id": 123,
  "rows": [
    {
      "external_lead_id": "your_user_12345",
      "contact_email": "user@example.com",
      "outcome": "paid",
      "value": 49.99,
      "currency": "EUR",
      "plan": "pro",
      "occurred_at": "2026-10-03T09:15:00Z",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "your_campaign",
      "gclid": "...",
      "fbclid": "..."
    }
  ]
}

Публічний контракт з усіма полями, статусами та синонімами (ключ не потрібен):

GET https://adsbeast.pro/api/integrations/quality-outcomes/{org_slug}/contract

Статуси (outcome)

СтатусКоли використовуватиТип
registeredКористувач зареєструвався / створив акаунтПозитивний
activatedПройшов onboarding, почав користуватися продуктомПозитивний
demo_bookedЗаброньовано демо / консультаціюПозитивний
qualifiedМенеджер підтвердив, що лід цільовийПозитивний
proposal_sentВідправлено комерційну пропозиціюПозитивний
paidОтримано оплатуПозитивний
wonУгода виграна / підписано договірПозитивний
unqualifiedЛід нецільовий за критеріямиНегативний
no_budgetУ ліда немає бюджетуНегативний
duplicateДублікат існуючого лідаНегативний
unreachableНе вдалося зв’язатисяНегативний
invalid_phoneНевірний телефон / фейкові даніНегативний
claimed_no_requestЛюдина каже, що заявку не залишалаНегативний
spamСпам / ботНегативний

Синоніми приймаються автоматично (наприклад, signup → registered, payment → paid) — повний список у контракті.

4. Готові CRM-адаптери

Для keepincrm, hubspot, amocrm і pipedrive ADS Beast уміє сам забирати статуси з CRM. Такий зв’язок налаштовує менеджер у кабінеті ADS Beast; адреси /api/crm-feedback/… закриті для ключів інтеграції (відповідь 403). Для будь-якої іншої CRM використовуйте метод із розділу 3.

5. Читання лідів з ADS Beast

GET https://adsbeast.pro/api/leads-pipeline/export?client_id=123&format=json
X-API-Key: absk_...

Потрібне право read:leads. Відповідь посторінкова: count, leads, has_more, next_offset — поки has_more дорівнює true, запитуйте &offset=<next_offset>. Короткий список: GET /api/leads-pipeline/?client_id=123&limit=200 (зі слешем перед ?).

6. Як ADS Beast використовує ці дані

7. Повний цикл на прикладі SaaS

  1. Користувач бачить рекламу → переходить на yoursaas.com/?utm_source=google&utm_campaign=saas_trial_ua&gclid=ABC.
  2. Сайт зберігає UTM і gclid у cookie / localStorage і передає їх у CRM при реєстрації.
  3. Користувач реєструється → CRM надсилає outcome: registered.
  4. Почав користуватися продуктом → activated з тим самим external_lead_id.
  5. Оформив підписку → paid.
  6. ADS Beast бачить: реєстрації дешевші з кампанії A, але оплати — з кампанії B. Бюджет переходить на B.

8. Безпека та коди відповідей

9. Обов’язкові поля

ПодіяОбов’язкові поляРекомендовані
Реєстраціяexternal_lead_id або contact_email, outcome=registeredUTM, click ID, occurred_at
Активаціятой самий ідентифікатор, outcome=activatedoccurred_at
Оплататой самий ідентифікатор, outcome=paidoccurred_at, click ID
Відсіюванняідентифікатор, outcome=unqualified / spam / duplicateoutcome_reason

10. Питання та підтримка

Для налаштування індивідуальної інтеграції звертайтесь до адміністратора ADS Beast.

Примітка: ця документація універсальна. Для конкретного проєкту (наприклад, Manaro) створюється окремий API-ключ і client_id. Ніколи не використовуйте один API-ключ для кількох непов’язаних інтеграцій.