Документация 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: для точной маршрутизации запроса к базам компрометаций учётных записей.
Поиск по паролю
Используйте префикс 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()))