> ## 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. # واجهة API للمستفيدين الحقيقيين في سجل KYB > استدعِ POST /v3/kyb/ubo/ مع kyb_response_id من البحث في السجل في Didit للحصول على ملف الشركة والمساهمين والمستفيدين الحقيقيين عبر سلسلة الملكية. استخدم endpoint هذه بعد أن يعيد `POST /v3/kyb/search/` الشركات المرشحة، عندما تحتاج إلى **المستفيدين الحقيقيين النهائيين**: المساهمين، بالإضافة إلى الأشخاص الطبيعيين والشركات الأم الذين يتم تحديدهم عبر سلسلة الملكية (`registry_data.ubo_resolution`). يُحتسب سعر هذه الخدمة بسعر UBO المعتمد في الدولة ([أسعار كل دولة](https://docs.didit.me/ar/getting-started/kyb-registry-pricing.md)). المستوى المُسلَّم هو أعلى مستوى يمكن للدولة والسجل تقديمه، ويُسمّي `registry_tier_delivered` المستوى الذي تمّت فوترة رسومه: `shareholders` عندما لا يذكر التقرير أي شخص طبيعي بصفته مستفيدًا حقيقيًا، و`basic` عندما لا يوجد أي سجل ملكية على الإطلاق، وعندها تكون قيمة `registry_ownership_status` هي `unavailable`، أو `not_held` عندما يجيب مصدر الملكية بأنه لا يحتفظ بهذه الشركة ([حالة الملكية](https://docs.didit.me/ar/standalone-apis/kyb-registry.md#حالة-الملكية)). عندما يكون التقرير لا يزال قيد الإعداد، أو لم يُسترجع قسم الملكية من السجل بعد، تعيد 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/` بالعقد والسعر الخاصين بهما. ## OpenAPI ````yaml ar/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: >- استرجع ملف Lite والمساهمين المباشرين **والمستفيدين الحقيقيين النهائيين** الذين تم تحديدهم عبر سلسلة الملكية (يحمل `registry_data.ubo_resolution` سلسلة الشركات الأم) لمرشح واحد تم إرجاعه بواسطة `POST /v3/kyb/search/`. **الاقتران بالبحث.** مرر `kyb_response_id` الخاص بالمرشح تماماً كما تم إرجاعه من خلال بحث في التطبيق نفسه. ابحث في المستوى الذي تنوي شراؤه (`tier` في `POST /v3/kyb/search/`)، لأن البحث يعمل على سلسلة السجلات التي تخدم ذلك المستوى، ولا يُعد بحث Lite الفارغ دليلاً على أن السجل لا يتضمن الشركة. عندما تكون بيانات الملكية الخاصة بالدولة موجودة في سجل آخر، تقوم Didit بالعثور على الشركة مجدداً هناك باستخدام رقم التسجيل، دون أي تكلفة إضافية. **الفوترة.** تتم الفوترة وفقاً لسعر UBO الخاص بالدولة - راجع [أسعار سجل KYB](/ar/getting-started/kyb-registry-pricing). المستوى المسلَّم هو أعلى مستوى يمكن للدولة والسجل تقديمه: Shareholders عندما لا يحدد التقرير الناتج أي شخص طبيعي كمستفيد حقيقي، وLite عندما لا يكون هناك أي سجل ملكية على الإطلاق؛ يحدد `registry_tier_delivered` ما تمت فوترته. يتم التحقق من الرصيد مقابل سعر UBO قبل أي استدعاء للسجل (`403` عند عدم كفايته). **التوفر.** الإصدار v3 فقط. ينشئ كل استدعاء جلسة شركة (معرّفها هو `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: >- معرّف جلسة الشركة التي تم إنشاؤها لعملية الاسترداد هذه. يستمر السجل المخزن (المرئي في لوحة التحكم) في التحديث إذا تمكّن السجل من حلّ البيانات بعد إرسال الاستجابة. registry_tier_requested: type: string enum: - basic - shareholders - ubo description: >- المستوى الذي يبيعه هذا الـ endpoint: `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 لسجل هذه الشركة. 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: >- رمز التقسيم الفرعي عندما يكون السجل إقليمياً (مثل `CA` لـ `US-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: >- حالة التحقق عبر الولايات القضائية: `verified` عندما تُثبت حالة السجل الوضع القانوني القائم للشركة (`active`)، و`failed` عندما تفيد بأن الشركة لم تعد قائمة (على سبيل المثال `dissolved`)، وتكون `unknown` في الحالات الأخرى. وتكون القيمة `null` للشركة التي لم تأتِ من سجل وطالما أن التحديد لا يزال `pending`. is_from_registry: type: boolean description: >- دائماً `true` لهذا الـ endpoint — تم استرداد الملف التعريفي من سجل رسمي. 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: >- رقم ضريبة القيمة المضافة في الاتحاد الأوروبي (EU VAT)، عند جمعه أثناء خطوة السجل المستضاف أو تعديله لاحقاً. في وقت التحديد، لا يكون هذا الحقل معيناً في العادة — إذ يتم التحقق من صحة ضريبة القيمة المضافة والرقم الضريبي عندما يرسل المستخدم النهائي خطوة السجل في المسار المستضاف. vat_validation_status: type: string enum: - valid - invalid - format_valid - invalid_format - could_not_validate - not_applicable description: >- نتيجة التحقق من صحة رقم ضريبة القيمة المضافة أو، عند عدم وجوده، `tax_number`، عند الإرسال إلى السجل. `valid` / `invalid`: يتم تحديدها بواسطة السجل الرسمي للدولة (EU 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: >- دائماً `null` في هذا الـ endpoint (يُستخدم بواسطة مسار KYB المستضاف عندما يقوم المستخدمون النهائيون بتعديل بيانات السجل). confirmed_by_user_at: type: string format: date-time nullable: true description: دائماً `null` في هذا الـ endpoint. 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`)، و`pending` عندما لا يكون قسم الملكية قد استُرد من السجل بعد ولا تزال Didit تستكمله، و`not_requested` في المستوى Lite. 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: c832aa29-5fbc-4ff2-b2e0-d1c062cb3500 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: >- تم تجاوز حد المعدل. تشترك نقاط endpoint الخاصة بـ POST/PATCH/DELETE في ميزانية قدرها 300 طلب كتابة في الدقيقة لكل مفتاح API (إنشاء المعاملات واستيعاب الأحداث لهما ميزانية منفصلة تبلغ 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 عندما لا يذكر السجل أي حصة. النطاق (على سبيل المثال 25-50% لـ UK PSC) لا يُعد حصة: يكون `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: رقم ضريبة القيمة المضافة (VAT). 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` بينما لا يزال السجل يجلبها؛ و`not_requested` للمستوى Basic. 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`. direct_ownership_complete: type: boolean nullable: true description: >- تكون القيمة True عندما يصل مجموع الحصص المعلنة للمساهمين المباشرين إلى 100% (مع فارق نقطة مئوية واحدة للتقريب)؛ وتكون 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 الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ 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.