Skip to main content
POST
curl
Use this endpoint first to find matching company registry candidates. Search is free and does not create a saved Manual Check. If you send 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/ (Lite), POST /v3/kyb/shareholders/ or POST /v3/kyb/ubo/ to retrieve the billable registry profile at the tier you need.
Each candidate’s 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 opaque, ephemeral handle scoped to one search request: pass it back exactly as you received it and never parse it or derive anything from its contents, and expect repeating the same search to return new ids. Select the candidate promptly after searching, and use registration_number when you need a stable identifier for the company itself.

Handle registry outages

If the registry provider is temporarily unavailable, the endpoint returns 502 with a stable machine-readable code:
When you receive this code, let the user continue with manual company entry or ask them to retry later. Keep validation errors separate: invalid search input returns 400 and does not use this outage code.

Authorizations

x-api-key
string
header
required

Body

application/json
country_code
string
required

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.

Maximum string length: 10
Example:

"GB"

name
string

Company name to search for. Either name or registration_number is required.

Maximum string length: 255
Example:

"Tesco"

registration_number
string

Registry registration number to search for. Either name or registration_number is required.

Maximum string length: 100
search_type
enum<string>
default:contains

Name-matching strategy applied by the registry search.

Available options:
contains,
start_with,
fuzzy
vendor_data
string

Your identifier for this lookup; echoed back and included in the webhook callback.

metadata
object | null

Free-form JSON; echoed back and included in the webhook callback.

webhook_url
string<uri>

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.

Maximum string length: 500

Response

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.

request_id
string<uuid>

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).

kyb_registry
object
vendor_data
string | null

Echo of the vendor_data you sent.

metadata
object | null

Echo of the metadata you sent.

created_at
string<date-time>