Довідник API Lumenbase

1. Крок 1

   Створіть ключ

   Надайте лише ті права доступу, які використовує інтеграція. Ключ показується один раз.

   НалаштуванняНалаштування компаніїAPI
3. Крок 2

   Надішліть запит

   Передавайте ключ у заголовку Authorization кожного виклику.

   Bearer lmb_…
5. Крок 3

   Прочитайте конверт

   Перевірте success, прочитайте data і записуйте meta.request_id для підтримки.

   meta.request_id

https://api.lumenbase.io/functions/v1

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Необов'язкові заголовки

• X-Idempotency-Key Робить повторний імпорт безпечним. Див. Ідемпотентність.
• X-Request-Id Ваш власний ідентифікатор трасування, повертається в meta.request_id.

Кожна відповідь

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_...",
    "api_version": "1",
    "timestamp": "..."
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "...",
    "details": { "field": "..." }
  },
  "meta": { ... }
}

Кожен запит несе API-ключ робочого простору як токен Bearer. Інша форма не приймається.

Authorization: Bearer lmb_0f2a...

• Ключ складається з префікса lmb_ і 64 шістнадцяткових символів після нього.
• Ключі зберігаються в хешованому вигляді. Ми не можемо показати ключ повторно, тому збережіть його під час створення.
• Відкликання діє з наступного запиту. Спершу створіть заміну, щоб ротація відбулася без перерви.
• Ключ належить одному робочому простору. Він може читати лише записи цього робочого простору і пов'язуватися лише з ними.
• Записи, які створює ключ, приписуються людині, що створила ключ, або адміністратору робочого простору, якщо ця людина вже його покинула.

Кожен ключ має одне або кілька прав доступу. Надавайте лише те, що використовує інтеграція.

Старі назви contact_ingest та activity_ingest досі працюють. Кожна надає читання і запис контактів або активностей.

Кожна кінцева точка списку приймає ці параметри запиту.

{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 }
  },
  "meta": { ... }
}

Розгалужуйте логіку за error.code, а не за повідомленням. Повідомлення написані для людей і можуть змінюватися; коди є частиною договору.

Обмеження діють на робочий простір і рахуються у хвилинних вікнах. Кожен ресурс має власний кошик.

• Кожен ресурс: 100 запитів за хвилину. Пакетний імпорт витрачає кошик контактів.
• Контакти: також 10 000 запитів на добу.
• Активності: також 50 000 запитів на добу.
• Пакетний виклик зараховується до добового ліміту один раз, скільки б контактів він не містив.

Успішні відповіді містять

• X-RateLimit-LimitДозволена кількість запитів за хвилину в цьому кошику.
• X-RateLimit-RemainingСкільки запитів залишилося в цій хвилині.
• X-RateLimit-ResetКоли хвилина скидається, у секундах Unix.
• X-DailyLimit-RemainingСкільки запитів залишилося сьогодні. Лише для контактів і активностей.
• X-DailyLimit-ResetКоли доба скидається, у секундах Unix. Лише для контактів і активностей.
• Retry-AfterПри 429: час очікування в секундах.

Надсилайте X-Idempotency-Key, щоб повтор після тайм-ауту не створив дублікат. Той самий ключ протягом 24 годин повертає початковий результат замість нового запису.

X-Idempotency-Key: 7d3f9c1e-2b84-4a17-9f0d-6c5e8a2b1d34

Використовуйте значення від 8 до 128 символів, унікальне для кожної операції. UUID підходить. Ключ іншої довжини ігнорується, а не відхиляється.

Ключі діють у межах робочого простору й ресурсу протягом 24 годин. Повтор отримує 200 з першою відповіддю. Idempotency-Key працює як псевдонім.

• Контакти зіставляються за електронною поштою, потім за телефоном.
• Компанії зіставляються за доменом (його беруть із робочої електронної пошти, якщо домен не надіслано), потім за вебсайтом, потім за назвою.
• Активність без deal_id приєднується до найновішої відкритої угоди своєї компанії.
• Конектор зіставляє ваші власні назви полів із цими полями для кінцевих точок імпорту. Для вкладеного JSON використовуйте крапкову нотацію, наприклад user.profile.email.

Версія міститься у шляху й повторюється в кожній відповіді як meta.api_version і заголовок X-API-Version.

Нові поля можуть з являтися у відповіді будь-коли й не вважаються змінами, що ламають сумісність. Розбирайте відповідь обережно та ігноруйте незнайомі поля замість перевірки на точну форму.

Зміна, що ламає сумісність, означає новий префікс шляху. Наявний продовжує працювати через процес нижче.

Версія застосунку, яку показано в інших місцях продукту, це дата випуску, а не версія API. Вони змінюються незалежно.

Коли кінцева точка виходить з ужитку, вона повідомляє про це у власних відповідях, перш ніж перестати працювати.

Кінцева точка, що виходить з ужитку, повертає

• Deprecationtrue
• Sunsetдата, коли вона перестане відповідати, у форматі дати HTTP.
• Linkзаміна, з rel, що вказує на наступну версію.

Дата Sunset настає щонайменше через шість місяців після оголошення. Після неї кінцева точка повертає 410 Gone і називає свою заміну.

Виходить з ужитку зараз

• POST /public-contactsPOST /v1-public-contactsSunset 26 листопада 2026
• POST /public-activitiesPOST /v1-public-activitiesSunset 31 березня 2027

Записуйте ці заголовки в лог. Це найраніше попередження, яке ви отримаєте, і воно приходить на відповідях, які загалом успішні.

Повний договір опубліковано як документ OpenAPI 3.1. Імпортуйте його в Postman чи Insomnia, згенеруйте клієнт або порівняйте між випусками, щоб побачити, що саме змінилося.

https://lumenbase.io/api/openapi.json

curl -s https://lumenbase.io/api/openapi.json -o lumenbase-openapi.json

1. 1Дайте кожній інтеграції власний ключ, щоб можна було відкликати один, не зламавши решту.
2. 2Надсилайте адресу електронної пошти з кожним контактом. Це найнадійніший критерій збігу.
3. 3Надсилайте X-Idempotency-Key під час повтору імпорту.
4. 4Масово завантажуйте контакти через пакетну кінцеву точку.
5. 5Надсилайте форми з сайту на POST /v1-public-inbound-submissions ключем, що має лише inbound:submit. Тоді ключ, що витік, може лише надсилати відповіді.
6. 6Стежте за X-RateLimit-Remaining, а при 429 чекайте Retry-After.
7. 7Записуйте meta.request_id з кожної відповіді. За ним підтримка знаходить ваш запит.

Поведінка, яка не відповідає тому, чого можна очікувати з решти цієї сторінки. Ми пишемо про неї тут, бо виявити її під час роботи гірше.

• Два запити з однаковим X-Idempotency-Key, надіслані одночасно, можуть обидва здійснити запис.
• activity_id з відповіді на імпорт контакту неможливо отримати через кінцеві точки активностей.
• Імпортована активність зберігає свій type лише в журналі імпорту. У хронології вона має type note.
• Запити, відхилені хвилинним лімітом, усе одно зараховуються до добового ліміту.
• Відповіді форм Inbound використовують X-Idempotency-Key спільно з контактами. Ключ, уже використаний на POST /v1-public-contacts, поверне ту саму відповідь. Натомість надсилайте external_id, він зберігається окремо для кожної форми.