Skip to main content
POST
/
v3
/
kyb
/
search
curl
curl -X POST https://verification.didit.me/v3/kyb/search/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "GB",
    "name": "Tesco",
    "search_type": "contains"
  }'
{
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "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": "resolved"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2025-01-01T00:00:00+00:00"
}
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. After you pick the correct kyb_response_id, call POST /v3/kyb/select/ to retrieve the billable registry profile.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
country_code
string
required

ISO 3166-1 alpha-2 country code, or subdivision code where required by the registry provider, such as US-CA.

Example:

"GB"

​
name
string

Company name to search.

​
registration_number
string

Company registration number to search.

​
search_type
enum<string>
default:contains
Available options:
contains,
start_with,
fuzzy
​
vendor_data
string

Optional caller-controlled identifier echoed back in the response.

​
metadata
object
​
webhook_url
string<uri>

Optional callback URL for asynchronous search results. If the provider search is pending, Didit returns immediately and sends one unsigned POST to this URL when candidates are ready.

Response

Registry search candidates. This response is not billable.

​
request_id
string<uuid>
required
​
kyb_registry
object
required
​
created_at
string<date-time>
required
​
vendor_data
string | null
​
metadata
object