API реестра KYB: поиск и выбор компании

Endpoints и биллинг

Успешные автономные поиски с использованием платного источника данных о компаниях стоят $0.50 за запрос, независимо от количества кандидатов. Пустые результаты, неуспешные поиски и результаты, полученные только из других источников, не тарифицируются. Последующее получение профиля оплачивается отдельно. Получение данных продаётся в трёх уровнях детализации, по одному эндпоинту на каждый, с ценами по странам (цены по странам):

Эндпоинт	Что вы получаете	Цена
`POST /v3/kyb/search/`	Компании-кандидаты: название, регистрационный номер, статус, тип	$0.50, если возвращены результаты платного источника
`POST /v3/kyb/select/`	Lite: профиль компании (идентификаторы, статус, организационно-правовая форма, дата регистрации, зарегистрированный адрес, вид деятельности, контактные данные) и должностные лица	Цена Lite: $2.00-$3.00 в зависимости от страны
`POST /v3/kyb/shareholders/`	Lite плюс прямые акционеры с диапазонами их долей	Цена Shareholders: $5.00-$22.00 в зависимости от страны
`POST /v3/kyb/ubo/`	Shareholders плюс конечные бенефициарные владельцы, установленные по цепочке владения	Цена UBO: $9.00-$96.00 в зависимости от страны

select относится к уровню Lite: именно его размещённый сценарий KYB оплачивает при проверке по реестру на уровне Lite, и он сохраняет действовавший ранее контракт. Под Европой понимаются ЕЭЗ, Соединённое Королевство и Швейцария. Поиск Shareholders или UBO запрашивает источник данных о владении, который обслуживает этот уровень. Если этот источник сообщает, что не располагает данными о компании, поиск дополнительно запрашивает другие реестровые источники страны, поэтому компания, которой нет в источнике данных о владении, всё равно предлагается как кандидат, а не завершается ручным вводом. Кандидаты, найденные таким образом, сохраняют запрошенный вами уровень: при их получении повторно проверяется источник данных о владении, и если он по-прежнему не располагает данными о компании, доставляется и оплачивается профиль Lite с registry_ownership_status: "not_held".

Вы платите за доставленный уровень. Каждый ответ содержит registry_tier_requested и registry_tier_delivered. Если реестры страны не содержат данных о владении или в реестре нет записи о владении для выбранной компании, результат запроса данных о владении предоставляется и оплачивается по самому высокому доступному уровню (обычно Lite), а registry_ownership_status указывает причину. Запрос UBO, в результате которого отчёт не называет ни одного физического лица как бенефициарного владельца, доставляется и оплачивается как Shareholders.

Версии. Эндпоинты Shareholders и UBO существуют только в /v3/. Плата за автономный поиск также применяется к /v2/kyb/search/; получение профиля оплачивается отдельно.

Статус владения

registry_ownership_status показывает, что произошло с разделом о владении в запросе Shareholders или UBO:

Значение	Описание
`not_requested`	Вызов был запросом на получение Lite-профиля, поэтому данные о владении не запрашивались.
`delivered`	Реестр предоставил данные о владении, и уровень из `registry_tier_delivered` и есть тот, за который вы платите.
`not_held`	Реестр владения ответил, но не содержит сведений об этой компании, поэтому записи о владении для выдачи нет: компания найдена другим реестровым источником страны. Вместо этого доставляется и оплачивается профиль Lite, с `registry_data.ownership_error: "company_not_found"`.
`unavailable`	Данные о владении не были предоставлены по любой другой причине: запись в реестре не называет ни одного владельца, либо реестр вообще не вернул раздел владения, либо к нему не удалось обратиться. `registry_data.ownership_error` указывает, какая именно. Вместо этого доставляется и оплачивается профиль Lite.
`pending`	Раздел владения ещё не получен из реестра. Ничего не списывается, а `registry_tier_delivered` равен `null`, пока раздел не получен.

not_held и unavailable доставляются и оплачиваются как Lite, но это разные результаты: not_held означает, что источник данных о владении не охватывает компанию, то есть пробел в покрытии, тогда как unavailable означает, что данные не были предоставлены, из-за сбоя или потому что раздел в реестре остался пустым. Причину называет registry_data.ownership_error. Запросы, которые раньше возвращали unavailable, потому что реестр владения не находил компанию, теперь возвращают not_held; если вы реализуете ветвление по статусу, обрабатывайте оба значения одинаково как доставку Lite. Два её значения означают разное и не должны читаться как один и тот же результат:

`ownership_error`	Описание
`no_owners_on_record`	Реестр ответил по разделу владения, и в нём не указано ни одного владельца. У этого реестра на компанию нет таблицы капитализации.
`ownership_section_unavailable`	Реестр не вернул раздел владения, поэтому для него ничего не было предоставлено. Список отсутствует, а не пуст: это ничего не говорит о том, кто владеет компанией.

