Документация по API AI-UP

Внешний API AI-UP позволяет управлять проектами и источниками, а также выгружать идентификации контактов программно — из вашей CRM, скрипта или любой другой системы, без входа в кабинет. Все методы находятся под префиксом /api/ext и авторизуются персональным API-токеном.

Кратко: получите API-токен → передавайте его в заголовке Authorization: Bearer с каждым запросом → создавайте проекты, добавляйте источники, выгружайте идентификации. Токен один на аккаунт, перевыпуск отключает предыдущий.

Базовый адрес и авторизация

Все запросы отправляются на домен ai-up.ru по путям вида /api/ext/.... Каждый запрос должен содержать заголовок:

Authorization: Bearer <ваш_токен>

Параметры токена:

Обратите внимание: токен даёт полный доступ к проектам и источникам аккаунта. Храните его как пароль. Если токен попал к третьим лицам — перевыпустите его через token/rotate, старый перестанет действовать сразу.

Ошибки авторизации:

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

API возвращает JSON в едином конверте. Четыре варианта:

Одиночный объект

{ "result": { ... } }

Список с пагинацией

{
  "result": [ ... ],
  "page": { "number": 0, "limit": 3 }
}

Обратите внимание: в ответе поле page.limit — это общее количество страниц по вашему запросу, а не размер страницы, который вы передали. Используйте его, чтобы понять, сколько страниц нужно перебрать.

Успешная операция без данных

Изменения, удаления и переключения возвращают:

{ "result": "ok" }

Ошибка

{
  "error": "invalid_token",
  "code": "b1c2...-uuid",
  "time": "2026-07-02T12:00:00Z"
}

Поле code — уникальный идентификатор запроса. Он записывается в лог сервера вместе с реальной причиной ошибки. При обращении в поддержку по ошибке API укажите этот код — так проблему найдут быстрее. Внутренние ошибки сервера (5xx) всегда возвращаются с текстом something_went_wrong.

Общие параметры запросов

Все списочные методы принимают параметры пагинации:

Обратите внимание: размер страницы по умолчанию — 1 запись. Всегда передавайте limit явно (максимум 50), иначе получите по одной записи на страницу.

Методы с выборкой по датам принимают from и to — временные метки в формате RFC 3339 (например 2026-07-13T00:00:00Z). Если to не указан, он равен текущему моменту плюс 24 часа.

Объекты API

DailyLimits — лимиты по каналам

Дневные лимиты источника в разрезе каналов сбора. Ключи JSON соответствуют каналам:

{ "vaultCore": 0, "terraLink": 0, "novaNet": 0, "dataRay": 0 }

Project — проект

{
  "id": "uuid",
  "ownerId": "uuid",
  "name": "My project",
  "isActive": true,
  "isCallCentreActive": false,
  "createdAt": "2026-07-02T12:00:00Z",
  "dailyLimit": 100,
  "sourcesCount": 3,
  "identificationsCount": 42,
  "schedule": [1, 2, 3, 4, 5],
  "warnings": {}
}

Обратите внимание: дни недели в schedule считаются от воскресенья: 0 — воскресенье, 1 — понедельник, … 6 — суббота. Пример [1, 2, 3, 4, 5] — сбор с понедельника по пятницу.

Source — источник

{
  "id": "uuid",
  "projectID": "uuid",
  "type": "phone",
  "value": "...",
  "isActive": true,
  "dailyLimit": 12,
  "dailyLimits": { "vaultCore": 0, "terraLink": 0, "novaNet": 0, "dataRay": 0 },
  "geo": ["77"],
  "identificationsCount": 10,
  "managed": "automatically",
  "note": "",
  "createdAt": "2026-07-02T12:00:00Z"
}

PixelSource — источник «Пиксель»

{
  "type": "pixel",
  "projectId": "uuid",
  "sourceId": "uuid",
  "dailyLimit": 100,
  "isActive": true,
  "pageId": 12345,
  "name": "Landing pixel",
  "createdAt": "2026-07-02T12:00:00Z"
}

Identification — идентификация контакта

{
  "id": "uuid",
  "type": "phone",
  "isOut": false,
  "source": "...",
  "sourceNote": "",
  "phone": "79001234567",
  "channel": "...",
  "createdAt": "2026-07-02T12:00:00Z"
}

Методы: проекты

Создать проект

POST /api/ext/project

{
  "name": "My project",
  "schedule": [1, 2, 3, 4, 5]
}

name — обязательное, от 2 до 255 символов. schedule — набор дней недели 0..6, максимум 7 значений. Возвращает объект Project.

Список проектов

GET /api/ext/projects?like=My&page=0&limit=50

Параметр like фильтрует проекты по подстроке в названии. Возвращает пагинированный список Project.

Массовое изменение проектов

PATCH /api/ext/projects

{
  "ids": ["uuid", "uuid"],
  "name": "New name",
  "isActive": true
}

ids — обязательное, непустой массив. name и isActive — необязательные: не передавайте поле, если менять его не нужно. Через isActive: false проект приостанавливается, через true — возобновляется. Пустой ids вернёт ошибку 400.

Массовое удаление проектов

DELETE /api/ext/projects

{ "ids": ["uuid", "uuid"] }

Переключить день графика

POST /api/ext/project/{id}/schedule/day/{d}

{d} — день недели 0..6 (0 — воскресенье). Запрос переключает состояние дня: если день был в графике — убирает, если не было — добавляет.

