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

# KYB Registry API

> Search and select company registry entries through Didit's KYB Registry API. Free company search, billable profile retrieval after selection.

## How billing works

This flow has two separate API endpoints:

* [KYB Registry Search](/standalone-apis/kyb-registry-search) — free company candidate search.
* [KYB Registry Select](/standalone-apis/kyb-registry-select) — billable company profile retrieval.

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/` with the returned `kyb_response_id` to retrieve the full registry profile. Select 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. Select the matching `kyb_response_id`.
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`:

```json theme={null}
{
  "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",
        "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
}
```

Treat the callback as a delivery notification. Use the returned `kyb_response_id` with `POST /v3/kyb/select/` to run the billable registry profile retrieval.