مرجع API كبار الحاملين

الحاملون لأكثر من 5% من شركة، من Schedule 13D وSchedule 13G

نظرة عامة

كبار الحاملين هم الأشخاص والشركات الذين يملكون أكثر من 5% من أسهم شركة أمريكية. يُبلغون على Schedule 13D، للحامل الذي قد يسعى إلى السيطرة (الوسم activist)، وعلى Schedule 13G، للحامل السلبي (الوسم passive)، وعلى تعديلات أيٍّ منهما. يحتاج كل طلب إلى مفتاح Bearer، ويستخدم REST وMCP رصيدًا واحدًا.

أربعة مسارات تغطي كبار الحاملين في شركة، والحصص الكبيرة لحامل واحد عبر الشركات، وبحثين بالاسم يجدان حاملًا أو شركة للقراءة. تُحدَّد الشركة بمعرّفها في Filings API، مثل usa:0000320193. ويُحدَّد الحامل بـ CIK الخاص به.

افتراضيًا يُجيب المسار بالحصص الحالية: أحدث إفصاح لكل حامل في كل فئة أسهم. لا تُدرج الحصة التي يُبلغ أحدث إفصاح لها عن خروج، أو التي أسقطها إفصاح لاحق لمجموعة مقدّمي الإفصاح نفسها. أرسل history=true لقراءة كل إفصاح، الأحدث أولًا.

يبدأ السجل بإفصاحات أكتوبر 2024. قد تحمل صفحة حصص الحامل صفوفًا أقل من limit وتنتهي مع ذلك بـ next_cursor، فواصل القراءة حتى تصبح next_cursor هي null. الولايات المتحدة هي الدولة الوحيدة المغطاة.

عنوان URL الأساسي: https://api.narwhalapi.com. كل مسار أدناه أداة MCP قائمة بذاتها، بالمعاملات نفسها.

المسؤولون والمديرون ومالكو 10% في صفحة تداولات المطلعين.

معرّفات الشركات هي التي واجهة الإفصاحات (Filings API) يُرجعها بحث الشركات.

ما يحصل عليه كل حساب

ما	كل حساب
كبار الحاملين، أربعة مسارات	مشمول

راجع التسعير لمعرفة تكلفة الاستدعاء. يُحاسَب الطلب بسعر واجهته ما لم يذكر المسار خلاف ذلك.

يُحاسَب بسعر Companies. كل إجابة ناجحة استدعاء واحد، مهما كان عدد الصفوف، وتُحاسَب الصفحة الفارغة أيضًا. لا تُحاسَب الأخطاء. ويُحاسَب البحث الذي لا نتائج له أيضًا.
الأرقام سلاسل عشرية. يُحذف الحقل الذي لا قيمة له، وتكون القائمة موجودة دائمًا، ولا يُرسل علم مثل officer إلا عندما يكون true.
للإفصاح المشترك صف لكل شخص مُبلِّغ، وتشترك الصفوف في filing_id. يذكر كل شخص رقم المجموعة نفسه على صفحة غلافه، فلا تجمع shares عبر أشخاص إفصاح واحد. جمّع الصفوف بـ filing_id واقرأ رقم المجموعة من group_total.
الرقم الذي لا يذكره الإفصاح، أو الذي تعذّرت قراءته بوضوح، يُحذف. لا شيء يُقدَّر.
تقرأ صفحة الحامل 30 ملف شركة على الأكثر، فالحامل في إفصاحات مشتركة عبر مئات الشركات تأتي صفحاته قصيرة وتنتهي بمؤشر متابعة.
عدد قليل من الإفصاحات التي لا نستطيع قراءتها يُستبعد من الإجابات. CUSIP ليس جزءًا من أي إجابة.

نقاط النهاية

كل مسار هو طلب GET ويحتاج إلى مفتاحك في: Authorization: Bearer الترويسة. تعرض الأمثلة شكل الاستجابة، وليست بيانات مباشرة.

قائمة كبار الحاملين في شركة

GET /v1/companies/{company_id}/beneficial-owners

الحاملون لأكثر من 5% من أسهم الشركة، من Schedule 13D وSchedule 13G وتعديلاتهما. افتراضيًا حصة كل حامل الحالية في كل فئة؛ وhistory يعرض كل إفصاح.

