Lumenbase

    Довідник API Lumenbase

    API Lumenbase побудовано на основі REST. Наш API має передбачувані URL-адреси, орієнтовані на ресурси, приймає тіла запитів у форматі JSON, повертає відповіді у форматі JSON та використовує стандартні коди відповідей HTTP, автентифікацію та методи.

    Для автентифікації запитів використовуйте API-ключі з вашого робочого простору. Створюйте ключі та керуйте ними в розділі Налаштування -> Налаштування компанії -> Інтеграції -> API. API-ключ визначає, до якого робочого простору відноситься запит.

    Повний CRUD доступний для Контактів, Компаній, Угод, Завдань, Рахунків та Активностей.

    Базова URL та автентифікація

    https://api.lumenbase.io

    Усі запити вимагають:

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

    Необов'язково: X-Idempotency-Key для запобігання повторній обробці при повторних спробах; X-Request-Id для відстеження.

    Конверт відповіді: Успішні відповіді повертають { success: true, data: { ... }, meta: { request_id, api_version, timestamp } }. Помилки повертають { success: false, error: { code, message, details? }, meta: { ... } }.

    Налаштування

    1. Перейдіть до Налаштування -> Налаштування компанії -> Інтеграції -> API. Натисніть "Створити API-ключ" та оберіть потрібні права доступу.
    2. Скопіюйте ключ одразу: він більше не відображатиметься.
    3. За бажанням створіть Конектор для зіставлення вхідних полів із полями CRM та налаштування правил збігу (для кінцевих точок імпорту).

    Права доступу API-ключа

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

    ПолеТипОпис
    contacts:readscopeЧитати та переглядати список контактів
    contacts:writescopeСтворювати, оновлювати та видаляти контакти
    companies:readscopeЧитати та переглядати список компаній
    companies:writescopeСтворювати, оновлювати та видаляти компанії
    deals:readscopeЧитати та переглядати список угод
    deals:writescopeСтворювати, оновлювати та видаляти угоди
    tasks:readscopeЧитати та переглядати список завдань
    tasks:writescopeСтворювати, оновлювати та видаляти завдання
    invoices:readscopeЧитати та переглядати список рахунків
    invoices:writescopeСтворювати, оновлювати та видаляти рахунки
    activities:readscopeЧитати та переглядати список активностей
    activities:writescopeСтворювати та видаляти активності
    readscopeДоступ для читання до всіх типів записів
    adminscopeПовний доступ до всіх кінцевих точок

    Застарілі права contact_ingest та activity_ingest досі працюють і відповідають правам читання та запису.

    Пагінація

    Усі кінцеві точки списків підтримують пагінацію через параметри запиту:

    ПолеТипОпис
    pageintegerНомер сторінки (за замовчуванням: 1)
    per_pageintegerЗаписів на сторінку, макс. 100 (за замовчуванням: 25)
    sort_bystringПоле для сортування (залежить від типу запису)
    sort_orderstring"asc" або "desc" (за замовчуванням: "desc")
    searchstringПовнотекстовий пошук за ключовими полями

    Формат пагінованої відповіді:

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

    POST: Створити / Імпортувати контакт

    Створення або оновлення контактів з форм, лендингових сторінок або сторонніх систем. Збіг визначається за електронною поштою; за потреби створює або пов'язує компанії.

    POSThttps://api.lumenbase.io/functions/v1/v1-public-contacts

    Scope:

    contacts:write
    or
    contact_ingest

    Request body:

    {
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-123-4567",
  "title": "Product Manager",
  "company_name": "Acme Inc",
  "company_domain": "acme.com",
  "source": "website_form",
  "signal_strength": 75,
  "message": "Interested in your enterprise plan"
}
    ПолеТипОпис
    first_namestringІм'я контакту
    last_namestringПрізвище контакту
    emailstringЕлектронна пошта (використовується для збігу)
    phonestringНомер телефону
    titlestringПосада
    company_namestringНазва компанії (створюється, якщо нова)
    company_domainstringДомен компанії для збігу
    sourcestringДжерело ліда
    signal_strengthnumberСигнал наміру 0-100
    messagestringНотатки

    201 - новий контакт створено; 200 - наявний контакт оновлено.

    POST: Масовий імпорт контактів

    Імпорт до 100 контактів за один запит. Та сама схема полів, що й при імпорті контакту.

    POSThttps://api.lumenbase.io/functions/v1/v1-public-contacts-batch

    Scope:

    contacts:write

    {
  "contacts": [
    { "email": "a@example.com", "first_name": "Alice" },
    { "email": "b@example.com", "first_name": "Bob" }
  ],
  "options": { "stop_on_error": false }
}

    201 - усі успішно; 207 - частково; 400 - усі помилково. Макс. 100 контактів, 500 КБ корисного навантаження.

    GET: Отримати / Список контактів

    GEThttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?id={uuid}

    Отримати один контакт за ID.

    GEThttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?page=1&per_page=25

    Список контактів із пагінацією.

    Scope:

    contacts:read

    Фільтри:

    ПолеТипОпис
    emailstringФільтр за точною електронною поштою
    company_iduuidФільтр за компанією
    statusstringФільтр за статусом
    searchstringПошук за first_name, last_name, email

    Сортувати за: created_at, updated_at, first_name, last_name, email

    PATCH: Оновити контакт

    PATCHhttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?id={uuid}

    Scope:

    contacts:write

    {
  "title": "Senior Product Manager",
  "phone": "+1-555-999-0000"
}

    Поля, що оновлюються: first_name, last_name, email, phone, title, company_id, source, status.

    DELETE: Видалити контакт

    DELETEhttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?id={uuid}

    Scope:

    contacts:write

    { "success": true, "data": { "deleted": true, "id": "uuid" } }

    POST: Створити компанію

    POSThttps://api.lumenbase.io/functions/v1/v1-public-companies

    Scope:

    companies:write

    Upsert за доменом, якщо вказано. Створює новий запис, якщо збігу не знайдено.

    {
  "name": "Acme Inc",
  "domain": "acme.com",
  "industry": "Technology",
  "size": "51-200",
  "website": "https://acme.com",
  "city": "San Francisco",
  "country": "US"
}
    ПолеТипОпис
    namestringНазва компанії
    domainstringДомен компанії (використовується для збігу)
    industrystringГалузь
    sizestringДіапазон розміру компанії
    websitestringURL веб-сайту
    phonestringНомер телефону
    citystringМісто
    statestringШтат/регіон
    countrystringКод країни
    statusstringСтатус

    GET: Отримати / Список компаній

    GEThttps://api.lumenbase.io/functions/v1/v1-public-companies?id={uuid}
    GEThttps://api.lumenbase.io/functions/v1/v1-public-companies?page=1&per_page=25

    Scope:

    companies:read

    Фільтри:

    ПолеТипОпис
    domainstringФільтр за точним доменом
    industrystringФільтр за галуззю
    searchstringПошук за name, domain

    Сортувати за: created_at, updated_at, name, domain

    PATCH: Оновити компанію

    PATCHhttps://api.lumenbase.io/functions/v1/v1-public-companies?id={uuid}

    Scope:

    companies:write

    { "industry": "SaaS", "size": "201-500" }

    DELETE: Видалити компанію

    DELETEhttps://api.lumenbase.io/functions/v1/v1-public-companies?id={uuid}

    Scope:

    companies:write

    POST: Створити угоду

    POSThttps://api.lumenbase.io/functions/v1/v1-public-deals

    Scope:

    deals:write

    {
  "title": "Enterprise License: Acme",
  "value": 50000,
  "currency": "USD",
  "stage": "Proposal",
  "expected_close_date": "2026-04-15",
  "company_id": "uuid",
  "contact_id": "uuid"
}
    ПолеТипОпис
    titlestring (required)Назва угоди
    valuenumberВартість угоди
    currencystringКод валюти (за замовчуванням: USD)
    stagestringЕтап воронки
    statusstringСтатус угоди
    probabilitynumberЙмовірність перемоги 0-100
    expected_close_datedateОчікувана дата закриття
    company_iduuidПов'язана компанія
    contact_iduuidПов'язаний контакт
    pipeline_iduuidID воронки
    assigned_touuidID призначеного користувача

    GET: Отримати / Список угод

    GEThttps://api.lumenbase.io/functions/v1/v1-public-deals?id={uuid}
    GEThttps://api.lumenbase.io/functions/v1/v1-public-deals?page=1&per_page=25

    Scope:

    deals:read

    Фільтри:

    ПолеТипОпис
    stagestringФільтр за етапом
    statusstringФільтр за статусом
    company_iduuidФільтр за компанією
    pipeline_iduuidФільтр за воронкою
    searchstringПошук за title

    Сортувати за: created_at, updated_at, title, value, expected_close_date

    PATCH: Оновити угоду

    PATCHhttps://api.lumenbase.io/functions/v1/v1-public-deals?id={uuid}

    Scope:

    deals:write

    { "stage": "Negotiation", "probability": 80 }

    DELETE: Видалити угоду

    DELETEhttps://api.lumenbase.io/functions/v1/v1-public-deals?id={uuid}

    Scope:

    deals:write

    POST: Створити завдання

    POSThttps://api.lumenbase.io/functions/v1/v1-public-tasks

    Scope:

    tasks:write

    {
  "title": "Follow up with Acme",
  "description": "Send proposal by Friday",
  "priority": "high",
  "due_date": "2026-03-01",
  "assigned_to": "uuid",
  "contact_id": "uuid",
  "deal_id": "uuid"
}
    ПолеТипОпис
    titlestring (required)Назва завдання
    descriptionstringОпис завдання
    statusstringСтатус завдання
    prioritystringПріоритет: low, medium, high, urgent
    due_datedateТермін виконання
    assigned_touuidID призначеного користувача
    contact_iduuidПов'язаний контакт
    company_iduuidПов'язана компанія
    deal_iduuidПов'язана угода

    GET: Отримати / Список завдань

    GEThttps://api.lumenbase.io/functions/v1/v1-public-tasks?id={uuid}
    GEThttps://api.lumenbase.io/functions/v1/v1-public-tasks?page=1&per_page=25

    Scope:

    tasks:read

    Фільтри:

    ПолеТипОпис
    statusstringФільтр за статусом
    prioritystringФільтр за пріоритетом
    assigned_touuidФільтр за виконавцем
    contact_iduuidФільтр за контактом
    company_iduuidФільтр за компанією
    deal_iduuidФільтр за угодою
    searchstringПошук за title

    Сортувати за: created_at, updated_at, title, due_date, priority

    PATCH: Оновити завдання

    PATCHhttps://api.lumenbase.io/functions/v1/v1-public-tasks?id={uuid}

    Scope:

    tasks:write

    { "status": "completed", "description": "Proposal sent" }

    DELETE: Видалити завдання

    DELETEhttps://api.lumenbase.io/functions/v1/v1-public-tasks?id={uuid}

    Scope:

    tasks:write

    POST: Створити рахунок

    POSThttps://api.lumenbase.io/functions/v1/v1-public-invoices

    Scope:

    invoices:write

    {
  "invoice_number": "INV-2026-001",
  "status": "draft",
  "issue_date": "2026-02-19",
  "due_date": "2026-03-19",
  "subtotal": 5000,
  "tax_amount": 500,
  "total": 5500,
  "currency": "USD",
  "company_id": "uuid",
  "contact_id": "uuid",
  "notes": "Net 30"
}
    ПолеТипОпис
    invoice_numberstringНомер рахунку
    statusstringdraft, sent, paid, overdue, cancelled
    issue_datedateДата виставлення
    due_datedateТермін оплати
    subtotalnumberСума без податків
    tax_amountnumberСума податку
    totalnumberЗагальна сума
    currencystringКод валюти
    company_iduuidПов'язана компанія
    contact_iduuidПов'язаний контакт
    deal_iduuidПов'язана угода
    notesstringНотатки
    line_itemsjsonМасив позицій рахунку

    GET: Отримати / Список рахунків

    GEThttps://api.lumenbase.io/functions/v1/v1-public-invoices?id={uuid}
    GEThttps://api.lumenbase.io/functions/v1/v1-public-invoices?page=1&per_page=25

    Scope:

    invoices:read

    Фільтри:

    ПолеТипОпис
    statusstringФільтр за статусом
    company_iduuidФільтр за компанією
    contact_iduuidФільтр за контактом
    searchstringПошук за invoice_number

    Сортувати за: created_at, updated_at, invoice_number, due_date, total, issue_date

    PATCH: Оновити рахунок

    PATCHhttps://api.lumenbase.io/functions/v1/v1-public-invoices?id={uuid}

    Scope:

    invoices:write

    { "status": "sent", "due_date": "2026-04-01" }

    DELETE: Видалити рахунок

    DELETEhttps://api.lumenbase.io/functions/v1/v1-public-invoices?id={uuid}

    Scope:

    invoices:write

    POST: Створити / Імпортувати активність

    POSThttps://api.lumenbase.io/functions/v1/v1-public-activities

    Scope:

    activities:write
    or
    activity_ingest

    Записуйте активності з Jira, засобів підтримки, вебхуків або будь-яких зовнішніх джерел. Пов'язується з контактами та компаніями за електронною поштою або доменом.

    {
  "type": "jira_issue_created",
  "entity_email": "john.doe@example.com",
  "entity_domain": "acme.com",
  "title": "PROJ-123: New Feature Request",
  "description": "Customer requested dashboard export",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": { "issue_key": "PROJ-123", "priority": "high" }
}

    Типи активностей:

    jira_issue
    support_ticket
    form_submission
    webhook
    external_activity

    Прив'язка до записів:

    • entity_email → Контакт за електронною поштою
    • entity_domain → Компанія за доменом
    • entity_id → Угода за ID

    GET: Отримати / Список активностей

    GEThttps://api.lumenbase.io/functions/v1/v1-public-activities-crud?id={uuid}
    GEThttps://api.lumenbase.io/functions/v1/v1-public-activities-crud?page=1&per_page=25

    Scope:

    activities:read

    Фільтри:

    ПолеТипОпис
    typestringФільтр за типом активності
    contact_iduuidФільтр за контактом
    company_iduuidФільтр за компанією
    deal_iduuidФільтр за угодою
    searchstringПошук за title

    Сортувати за: created_at, type, title

    DELETE: Видалити активність

    DELETEhttps://api.lumenbase.io/functions/v1/v1-public-activities-crud?id={uuid}

    Scope:

    activities:write

    Зіставлення полів (Конектори)

    Конектори зіставляють вхідні поля JSON із полями CRM. Використовуйте крапкову нотацію для вкладеного JSON, наприклад user.profile.email -> Електронна пошта. Конектори застосовуються до кінцевих точок імпорту (Імпорт контактів, Імпорт активностей).

    Правила збігу

    Контакт: електронна пошта (рекомендовано), телефон або ID. Компанія: домен (рекомендовано), назва або ID. Угода: ID або назва. Якщо збігу не знайдено і надано необхідні дані, створюється новий запис.

    Обробка помилок

    ПолеТипОпис
    401UNAUTHORIZEDНедійсний або відсутній API-ключ; використовуйте Bearer <ключ>
    403FORBIDDENAPI-ключу бракує необхідного права доступу
    400VALIDATION_ERRORНедійсне тіло запиту або відсутні обов'язкові поля
    404NOT_FOUNDРесурс не знайдено
    405METHOD_NOT_ALLOWEDМетод HTTP не підтримується для цієї кінцевої точки
    413PAYLOAD_TOO_LARGEТіло запиту перевищує максимальний розмір (50 КБ одиничний, 500 КБ пакетний)
    429RATE_LIMIT_EXCEEDEDЗабагато запитів; перевірте X-RateLimit-* та Retry-After
    500INTERNAL_ERRORПомилка сервера

    Тіло відповіді з помилкою:

    {
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": { }
  },
  "meta": { "request_id": "...", "api_version": "1", "timestamp": "..." }
}

    Найкращі практики

    • Використовуйте окремі конектори для кожного джерела, щоб відстежувати походження та налаштовувати зіставлення.
    • Включайте електронну пошту для збігу контактів (найнадійніший спосіб).
    • Надсилайте X-Idempotency-Key при повторних спробах, щоб уникнути дублікатів.
    • Ліміт запитів: 100 запитів на хвилину на робочий простір; добові обмеження 10 тис. контактів та 50 тис. активностей. Перевіряйте X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset та Retry-After при статусі 429.
    • Використовуйте детальні права доступу (наприклад contacts:read) замість admin для мінімально необхідних привілеїв.
    • Для масових операцій використовуйте пакетну кінцеву точку, щоб зменшити кількість API-викликів.

    Не розробник?

    Використовуйте Zapier для підключення Lumenbase до 6 000+ застосунків або перегляньте Довідковий центр.

    Потрібен API-ключ? Увійдіть та перейдіть до Налаштування -> Інтеграції -> API.