KYB 注册表 UBO API：最终实际受益人

curl

curl -X POST https://verification.didit.me/v3/kyb/ubo/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "kyb_response_id": "69aeeb95febb0f1704042259",
    "vendor_data": "company-1234"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.kyb.listUbos({
  kyb_response_id: "69aeeb95febb0f1704042259",
  vendor_data: "company-1234",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.KYB.ListUBOs(ctx, didit.KYBRegistryCandidateRequest{
	KYBResponseID: "69aeeb95febb0f1704042259",
	VendorData:    didit.String("company-1234"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.KYBRegistryCandidateRequest;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.kyb().listUbos(KYBRegistryCandidateRequest.builder()
        .kybResponseId("69aeeb95febb0f1704042259")
        .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->listUbos([
    'kyb_response_id' => '69aeeb95febb0f1704042259',
    'vendor_data' => 'company-1234',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Kyb.ListUbosAsync(new KYBRegistryCandidateRequest
{
    KybResponseId = "69aeeb95febb0f1704042259",
    VendorData = "company-1234",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e",
  "kyb_registry": {
    "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d",
    "node_id": "feature_kyb_registry",
    "status": "In Review",
    "registry_status": "active",
    "data_resolved": true,
    "company_name": "Tesco PLC",
    "registration_number": "00445790",
    "country_code": "GB",
    "region": "",
    "company_type": "Public Limited Company",
    "incorporation_date": "1947-11-27",
    "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA",
    "tax_number": "GB412 8925 93",
    "risk_level": "low risk",
    "verification_status": "verified",
    "is_from_registry": true,
    "fetch_status": "resolved",
    "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY",
    "nature_of_business": null,
    "registered_capital": null,
    "registered_capital_amount": null,
    "registered_capital_currency": null,
    "website": "https://www.tesco.com/",
    "email": "customer.service@tesco.co.uk",
    "phone": "03301231688",
    "legal_entity_identifier": null,
    "location_of_registration": null,
    "financial_summary": {
      "currency": "Pound (£)",
      "total_number_of_shares": "8174378721",
      "meta_detail": {
        "Class_Of_Share": "Ordinary"
      }
    },
    "officers": [
      {
        "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b",
        "name": "CHRISTOPHER JON TAYLOR",
        "designation": "Secretary",
        "role": "secretary",
        "nationality": null,
        "is_active": true,
        "kyc_status": null,
        "kyc_session_url": null
      },
      {
        "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c",
        "name": "MELISSA BETHELL",
        "designation": "Director",
        "role": "director",
        "nationality": "British",
        "is_active": true,
        "kyc_status": null,
        "kyc_session_url": null
      }
    ],
    "beneficial_owners": [],
    "addresses": [
      {
        "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA",
        "type": "legal_entity_registry_address",
        "description": "registered office address"
      }
    ],
    "industries": null,
    "accounts": {
      "last_account": "26 February 2025",
      "next_account": "26 February 2026",
      "due_by_date": "26 August 2026"
    },
    "registry_data": {
      "ubo_resolution": {
        "parent_chain": [],
        "subsidiaries": [],
        "unresolved": []
      }
    },
    "user_provided_data": null,
    "confirmed_by_user_at": null,
    "last_console_edit_at": null,
    "is_editable": true
  },
  "vendor_data": "company-1234",
  "metadata": null,
  "created_at": "2026-06-11T10:45:00.000000+00:00"
}

POST

kyb

ubo

curl

curl -X POST https://verification.didit.me/v3/kyb/ubo/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "kyb_response_id": "69aeeb95febb0f1704042259",
    "vendor_data": "company-1234"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.kyb.listUbos({
  kyb_response_id: "69aeeb95febb0f1704042259",
  vendor_data: "company-1234",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.KYB.ListUBOs(ctx, didit.KYBRegistryCandidateRequest{
	KYBResponseID: "69aeeb95febb0f1704042259",
	VendorData:    didit.String("company-1234"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.KYBRegistryCandidateRequest;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.kyb().listUbos(KYBRegistryCandidateRequest.builder()
        .kybResponseId("69aeeb95febb0f1704042259")
        .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->listUbos([
    'kyb_response_id' => '69aeeb95febb0f1704042259',
    'vendor_data' => 'company-1234',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Kyb.ListUbosAsync(new KYBRegistryCandidateRequest
{
    KybResponseId = "69aeeb95febb0f1704042259",
    VendorData = "company-1234",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e",
  "kyb_registry": {
    "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d",
    "node_id": "feature_kyb_registry",
    "status": "In Review",
    "registry_status": "active",
    "data_resolved": true,
    "company_name": "Tesco PLC",
    "registration_number": "00445790",
    "country_code": "GB",
    "region": "",
    "company_type": "Public Limited Company",
    "incorporation_date": "1947-11-27",
    "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA",
    "tax_number": "GB412 8925 93",
    "risk_level": "low risk",
    "verification_status": "verified",
    "is_from_registry": true,
    "fetch_status": "resolved",
    "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY",
    "nature_of_business": null,
    "registered_capital": null,
    "registered_capital_amount": null,
    "registered_capital_currency": null,
    "website": "https://www.tesco.com/",
    "email": "customer.service@tesco.co.uk",
    "phone": "03301231688",
    "legal_entity_identifier": null,
    "location_of_registration": null,
    "financial_summary": {
      "currency": "Pound (£)",
      "total_number_of_shares": "8174378721",
      "meta_detail": {
        "Class_Of_Share": "Ordinary"
      }
    },
    "officers": [
      {
        "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b",
        "name": "CHRISTOPHER JON TAYLOR",
        "designation": "Secretary",
        "role": "secretary",
        "nationality": null,
        "is_active": true,
        "kyc_status": null,
        "kyc_session_url": null
      },
      {
        "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c",
        "name": "MELISSA BETHELL",
        "designation": "Director",
        "role": "director",
        "nationality": "British",
        "is_active": true,
        "kyc_status": null,
        "kyc_session_url": null
      }
    ],
    "beneficial_owners": [],
    "addresses": [
      {
        "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA",
        "type": "legal_entity_registry_address",
        "description": "registered office address"
      }
    ],
    "industries": null,
    "accounts": {
      "last_account": "26 February 2025",
      "next_account": "26 February 2026",
      "due_by_date": "26 August 2026"
    },
    "registry_data": {
      "ubo_resolution": {
        "parent_chain": [],
        "subsidiaries": [],
        "unresolved": []
      }
    },
    "user_provided_data": null,
    "confirmed_by_user_at": null,
    "last_console_edit_at": null,
    "is_editable": true
  },
  "vendor_data": "company-1234",
  "metadata": null,
  "created_at": "2026-06-11T10:45:00.000000+00:00"
}

使用此端点的时机是：POST /v3/kyb/search/ 返回候选公司后，需要获取最终实际受益人，包括股东，以及通过股权链解析出的自然人和企业母公司（registry_data.ubo_resolution）。该端点按该国的 UBO 价格计费（各国价格）。交付的等级是该国和登记机构所能提供的最高等级。registry_tier_delivered 会标明实际计费的等级：报告中未列出任何自然人实际受益人时为 shareholders；完全没有股权记录时为 basic，此时 registry_ownership_status 为 unavailable，或者股权来源答复其不持有该公司时为 not_held（股权状态）。报告仍在生成中，或股权部分尚未从登记机构获取时，端点返回 202 Accepted，kyb_registry.fetch_status: "pending"，kyb_registry.registry_ownership_status: "pending"，以及 registry_tier_delivered: null。请保存返回的 request_id，并持续调用 GET /v3/session/{request_id}/decision/，直到 registry_checks[0].company.fetch_status 变为 resolved。待处理报告会由 Didit 自动完成，完成后将按交付的等级计费。报告待处理期间请勿重复发起购买请求：每次新的 POST 都会创建一个单独的请求。仅支持 v3。POST /v2/kyb/select/ 和 POST /v3/kyb/select/ 保持其合同和价格不变。

授权

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

kyb_response_id

string

必填

来自 POST /v3/kyb/search/ 的候选句柄（kyb_registry.companies[].kyb_response_id）。临时有效：在生成它的搜索之后不久使用。句柄可能很长，因此请严格按返回的原样存储和发送该值，不要修剪或假定其长度。

Maximum string length: 1024

示例:

"69aeeb95febb0f1704042259"

vendor_data

string

您为此企业指定的标识符；将原样返回并与企业会话一起存储。

metadata

object | null

随企业会话一同存储并回显的自由格式 JSON。

save_api_request

boolean

默认值:true

必须为 true（默认值）。KYB 公司登记查询始终会持久化保存，以便跟踪计费和检索；传 false 将返回 400。

响应

返回企业报告并按实际交付的等级计费。仍在准备中的股权结构报告可能会返回 202；请保留 request_id 以检索其已保存的决策。

request_id

string<uuid>

为此检索创建的企业会话 ID。如果在响应返回后公司登记信息才解析完成，已存储的记录（在控制台中可见）将持续更新。

registry_tier_requested

enum<string>

此 endpoint 销售的等级：针对 select 的 basic (Lite)、shareholders、ubo。

可用选项:

basic,

shareholders,

ubo

registry_tier_delivered

enum<string> | null

实际交付并计费的等级。当该国家/地区的公司登记不包含股权结构数据、登记机构没有该公司的股权结构记录，或 ubo 请求的解析报告未将任何自然人列为实际受益人时，该等级会低于请求的等级。

可用选项:

basic,

shareholders,

ubo,

null

kyb_registry

object

完整的公司登记档案。

Show child attributes

vendor_data

string | null

回显您发送的 vendor_data。

metadata

object | null

您发送的 metadata 回显。

created_at

string<date-time>

最后修改于 2026年11月7日