تضيّق التواريخ الإفصاحات قبل اختيار أحدثها لكل حصة، فيعطي filed_lte كبار حاملي الشركة كما كانوا في ذلك اليوم.

MCP: الأداة filings_list_beneficial_owners.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`company_id`	مسار	نعم	سلسلة نصية	معرّف الشركة، مثل `usa:0000320193`. يُقبل رمز تداول بديل مثل `usa:AAPL`.
`schedule`	استعلام	لا	one of 13D, 13G	`13D` فقط (الحاملون الذين قد يسعون إلى السيطرة) أو `13G` (الحاملون السلبيون).
`type`	استعلام	لا	one of activist, passive	`activist` مثل `13D` و`passive` مثل `13G`. عند إرسال `schedule` أيضًا يجب أن تتفق القيمتان.
`history`	استعلام	لا	منطقي	`false` (الافتراضي) يُجيب بالحصص الحالية. `true` يعرض كل إفصاح، الأحدث أولًا.
`is_latest`	استعلام	لا	منطقي	مع `history=true` فقط. `true` يُبقي أحدث إفصاح لكل حصة و`false` يُبقي الأقدم.
`filed`	استعلام	لا	التاريخ	الإفصاحات المقدمة في هذا اليوم فقط.
`filed_from`	استعلام	لا	التاريخ	مثل `filed_gte`.
`filed_to`	استعلام	لا	التاريخ	مثل `filed_lte`.
`filed_gt`	استعلام	لا	التاريخ	الإفصاحات المقدمة بعد هذا اليوم فقط.
`filed_gte`	استعلام	لا	التاريخ	الإفصاحات المقدمة في هذا اليوم أو بعده فقط.
`filed_lt`	استعلام	لا	التاريخ	الإفصاحات المقدمة قبل هذا اليوم فقط.
`filed_lte`	استعلام	لا	التاريخ	الإفصاحات المقدمة في هذا اليوم أو قبله فقط.
`cursor`	استعلام	لا	سلسلة نصية	قيمة `next_cursor` من الصفحة السابقة، مع المعاملات الأخرى نفسها.
`limit`	استعلام	لا	عدد صحيح	عدد الصفوف في الصفحة. الافتراضي 50 وبحد أقصى 1000.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`id`	سلسلة نصية	دائمًا	معرّف الشركة في مسار المالكين، ومعرّف الحامل في مسار الحصص.
`company`	سلسلة نصية	اختياري	اسم الشركة.
`owners`	قائمة كائنات	دائمًا	كبار الحاملين في الشركة، الأحدث أولًا.
`owners[].filing_id`	سلسلة نصية	دائمًا	معرّف الإفصاح الذي جاء منه الصف.
`owners[].form`	one of 13D, 13D/A, 13G, 13G/A	دائمًا	النموذج (Schedule) وهل يعدّل نموذجًا سابقًا: `13D` أو `13D/A` أو `13G` أو `13G/A`.
`owners[].filed`	التاريخ	دائمًا	يوم تقديم الإفصاح.
`owners[].accepted`	تاريخ ووقت	اختياري	اللحظة التي قبلت فيها SEC الإفصاح.
`owners[].event_date`	التاريخ	اختياري	تاريخ الحدث الذي استوجب الإفصاح.
`owners[].amendment_number`	عدد صحيح	اختياري	رقم التعديل، عندما يذكره الإفصاح.
`owners[].filer_id`	سلسلة نصية	اختياري	معرّف أول مقدّم في الإفصاح، أي الشركة التي قدّمته.
`owners[].filer`	سلسلة نصية	اختياري	اسم أول مقدّم. قد يختلف عن الشخص المُبلِّغ.
`owners[].holder_id`	سلسلة نصية	اختياري	معرّف الشخص المُبلِّغ. الفرد ليس له معرّف.
`owners[].holder`	سلسلة نصية	دائمًا	اسم الشخص المُبلِّغ.
`owners[].holder_type`	سلسلة نصية	اختياري	رمز صفحة الغلاف للشخص: `IN` فرد و`CO` شركة مساهمة و`PN` شراكة و`IA` مستشار استثمار و`HC` شركة قابضة و`BK` بنك، وغيرها.
`owners[].citizenship`	سلسلة نصية	اختياري	جنسية الشخص أو مكان تأسيسه.
`owners[].class_title`	سلسلة نصية	اختياري	عنوان فئة الأسهم.
`owners[].shares`	سلسلة نصية	اختياري	الأسهم التي يُبلغ الشخص أنه يملكها. في الإفصاح المشترك لا تجمع هذه الأرقام عبر الأشخاص. استخدم `group_total`.
`owners[].percent_of_class`	سلسلة نصية	اختياري	نسبة الفئة التي يُبلغ الشخص أنه يملكها.
`owners[].sole_voting_power`	سلسلة نصية	اختياري	الأسهم التي يستطيع الشخص وحده التصويت بها.
`owners[].shared_voting_power`	سلسلة نصية	اختياري	الأسهم التي يشارك الشخص في التصويت بها.
`owners[].sole_dispositive_power`	سلسلة نصية	اختياري	الأسهم التي يستطيع الشخص وحده بيعها.
`owners[].shared_dispositive_power`	سلسلة نصية	اختياري	الأسهم التي يشارك الشخص في سلطة بيعها.
`owners[].group_box`	one of a, b, ab	اختياري	ما علّم عليه الشخص في الصف 2 من الغلاف: `a` عضو في مجموعة و`b` ليس عضوًا أو لا يقرّ بذلك و`ab` كلاهما.
`owners[].rule`	سلسلة نصية	اختياري	القاعدة التي قُدّم 13G بموجبها: `13d-1(b)` أو `13d-1(c)` أو `13d-1(d)`.
`owners[].funds`	سلسلة نصية	اختياري	رمز مصدر الأموال في 13D، مثل `WC` أو `AF` أو `PF` أو `OO`.
`owners[].type`	one of activist, passive	اختياري	`activist` لـ Schedule 13D و`passive` لـ Schedule 13G.
`owners[].legal_proceedings`	دائمًا true	اختياري	تكون القيمة true عندما تكون خانة الغلاف الخاصة بالإجراءات القانونية معلَّمة.
`owners[].excludes_certain_shares`	دائمًا true	اختياري	تكون القيمة true عندما تكون خانة الغلاف الخاصة باستبعاد أسهم معينة معلَّمة.
`owners[].previously_filed`	دائمًا true	اختياري	تكون القيمة true عندما يحمل الإفصاح علامة سبق تقديمه.
`owners[].issuer_address`	سلسلة نصية	اختياري	عنوان الشركة كما ورد في الإفصاح.
`owners[].purpose`	سلسلة نصية	اختياري	البند 4 في 13D، غرض المعاملة. يُقتطع عند 4,000 حرف.
`owners[].items`	كائن	اختياري	نص البنود 1 و2 و3 و5 و6 في 13D، أو البند 8 في 13G، كل منها يُقتطع عند 4,000 حرف. البنود التي يذكرها الإفصاح فقط.
`owners[].joint`	عدد صحيح	اختياري	عدد الأشخاص الذين يذكرهم الإفصاح.
`owners[].repeat`	دائمًا true	اختياري	تكون القيمة true عندما يذكر الشخص رقمًا سبق أن ذكره شخص أسبق في الإفصاح.
`owners[].group_total`	سلسلة نصية	اختياري	في الإفصاح المشترك، أكبر إجمالي يُبلغ عنه أي من أشخاصه. اقرأ رقم المجموعة هنا.
`owners[].is_latest`	منطقي	دائمًا	تكون القيمة true على أحدث إفصاح للحصة بين الإفصاحات التي يُبقيها الطلب.
`owners[].exit`	دائمًا true	اختياري	تكون القيمة true عندما يُبلغ الإفصاح عن الحامل بنسبة 5% أو أقل، أو من دون أسهم.
`owners[].superseded`	دائمًا true	اختياري	تكون القيمة true على أحدث إفصاح لحصة لم يعد إفصاح لاحق لمجموعة مقدّمي الإفصاح نفسها يُدرجها.
`next_cursor`	سلسلة نصية	دائمًا	مرّره بوصفه cursor لقراءة الصفحة التالية. يُرسل دائمًا؛ وقيمته null في الصفحة الأخيرة.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/companies/usa:0000320193/beneficial-owners?limit=1"

