跳转到主要内容
POST
curl
请先使用此端点查找匹配的公司登记候选记录。 搜索不会创建已保存的 Manual Check。 使用付费企业数据源的独立搜索成功后,每次请求收费 $0.50,与候选记录数量无关。空结果、失败的搜索以及仅由其他数据源返回的结果均不收费。之后获取企业档案将另行计费。 对于可能使用付费数据源的搜索,Didit 会在联系登记机构之前检查并预留相应的搜索价格。 余额不足时返回 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 搜索结果为空并不能证明登记机构未收录该公司,请在您需要的层级重新搜索。 若该国家/地区不提供您指定的层级,搜索将运行在该国家/地区提供的、不高于该层级的最高层级上。没有任何登记数据的国家/地区不提供登记核验,请改为手动录入企业信息。 请在您打算购买的层级上进行搜索,然后通过提供该层级可计费登记档案的端点获取候选记录:

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,并附带稳定的机器可读代码:
收到此代码后,可让用户改为手动录入企业信息,或请其稍后重试。请将校验错误与之区分:无效的搜索输入返回 400,不会使用此中断代码。

处理不支持的国家/地区和搜索限制

另有两个稳定代码,提示您停止重试,改为手动录入企业信息: 在托管流程中,每个登记步骤最多允许对付费企业数据源进行 3 次搜索。第三次之后,系统会提示申请人手动录入。 若选定的候选记录是商标注册而非公司,将返回 400,并带有 code: "kyb_registry_entry_not_a_company"。请改为从搜索结果中选择一家公司。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
country_code
string
必填

要搜索其公司登记所在国家/地区的 ISO 3166-1 alpha-2 代码。例如 GB。若公司登记在州或省级别运作,请以 XX-YY 格式附加 ISO 3166-2 行政区划代码:US-CA 搜索加利福尼亚州登记。美国搜索始终需要行政区划,仅传 US 将被拒绝。不区分大小写;规范化为大写。

Maximum string length: 10
示例:

"GB"

name
string

要搜索的企业名称。name 或 registration_number 必填其一。

Maximum string length: 255
示例:

"Tesco"

registration_number
string

要搜索的公司登记注册号。name 或 registration_number 必须提供其一。

Maximum string length: 100
tier
enum<string>
默认值:basic

本次搜索运行所依托的服务商链对应的公司登记等级。basic(默认)搜索该国家/地区的 Lite 链;shareholders 和 ubo 搜索该等级的股权结构链,两者可能来自不同数据源,因此 Lite 搜索结果为空并不代表公司登记中没有该企业。对于不提供指定等级的国家/地区,将使用其支持的最高等级(不超过该等级)进行搜索。从售卖所搜索等级的 endpoint 获取候选对象:POST /v3/kyb/select/(Lite)、POST /v3/kyb/shareholders/ 或 POST /v3/kyb/ubo/。

可用选项:
basic,
shareholders,
ubo
示例:

"basic"

search_type
enum<string>
默认值:contains

登记处搜索所应用的名称匹配策略。contains 是唯一接受的值:搜索背后的登记处数据源均不提供前缀或模糊模式,因此 start_with 和 fuzzy 会被拒绝并返回 400(not a valid choice)。

可用选项:
contains
vendor_data
string

您为此查询指定的标识符;将原样返回并包含在 Webhook 回调中。

metadata
object | null

自由格式 JSON;回显并包含在 Webhook 回调中。

webhook_url
string<uri>

将搜索切换为异步模式:API 会立即返回,并在候选列表准备就绪时向此 URL 发送未签名的 kyb.registry_search.resolved 回调 POST 请求。

Maximum string length: 500

响应

搜索已受理。同步模式返回已确定的候选名单;Webhook 模式立即返回(通常为 search_status: "pending")并通过 kyb.registry_search.resolved 回调投递最终名单。

request_id
string<uuid>

包含 webhook_url 时:持久化的搜索请求 ID,在 kyb.registry_search.resolved 回调中作为 request_id 返回。不包含 webhook_url 时:临时关联 UUID(搜索不会被存储)。

kyb_registry
object
vendor_data
string | null

回显您发送的 vendor_data。

metadata
object | null

您发送的 metadata 回显。

created_at
string<date-time>
最后修改于 2026年11月7日