Перейти к основному содержанию
POST
curl
Для поиска кандидатов в реестрах компаний сначала используйте этот endpoint. Поиск не создаёт сохранённую Manual Check. Успешные автономные поиски по платному источнику данных о компаниях стоят $0.50 за запрос, независимо от количества кандидатов. Пустые результаты, неудачные поиски и результаты, полученные только из других источников, не тарифицируются. Последующее получение профиля тарифицируется отдельно. Для поиска, который может использовать платный источник, Didit проверяет и резервирует применимую цену поиска до обращения к реестру. Недостаточный баланс возвращает 403 с code: "insufficient_credits". Контрактный биллинг следует согласованной с вами ставке за поиск; ненастроенная контрактная ставка отклоняется до поиска. Поиски в песочнице бесплатны. Каждый повторный успешный поиск является новым платным запросом; доставка обратного вызова не добавляет ещё одного списания за поиск. Если вы передаёте webhook_url, Didit может вернуть ответ сразу, пока провайдер обрабатывает поиск, а затем отправить кандидатов на ваш URL обратного вызова, когда они будут готовы. Обратный вызов намеренно не подписывается, поэтому для этого уведомления о поиске не нужно настраивать секрет webhook. См. пример payload обратного вызова поиска. После того как вы выберете нужный kyb_response_id, вызовите POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ или POST /v3/kyb/ubo/, чтобы получить тарифицируемый профиль реестра на нужном вам уровне.
fetch_status каждого кандидата равен pending во время поиска и остаётся pending, пока вы не выберете этого кандидата. Поиск только перечисляет кандидатов, а выбор получает полный профиль. Не опрашивайте поиск в ожидании его завершения.kyb_response_id — это непрозрачный временный дескриптор, привязанный к одному поисковому запросу: передавайте его обратно точно в том виде, в каком получили, никогда не разбирайте его и не выводите из него ничего, и ожидайте, что повтор того же поиска вернёт новые идентификаторы. Выбирайте кандидата сразу после поиска, а когда вам нужен стабильный идентификатор самой компании, используйте registration_number.

Уровень поиска

tier выбирает уровень реестра, цепочку провайдеров которого использует поиск: basic (по умолчанию, цепочка Lite), shareholders или ubo. Список кандидатов формируется по цепочке этого уровня, которая не всегда совпадает с источником, по которому работает поиск Lite. Поэтому пустой результат поиска Lite не доказывает, что реестр не содержит компанию. Повторите поиск на нужном вам уровне. Если страна не предлагает указанный вами уровень, поиск выполняется на самом высоком из доступных уровней, не превышающем запрошенный. Страна без каких-либо данных реестра не предлагается для проверок по реестрам. В этом случае продолжайте ввод компании вручную. Выполняйте поиск на уровне, который вы планируете купить, а затем получайте кандидата через endpoint, который его продаёт:

search_type

search_type принимает только contains, и это значение по умолчанию. Источники реестра, на которых выполняется поиск, сопоставляют название компании по вхождению. Поэтому start_with и fuzzy отклоняются с 400 ("start_with" is not a valid choice), а не молча обрабатываются как contains. Для точного совпадения компании передавайте registration_number.

Размещённый и автономный поиск

POST /v1/kyb/search/ является поиском, который выполняет размещённый поток верификации. Он аутентифицируется по сессии верификации, возвращает 403 на запрос с API-ключом и не принимает tier: конфигурация реестра KYB в сценарии определяет цепочку. Автономный API вызывает POST /v2/kyb/search/ или POST /v3/kyb/search/ с вашим x-api-key. Входной параметр tier и endpoint’ы выбора по уровням позволяют автономной интеграции получать тех же кандидатов на нужном ей уровне.

Обработка сбоев реестра

Если провайдер реестра временно недоступен, endpoint возвращает 502 со стабильным машиночитаемым кодом:
Получив этот код, позвольте пользователю продолжить ввод компании вручную или попросите его повторить попытку позже. Ошибки валидации держите отдельно: некорректные входные данные поиска возвращают 400 и не используют этот код сбоя.

Обработка неподдерживаемых стран и лимитов поиска

Два других стабильных кода сообщают, что нужно прекратить повторные попытки и продолжить ввод компании вручную: В размещённом потоке каждый шаг реестра допускает 3 поиска по платному источнику данных о компаниях. После третьего поиска заявителю предлагается ручной ввод. Выбор кандидата, который является регистрацией товарного знака, а не компанией, возвращает 400 с code: "kyb_registry_entry_not_a_company". Выберите компанию из результатов поиска.

Авторизации

x-api-key
string
header
обязательно

API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys.

Тело

application/json
country_code
string
обязательно

Двухбуквенный код страны ISO 3166-1 alpha-2, в реестре компаний которой выполняется поиск. Например, GB. Если реестры компаний действуют на уровне штата или провинции, добавьте код подразделения ISO 3166-2 в формате XX-YY: US-CA выполняет поиск по реестру Калифорнии. Для поиска по США всегда требуется код подразделения — одиночный код US отклоняется. Нечувствителен к регистру; нормализуется к верхнему регистру.

Maximum string length: 10
Пример:

"GB"

name
string

Название компании для поиска. Требуется либо name, либо registration_number.

Maximum string length: 255
Пример:

"Tesco"

registration_number
string

Регистрационный номер в реестре для поиска. Требуется указать либо name, либо registration_number.

Maximum string length: 100
tier
enum<string>
по умолчанию:basic

Уровень реестра, по цепочке провайдеров которого выполняется этот поиск. basic (по умолчанию) выполняет поиск по цепочке Lite для страны; shareholders и ubo выполняют поиск по цепочке структуры владения соответствующего уровня, которая может использовать другой источник, поэтому пустой результат поиска Lite не доказывает отсутствие компании в реестре. Если для страны указанный уровень недоступен, поиск выполняется на наивысшем доступном уровне вплоть до запрошенного. Получите кандидата с endpoint, предоставляющего запрошенный уровень: POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ или POST /v3/kyb/ubo/.

Доступные опции:
basic,
shareholders,
ubo
Пример:

"basic"

search_type
enum<string>
по умолчанию:contains

Стратегия сопоставления имён, применяемая при поиске по реестрам. Единственным допустимым значением является contains: ни один источник реестров, используемый при поиске, не поддерживает режим префикса или нечёткого поиска, поэтому start_with и fuzzy отклоняются с кодом 400 (not a valid choice).

Доступные опции:
contains
vendor_data
string

Ваш идентификатор этого поиска; возвращается в ответе и включается в обратный вызов webhook.

metadata
object | null

JSON в свободной форме; возвращается в ответе и включается в обратный вызов webhook.

webhook_url
string<uri>

Переключает поиск в асинхронный режим: API немедленно возвращает ответ и отправляет неподписанный callback kyb.registry_search.resolved методом POST на этот URL, когда список кандидатов готов.

Maximum string length: 500

Ответ

Поиск принят. Синхронный режим возвращает сформированный список кандидатов; режим webhook возвращает ответ немедленно (часто со статусом search_status: "pending") и доставляет финальный список через обратный вызов kyb.registry_search.resolved.

request_id
string<uuid>

С webhook_url: сохранённый id запроса на поиск, возвращаемый как request_id в обратном вызове kyb.registry_search.resolved. Без webhook_url: временный UUID корреляции (поиск не сохраняется).

kyb_registry
object
vendor_data
string | null

Эхо отправленных вами vendor_data.

metadata
object | null

Эхо-значение переданного вами metadata.

created_at
string<date-time>
Последнее изменение 7 ноября 2026 г.