Skip to main content

​
How billing works

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: 
{
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "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",
        "fetch_status": "pending"
      }
    ]
  }
}
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.