{
  "id": "usa:0000320193",
  "company": "Apple Inc.",
  "owners": [
    {
      "filing_id": "usa:0000320193:0002100119-26-000139",
      "form": "13G",
      "filed": "2026-04-29",
      "accepted": "2026-04-29T16:40:10Z",
      "event_date": "2026-03-31",
      "filer_id": "usa:0002100119",
      "filer": "VANGUARD CAPITAL MANAGEMENT LLC",
      "holder_id": "usa:0002100119",
      "holder": "Vanguard Capital Management",
      "holder_type": "IA",
      "citizenship": "PA",
      "class_title": "Common Stock",
      "shares": "1099168953",
      "percent_of_class": "7.48",
      "sole_voting_power": "145321305",
      "shared_voting_power": "0",
      "sole_dispositive_power": "1099168953",
      "shared_dispositive_power": "0",
      "rule": "13d-1(b)",
      "issuer_address": "1 Apple Park Way, Cupertino, CA, 95014",
      "is_latest": true
    }
  ],
  "next_cursor": null
}

قائمة الحصص الكبيرة لحامل

GET /v1/investors/{cik}/beneficial-ownership

ما يملكه حامل واحد عبر الشركات، من Schedule 13D وSchedule 13G. افتراضيًا الحصة الحالية في كل فئة من كل شركة؛ وhistory يعرض كل إفصاح. قد تحمل الصفحة صفوفًا أقل من limit وتنتهي مع ذلك بـ next_cursor: واصل القراءة حتى يصبح null.