Раздел, который реестр не вернул, также фиксируется структурно в registry_data.section_errors с ключами разделов (officers, shareholders, group_structure) и соответствующими им статусами, которые вернул реестр:

{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}

section_errors описывает ответ, который вы получили, а не историю, которая к нему привела. Раздел, не возвращённый при первом запросе и предоставленный при последующем проходе (см. асинхронное получение ниже), теряет свою запись, поэтому registry_ownership_status, ownership_error и section_errors всегда согласованы: у раздела со статусом delivered никогда не бывает записи, а у no_owners_on_record никогда не бывает записи для shareholders. Раздел также никогда не предоставляется частично: если реестр отдаёт первую страницу списка, а затем не отдаёт более позднюю, получение на этой попытке не завершается. Получение со статусом pending повторяется при следующем проходе, а новый запрос получает ответ с ошибкой недоступности реестра. Поэтому предоставленный список officers или акционеров всегда является полным списком, который хранит реестр. Раздел, перечисленный в section_errors, нужно считать данными, которые так и не были предоставлены, а не пустым результатом: пустой список officers или акционеров рядом с записью в section_errors для того же раздела ничего не говорит о компании.

Асинхронное получение данных о владении

Некоторые реестры запрашиваются по требованию: первый запрос по компании, по поводу которой к источнику ещё не обращались, возвращается без раздела владения, пока данные получаются, и они появляются в течение пары минут. Считать это «нет данных о владении» означало бы занизить оценку компании, у которой действительно есть акционеры, поэтому запрос возвращается со статусом pending. Пока получение находится в статусе pending, fetch_status тоже равен pending, а статус ответа равен 202 Accepted. Didit сам повторяет запрос к разделу и завершает получение без дополнительных вызовов с вашей стороны:

когда данные о владении поступят, акционеры и бенефициарные владельцы появятся в сохранённой проверке, registry_tier_delivered станет уровнем, который был предоставлен, и списание произойдёт по этому уровню;
если раздел всё ещё пуст, когда закрывается окно повторных попыток, статус становится unavailable, а запрос доставляется и оплачивается как Lite.

Сохраните request_id и опрашивайте GET /v3/session/{request_id}/decision/, пока registry_checks[0].company.fetch_status не станет resolved. Не повторяйте запрос на получение, пока статус pending: каждый новый POST является отдельным запросом, который тарифицируется отдельно. Используйте POST /v3/kyb/search/, чтобы найти подходящие компании. Поиск не создаёт сохранённой проверки. Параметр tier при поиске задаёт цепочку, по которой выполняется поиск: см. уровень поиска. Поиск по реестрам может занимать около 90 секунд. Передайте webhook_url, если хотите, чтобы Didit сразу вернул ответ и уведомил ваш URL, когда кандидаты будут готовы. Обратный вызов поиска намеренно не подписывается, поэтому для этого облегчённого уведомления не нужно настраивать общий секрет. Используйте POST /v3/kyb/select/, POST /v3/kyb/shareholders/ или POST /v3/kyb/ubo/ с возвращённым kyb_response_id, чтобы получить профиль на нужном уровне. Получение тарифицируется и сохраняет результат как Manual Check в Business Console.

Типичный сценарий

Ищите по названию компании, регистрационному номеру и стране на том tier, который вы собираетесь купить (по умолчанию используется цепочка Lite basic; shareholders и ubo ищут по цепочке этого уровня).
Если search_resolved=false, дождитесь необязательного обратного вызова по webhook_url вместо опроса.
Покажите найденных кандидатов вашему оператору или клиенту.
Получите соответствующий kyb_response_id на нужном уровне (select для Lite, shareholders или ubo).
Сохраните возвращённый request_id и используйте его, чтобы получить сохранённый результат верификации бизнеса.

Обратный вызов после поиска

Когда провайдер сообщает Didit, что поиск завершён, Didit отправляет один POST на ваш webhook_url:

{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}

Относитесь к обратному вызову как к уведомлению о доставке. Используйте возвращённый kyb_response_id в запросах POST /v3/kyb/select/, POST /v3/kyb/shareholders/ или POST /v3/kyb/ubo/, чтобы получить профиль из реестра. Этот запрос тарифицируется.

Последнее изменение 7 ноября 2026 г.

​Endpoints и биллинг

​Статус владения

​Асинхронное получение данных о владении

​Типичный сценарий

​Обратный вызов после поиска

Endpoints и биллинг

Статус владения

Асинхронное получение данных о владении

Типичный сценарий

Обратный вызов после поиска