Base URL: https://api.black-box.cc/v1.1

Документация BlackBox API

Прямой программный доступ к поисковому ядру BlackBox. Агрегация данных по 20+ миллиардам записей, 50+ источникам РФ и СНГ, цифровым идентификаторам, телеком-операторам и Telegram.

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

Каждый запрос к API должен быть авторизован с использованием вашего уникального ключа (уникальный буквенно-цифровой токен длиной 28 символов).

Ключ можно передавать одним из трех способов (рекомендуется через заголовок):

Способ Синтаксис / Пример Примечание
HTTP Header X-API-Key: XyKpLmQrTzBnVwCdFsHjKaRmPqWs Рекомендуемый безопасный вариант
Bearer Token Authorization: Bearer XyKpLmQrTzBnVwCdFsHjKaRmPqWs Стандарт OAuth2 / RFC 6750
Query Param ?token=XyKpLmQrTzBnVwCdFsHjKaRmPqWs или ?api_key=... Для быстрых тестов и веб-хуков
Где получить ключ: Обратитесь в поддержку @mnyadox для получения токена.

Лимиты и биллинг

Прозрачные условия тарификации запросов без скрытых списаний.
  • Расход баланса: 1 успешный поисковый запрос списывает ровно 1 кредит с баланса вашего ключа. При ошибках валидации параметры (400/401) баланс не списывается.
  • Ограничение частоты (Rate Limit): 70 запросов в минуту на каждый токен. При превышении возвращается код 429 Too Many Requests.
  • Формат ответа: Все ответы возвращаются в формате JSON с кодировкой UTF-8 и временем выполнения в миллисекундах (execution_time_ms).

Поиск по телефону (phone)

Поиск данных, привязанных к номеру телефона (РФ, СНГ, мир).

Запрос
curl -X GET "https://api.black-box.cc/v1.1/search?q=%2B79991234567&type=phone"      -H "X-API-Key: XyKpLmQrTzBnVwCdFsHjKaRmPqWs"
Ответ (JSON)
{
  "status": "success",
  "profile": {
    "full_name": "Иванов Иван Иванович",
    "age": 32
  },
  "telecom": {
    "operator": "МегаФон",
    "region": "Москва"
  },
  "databases": {
    "СДЭК": [{ "ФИО": "Иванов Иван", "Адрес": "г. Москва..." }]
  }
}

Поиск по ФИО (fio)

Поиск информации по фамилии, имени и отчеству. Можно добавить дату рождения для точности.

Запрос
curl -X GET "https://api.black-box.cc/v1.1/search?q=Иванов%20Иван%20Иванович&type=fio"      -H "X-API-Key: XyKpLmQrTzBnVwCdFsHjKaRmPqWs"
Ответ (JSON)
{
  "status": "success",
  "profile": {
    "primary_fio": "Иванов Иван Иванович",
    "phones": ["79991112233", "79035557788"]
  },
  "locations": [
    { "address": "г. Москва, ул. Ленина 1", "count": 3 }
  ]
}

Поиск по Email (email)

Поиск по адресу электронной почты, утечкам паролей и связанным аккаунтам.

Запрос
curl -X GET "https://api.black-box.cc/v1.1/search?q=example%40gmail.com&type=email"      -H "X-API-Key: XyKpLmQrTzBnVwCdFsHjKaRmPqWs"
Ответ (JSON)
{
  "status": "success",
  "digital": {
    "socials": ["vk.com/id123"],
    "usernames": ["example_user"]
  },
  "databases": {
    "LeakCheck": [
      { "email": "example@gmail.com", "password": "qwerty12345" }
    ]
  }
}

Поиск по авто (auto_number)

Поиск по госномеру автомобиля (РФ) или VIN-коду (парковки, страховки, штрафы).