cik هو CIK الحامل. company_id وcompany في كل صف يسميان الشركة التي فيها الحصة. ticker يُبقي الحصص في شركة واحدة، والرمز الذي لا يطابق أي شركة يعطي 404 company_not_found.

قد تكون الصفحة أقصر من limit. واصل اتباع next_cursor حتى يصبح null.

MCP: الأداة filings_list_investor_beneficial_ownership.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`cik`	مسار	نعم	سلسلة نصية	CIK الحامل، من رقم إلى عشرة أرقام.
`schedule`	استعلام	لا	one of 13D, 13G	`13D` فقط (الحاملون الذين قد يسعون إلى السيطرة) أو `13G` (الحاملون السلبيون).
`type`	استعلام	لا	one of activist, passive	`activist` مثل `13D` و`passive` مثل `13G`. عند إرسال `schedule` أيضًا يجب أن تتفق القيمتان.
`history`	استعلام	لا	منطقي	`false` (الافتراضي) يُجيب بالحصص الحالية. `true` يعرض كل إفصاح، الأحدث أولًا.
`is_latest`	استعلام	لا	منطقي	مع `history=true` فقط. `true` يُبقي أحدث إفصاح لكل حصة و`false` يُبقي الأقدم.
`filed`	استعلام	لا	التاريخ	الإفصاحات المقدمة في هذا اليوم فقط.
`filed_from`	استعلام	لا	التاريخ	مثل `filed_gte`.
`filed_to`	استعلام	لا	التاريخ	مثل `filed_lte`.
`filed_gt`	استعلام	لا	التاريخ	الإفصاحات المقدمة بعد هذا اليوم فقط.
`filed_gte`	استعلام	لا	التاريخ	الإفصاحات المقدمة في هذا اليوم أو بعده فقط.
`filed_lt`	استعلام	لا	التاريخ	الإفصاحات المقدمة قبل هذا اليوم فقط.
`filed_lte`	استعلام	لا	التاريخ	الإفصاحات المقدمة في هذا اليوم أو قبله فقط.
`cursor`	استعلام	لا	سلسلة نصية	قيمة `next_cursor` من الصفحة السابقة، مع المعاملات الأخرى نفسها.
`limit`	استعلام	لا	عدد صحيح	عدد الصفوف في الصفحة. الافتراضي 50 وبحد أقصى 1000.
`ticker`	استعلام	لا	سلسلة نصية	الحصص في الشركة ذات هذا الرمز فقط.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`id`	سلسلة نصية	دائمًا	معرّف الشركة في مسار المالكين، ومعرّف الحامل في مسار الحصص.
`holder`	سلسلة نصية	اختياري	اسم الحامل.
`stakes`	قائمة كائنات	دائمًا	حصص الحامل، الأحدث أولًا.
`stakes[].filing_id`	سلسلة نصية	دائمًا	معرّف الإفصاح الذي جاء منه الصف.
`stakes[].form`	one of 13D, 13D/A, 13G, 13G/A	دائمًا	النموذج (Schedule) وهل يعدّل نموذجًا سابقًا: `13D` أو `13D/A` أو `13G` أو `13G/A`.
`stakes[].filed`	التاريخ	دائمًا	يوم تقديم الإفصاح.
`stakes[].accepted`	تاريخ ووقت	اختياري	اللحظة التي قبلت فيها SEC الإفصاح.
`stakes[].event_date`	التاريخ	اختياري	تاريخ الحدث الذي استوجب الإفصاح.
`stakes[].amendment_number`	عدد صحيح	اختياري	رقم التعديل، عندما يذكره الإفصاح.
`stakes[].filer_id`	سلسلة نصية	اختياري	معرّف أول مقدّم في الإفصاح، أي الشركة التي قدّمته.
`stakes[].filer`	سلسلة نصية	اختياري	اسم أول مقدّم. قد يختلف عن الشخص المُبلِّغ.
`stakes[].holder_id`	سلسلة نصية	اختياري	معرّف الشخص المُبلِّغ. الفرد ليس له معرّف.
`stakes[].holder`	سلسلة نصية	دائمًا	اسم الشخص المُبلِّغ.
`stakes[].holder_type`	سلسلة نصية	اختياري	رمز صفحة الغلاف للشخص: `IN` فرد و`CO` شركة مساهمة و`PN` شراكة و`IA` مستشار استثمار و`HC` شركة قابضة و`BK` بنك، وغيرها.
`stakes[].citizenship`	سلسلة نصية	اختياري	جنسية الشخص أو مكان تأسيسه.
`stakes[].class_title`	سلسلة نصية	اختياري	عنوان فئة الأسهم.
`stakes[].shares`	سلسلة نصية	اختياري	الأسهم التي يُبلغ الشخص أنه يملكها. في الإفصاح المشترك لا تجمع هذه الأرقام عبر الأشخاص. استخدم `group_total`.
`stakes[].percent_of_class`	سلسلة نصية	اختياري	نسبة الفئة التي يُبلغ الشخص أنه يملكها.
`stakes[].sole_voting_power`	سلسلة نصية	اختياري	الأسهم التي يستطيع الشخص وحده التصويت بها.
`stakes[].shared_voting_power`	سلسلة نصية	اختياري	الأسهم التي يشارك الشخص في التصويت بها.
`stakes[].sole_dispositive_power`	سلسلة نصية	اختياري	الأسهم التي يستطيع الشخص وحده بيعها.
`stakes[].shared_dispositive_power`	سلسلة نصية	اختياري	الأسهم التي يشارك الشخص في سلطة بيعها.
`stakes[].group_box`	one of a, b, ab	اختياري	ما علّم عليه الشخص في الصف 2 من الغلاف: `a` عضو في مجموعة و`b` ليس عضوًا أو لا يقرّ بذلك و`ab` كلاهما.
`stakes[].rule`	سلسلة نصية	اختياري	القاعدة التي قُدّم 13G بموجبها: `13d-1(b)` أو `13d-1(c)` أو `13d-1(d)`.
`stakes[].funds`	سلسلة نصية	اختياري	رمز مصدر الأموال في 13D، مثل `WC` أو `AF` أو `PF` أو `OO`.
`stakes[].type`	one of activist, passive	اختياري	`activist` لـ Schedule 13D و`passive` لـ Schedule 13G.
`stakes[].legal_proceedings`	دائمًا true	اختياري	تكون القيمة true عندما تكون خانة الغلاف الخاصة بالإجراءات القانونية معلَّمة.
`stakes[].excludes_certain_shares`	دائمًا true	اختياري	تكون القيمة true عندما تكون خانة الغلاف الخاصة باستبعاد أسهم معينة معلَّمة.
`stakes[].previously_filed`	دائمًا true	اختياري	تكون القيمة true عندما يحمل الإفصاح علامة سبق تقديمه.
`stakes[].issuer_address`	سلسلة نصية	اختياري	عنوان الشركة كما ورد في الإفصاح.
`stakes[].purpose`	سلسلة نصية	اختياري	البند 4 في 13D، غرض المعاملة. يُقتطع عند 4,000 حرف.
`stakes[].items`	كائن	اختياري	نص البنود 1 و2 و3 و5 و6 في 13D، أو البند 8 في 13G، كل منها يُقتطع عند 4,000 حرف. البنود التي يذكرها الإفصاح فقط.
`stakes[].joint`	عدد صحيح	اختياري	عدد الأشخاص الذين يذكرهم الإفصاح.
`stakes[].repeat`	دائمًا true	اختياري	تكون القيمة true عندما يذكر الشخص رقمًا سبق أن ذكره شخص أسبق في الإفصاح.
`stakes[].group_total`	سلسلة نصية	اختياري	في الإفصاح المشترك، أكبر إجمالي يُبلغ عنه أي من أشخاصه. اقرأ رقم المجموعة هنا.
`stakes[].is_latest`	منطقي	دائمًا	تكون القيمة true على أحدث إفصاح للحصة بين الإفصاحات التي يُبقيها الطلب.
`stakes[].exit`	دائمًا true	اختياري	تكون القيمة true عندما يُبلغ الإفصاح عن الحامل بنسبة 5% أو أقل، أو من دون أسهم.
`stakes[].superseded`	دائمًا true	اختياري	تكون القيمة true على أحدث إفصاح لحصة لم يعد إفصاح لاحق لمجموعة مقدّمي الإفصاح نفسها يُدرجها.
`stakes[].company_id`	سلسلة نصية	دائمًا	معرّف الشركة التي فيها الحصة.
`stakes[].company`	سلسلة نصية	اختياري	اسم الشركة التي فيها الحصة.
`next_cursor`	سلسلة نصية	دائمًا	مرّره بوصفه cursor لقراءة الصفحة التالية. يُرسل دائمًا؛ وقيمته null في الصفحة الأخيرة.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/investors/0000102909/beneficial-ownership?filed_lte=2025-10-31&limit=1"

