Документация API
Добро пожаловать в спецификацию BlackBox API. Шлюз позволяет выполнять потоковый поиск данных по физическим лицам, контактам, цифровым следам, реестрам и объектам. Все ответы возвращаются в стандартизированном формате JSON с чистой иерархической структурой сущностей.
Авторизация
Каждый исходящий запрос требует токена доступа. Передавайте его через заголовок X-API-Key, Authorization: Bearer или GET-параметром ?token=.
| Метод | Формат | Пример |
|---|---|---|
| X-API-Key | X-API-Key: {ключ} |
X-API-Key: bb_live_9f8c12a4b8... |
| Bearer Token | Authorization: Bearer {ключ} |
Authorization: Bearer bb_live_9f8c12... |
| Query Param | ?token={ключ} |
...v1/search?q=...&token=bb_live_... |
Поиск по ФИО
Строка из кириллических слов без спецсимволов автоматически валидируется как ФИО. В одном запросе можно передавать имя вместе с годом рождения, датой или городом — система нормализует строку автоматически.
Поддерживаемые форматы даты:
Поиск по телефону
Номер нормализуется автоматически независимо от формата записи. Для РФ-номеров возвращается блок метаданных telecom с оператором, регионом и таймзоной.
{
"telecom": {
"query_phone": "79261234567",
"operator": "ПАО МегаФон",
"region": "г. Москва",
"country": "Россия"
},
"profile": { /* ... */ },
"databases": { /* ... */ }
}
Поиск по Email
Определяется автоматически по наличию символа @. Регистр букв игнорируется.
Поиск по никнейму
Используйте префикс nick: для точной маршрутизации запроса к базам компрометаций учётных записей.
Поиск по Telegram
Принимает @username или числовой Telegram ID. Никнейм автоматически резолвится в ID, затем выполняется поиск по индексу из 3+ млрд записей, подтягиваются профиль, история имён и юзернеймов, подарки, отправленные подарки, NFT и история их передач.
| Поле (блок telegram) | Описание |
|---|---|
| id | Числовой Telegram ID |
| username | Актуальный @username без префикса |
| full_name | Текущие имя и фамилия |
| is_scam | Метка SCAM-аккаунта |
| in_system | Метка времени первого появления в системе (миллисекунды) |
| current_usernames | Активные юзернеймы |
| names_history | История имён: firstName + date фиксации |
| usernames_history | История юзернеймов: username + date фиксации |
| phones | Привязанные телефоны из индекса и профиля |
| gifts_total / gifts | Количество и список полученных подарков: звёзды, отправитель, сообщение, дата |
| sent_gifts | Кому дарил подарки: id, username, имя |
| nfts_total / nfts | NFT-подарки: slug, название, номер, модель, паттерн, фон, цена в TON |
| nft_broadcasts | История передач NFT: slug, номер, число перемещений, последний владелец |
{
"query": "@Use4tone",
"type": "auto",
"telegram": {
"id": "7932850230",
"username": "Use4tone",
"full_name": "44tоne",
"is_scam": false,
"phones": ["79042743706"],
"gifts_total": 25,
"gifts": [{"stars": 50, "date": "2026-08-15 06:22:56", "from": {"username": "thremorr"}}],
"nfts_total": 7,
"nfts": [{"slug": "DeskCalendar-206001", "model": "Purple Front", "fullPrice": 4.3}]
}
}
Поиск по паролю
Используйте префикс pass: для поиска связанных учётных записей и почт, фигурирующих в утечках с данным паролем.
Поиск по СНИЛС
Префикс snils: + 11 цифр страхового номера без разделителей.
Поиск по ИНН / Бизнес
Префикс inn: + идентификатор (12 цифр для физлиц, 10 цифр для организаций).
Автотранспорт (ГРЗ / VIN)
ГРЗ и VIN определяются автоматически. Латинские литеры в номере приводятся к ГОСТ-эквивалентам.
Поиск по IP-адресу
IPv4 валидируется автоматически. Возвращает сведения о провайдере, геолокации и признаках проксирования.
{
"ip_info": {
"country": "США",
"city": "Mountain View",
"provider": "Google LLC",
"is_proxy": "Возможно",
"is_hosting": "Да"
},
"databases": { /* ... */ }
}
ВКонтакте
Поиск по идентификатору профиля VK. Используйте префикс vkid:.
TikTok
Выборка карточки пользователя по префиксу tt:. Возвращает статистику, дату регистрации и статус приватности.
Поиск по адресу
Парсинг структуры адреса (город, улица, дом, квартира). Поддерживаются префиксы addr:, адрес: или обозначение г..
Перевод полей
Параметр &lang=ru транслирует системные ключи объектов в читабельный вид.
Коды ответов
Лимиты и квоты
Каждый токен ограничен балансом запросов. Лимит пропускной способности — 70 запросов в минуту.
{
"status": "error",
"code": 429,
"message": "Превышен лимит запросов (70/мин). Попробуйте через 23 сек."
}
{
"status": "error",
"code": 402,
"message": "Insufficient API balance. Please refill your balance."
}
Статус шлюза
Публичный эндпоинт проверки работоспособности узлов. Не требует передачи токена.
// Все узлы активны { "status": "ok" } // Частичные работы { "status": "degraded" }
Примеры интеграции
import httpx
API_KEY = "bb_live_ВАШ_КЛЮЧ"
BASE = "https://api.black-box.cc/v1"
headers = {"X-API-Key": API_KEY}
with httpx.Client(base_url=BASE, headers=headers) as c:
r = c.get("/search", params={"q": "Иванов Иван Иванович 1985"})
data = r.json()
print("ФИО:", data["profile"]["primary_fio"])
print("Оператор:", data["telecom"]["operator"] if data["telecom"] else "-")
print("Базы:", list(data["databases"].keys()))