Skip to main content

​
Endpoints and billing

Search is free. Retrieval is sold in three data tiers, one endpoint each, priced per country (per-country prices): select is the Lite tier: it is what a hosted KYB workflow bills for a registry check at the Lite level, and it keeps the contract it has always had. Europe means the EEA, the United Kingdom and Switzerland.
You pay for the tier delivered. Every response carries registry_tier_requested and registry_tier_delivered. When the country’s registries hold no ownership data, or the registry has no ownership record for the selected company, an ownership request is delivered and billed as the highest tier available (usually Lite), and registry_ownership_status says why.
Versioning. The Shareholders and UBO endpoints exist on /v3/ only. /v2/kyb/search/ and /v2/kyb/select/ are unchanged, so no existing integration’s bill changes without moving to v3.
Use POST /v3/kyb/search/ to find candidate companies. Search is free and does not create a saved check. Registry searches can take around 90 seconds. Send webhook_url when you want Didit to return immediately and notify your URL once candidates are ready. The search callback is unsigned on purpose, so you do not need to configure a shared secret for this lightweight notification. Use POST /v3/kyb/select/, POST /v3/kyb/shareholders/ or POST /v3/kyb/ubo/ with the returned kyb_response_id to retrieve the profile at the tier you need. Retrieval is billable and saves the result as a Manual Check in the Business Console.

​
Typical flow

  1. Search by company name, registration number, and country.
  2. If search_resolved=false, wait for the optional webhook_url callback instead of polling.
  3. Show the returned candidates to your operator or customer.
  4. Retrieve the matching kyb_response_id at the tier you need (select for Lite, shareholders, or ubo).
  5. Store the returned request_id and use it to retrieve the saved business verification result.

​
Search callback

When the provider tells Didit the search is resolved, Didit sends one POST to your webhook_url:
Treat the callback as a delivery notification. Use the returned kyb_response_id with POST /v3/kyb/select/, POST /v3/kyb/shareholders/ or POST /v3/kyb/ubo/ to run the billable registry profile retrieval.