> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # KYB 注册表 UBO API：最终实际受益人 > 调用 POST /v3/kyb/ubo/，传入注册表搜索得到的 kyb_response_id，Didit 将通过股权链返回企业资料、股东及实际受益人。 使用此端点的时机是：`POST /v3/kyb/search/` 返回候选公司后，需要获取**最终实际受益人**，包括股东，以及通过股权链解析出的自然人和企业母公司（`registry_data.ubo_resolution`）。 该端点按该国的 UBO 价格计费（[各国价格](https://docs.didit.me/zh/getting-started/kyb-registry-pricing.md)）。交付的等级是该国和登记机构所能提供的最高等级。`registry_tier_delivered` 会标明实际计费的等级：报告中未列出任何自然人实际受益人时为 `shareholders`；完全没有股权记录时为 `basic`，此时 `registry_ownership_status` 为 `unavailable`，或者股权来源答复其不持有该公司时为 `not_held`（[股权状态](https://docs.didit.me/zh/standalone-apis/kyb-registry.md#股权结构状态)）。 报告仍在生成中，或股权部分尚未从登记机构获取时，端点返回 `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/` 保持其合同和价格不变。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/kyb/ubo/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/ubo/: post: tags: - Standalone APIs summary: KYB 公司登记企业含实际受益人信息（独立项） description: >- 检索由 `POST /v3/kyb/search/` 返回的某一候选企业的 Lite 档案、直接股东**以及通过股权链穿透解析出的最终实际受益人**（`registry_data.ubo_resolution` 包含母公司层级链）。 **与搜索配对。** 传入候选企业的 `kyb_response_id`，必须与同一应用搜索返回的完全一致。请在您打算购买的等级（`POST /v3/kyb/search/` 上的 `tier`）进行搜索，因为搜索运行在为该等级提供服务的公司登记链上，而空的 Lite 搜索并不能证明公司登记中没有该公司。当该国家/地区的股权结构数据位于另一个公司登记时，Didit 会按注册号在该处重新查找该公司，无需额外费用。 **计费。** 按该国家/地区的 UBO 价格计费（参见 [KYB 公司登记定价](/zh/getting-started/kyb-registry-pricing)）。投递的等级是该国家/地区和公司登记所能提供的最高等级：当穿透解析后的报告未列出任何自然人作为实际受益人时投递 Shareholders，当根本没有股权结构记录时投递 Lite；`registry_tier_delivered` 说明实际计费的等级。在进行任何公司登记调用之前，会根据 UBO 价格核查余额（不足时返回 `403`）。 **可用性。** 仅限 v3。每次调用都会创建一个企业会话（其 id 即为 `request_id`）。 **待处理报告。** 当报告仍在生成中，或者股权结构部分尚未从公司登记中检索完毕时，endpoint 返回 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 解析完成。Didit 会自动完成报告，并在准备就绪后按实际投递的等级扣费。处于待处理状态时请勿重复购买；每次新的 POST 都会创建一个单独的请求。 operationId: post_v3_kyb_ubo parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KYBRegistryCandidateRequest' example: kyb_response_id: 69aeeb95febb0f1704042259 vendor_data: company-1234 responses: '200': description: 返回企业报告并按实际交付的等级计费。仍在准备中的股权结构报告可能会返回 202；请保留 request_id 以检索其已保存的决策。 content: application/json: schema: type: object properties: request_id: type: string format: uuid description: 为此检索创建的企业会话 ID。如果在响应返回后公司登记信息才解析完成，已存储的记录（在控制台中可见）将持续更新。 registry_tier_requested: type: string enum: - basic - shareholders - ubo description: >- 此 endpoint 销售的等级：针对 select 的 `basic` (Lite)、`shareholders`、`ubo`。 registry_tier_delivered: type: string enum: - basic - shareholders - ubo - null description: >- 实际交付并计费的等级。当该国家/地区的公司登记不包含股权结构数据、登记机构没有该公司的股权结构记录，或 `ubo` 请求的解析报告未将任何自然人列为实际受益人时，该等级会低于请求的等级。 nullable: true kyb_registry: type: object description: 完整的公司登记档案。 properties: uuid: type: string format: uuid description: Didit 为此企业记录分配的 ID。 node_id: type: string example: feature_kyb_registry status: type: string enum: - Not Finished - Approved - Declined - In Review description: >- Didit 对公司登记核验的评估（例如，当企业在登记处中处于非活跃状态或无法获取股权结构数据时为 `In Review`）。 registry_status: type: string nullable: true enum: - active - dissolved - deregistered - see full details - authorised - appointed representative - unauthorised - inactive - no longer authorised - closed - struck off - null description: 公司登记机构报告的归一化企业状态。 data_resolved: type: boolean description: >- 公司登记处返回完整资料后为 `true`。轮询后登记处仍在处理中时为 `false`，一旦登记处处理完成，存储的记录将自动补充完整。 company_name: type: string example: Tesco PLC registration_number: type: string nullable: true example: '00445790' country_code: type: string description: ISO 3166-1 alpha-2。 example: GB region: type: string nullable: true description: 登记属于地区性时的行政区划代码（例如 `US-CA` 对应 `CA`）；否则为空。 company_type: type: string nullable: true example: Public Limited Company incorporation_date: type: string format: date nullable: true example: '1947-11-27' registered_address: type: string nullable: true example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: type: string nullable: true example: GB412 8925 93 risk_level: type: string nullable: true description: 公司登记所报告的风险等级（如可用）。 verification_status: type: string enum: - verified - failed - unknown nullable: true description: >- 跨司法管辖区验证状态：当公司登记状态确认存续（`active`）时为 `verified`；当其显示公司不再存续（例如 `dissolved`）时为 `failed`；否则为 `unknown`。对于非来自公司登记且选择仍处于 `pending` 状态的公司，该值为 `null`。 is_from_registry: type: boolean description: 对于此 endpoint 始终为 `true`，该档案从官方登记机构检索获取。 fetch_status: type: string enum: - pending - resolved description: 公司登记获取生命周期。由 `data_resolved` 镜像。 alternative_names: type: string nullable: true description: 上报时的替代名称、商业名称、曾用名或原始语言公司名称（文本格式）。 nature_of_business: type: string nullable: true description: 活动描述或分类代码（如有报告）。 registered_capital: type: string nullable: true registered_capital_amount: type: string nullable: true description: 字符串形式的十进制金额（若有上报）。 registered_capital_currency: type: string nullable: true description: 报告的 ISO 4217 代码（如有）。 website: type: string nullable: true example: https://www.tesco.com/ email: type: string nullable: true example: customer.service@tesco.co.uk phone: type: string nullable: true example: '03301231688' legal_entity_identifier: type: string nullable: true description: LEI（若已上报）。 location_of_registration: type: string nullable: true description: 企业注册所在的登记机构/司法管辖区（如有报告）。 vat_number: type: string nullable: true description: >- 欧盟增值税号，在托管登记步骤中收集或随后编辑时提供。在选择时通常尚未设置。增值税号和税号核验会在终端用户在托管流程中提交登记步骤时运行。 vat_validation_status: type: string enum: - valid - invalid - format_valid - invalid_format - could_not_validate - not_applicable description: >- 在登记提交时验证增值税号（若无，则为 `tax_number`）的结果。`valid` / `invalid`：由相应国家/地区的官方登记处判定（欧盟 VIES、挪威、瑞士、巴西、哥伦比亚、哥斯达黎加、厄瓜多尔、巴拉圭；波兰还由其国内增值税登记册判定）。`format_valid` / `invalid_format`：在无法查询登记处时，由该国家/地区的格式和校验位规则判定。`could_not_validate`：登记处不可用。`not_applicable`：无号码、无登记处或规则的国家/地区，或者沙盒会话。 vat_validated_number: type: string nullable: true description: >- 已核验的号码，格式以数据源所知为准（例如从法国 SIREN 或荷兰 RSIN 派生的增值税号）。若未运行核验，则为 `null`。 vat_validation_source: type: string nullable: true enum: - eu_vies - pl_vat_white_list - no_brreg - ch_uid_register - br_receita_federal - co_rues - cr_hacienda - ec_sri - py_dnit - format_rules - null description: >- 判定 `vat_validation_status` 的来源：官方登记，或 `format_rules`。未运行任何检查时为 `null`。 vat_validated_name: type: string nullable: true description: 向验证该号码的数据源登记的名称（如果该数据源公开名称）。仅当状态为 `valid` 时设置。 vat_validated_address: type: string nullable: true description: 核验该号码的数据源中登记的地址（若该数据源披露）。仅在状态为 `valid` 时设置。 vat_checked_at: type: string format: date-time nullable: true description: 检查的时间戳。未运行检查时为 `null`。 financial_summary: type: object nullable: true description: 公司登记所报告的股份/资本详情（币种、总股数、股份类别，如可用）。 officers: type: array items: type: object properties: uuid: type: string format: uuid name: type: string example: MELISSA BETHELL designation: type: string nullable: true description: 原始登记处的职务名称（例如 `Director`、`Secretary`）。 role: type: string description: >- 根据职务衍生出的归一化角色。包含完整的 17 个值的模型集；该 endpoint 上的登记解析通常会输出 director、non_executive_director、secretary、chairman 或 company_officer。 enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - company_officer - settlor - protector - investor - other nationality: type: string nullable: true is_active: type: boolean description: 当公司登记处将该任命标记为已辞任时为 `false`。 kyc_status: type: string nullable: true enum: - Approved - Declined - Pending - null description: 关联的 KYC 会话状态（若已为此负责人发起）；否则为 `null`。 kyc_session_url: type: string nullable: true description: 关联 KYC 会话的验证链接（如果存在）。 first_name: type: string nullable: true description: 公司登记明确报告时的名字；并非从全名中推断。 last_name: type: string nullable: true description: 公司登记明确报告时的姓氏。 address: type: string nullable: true description: 登记处报告的官员地址。 appointment_date: type: string nullable: true description: 管理人员被任命的日期。 format: date termination_date: type: string nullable: true description: 任期结束的日期（若有报告）。 format: date date_of_birth: type: string nullable: true description: 公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。 format: date date_of_birth_year: type: integer nullable: true minimum: 1 maximum: 9999 description: 公司登记所报告的出生年份，包括完整日期不可用的情况。 date_of_birth_month: type: integer nullable: true minimum: 1 maximum: 12 description: 公司登记所报告的出生月份。仅知晓年份时为 null。 description: 从公司登记中提取的董事、秘书和其他高管。 beneficial_owners: type: array items: type: object properties: uuid: type: string format: uuid name: type: string first_name: type: string nullable: true last_name: type: string nullable: true entity_type: type: string enum: - person - company description: 所有者是自然人还是企业实体。 roles: type: array items: type: string description: 归一化的角色（例如 `ubo`、`shareholder`）。 ownership_min_shares: type: string nullable: true description: 公司登记报告的股权范围下限（例如 `25%`）。 ownership_max_shares: type: string nullable: true description: 公司登记报告的股权结构区间上限。 is_active: type: boolean kyc_status: type: string nullable: true enum: - Approved - Declined - Pending - null kyc_session_url: type: string nullable: true effective_ownership_percent: type: number nullable: true description: 解析出的股权百分比（上限值，回退为下限值）。 company_name: type: string nullable: true registration_number: type: string nullable: true country_of_birth: type: string nullable: true email: type: string nullable: true nationality: type: string nullable: true designation: type: string nullable: true voting_min_shares: type: string nullable: true voting_max_shares: type: string nullable: true date_of_birth: type: string nullable: true description: 完整的出生日期（如有报告）。 format: date appointment_date: type: string nullable: true description: 有报告时的委任日期。 format: date shareholding: $ref: '#/components/schemas/KYBRegistryShareholding' description: 从登记处提取的实际受益人/重大控制权人。当登记处未公开股权结构时可能为空。 addresses: type: array nullable: true description: 登记处注明的每个地址，采用标准规范格式。如果未注明，则为 null。 items: $ref: '#/components/schemas/KYBRegistryAddress' industries: type: array nullable: true description: 登记机构对企业进行分类的业务活动，采用一种规范化格式。若未注明则为 null。 items: $ref: '#/components/schemas/KYBRegistryIndustry' accounts: type: object nullable: true additionalProperties: true description: >- 公司登记备案日期（如可用）。年度申报表和大会使用 last_annual_return_date 与 last_agm_date；它们与财务账目不同。 registry_data: $ref: '#/components/schemas/KYBRegistryData' user_provided_data: type: object nullable: true description: 在此 endpoint 上始终为 `null`（终端用户编辑公司登记数据时由托管 KYB 流程使用）。 confirmed_by_user_at: type: string format: date-time nullable: true description: 在此 endpoint 上始终为 `null`。 last_console_edit_at: type: string format: date-time nullable: true description: 当控制台审核员随后编辑该记录时设置。 is_editable: type: boolean description: 来自公司登记的数据是否仍可在托管流程/控制台中进行编辑。 registry_tier_delivered: type: string enum: - basic - shareholders - ubo - null description: 与顶级 `registry_tier_delivered` 相同。 nullable: true registry_ownership_status: type: string nullable: true enum: - not_requested - delivered - not_held - unavailable - pending - null description: >- 当股权结构数据返回时为 `delivered`；当股权登记处已响应但未列出此企业时为 `not_held`（参见 `registry_data.ownership_error`）；当请求了股权结构等级但登记处没有此企业的数据或无法查询时为 `unavailable`（参见 `registry_data.ownership_error`）；当股权结构部分尚未从登记处检索完成且 Didit 仍在处理时为 `pending`；在 Lite 等级上为 `not_requested`。 ownership: $ref: '#/components/schemas/KYBRegistryOwnership' registry_tier: type: string nullable: true description: >- 工作流订购的公司登记等级：`basic`、`shareholders` 或 `ubo`。也可在 `ownership.tier_requested` 中查看。 registry_monitoring: type: object nullable: true description: 该企业的最新登记监控，不存在时为 `null`。 properties: uuid: type: string format: uuid status: type: string unavailable_reason: type: string nullable: true enrolled_at: type: string format: date-time nullable: true cancelled_at: type: string format: date-time nullable: true last_bill_date: type: string format: date nullable: true next_bill_date: type: string format: date nullable: true last_event_at: type: string format: date-time nullable: true events_count: type: integer watched_fields: description: 监控器监视的企业字段。 vendor_data: type: string nullable: true description: 回显您发送的 `vendor_data`。 metadata: type: object nullable: true description: 您发送的 `metadata` 回显。 created_at: type: string format: date-time examples: Resolved company: summary: 完整的公司登记档案（为简明起见截断了管理人员列表） value: 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' '202': description: >- 报告已接受并仍在处理中。当报告仍在准备中时，endpoint 返回 202 Accepted、kyb_registry.fetch_status=pending 以及 registry_tier_delivered=null。请保留 request_id 并轮询调用 GET /v3/session/{request_id}/decision/，直至 registry_checks[0].company.fetch_status 解决。Didit 会自动完成报告，并在报告准备就绪后按交付的等级扣费。处于待处理状态时请勿重复购买；每个新的 POST 都会创建一个单独的请求。 content: application/json: schema: $ref: a3a18f7a-caa3-47c6-9f2b-0f376ceb7cff examples: Pending (registry still resolving): summary: 股权结构报告仍在处理中；获取已保存的决策 value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: 7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d node_id: feature_kyb_registry status: Not Finished registry_status: null data_resolved: false company_name: Example Holdings Limited registration_number: '12345678' country_code: HK region: null company_type: null incorporation_date: null registered_address: null tax_number: null risk_level: null verification_status: null is_from_registry: true fetch_status: pending alternative_names: null nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: null email: null phone: null legal_entity_identifier: null location_of_registration: null financial_summary: {} officers: [] beneficial_owners: [] addresses: null industries: null accounts: null registry_data: {} user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true registry_tier_delivered: null registry_ownership_status: pending vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' registry_tier_delivered: null registry_tier_requested: ubo '400': description: 验证错误。字段级问题使用 DRF 的标准外层结构。 content: application/json: examples: Missing kyb_response_id: summary: '`kyb_response_id` 为必填项' value: kyb_response_id: - This field is required. save_api_request=false rejected: summary: 选择内容始终持久化保存 value: save_api_request: - >- KYB registry select must be saved so billing and retrieval can be tracked. '403': description: >- 权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{"detail": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{"error": ...}`。 content: application/json: examples: Missing or invalid API key: summary: 缺少 `x-api-key` 请求头，或者密钥无效/已被吊销 value: detail: You do not have permission to perform this action. Not enough credits: summary: 组织余额不足以支付本次调用 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。 content: application/json: examples: Write rate limit exceeded: summary: 当前分钟内的写入请求超过 300 次 value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- 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" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.list_ubos( kyb_response_id="69aeeb95febb0f1704042259", vendor_data="company-1234", ) print(result) - lang: javascript label: Node.js source: |- 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); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListUBOs(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- 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); - lang: php label: PHP source: |- kyb->listUbos([ 'kyb_response_id' => '69aeeb95febb0f1704042259', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.list_ubos( kyb_response_id: "69aeeb95febb0f1704042259", vendor_data: "company-1234" ) puts result.to_h - lang: csharp label: .NET source: >- 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)); components: schemas: KYBRegistryCandidateRequest: type: object required: - kyb_response_id properties: kyb_response_id: type: string maxLength: 1024 description: >- 来自 `POST /v3/kyb/search/` 的候选句柄（`kyb_registry.companies[].kyb_response_id`）。临时有效：在生成它的搜索之后不久使用。句柄可能很长，因此请严格按返回的原样存储和发送该值，不要修剪或假定其长度。 example: 69aeeb95febb0f1704042259 vendor_data: type: string description: 您为此企业指定的标识符；将原样返回并与企业会话一起存储。 metadata: type: object nullable: true description: 随企业会话一同存储并回显的自由格式 JSON。 save_api_request: type: boolean default: true description: 必须为 `true`（默认值）。KYB 公司登记查询始终会持久化保存，以便跟踪计费和检索；传 `false` 将返回 `400`。 KYBRegistryShareholding: type: object nullable: true description: >- 所有人持有的权益，对所有国家/地区和登记来源采用相同的结构。当登记来源未声明持股时为 Null。区间（例如英国 PSC 的 25-50%）不属于持股权益：`percentage` 为 null，区间保留在 `ownership_min_shares` / `ownership_max_shares` 中。 properties: share_class: type: string nullable: true description: 登记机构命名的股份类别或类型。 number_of_shares: type: number nullable: true description: 持有的股份数量。 currency: type: string nullable: true description: 以下数值对应的 ISO 4217 货币。 nominal_value: type: number nullable: true description: 每股面值。 total_value: type: number nullable: true description: 持仓总价值。 percentage: type: number nullable: true description: 以百分比表示的精确持股比例，精确到小数点后四位。 required: - share_class - number_of_shares - currency - nominal_value - total_value - percentage KYBRegistryAddress: type: object description: 登记机构声明的地址，对于每个国家/地区和登记来源均采用相同格式。每个键始终存在；登记机构未公布的部分为 null。 properties: type: type: string nullable: true description: >- 小写形式的地址类型：注册办事处为 `registered`；其他类型按登记处的命名方式（例如 `postal`、`office`）。当登记处未说明该地址是什么类型时为 `null`。 address: type: string description: 单行格式的完整地址。每个地址中始终都提供该完整地址。 street: type: string nullable: true description: 街道与门牌号。 city: type: string nullable: true description: 城市或地区。 postal_code: type: string nullable: true description: 邮政编码。 region: type: string nullable: true description: 地区、州或省。 country_code: type: string nullable: true description: ISO 3166-1 alpha-2 国家/地区代码。 description: type: string nullable: true description: 登记处针对该地址自有的标签（如有）。 required: - type - address - street - city - postal_code - region - country_code - description KYBRegistryIndustry: type: object description: 登记机构对企业进行分类的经营活动，对于每个国家/地区和登记来源均采用相同格式。 properties: code: type: string nullable: true description: 公司登记载明的活动代码（例如 `73110`）。 description: type: string nullable: true description: 活动标签（若公司登记已发布）。 scheme: type: string nullable: true description: >- 分类体系，无论哪个来源报告，每个体系对应一个名称：`UK SIC 2007`、`US SIC`、`NACE Rev. 2`、`NACE Rev. 2.1`、`NAF Rev. 2`、`CNAE`、`SBI`、`NOGA 2008`、`CAE Rev. 4`、`Canada SIC 1977`；其他国家体系保留登记机构自身的名称。当登记机构未指明体系名称时为 Null。 is_primary: type: boolean description: 如果是公司的主要业务活动，则为 true。列表非空时恰好有一项为主活动。 required: - code - description - scheme - is_primary KYBRegistryData: type: object nullable: true description: >- Didit 为该企业标准化的公司登记详情：股权结构结果（`ownership_error`、`section_errors`、`ubo_resolution`、`lite_enrichment`）、使用 update-data 所做的更正，以及没有专属字段的公司登记事实。它绝不会携带登记来源自身的记录。每个键均为可选，且仅在企业具有相应值时才存在；可能会添加新键。对于规范字段（`addresses`、`industries`、`ownership`、`beneficial_owners[].shareholding`）涵盖的任何内容，请直接读取这些规范字段。 properties: company_name: type: string description: 在控制台中更正后的企业名称。 registration_number: type: string description: 公司登记或控制台更正注明的注册号。 country_code: type: string description: 登记处或控制台更正所声明的注册国家/地区。 region: type: string description: 注册的地区或州/省。 incorporation_date: type: string description: 注册成立日期（ISO 8601）。 registration_date: type: string description: 公司登记注明的注册日期（ISO 8601，独立于成立日期时提供）。 dissolution_date: type: string description: 注销日期（ISO 8601），由登记机构提供时包含。 tax_number: type: string description: 税号。 vat_number: type: string description: 增值税号。 legal_address: type: string description: 在控制台中更正后的法定地址。 registered_address: type: string description: 登记机构列明的注册地址。 company_type: type: string description: 法律形式。 registry_status: type: string description: 企业在公司登记的状态。 verification_status: type: string description: 验证状态。 alternative_names: type: string description: 该公司当前或曾经使用的其他商业名称。 nature_of_business: type: string description: 活动描述。 registered_capital: type: string description: 印示的注册资本。 registered_capital_amount: type: string description: 注册资本金额，以十进制字符串表示。 registered_capital_currency: type: string description: 注册资本货币（ISO 4217）。 website: type: string description: 网站。 email: type: string description: 联系邮箱。 phone: type: string description: 联系电话。 legal_entity_identifier: type: string description: 全球法人机构识别编码（LEI）。 location_of_registration: type: string description: 注册地。 control_scheme: type: string description: 公司登记提供该信息时的治理方案。 ownership_error: type: string enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other description: >- 所请求的股权结构等级未能交付的原因，代码与 `ownership.unavailable_reason` 相同。`no_owners_on_record`（登记机构已响应但未列出任何所有人）与 `ownership_section_unavailable`（登记机构未返回股权结构部分）是不同的结果。 section_errors: type: object description: >- 公司登记未返回的板块，以板块（`officers`、`shareholders`、`group_structure`）为键。此处列出的板块从未投递过：其旁的空列表并不表示关于该企业的任何信息。 additionalProperties: $ref: '#/components/schemas/KYBRegistrySectionError' ubo_resolution: $ref: '#/components/schemas/KYBRegistryUboResolution' lite_enrichment: $ref: '#/components/schemas/KYBRegistryLiteEnrichment' registry_metadata: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: 公司登记处针对该企业自有的原始字段，以登记处命名为键，作为普通值返回（旧版记录）。仅包含审核确认为登记事实的字段。 registry_sources: type: array description: 读取该记录的官方登记册（历史遗留记录）。未标明其他来源名称。 items: $ref: '#/components/schemas/KYBRegistrySource' previous_names: type: array items: type: string description: 企业以往注册所使用的名称（历史记录）。 parent_companies: type: array items: type: string description: 登记处列出的母公司（历史记录）。 documents_available: type: integer description: 登记处为该公司提供的备案记录数量（历史记录）。 KYBRegistryOwnership: type: object description: 股权结构（股东 / UBO）等级的结果，对所有国家/地区和登记册来源采用相同的结构。 properties: status: type: string nullable: true enum: - not_requested - pending - delivered - not_held - unavailable - null description: >- 当登记处发布股权结构时为 `delivered`；当股权登记处已响应且完全未列出该企业时为 `not_held`（参见 `unavailable_reason`）；当由于任何其他原因未提供股权结构数据时为 `unavailable`（参见 `unavailable_reason`）；当登记处仍在获取数据时为 `pending`；对于 Basic 等级为 `not_requested`。 tier_requested: type: string nullable: true enum: - basic - shareholders - ubo - null description: 工作流订购的等级。 tier_delivered: type: string nullable: true enum: - basic - shareholders - ubo - null description: 登记机构交付（且计费）的等级。仅返回直接股东的 UBO 请求为 `shareholders`。 unavailable_reason: type: string nullable: true enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other - null description: 所请求的股权结构等级未能交付的原因。除非 `status` 为 `unavailable` 或 `pending`，否则为 null。 direct_ownership_complete: type: boolean nullable: true description: >- 当直接股东申报的持股比例总和等于 100%（允许 1 个百分点的四舍五入误差）时为 true；否则为 false；未提供股权结构或未申报持股比例时为 null。 unresolved: type: array description: 登记处无法解析的股权链部分，例如记录中直接所有者之上不存在集团架构。 items: type: object properties: reason: type: string section: type: string nullable: true required: - status - tier_requested - tier_delivered - unavailable_reason - direct_ownership_complete - unresolved KYBRegistrySectionError: type: object description: 公司登记未返回的部分。 properties: status_code: type: integer nullable: true description: 登记机关针对该板块返回的状态。 required: - status_code KYBRegistryUboResolution: type: object description: UBO 层级遍历公司上层股权结构链的方式。 properties: parent_chain: type: array description: 从最终母公司到该公司的企业母实体层级。 items: $ref: '#/components/schemas/KYBRegistryGroupCompany' subsidiaries: type: array description: 企业集团内直接隶属于该企业的下级公司。 items: $ref: '#/components/schemas/KYBRegistryGroupCompany' unresolved: type: array description: 登记处无法解析的股权链部分（与 `ownership.unresolved` 条目相同）。 items: type: object properties: reason: type: string description: >- 原因，例如 `no_group_structure_on_record`、`selected_company_not_in_group_structure` 或 `section_error`。 section: type: string nullable: true description: 相关的部分，例如 `group_structure`。 required: - reason - section required: - parent_chain - subsidiaries - unresolved KYBRegistryLiteEnrichment: type: object description: 由该国家/地区的其他登记数据源填充的空白 Lite 档案字段。数据源名称未公开。 properties: fields: type: array items: type: string description: 已填写的企业字段。 people_added: type: integer description: 添加的高管或所有者数量。 required: - fields - people_added KYBRegistrySource: type: object description: 读取该记录的官方登记册。仅列出官方政府登记册、监管机构和官方标识符系统；忽略任何其他来源。 properties: name: type: string description: 登记机构名称，例如 `UK Companies House`。 source_type: type: string enum: - official description: 始终为 `official`。 required: - name - source_type KYBRegistryGroupCompany: type: object description: 根据公司登记身份确定的企业集团所属公司。 properties: name: type: string nullable: true description: 企业名称。 country_code: type: string nullable: true description: 注册国家/地区。 registration_number: type: string nullable: true description: 注册号。 required: - name - country_code - registration_number securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.