Методы: источники

Добавление источников доступно в двух вариантах:

• manual — вы передаёте объект dailyLimits с лимитом на каждый канал отдельно;

• auto — вы передаёте один общий dailyLimit, система сама распределяет его между каналами.

В одном запросе можно передать несколько значений (номеров, доменов, отправителей) — система создаст отдельный источник для каждого. Все методы добавления возвращают { "result": "ok" }, кроме пикселя.

Пример: добавить телефоны конкурентов (auto)

POST /api/ext/v1/project/{id}/sources/phone/auto

{
  "phones": ["79001234567", "79007654321"],
  "dailyLimit": 12,
  "geo": ["77"]
}

Пример: добавить сайт конкурента (manual)

POST /api/ext/v1/project/{id}/sources/domain/manual

{
  "domains": ["example.com"],
  "dailyLimits": { "vaultCore": 5, "terraLink": 5, "novaNet": 5, "dataRay": 0 },
  "geo": []
}

Параметр geo принимает до 100 кодов регионов. Пустой массив — сбор по всей РФ.

Пример: создать пиксель

POST /api/ext/project/{id}/sources/pixel

{
  "name": "Landing pixel",
  "dailyLimit": 100
}

Единственный метод добавления, который возвращает не "ok", а код 201 и объект PixelSource.

Список источников проекта

GET /api/ext/project/{id}/sources?isActive=true&page=0&limit=50

Параметры: like — фильтр по названию, isActive — фильтр по активности, orderBy — сортировка, плюс стандартные page и limit.

Получить и переименовать пиксель

GET /api/ext/project/{id}/source/pixel/{sid}

PUT /api/ext/project/{id}/source/pixel/{sid}
{ "name": "Renamed pixel" }

Массово изменить регионы источников

PUT /api/ext/v1/sources/geo

{
  "ids": ["uuid"],
  "geo": ["77", "78"]
}

Пустой ids вернёт 400 no_source_ids.

Массово изменить лимиты источников

PUT /api/ext/v1/sources/limits

{
  "ids": ["uuid"],
  "dailyLimits": { "vaultCore": 0, "terraLink": 0, "novaNet": 0, "dataRay": 0 },
  "dailyLimit": 12,
  "managed": "automatically"
}

managed задаёт режим: automatically — общий лимит с автораспределением, manually — лимиты по каналам из dailyLimits. При automatically значение dailyLimit должно быть не меньше 12, иначе вернётся 400 daily_limit_too_small.

Массовое обновление источников

PATCH /api/ext/sources

{
  "ids": ["uuid"],
  "dailyLimit": 20,
  "isActive": true,
  "geo": ["77"],
  "minContacts": 1
}

Все поля кроме ids необязательные — не передавайте то, что менять не нужно. Приостановка источника — isActive: false, возобновление — true. minContacts — минимальное количество контактов (необязательное).

Заметка к источнику

PATCH /api/ext/source/{id}/note

{ "note": "Follow up next week" }

Длина заметки — от 0 до 255 символов. Пустая строка очищает заметку.

Методы: идентификации

Список идентификаций проекта

GET /api/ext/project/{id}/identifications?from=2026-07-12T00:00:00Z&to=2026-07-13T00:00:00Z&page=0&limit=50

Параметры: sourceId — фильтр по конкретному источнику (необязательный), from и to — диапазон дат в RFC 3339, плюс page и limit. Возвращает пагинированный список Identification.

Новые идентификации появляются в API по мере поступления контактов — ежедневно с 06:00 до 14:00 МСК. Чтобы забрать все контакты за день, опрашивайте метод после 14:00 МСК с диапазоном за текущие сутки и перебирайте страницы, пока не дойдёте до значения page.limit из ответа.

Коды ошибок

При обращении в поддержку по ошибке API укажите значение поля code из ответа — это идентификатор конкретного запроса в логах. Поддержка: t.me/aiup_support.

Что нельзя сделать через API

Частые вопросы

Чем API отличается от интеграции Webhook?

Webhook — AI-UP сам отправляет каждый новый контакт на указанный вами URL. API — вы сами запрашиваете данные и управляете проектами и источниками из своего кода. Для простой передачи контактов в CRM достаточно Webhook или готовых интеграций. API нужен, когда требуется программное управление: создание проектов, добавление источников, изменение лимитов и регионов.

Токен попал к третьим лицам — что делать?

Перевыпустите токен запросом POST /api/my/token/rotate из-под сессии кабинета. Старый токен перестанет действовать сразу после перевыпуска.

Почему в ответе page.limit не равен переданному limit?

В ответе это поле показывает общее количество страниц по запросу, а не размер страницы. Например "page": { "number": 0, "limit": 3 } означает: вы на первой странице, всего страниц три.

В каком часовом поясе временные метки?

Все даты — в формате RFC 3339 с явным указанием зоны. В примерах используется UTC (суффикс Z). При передаче from и to указывайте зону явно.

Можно ли создать источник с лимитом меньше 12?

В режиме automatically — нет, минимум 12 (для альфа-имён — 9). В режиме manual лимиты задаются на каждый канал отдельно через dailyLimits.

Нужна помощь с подключением API? Напишите в поддержку — поможем с авторизацией и первым запросом.

Написать в поддержку →

Следующие шаги

8.1 Доступные интеграции — обзор →

8.4 Интеграция через Webhook →

8.6 Как протестировать и удалить интеграцию →