{
  "id": "usa:0000102909",
  "holder": "The Vanguard Group",
  "stakes": [
    {
      "filing_id": "usa:0001770450:0000102909-25-000347",
      "form": "13G/A",
      "filed": "2025-10-31",
      "accepted": "2025-10-31T11:42:47Z",
      "event_date": "2025-09-30",
      "amendment_number": 8,
      "filer_id": "usa:0000102909",
      "filer": "VANGUARD GROUP INC",
      "holder_id": "usa:0000102909",
      "holder": "The Vanguard Group",
      "holder_type": "IA",
      "citizenship": "PA",
      "class_title": "Common Stock",
      "shares": "10397351",
      "percent_of_class": "8.26",
      "sole_voting_power": "0",
      "shared_voting_power": "733054",
      "sole_dispositive_power": "9549123",
      "shared_dispositive_power": "848228",
      "rule": "13d-1(b)",
      "issuer_address": "201 Merritt 7, Norwalk, CT, 06851",
      "is_latest": true,
      "company_id": "usa:0001770450",
      "company": "Xerox Holdings Corp"
    }
  ],
  "next_cursor": "eyJrIjoiNzk3NDg5Njg3OTc0…"
}

البحث عن مقدمي إفصاحات كبار الحاملين بالاسم

GET /v1/beneficial-ownership/filers

