Документация BlackBox API
Прямой программный доступ к поисковому ядру BlackBox. Агрегация данных по 20+ миллиардам записей, 50+ источникам РФ и СНГ, цифровым идентификаторам, телеком-операторам и Telegram.
Аутентификация
bb_live_....
Ключ можно передавать одним из трёх способов (рекомендуется через заголовок):
| Способ | Синтаксис / Пример | Примечание |
|---|---|---|
| HTTP Header | X-API-Key: bb_live_3f9a7c... |
Рекомендуемый безопасный вариант |
| Bearer Token | Authorization: Bearer bb_live_3f9a7c... |
Стандарт OAuth2 / RFC 6750 |
| Query Param | ?token=bb_live_3f9a7c... или ?api_key=... |
Для быстрых тестов и веб-хуков |
Лимиты и биллинг
-
Расход баланса: 1 успешный поисковый запрос списывает ровно 1 кредит с баланса вашего ключа. При ошибках валидации параметры (400/401) баланс не списывается.
-
Ограничение частоты (Rate Limit): 70 запросов в минуту на каждый токен. При превышении возвращается код
429 Too Many Requests. -
Формат ответа: Все ответы возвращаются в формате JSON с кодировкой UTF-8 и временем выполнения в миллисекундах (
execution_time_ms).
Поиск по базам данных
Параметры запроса (Query Parameters):
| Параметр | Тип | Обязательный | Описание и форматы |
|---|---|---|---|
| q | string | Да |
Поисковый запрос (минимум 3 символа). Примеры: +79991234567, Иванов Иван Иванович, mail@domain.com, А123АА777, durov
|
| type | string | Нет |
Тип поиска (по умолчанию auto). Доступные типы:auto — интеллектуальное автоопределениеphone — номер телефона (РФ / СНГ / мир)fio — ФИО персоныemail — электронная почтаauto_number — госномер авто РФvin — VIN-код транспортного средстваtg — Telegram username или IDvk — ссылка или ID ВКонтактеpass / pass_ru — серия и номер паспортаinn — ИНН физлица или компанииsnils — СНИЛС (11 знаков)
|
Пример запроса:
curl -X GET "https://api.black-box.cc/v1/search?q=%2B79991234567&type=phone" -H "X-API-Key: bb_live_your_api_key_here"
Пример структуры ответа (JSON):
{
"status": "success",
"query": "+79991234567",
"type": "phone",
"execution_time_ms": 482,
"stats": {
"total_records": 14,
"sources_count": 4
},
"profile": {
"full_name": "Иванов Иван Иванович",
"gender": "Мужской",
"age": 32,
"birth_date": "1994-05-18",
"risk_score": 0.12
},
"telegram": {
"id": 123456789,
"username": "ivanov_tg",
"first_name": "Иван",
"last_name": "Иванов",
"gifts_count": 2
},
"telecom": {
"phone": "+79991234567",
"operator": "МегаФон",
"region": "г. Москва и Московская область",
"mnc": "02",
"mcc": "250"
},
"locations": [
{
"address": "г. Москва, ул. Тверская, д. 12, кв. 45",
"count": 6,
"frequency_percentage": "75.0%"
}
],
"digital": {
"emails": ["ivanov@gmail.com", "ivanov@yandex.ru"],
"usernames": ["ivanov94", "ivan_msk"],
"socials": ["vk.com/id987654321"]
},
"databases": {
"СДЭК 2024": [
{ "ФИО": "Иванов Иван Иванович", "Телефон": "+79991234567", "Город": "Москва" }
],
"Яндекс Еда 2022": [
{ "Имя": "Иван", "Адрес доставки": "г. Москва, Тверская 12" }
]
}
}
Профиль и баланс ключа
Возвращает метаданные ключа: имя, текущий баланс, активность и дату создания.
{
"status": "success",
"name": "Production Core",
"balance": 480,
"is_active": true,
"created_at": "2026-09-17 14:20:00"
}
Быстрая проверка остатка баланса (удобно для индикаторов в CRM и ботах).
{
"status": "success",
"balance": 480
}
Партнерская и реферальная программа
Стандартная рефералка (+2)
Каждый пользователь получает личную реферальную ссылку. За каждого нового пользователя, запустившего бота, вам начисляется +2 поисковых запроса.
Партнерский статус (+5)
Подайте заявку на partner.black-box.cc. После подтверждения администратором вы получаете +5 поисковых запросов за каждого реферала и персональный alias ссылки.
Зеркала бота в 1 клик (+5 запросов)
Каждый пользователь может создать собственное зеркало BlackBox через @BotFather в Telegram. За каждое созданное зеркало мгновенно начисляется +5 поисковых запросов (лимит до 5 зеркал в календарный месяц).
Коды ответов и ошибки
Примеры интеграции
import asyncio
import httpx
API_KEY = "bb_live_your_token_here"
BASE_URL = "https://api.black-box.cc/v1"
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"))