واجهة API للمستفيدين الحقيقيين في سجل KYB

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"
}

استخدم endpoint هذه بعد أن يعيد POST /v3/kyb/search/ الشركات المرشحة، عندما تحتاج إلى المستفيدين الحقيقيين النهائيين: المساهمين، بالإضافة إلى الأشخاص الطبيعيين والشركات الأم الذين يتم تحديدهم عبر سلسلة الملكية (registry_data.ubo_resolution). يُحتسب سعر هذه الخدمة بسعر UBO المعتمد في الدولة (أسعار كل دولة). المستوى المُسلَّم هو أعلى مستوى يمكن للدولة والسجل تقديمه، ويُسمّي registry_tier_delivered المستوى الذي تمّت فوترة رسومه: shareholders عندما لا يذكر التقرير أي شخص طبيعي بصفته مستفيدًا حقيقيًا، وbasic عندما لا يوجد أي سجل ملكية على الإطلاق، وعندها تكون قيمة registry_ownership_status هي unavailable، أو not_held عندما يجيب مصدر الملكية بأنه لا يحتفظ بهذه الشركة (حالة الملكية). عندما يكون التقرير لا يزال قيد الإعداد، أو لم يُسترجع قسم الملكية من السجل بعد، تعيد 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 هي resolved. يُكمل Didit التقرير المعلّق تلقائيًا، ويُحتسب رسوم المستوى المُسلَّم بمجرد أن يصبح التقرير جاهزًا. لا تُكرر طلب الشراء أثناء بقائه معلّقًا، لأن كل طلب POST جديد ينشئ طلبًا منفصلًا. متاح في الإصدار v3 فقط. يحتفظ POST /v2/kyb/select/ وPOST /v3/kyb/select/ بالعقد والسعر الخاصين بهما.

التفويضات

x-api-key

string

header

مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ 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>

معرّف جلسة الشركة التي تم إنشاؤها لعملية الاسترداد هذه. يستمر السجل المخزن (المرئي في لوحة التحكم) في التحديث إذا تمكّن السجل من حلّ البيانات بعد إرسال الاستجابة.

registry_tier_requested

enum<string>

المستوى الذي يبيعه هذا الـ endpoint: 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>

آخر تعديل في ٧ نوفمبر ٢٠٢٦