اعثر على حامل يقدّم Schedule 13D أو 13G ببداية اسمه. يُرجع id لاستخدامه بوصفه cik في مسار الحصص.

يُرجع id لتمريره بوصفه cik في مسار الحصص. يحتاج الاسم إلى حرفين أو رقمين على الأقل غير كلمات مثل Inc، وإلا فالجواب 400 invalid_name.

MCP: الأداة filings_search_beneficial_ownership_filers.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`name`	استعلام	نعم	سلسلة نصية	الأحرف الأولى من الاسم. حرفان أو رقمان على الأقل.
`country`	استعلام	لا	سلسلة نصية	رمز الدولة من ثلاثة أحرف للسجل المراد البحث فيه. الحذف يعني USA. الدولة التي لا يغطيها المسار تُجيب 404 not_covered.
`limit`	استعلام	لا	عدد صحيح	عدد النتائج المراد إرجاعها. الافتراضي 20 وبحد أقصى 100.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`filers`	قائمة كائنات	دائمًا	مقدمو الإفصاحات الذين يبدأ اسمهم بالنص.
`filers[].id`	سلسلة نصية	دائمًا	معرّف مقدّم الإفصاح، ليمرَّر بوصفه `cik` في مسار الحصص.
`filers[].name`	سلسلة نصية	دائمًا	اسم استخدمه مقدّم الإفصاح في إفصاح.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/beneficial-ownership/filers?name=vanguard&limit=3"

