> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API поиска в реестрах KYB - поиск компаний > Didit: POST /v3/kyb/search/ находит компании-кандидатов. Успешный поиск в платных источниках стоит $0.50 за запрос; профиль — отдельно. Для поиска кандидатов в реестрах компаний сначала используйте этот endpoint. Поиск не создаёт сохранённую Manual Check. Успешные автономные поиски по платному источнику данных о компаниях стоят **\$0.50 за запрос**, независимо от количества кандидатов. Пустые результаты, неудачные поиски и результаты, полученные только из других источников, не тарифицируются. Последующее получение профиля тарифицируется отдельно. Для поиска, который может использовать платный источник, Didit проверяет и резервирует применимую цену поиска до обращения к реестру. Недостаточный баланс возвращает `403` с `code: "insufficient_credits"`. Контрактный биллинг следует согласованной с вами ставке за поиск; ненастроенная контрактная ставка отклоняется до поиска. Поиски в песочнице бесплатны. Каждый повторный успешный поиск является новым платным запросом; доставка обратного вызова не добавляет ещё одного списания за поиск. Если вы передаёте `webhook_url`, Didit может вернуть ответ сразу, пока провайдер обрабатывает поиск, а затем отправить кандидатов на ваш URL обратного вызова, когда они будут готовы. Обратный вызов намеренно не подписывается, поэтому для этого уведомления о поиске не нужно настраивать секрет webhook. См. [пример payload обратного вызова поиска](https://docs.didit.me/ru/standalone-apis/kyb-registry.md#обратный-вызов-после-поиска). После того как вы выберете нужный `kyb_response_id`, вызовите `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` или `POST /v3/kyb/ubo/`, чтобы получить тарифицируемый профиль реестра на нужном вам уровне. > [!NOTE] > > `fetch_status` каждого кандидата равен `pending` во время поиска и остаётся `pending`, пока вы не выберете этого кандидата. Поиск только перечисляет кандидатов, а выбор получает полный профиль. Не опрашивайте поиск в ожидании его завершения. > > `kyb_response_id` — это непрозрачный временный дескриптор, привязанный к одному поисковому запросу: передавайте его обратно точно в том виде, в каком получили, никогда не разбирайте его и не выводите из него ничего, и ожидайте, что повтор того же поиска вернёт новые идентификаторы. Выбирайте кандидата сразу после поиска, а когда вам нужен стабильный идентификатор самой компании, используйте `registration_number`. ## Уровень поиска `tier` выбирает уровень реестра, цепочку провайдеров которого использует поиск: `basic` (по умолчанию, цепочка Lite), `shareholders` или `ubo`. Список кандидатов формируется по цепочке этого уровня, которая не всегда совпадает с источником, по которому работает поиск Lite. Поэтому пустой результат поиска Lite не доказывает, что реестр не содержит компанию. Повторите поиск на нужном вам уровне. Если страна не предлагает указанный вами уровень, поиск выполняется на самом высоком из доступных уровней, не превышающем запрошенный. Страна без каких-либо данных реестра не предлагается для проверок по реестрам. В этом случае продолжайте ввод компании вручную. Выполняйте поиск на уровне, который вы планируете купить, а затем получайте кандидата через endpoint, который его продаёт: | `tier`, по которому выполнен поиск | Endpoint, который получает кандидата | | - | - | | `basic` (по умолчанию) | `POST /v3/kyb/select/` (Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## 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` со стабильным машиночитаемым кодом: ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` Получив этот код, позвольте пользователю продолжить ввод компании вручную или попросите его повторить попытку позже. Ошибки валидации держите отдельно: некорректные входные данные поиска возвращают `400` и не используют этот код сбоя. ## Обработка неподдерживаемых стран и лимитов поиска Два других стабильных кода сообщают, что нужно прекратить повторные попытки и продолжить ввод компании вручную: | Статус | `code` | Когда | | - | - | - | | `400` | `kyb_registry_country_unsupported` | У страны нет источника данных реестра компаний ни на одном уровне. Ограничение постоянное, поэтому повтор того же поиска никогда не приводит к успеху. | | `429` | `kyb_registry_search_limit_reached` | Ваше приложение израсходовало лимит в 600 поисков в час по платным источникам данных о компаниях, и для страны не осталось бесплатного источника. Дождитесь окончания окна или введите компанию вручную. | В размещённом потоке каждый шаг реестра допускает 3 поиска по платному источнику данных о компаниях. После третьего поиска заявителю предлагается ручной ввод. Выбор кандидата, который является регистрацией товарного знака, а не компанией, возвращает `400` с `code: "kyb_registry_entry_not_a_company"`. Выберите компанию из результатов поиска. ## OpenAPI ````yaml ru/openapi-25.json POST /v3/kyb/search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: >- API верификации личности. Аутентификация выполняется с помощью заголовка x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/search/: post: tags: - Standalone APIs summary: Поиск компании в реестре KYB (отдельный) description: >- Поиск компаний-кандидатов в официальных реестрах компаний по названию и/или регистрационному номеру. Это шаг 1 двухэтапного процесса работы с реестром: **поиск** возвращает краткие сведения о кандидатах, а затем `POST /v3/kyb/select/` получает полный профиль одного кандидата. **Биллинг поиска.** Успешные поисковые запросы с использованием платного источника данных о компаниях стоят USD 0.50 за запрос независимо от количества кандидатов. Пустые результаты, сбои и результаты, полученные только из других источников, не тарифицируются. Применимая цена резервируется до выполнения поиска; при недостаточном балансе возвращается 403 с кодом `insufficient_credits`. При наличии договорённостей применяются контрактные тарифы, а ненастроенный контрактный тариф на поиск возвращает 403. Поисковые запросы в песочнице бесплатны. Повторный успешный поиск может повлечь за собой дополнительное списание; доставка callback не тарифицируется. Получение профиля оплачивается отдельно. Эта плата за поиск также применяется к v2. Кандидаты всегда возвращаются со статусом `fetch_status: "pending"`: полные данные о компании запрашиваются (и тарифицируются) только при выборе (select). **`kyb_response_id` является временным.** Это дескриптор отдельного поиска, а не постоянный идентификатор компании. Выбирайте кандидата сразу после поиска и выполняйте повторный поиск для получения свежего дескриптора вместо его сохранения. **`tier` определяет цепочку провайдеров.** `tier` указывает уровень реестра, по которому выполняется поиск: `basic` (по умолчанию, цепочка Lite), `shareholders` или `ubo`. Поиск использует цепочку провайдеров, обслуживающую этот уровень, и это не всегда та же цепочка, к которой обращается поиск Lite. Поэтому пустой результат поиска Lite не является доказательством отсутствия компании в реестре — выполните повторный поиск на необходимом уровне. В стране, где запрашиваемый уровень недоступен, поиск выполняется на максимальном доступном уровне вплоть до указанного. Получайте данные кандидата через endpoint, соответствующий этому уровню: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` или `POST /v3/kyb/ubo/`. **Аутентификация.** `POST /v3/kyb/search/` (и `/v2/`) принимает API-ключ вашего приложения в заголовке `x-api-key`. Размещённый маршрут `POST /v1/kyb/search/` аутентифицируется по сессии и вызывается размещённым процессом верификации: он возвращает `403` при использовании API-ключа и не принимает `tier` — цепочку определяет конфигурация реестра KYB в сценарии. **Два режима.** - *Синхронный (по умолчанию):* API опрашивает реестр до завершения поиска и возвращает итоговый список кандидатов (`search_resolved: true`). - *Асинхронный:* передайте `webhook_url`, и API ответит немедленно — обычно со статусом `search_status: "pending"` и пустым списком кандидатов — а затем отправит POST-запрос с callback `kyb.registry_search.resolved` на ваш URL после завершения работы реестра. Тело callback содержит `{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}` — обратите внимание, что `timestamp` и `created_at` в callback представляют собой целые числа в формате epoch, в отличие от формата ISO в `created_at` этого endpoint — и отправляется **без подписи** (заголовок `X-Didit-Unsigned-Callback: true`, без `X-Signature`). **Коды стран.** ISO 3166-1 alpha-2 (`GB`, `DE`), а также коды подразделений `XX-YY`, если реестры региональные — например, `US-CA` для Калифорнии. **Песочница.** Ключи приложений из песочницы возвращают одного статического кандидата без обращения к реестрам. operationId: post_v3_kyb_search parameters: [] requestBody: required: true content: application/json: schema: type: object required: - country_code properties: country_code: type: string maxLength: 10 description: >- Двухбуквенный код страны ISO 3166-1 alpha-2, в реестре компаний которой выполняется поиск. Например, `GB`. Если реестры компаний действуют на уровне штата или провинции, добавьте код подразделения ISO 3166-2 в формате `XX-YY`: `US-CA` выполняет поиск по реестру Калифорнии. Для поиска по США всегда требуется код подразделения — одиночный код `US` отклоняется. Нечувствителен к регистру; нормализуется к верхнему регистру. example: GB name: type: string maxLength: 255 description: >- Название компании для поиска. Требуется либо `name`, либо `registration_number`. example: Tesco registration_number: type: string maxLength: 100 description: >- Регистрационный номер в реестре для поиска. Требуется указать либо `name`, либо `registration_number`. tier: type: string enum: - basic - shareholders - ubo default: basic description: >- Уровень реестра, по цепочке провайдеров которого выполняется этот поиск. `basic` (по умолчанию) выполняет поиск по цепочке Lite для страны; `shareholders` и `ubo` выполняют поиск по цепочке структуры владения соответствующего уровня, которая может использовать другой источник, поэтому пустой результат поиска Lite не доказывает отсутствие компании в реестре. Если для страны указанный уровень недоступен, поиск выполняется на наивысшем доступном уровне вплоть до запрошенного. Получите кандидата с endpoint, предоставляющего запрошенный уровень: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` или `POST /v3/kyb/ubo/`. example: basic search_type: type: string enum: - contains default: contains description: >- Стратегия сопоставления имён, применяемая при поиске по реестрам. Единственным допустимым значением является `contains`: ни один источник реестров, используемый при поиске, не поддерживает режим префикса или нечёткого поиска, поэтому `start_with` и `fuzzy` отклоняются с кодом `400` (`not a valid choice`). vendor_data: type: string description: >- Ваш идентификатор этого поиска; возвращается в ответе и включается в обратный вызов webhook. metadata: type: object nullable: true description: >- JSON в свободной форме; возвращается в ответе и включается в обратный вызов webhook. webhook_url: type: string format: uri maxLength: 500 description: >- Переключает поиск в асинхронный режим: API немедленно возвращает ответ и отправляет неподписанный callback `kyb.registry_search.resolved` методом POST на этот URL, когда список кандидатов готов. example: country_code: GB name: Tesco search_type: contains vendor_data: company-1234 responses: '200': description: >- Поиск принят. Синхронный режим возвращает сформированный список кандидатов; режим webhook возвращает ответ немедленно (часто со статусом `search_status: "pending"`) и доставляет финальный список через обратный вызов `kyb.registry_search.resolved`. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- С `webhook_url`: сохранённый id запроса на поиск, возвращаемый как `request_id` в обратном вызове `kyb.registry_search.resolved`. Без `webhook_url`: временный UUID корреляции (поиск не сохраняется). kyb_registry: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: Эхо отправленных вами `vendor_data`. metadata: type: object nullable: true description: Эхо-значение переданного вами `metadata`. created_at: type: string format: date-time examples: Resolved search: summary: Синхронный режим — итоговый список кандидатов value: request_id: 0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a kyb_registry: companies: - kyb_response_id: 69aeeb95febb0f1704042259 name: Tesco PLC registration_number: '00445790' status: active type: Public Limited Company risk_level: null fetch_status: pending - kyb_response_id: 69aeeb95febb0f170404225a name: E-TESCO LTD registration_number: '15168476' status: active type: Private Limited Company risk_level: null fetch_status: pending pagination: total: 2 page: 1 per_page: 25 search_status: resolved search_resolved: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:40:00.000000+00:00' Pending search (webhook mode): summary: >- `webhook_url` передан — кандидаты поступают через обратный вызов kyb.registry_search.resolved value: request_id: 5f2d8c1b-7e4a-4b9c-9f0d-3a6e8c2b1d4f kyb_registry: companies: [] pagination: total: 0 page: 1 per_page: 25 search_status: pending search_resolved: false vendor_data: company-1234 metadata: source: onboarding created_at: '2026-06-11T10:41:00.000000+00:00' '400': description: >- Ошибка валидации. Проблемы на уровне полей используют стандартную структуру DRF; правило проверки имени/регистрационного номера возвращает ошибку в `non_field_errors`. Если страна не поддерживается реестрами, возвращается `400` с `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing search criteria: summary: Не указаны ни `name`, ни `registration_number` value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: >- Должен быть `XX` (alpha-2) или подразделением в формате `XX-YY` value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: Принимается только `contains` value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url` должен быть корректным URL' value: webhook_url: - Enter a valid URL. Country not covered: summary: Ни один реестр компаний не охватывает эту страну value: detail: >- Company registry search is not available for this country. Enter the company details manually to continue. code: kyb_registry_country_unsupported '403': description: >- В доступе отказано. Возвращается, если заголовок `x-api-key` отсутствует; неверный, отозванный или истекший ключ возвращает `401`. Отсутствующий ключ возвращает `403` с `{"detail": ...}`; неверный, отозванный или истекший ключ возвращает `401`. Также возвращается перед поиском, если не удаётся покрыть применимую комиссию за поиск (`code: "insufficient_credits"`), или если отсутствует договорной тариф на поиск. content: application/json: examples: Missing or invalid API key: summary: >- Отсутствует заголовок `x-api-key`, либо ключ недействителен/отозван value: detail: You do not have permission to perform this action. '429': description: >- Превышен лимит запросов или исчерпан лимит поисковых запросов. Endpoint'ы POST/PATCH/DELETE делят общий лимит в 300 запросов на запись в минуту на один API-ключ (для создания транзакций и отправки событий действует отдельный лимит в 600) с заголовками `X-RateLimit-*` и `Retry-After`. Отдельно платные поисковые запросы по реестрам ограничены 600 запросами на приложение в час: сверх этого лимита возвращается ответ `429` с `code: kyb_registry_search_limit_reached`, при этом поиск только по бесплатным источникам продолжает работать. Подождите и повторите поиск позже. content: application/json: examples: Write rate limit exceeded: summary: Более 300 запросов на запись в текущую минуту value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. Search allowance spent: summary: Более 600 платных поисков за последний час value: detail: >- The maximum number of company registry searches for this session has been reached. Enter the company details manually to continue. code: kyb_registry_search_limit_reached schema: type: object properties: detail: type: string code: type: string '502': description: >- Провайдер реестра KYB временно недоступен: ответ 5xx, таймаут или сбой подключения со стороны вышестоящего реестра. Поиск не тарифицируется. Повторите попытку позже, либо, в размещённом сценарии верификации Didit, пользователю автоматически предлагается ручной ввод данных компании вместо ошибки, требующей только повтора. content: application/json: examples: Registry provider outage: summary: Провайдер реестра не ответил на поисковый запрос value: detail: >- The KYB registry provider is temporarily unavailable. Please try again shortly. code: kyb_registry_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/kyb/search/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "country_code": "GB", "name": "Tesco", "search_type": "contains", "vendor_data": "company-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.search( country_code="GB", name="Tesco", search_type="contains", vendor_data="company-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.kyb.search({ country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Search(ctx, didit.KYBSearchParams{\n\tCountryCode: \"GB\",\n\tName: didit.String(\"Tesco\"),\n\tSearchType: didit.Some(didit.KYBSearchParamsSearchType(\"contains\")),\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.KybSearchParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.kyb().search(KybSearchParams.builder() .countryCode("GB") .name("Tesco") .searchType(KybSearchParams.SearchType.of("contains")) .vendorData("company-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- kyb->search([ 'country_code' => 'GB', 'name' => 'Tesco', 'search_type' => 'contains', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.search( country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234" ) puts result.to_h - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Kyb.SearchAsync(new KybSearchParams { CountryCode = "GB", Name = "Tesco", SearchType = new KybSearchParamsSearchType("contains"), VendorData = "company-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBRegistrySearchResults: type: object properties: companies: type: array items: type: object properties: kyb_response_id: type: string nullable: true description: >- Идентификатор (handle) для этого кандидата — передайте его в `POST /v3/kyb/select/`, чтобы получить полный профиль. Является эфемерным и привязанным к этому поиску: не сохраняйте его на длительный срок; выполните повторный поиск, чтобы получить актуальный. example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: Зарегистрированное наименование компании. example: Tesco PLC registration_number: type: string nullable: true description: Регистрационный номер в реестре. example: '00445790' status: type: string nullable: true description: >- Нормализованный статус компании по данным реестра (например, `active`, `dissolved`, `inactive`, `struck off`). example: active type: type: string nullable: true description: Организационно-правовая форма по данным реестра. example: Public Limited Company registered_address: type: string nullable: true description: >- Зарегистрированный адрес кандидата, если он указан в реестре. Используйте его вместе с регистрационным номером, чтобы различать компании с одинаковыми названиями: в США кандидат может быть указан в штате, где компания ведёт деятельность, а не в том штате, по которому вы выполняли поиск. example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: >- Уровень риска по данным реестра, если доступен. Обычно `null` во время поиска. fetch_status: type: string nullable: true description: >- Всегда `pending` для кандидатов поиска — полный профиль компании запрашивается (и тарифицируется) только при выборе кандидата. example: pending description: >- Дедуплицированный список кандидатов. Пуст, пока `search_resolved=false` (режим webhook) или если совпадений не найдено. pagination: type: object properties: total: type: integer description: Количество возвращённых кандидатов. page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: Статус жизненного цикла поиска в реестре. search_resolved: type: boolean description: '`true`, когда список кандидатов окончательно сформирован.' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.