Справочник REST API

Обзор

LeadHub включает полноценный REST API, позволяющий внешним инструментам читать и записывать ваши данные — лиды, пайплайны, автоматизации, формы и многое другое. Используйте его для интеграции с Zapier, создания пользовательских дашбордов, подключения сайта или автоматизации чего угодно.

Базовый URL

Все запросы к API отправляются на:

https://yourdomain.com/api/v1

Замените yourdomain.com на ваш реальный домен LeadHub.

Аутентификация

Каждый запрос (кроме health check) требует API-ключ.

Создавайте API-ключи в административной панели в разделе Настройки → API-ключи. Инструкции см. на странице настроек.

Включайте API-ключ в каждый запрос как токен Bearer в заголовке Authorization:

Authorization: Bearer lh_your_api_key_here

Если вы отправите запрос без API-ключа или с недействительным ключом, получите ответ 401 Unauthorized.

Ограничение Скорости

Каждый API-ключ по умолчанию ограничен 1 000 запросами в час (настраивается для каждого ключа). При превышении лимита вы получите ответ 429 Too Many Requests.

Каждый ответ содержит заголовки для отслеживания использования:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711580400

X-RateLimit-Reset — Unix-временная метка сброса лимита.

Пагинация

Эндпоинты, возвращающие списки записей, поддерживают пагинацию. Добавьте следующие параметры запроса:

Параметр	По умолчанию	Максимум
`page`	`1`	—
`per_page`	`15`	`100`

Пример: GET /api/v1/leads?page=2&per_page=25

Формат Ответа

Успешный ответ

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "https://yourdomain.com/api/v1/leads?page=1",
    "last": "https://yourdomain.com/api/v1/leads?page=5",
    "prev": null,
    "next": "https://yourdomain.com/api/v1/leads?page=2",
    "self": "https://yourdomain.com/api/v1/leads?page=1"
  }
}

Для ответов с одной записью (show, create, update) data содержит объект записи, meta опускается.

Ответ с ошибкой

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Распространённые коды ошибок:

Код	HTTP-статус	Значение
`UNAUTHORIZED`	401	API-ключ отсутствует или недействителен
`FORBIDDEN`	403	API-ключ не имеет необходимого scope
`NOT_FOUND`	404	Запись не существует
`VALIDATION_FAILED`	422	Данные запроса не прошли валидацию
`RATE_LIMITED`	429	Слишком много запросов
`SERVER_ERROR`	500	Неожиданная ошибка сервера

Проверка Работоспособности

Аутентификация не требуется.

GET /api/v1/health

Ответ:

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-28T09:15:00+00:00"
}

Используйте это для проверки доступности вашего экземпляра LeadHub перед другими запросами.

Лиды (Leads)

Необходимый scope: read:leads для получения, write:leads для создания/обновления, delete:leads для удаления.

Список Лидов

GET /api/v1/leads

Параметры запроса для фильтрации:

Параметр	Описание
`source`	Фильтр по источнику (например, `facebook`, `website`)
`status`	Фильтр по статусу (например, `new`, `contacted`, `qualified`)
`pipeline_id`	Фильтр по ID пайплайна
`stage_id`	Фильтр по ID этапа пайплайна
`assigned_user_id`	Фильтр по ID назначенного пользователя
`tag`	Фильтр по имени тега
`search`	Поиск по имени, email или телефону
`created_after`	Дата ISO 8601 — только лиды, созданные после этой даты
`created_before`	Дата ISO 8601 — только лиды, созданные до этой даты
`starred`	`true` — только отмеченные лиды
`sort`	Поле сортировки: `created_at`, `updated_at`, `lead_score`, `first_name`, `last_name`, `email`
`direction`	`asc` или `desc` (по умолчанию: `desc`)

Получить лид

GET /api/v1/leads/{id}

Создать лид

POST /api/v1/leads

Тело запроса (JSON):

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+14155551234",
  "source": "website",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 2,
  "assigned_user_id": 5,
  "notes": "Interested in the enterprise plan.",
  "custom_fields": {
    "budget": "10000"
  },
  "tags": ["hot-lead", "enterprise"]
}

first_name обязательно. Все остальные поля необязательны.

Обновить лид

PUT /api/v1/leads/{id}
PATCH /api/v1/leads/{id}

Отправьте только поля, которые хотите обновить. Те же поля, что и при создании.

Удалить лид

DELETE /api/v1/leads/{id}

Добавить тег к лиду

POST /api/v1/leads/{id}/tags

Тело: { "tag": "vip-client" }

Удалить тег у лида

DELETE /api/v1/leads/{id}/tags/{tag}