{
  "filers": [
    {
      "id": "usa:0002100119",
      "name": "VANGUARD CAPITAL MANAGEMENT LLC"
    },
    {
      "id": "usa:0001623658",
      "name": "Vanguard Charitable Endowment Program"
    },
    {
      "id": "usa:0002059874",
      "name": "Vanguard Development Holdings Limited"
    }
  ]
}

البحث عن الشركات التي لها كبار حاملين بالاسم

GET /v1/beneficial-ownership/companies

اعثر على شركة قُدّمت عنها إفصاحات Schedule 13D أو 13G ببداية اسمها. يُرجع id لاستخدامه بوصفه company_id في مسار المالكين.

يُرجع id لتمريره بوصفه company_id في مسار المالكين.

MCP: الأداة filings_search_beneficial_ownership_companies.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`name`	استعلام	نعم	سلسلة نصية	الأحرف الأولى من الاسم. حرفان أو رقمان على الأقل.
`country`	استعلام	لا	سلسلة نصية	رمز الدولة من ثلاثة أحرف للسجل المراد البحث فيه. الحذف يعني USA. الدولة التي لا يغطيها المسار تُجيب 404 not_covered.
`limit`	استعلام	لا	عدد صحيح	عدد النتائج المراد إرجاعها. الافتراضي 20 وبحد أقصى 100.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`companies`	قائمة كائنات	دائمًا	الشركات التي يبدأ اسمها بالنص.
`companies[].id`	سلسلة نصية	دائمًا	معرّف الشركة، ليمرَّر بوصفه `company_id` في مسار المالكين.
`companies[].name`	سلسلة نصية	دائمًا	اسم الشركة.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/beneficial-ownership/companies?name=apple&limit=2"

{
  "companies": [
    {
      "id": "usa:0000320193",
      "name": "Apple Inc."
    },
    {
      "id": "usa:0001418121",
      "name": "Apple Hospitality REIT, Inc."
    }
  ]
}

الأخطاء

تستخدم الأخطاء بنية المشكلة المشتركة مع: request_id. راجع أخطاء API والرصيد لمعرفة الشكل وترويسات الرصيد. لا تُحاسَب الطلبات الفاشلة.

الرمز	الحالة	المعنى
`invalid_query`	400	معامل مفقود أو غير معروف أو مكرر أو خارج نطاقه.
`invalid_cursor`	400	مؤشر الصفحة هذا لم يُعده هذا الطلب، أو أنه من طلب مختلف.
`invalid_name`	400	الاسم فيه أقل من حرفين أو رقمين بعد استبعاد كلمات مثل Inc.
`company_not_found`	404	لا شركة تطابق المعرّف.
`investor_not_found`	404	لا مقدّم Schedule 13D أو 13G يطابق CIK.
`not_covered`	404	السوق أو البلد أو الشركة غير مغطى بعد.
`insufficient_credits`	402	رصيدك أقل من تكلفة الطلب.
`company_data_unavailable`	503	تعذّرت قراءة الإفصاحات وراء هذا المسار الآن. حاول مرة أخرى بعد قليل.

هل كانت هذه الصفحة مفيدة؟