KYB Registry Search
Search official company registries for candidate companies by name and/or registration number. This is step 1 of the two-step registry flow: search returns lightweight candidates, then POST /v3/kyb/select/ retrieves the full profile of one candidate.
The search is free — no balance check, no billing. Candidates always come back with fetch_status: "pending": the full company data is only fetched (and billed) on select.
kyb_response_id is ephemeral. It is a per-search handle, not a stable company id. Select promptly after searching and re-search to get a fresh handle instead of storing it.
Two modes.
- Synchronous (default): the API polls the registry until the search resolves and returns the final candidate list (
search_resolved: true). - Asynchronous: pass
webhook_urland the API returns immediately — usually withsearch_status: "pending"and an empty candidate list — then POSTs akyb.registry_search.resolvedcallback to your URL when the registry finishes. The callback body is{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}— notetimestampandcreated_atin the callback are epoch integers, unlike this endpoint’s ISOcreated_at— and is sent unsigned (headerX-Didit-Unsigned-Callback: true, noX-Signature).
Country codes. ISO 3166-1 alpha-2 (GB, DE), plus XX-YY subdivision codes where registries are regional — e.g. US-CA for California.
Sandbox. Keys from sandbox applications return one static candidate without contacting any registry.
webhook_url, Didit can return immediately while the provider resolves the search, then post the candidates to your callback URL when they are ready. The callback is unsigned by design, so you do not need to configure a webhook secret for this search notification. See the search callback payload example.
After you pick the correct kyb_response_id, call POST /v3/kyb/select/ to retrieve the billable registry profile.
fetch_status is pending at search time and stays pending until you select that candidate — search only lists candidates, and select is what fetches the full profile. Do not poll search waiting for it to resolve.kyb_response_id is an ephemeral handle scoped to one search request: repeating the same search returns new ids. Select the candidate promptly after searching, and use registration_number when you need a stable identifier for the company itself.Authorizations
Body
ISO 3166-1 alpha-2 code of the country whose company registry to search. For example, GB. Where company registries operate at state or province level, append the ISO 3166-2 subdivision code as XX-YY: US-CA searches the California registry. United States searches always require the subdivision — a bare US is rejected. Case-insensitive; normalized to upper case.
10"GB"
Company name to search for. Either name or registration_number is required.
255"Tesco"
Registry registration number to search for. Either name or registration_number is required.
100Name-matching strategy applied by the registry search.
contains, start_with, fuzzy Your identifier for this lookup; echoed back and included in the webhook callback.
Free-form JSON; echoed back and included in the webhook callback.
Switches the search to asynchronous mode: the API returns immediately and POSTs an unsigned kyb.registry_search.resolved callback to this URL when the candidate list is ready.
500Response
Search accepted. Synchronous mode returns the resolved candidate list; webhook mode returns immediately (often search_status: "pending") and delivers the final list via the kyb.registry_search.resolved callback.
With webhook_url: the persisted search-request id, echoed as request_id in the kyb.registry_search.resolved callback. Without webhook_url: a transient correlation UUID (the search is not stored).
Echo of the vendor_data you sent.
Echo of the metadata you sent.