Пайплайны (Pipelines)

Необходимый scope: read:pipelines или write:pipelines

GET    /api/v1/pipelines
POST   /api/v1/pipelines
GET    /api/v1/pipelines/{id}
PUT    /api/v1/pipelines/{id}
PATCH  /api/v1/pipelines/{id}
DELETE /api/v1/pipelines/{id}

Этапы пайплайна

GET    /api/v1/pipelines/{pipeline_id}/stages
POST   /api/v1/pipelines/{pipeline_id}/stages
GET    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PUT    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PATCH  /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

Теги (Tags)

Необходимый scope: read:tags или write:tags

GET    /api/v1/tags
POST   /api/v1/tags
GET    /api/v1/tags/{id}
PUT    /api/v1/tags/{id}
PATCH  /api/v1/tags/{id}
DELETE /api/v1/tags/{id}

Пользователи (Users)

Необходимый scope: read:users, write:users или delete:users

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
PATCH  /api/v1/users/{id}
DELETE /api/v1/users/{id}

Формы (Forms)

Необходимый scope: read:forms, write:forms или delete:forms

GET    /api/v1/forms
POST   /api/v1/forms
GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
PATCH  /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

Отправить форму

POST /api/v1/forms/{id}/submissions

Тело: значения полей формы в виде пар ключ-значение.

Автоматизации (Automations)

Необходимый scope: read:automations, write:automations или delete:automations

GET    /api/v1/automations
POST   /api/v1/automations
GET    /api/v1/automations/{id}
PUT    /api/v1/automations/{id}
PATCH  /api/v1/automations/{id}
DELETE /api/v1/automations/{id}

Интеграции (Integrations)

Необходимый scope: read:integrations или write:integrations

GET    /api/v1/integrations/types
GET    /api/v1/integrations
POST   /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
PATCH  /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}

GET /api/v1/integrations/types возвращает список доступных типов интеграций (Facebook, Google Ads, Mailgun и т.д.).

Приём входящих Лидов

Упрощённый эндпоинт для создания лидов из внешних источников, webhook'ов или инструментов без кода, таких как Zapier и Make.

POST /api/inbound/leads?tenant={workspace-slug}

Авторизация через Authorization: Bearer {api_key}, slug рабочего пространства передаётся как параметр запроса.

Тело запроса:

{
  "email": "[email protected]",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "phone": "+14155551234",
  "company": "Tech Corp",
  "source": "zapier",
  "notes": "Came from newsletter signup",
  "tags": ["newsletter"],
  "custom_fields": {
    "utm_campaign": "spring-promo"
  }
}

email обязательно. Все остальные поля необязательны.

Успешный ответ (201):

{
  "status": "created",
  "lead_id": 1842,
  "is_duplicate": false
}

Если лид уже существует (совпадение по email или телефону), is_duplicate равен true и возвращается ID существующего лида.

Примеры Кода

cURL

curl -X GET "https://yourdomain.com/api/v1/leads?status=new&per_page=25" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Accept: application/json"

curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Sarah","email":"[email protected]","source":"api"}'

PHP

$apiKey = 'lh_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/v1';

// List leads
$response = file_get_contents($baseUrl . '/leads', false, stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer {$apiKey}\r\nAccept: application/json\r\n",
    ],
]));
$leads = json_decode($response, true);

// Create a lead
$ch = curl_init($baseUrl . '/leads');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Content-Type: application/json",
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'Sarah',
    'email'      => '[email protected]',
    'source'     => 'api',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch)

const apiKey = 'lh_your_api_key_here';
const baseUrl = 'https://yourdomain.com/api/v1';

// List leads
const response = await fetch(`${baseUrl}/leads?status=new`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create a lead
const createResponse = await fetch(`${baseUrl}/leads`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Sarah',
    email: '[email protected]',
    source: 'website',
  }),
});
const newLead = await createResponse.json();

Обзор​

Базовый URL​

Аутентификация​

Ограничение Скорости​

Пагинация​

Формат Ответа​

Успешный ответ​

Ответ с ошибкой​

Проверка Работоспособности​

Лиды (Leads)​

Список Лидов​

Получить лид​

Создать лид​

Обновить лид​

Удалить лид​

Добавить тег к лиду​

Удалить тег у лида​

Пайплайны (Pipelines)​

Этапы пайплайна​

Теги (Tags)​

Пользователи (Users)​

Формы (Forms)​

Отправить форму​

Автоматизации (Automations)​

Интеграции (Integrations)​

Приём входящих Лидов​

Примеры Кода​

cURL​

PHP​

JavaScript (fetch)​