Запрос
curl -X GET "https://api.black-box.cc/v1.1/search?q=А123АА777&type=auto_number"      -H "X-API-Key: XyKpLmQrTzBnVwCdFsHjKaRmPqWs"
Ответ (JSON)
{
  "status": "success",
  "profile": {
    "phones": ["79261234567"]
  },
  "databases": {
    "Парковки Москвы": [
      { "Авто": "А123АА777", "Марка": "TOYOTA CAMRY", "Владелец": "Иванов И." }
    ]
  }
}

Поиск по Telegram (tg)

Поиск по username или числовому Telegram ID пользователя.

Запрос
curl -X GET "https://api.black-box.cc/v1.1/search?q=durov&type=tg"      -H "X-API-Key: XyKpLmQrTzBnVwCdFsHjKaRmPqWs"
Ответ (JSON)
{
  "status": "success",
  "telegram": {
    "id": "68315",
    "username": "durov",
    "first_name": "Pavel",
    "last_name": "Durov",
    "phones": ["4477...88"]
  },
  "databases": {
    "TG Leaks": [
      { "id": "68315", "phone": "4477..." }
    ]
  }
}

Профиль и баланс ключа

Методы для проверки статуса токена, остатка кредитов и привязки к аккаунту.
GET /v1.1/me
Бесплатный вызов · Баланс не списывается

Возвращает метаданные ключа: имя, текущий баланс, активность и дату создания.

{
  "status": "success",
  "name": "Production Core",
  "balance": 480,
  "is_active": true,
  "created_at": "2026-09-17 14:20:00"
}
GET /v1.1/balance
Легковесный запрос

Быстрая проверка остатка баланса (удобно для индикаторов в CRM и ботах).

{
  "status": "success",
  "balance": 480
}

Партнерская и реферальная программа

Условия начисления бонусов за привлечение пользователей и создание зеркал сервиса.

Стандартная рефералка (+2)

Каждый пользователь получает личную реферальную ссылку. За каждого нового пользователя, запустившего бота, вам начисляется +2 поисковых запроса.

Партнерский статус (+5)

Подайте заявку на partner.black-box.cc. После подтверждения администратором вы получаете +5 поисковых запросов за каждого реферала и персональный alias ссылки.

Зеркала бота в 1 клик (+5 запросов)

Каждый пользователь может создать собственное зеркало BlackBox через @BotFather в Telegram. За каждое созданное зеркало мгновенно начисляется +5 поисковых запросов (лимит до 5 зеркал в календарный месяц).

Если основной бот недоступен, откройте link.black-box.cc — ссылка ведет в активное зеркало.

Коды ответов и ошибки

API использует стандартные HTTP-коды состояния для индикации результатов запросов.
200 OK
Запрос успешно выполнен, найденные данные возвращены в JSON.
400 Bad Request
Некорректные параметры (запрос короче 3 символов или пустой).
401 Unauthorized
Отсутствует API-токен в заголовке или параметрах.
402 Payment Required
Баланс ключа исчерпан (0 запросов). Требуется пополнение.
403 Forbidden
Указанный API-ключ не существует или деактивирован.
429 Rate Limit
Превышен лимит 70 запросов в минуту. Повторите позже.

Примеры интеграции

Готовые шаблоны кода для быстрого подключения API в ваши сервисы.
import asyncio
import httpx

API_KEY = "XyKpLmQrTzBnVwCdFsHjKaRmPqWs"
BASE_URL = "https://api.black-box.cc/v1.1"

async def search_person(query: str):
    async with httpx.AsyncClient() as client:
        headers = {"X-API-Key": API_KEY}
        params = {"q": query, "type": "auto"}
        
        response = await client.get(f"{BASE_URL}/search", headers=headers, params=params, timeout=30.0)
        
        if response.status_code == 200:
            result = response.json()
            print(f"[+] Успешно! Найдено баз: {result['stats']['sources_count']}")
            return result
        elif response.status_code == 402:
            print("[-] Недостаточно кредитов на балансе ключа!")
        else:
            print(f"[-] Ошибка HTTP {response.status_code}: {response.text}")

asyncio.run(search_person("+79991234567"))