curl -X POST https://verification.didit.me/v3/kyb/search/ \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"country_code": "GB",
"name": "Tesco",
"search_type": "contains",
"vendor_data": "company-1234"
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.kyb.search(
country_code="GB",
name="Tesco",
search_type="contains",
vendor_data="company-1234",
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.kyb.search({
country_code: "GB",
name: "Tesco",
search_type: "contains",
vendor_data: "company-1234",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.KYB.Search(ctx, didit.KYBSearchParams{
CountryCode: "GB",
Name: didit.String("Tesco"),
SearchType: didit.Some(didit.KYBSearchParamsSearchType("contains")),
VendorData: didit.String("company-1234"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import me.didit.Didit;
import me.didit.types.KybSearchParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.kyb().search(KybSearchParams.builder()
.countryCode("GB")
.name("Tesco")
.searchType(KybSearchParams.SearchType.of("contains"))
.vendorData("company-1234")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->kyb->search([
'country_code' => 'GB',
'name' => 'Tesco',
'search_type' => 'contains',
'vendor_data' => 'company-1234',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.kyb.search(
country_code: "GB",
name: "Tesco",
search_type: "contains",
vendor_data: "company-1234"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Kyb.SearchAsync(new KybSearchParams
{
CountryCode = "GB",
Name = "Tesco",
SearchType = new KybSearchParamsSearchType("contains"),
VendorData = "company-1234",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"request_id": "0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a",
"kyb_registry": {
"companies": [
{
"kyb_response_id": "69aeeb95febb0f1704042259",
"name": "Tesco PLC",
"registration_number": "00445790",
"status": "active",
"type": "Public Limited Company",
"risk_level": null,
"fetch_status": "pending"
},
{
"kyb_response_id": "69aeeb95febb0f170404225a",
"name": "E-TESCO LTD",
"registration_number": "15168476",
"status": "active",
"type": "Private Limited Company",
"risk_level": null,
"fetch_status": "pending"
}
],
"pagination": {
"total": 2,
"page": 1,
"per_page": 25
},
"search_status": "resolved",
"search_resolved": true
},
"vendor_data": "company-1234",
"metadata": null,
"created_at": "2026-06-11T10:40:00.000000+00:00"
}KYB 企业登记库搜索 API - 企业查询
Didit 的 POST /v3/kyb/search/ 用于查找企业候选项。付费企业数据源的成功搜索每次请求收费 $0.50;档案获取另行计费。
curl -X POST https://verification.didit.me/v3/kyb/search/ \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"country_code": "GB",
"name": "Tesco",
"search_type": "contains",
"vendor_data": "company-1234"
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.kyb.search(
country_code="GB",
name="Tesco",
search_type="contains",
vendor_data="company-1234",
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.kyb.search({
country_code: "GB",
name: "Tesco",
search_type: "contains",
vendor_data: "company-1234",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.KYB.Search(ctx, didit.KYBSearchParams{
CountryCode: "GB",
Name: didit.String("Tesco"),
SearchType: didit.Some(didit.KYBSearchParamsSearchType("contains")),
VendorData: didit.String("company-1234"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import me.didit.Didit;
import me.didit.types.KybSearchParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.kyb().search(KybSearchParams.builder()
.countryCode("GB")
.name("Tesco")
.searchType(KybSearchParams.SearchType.of("contains"))
.vendorData("company-1234")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->kyb->search([
'country_code' => 'GB',
'name' => 'Tesco',
'search_type' => 'contains',
'vendor_data' => 'company-1234',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.kyb.search(
country_code: "GB",
name: "Tesco",
search_type: "contains",
vendor_data: "company-1234"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Kyb.SearchAsync(new KybSearchParams
{
CountryCode = "GB",
Name = "Tesco",
SearchType = new KybSearchParamsSearchType("contains"),
VendorData = "company-1234",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"request_id": "0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a",
"kyb_registry": {
"companies": [
{
"kyb_response_id": "69aeeb95febb0f1704042259",
"name": "Tesco PLC",
"registration_number": "00445790",
"status": "active",
"type": "Public Limited Company",
"risk_level": null,
"fetch_status": "pending"
},
{
"kyb_response_id": "69aeeb95febb0f170404225a",
"name": "E-TESCO LTD",
"registration_number": "15168476",
"status": "active",
"type": "Private Limited Company",
"risk_level": null,
"fetch_status": "pending"
}
],
"pagination": {
"total": 2,
"page": 1,
"per_page": 25
},
"search_status": "resolved",
"search_resolved": true
},
"vendor_data": "company-1234",
"metadata": null,
"created_at": "2026-06-11T10:40:00.000000+00:00"
}403,并带有 code: "insufficient_credits"。
合同计费按您约定的搜索费率执行;未配置的合同费率会在搜索前被拒绝。
沙盒中的搜索免费。
每次成功的重复搜索都是一次新的计费请求;回调投递不会再产生一次搜索费用。
如果您发送 webhook_url,Didit 可在服务提供商处理搜索期间立即返回,待候选记录就绪后再将其发送到您的回调 URL。该回调按设计未经签名,因此无需为此搜索通知配置 Webhook 密钥。请参阅搜索回调负载示例。
选定正确的 kyb_response_id 后,调用 POST /v3/kyb/select/(Lite)、POST /v3/kyb/shareholders/ 或 POST /v3/kyb/ubo/,即可按所需层级获取可计费的登记档案。
fetch_status 均为 pending,并一直保持 pending,直到您选定该候选记录为止。搜索仅列出候选记录,选定操作才会获取完整档案。请勿为等待其状态更新而轮询搜索。kyb_response_id 是仅限于单次搜索请求的不透明临时句柄:请原样回传您收到的值,切勿解析其内容或从中推导任何信息;重复相同搜索时会返回新的 ID。搜索后请及时选定候选记录;如需该公司的稳定标识符,请使用 registration_number。搜索层级
tier 用于选择搜索所运行的登记层级,即该层级对应的服务提供商链:basic(默认,即 Lite 链)、shareholders 或 ubo。候选列表来自该层级的服务提供商链,而该链所用的数据源不一定与 Lite 搜索读取的数据源相同。因此,Lite 搜索结果为空并不能证明登记机构未收录该公司,请在您需要的层级重新搜索。
若该国家/地区不提供您指定的层级,搜索将运行在该国家/地区提供的、不高于该层级的最高层级上。没有任何登记数据的国家/地区不提供登记核验,请改为手动录入企业信息。
请在您打算购买的层级上进行搜索,然后通过提供该层级可计费登记档案的端点获取候选记录:
您搜索的 tier | 获取候选记录的端点 |
|---|---|
basic(默认) | POST /v3/kyb/select/(Lite) |
shareholders | POST /v3/kyb/shareholders/ |
ubo | POST /v3/kyb/ubo/ |
search_type
search_type 仅接受 contains,且为默认值。背后的登记数据源按公司名称包含关系进行匹配,因此 start_with 和 fuzzy 会被拒绝并返回 400("start_with" is not a valid choice),而不会被静默视为 contains。如需精确匹配公司,请发送 registration_number。
托管与独立搜索
POST /v1/kyb/search/ 是托管验证流程运行的搜索:它通过验证会话进行身份验证,使用 API 密钥进行身份验证时返回 403,且不接受 tier,由工作流的 KYB 登记配置决定使用哪条链。独立 API 使用您的 x-api-key 调用 POST /v2/kyb/search/ 或 POST /v3/kyb/search/。tier 输入参数以及分层的 select 端点,是独立集成在所需层级上获取相同候选记录的方式。
处理登记服务中断
若登记服务提供商暂时不可用,该端点将返回502,并附带稳定的机器可读代码:
{
"detail": "The company registry provider is temporarily unavailable.",
"code": "kyb_registry_provider_unavailable"
}
400,不会使用此中断代码。
处理不支持的国家/地区和搜索限制
另有两个稳定代码,提示您停止重试,改为手动录入企业信息:| 状态 | code | 适用情况 |
|---|---|---|
400 | kyb_registry_country_unsupported | 该国家/地区在任何层级都没有公司登记数据源。此限制是永久性的,因此重试相同搜索永远不会成功。 |
429 | kyb_registry_search_limit_reached | 您的应用在付费企业数据源上的搜索额度(每小时 600 次)已用尽,且该国家/地区已无可用的免费数据源。请等待该时间窗口过去,或手动录入企业信息。 |
400,并带有 code: "kyb_registry_entry_not_a_company"。请改为从搜索结果中选择一家公司。授权
您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。
请求体
要搜索其公司登记所在国家/地区的 ISO 3166-1 alpha-2 代码。例如 GB。若公司登记在州或省级别运作,请以 XX-YY 格式附加 ISO 3166-2 行政区划代码:US-CA 搜索加利福尼亚州登记。美国搜索始终需要行政区划,仅传 US 将被拒绝。不区分大小写;规范化为大写。
10"GB"
要搜索的企业名称。name 或 registration_number 必填其一。
255"Tesco"
要搜索的公司登记注册号。name 或 registration_number 必须提供其一。
100本次搜索运行所依托的服务商链对应的公司登记等级。basic(默认)搜索该国家/地区的 Lite 链;shareholders 和 ubo 搜索该等级的股权结构链,两者可能来自不同数据源,因此 Lite 搜索结果为空并不代表公司登记中没有该企业。对于不提供指定等级的国家/地区,将使用其支持的最高等级(不超过该等级)进行搜索。从售卖所搜索等级的 endpoint 获取候选对象:POST /v3/kyb/select/(Lite)、POST /v3/kyb/shareholders/ 或 POST /v3/kyb/ubo/。
basic, shareholders, ubo "basic"
登记处搜索所应用的名称匹配策略。contains 是唯一接受的值:搜索背后的登记处数据源均不提供前缀或模糊模式,因此 start_with 和 fuzzy 会被拒绝并返回 400(not a valid choice)。
contains 您为此查询指定的标识符;将原样返回并包含在 Webhook 回调中。
自由格式 JSON;回显并包含在 Webhook 回调中。
将搜索切换为异步模式:API 会立即返回,并在候选列表准备就绪时向此 URL 发送未签名的 kyb.registry_search.resolved 回调 POST 请求。
500响应
搜索已受理。同步模式返回已确定的候选名单;Webhook 模式立即返回(通常为 search_status: "pending")并通过 kyb.registry_search.resolved 回调投递最终名单。