> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# البحث عن بيانات التواصل لشخص

> البحث العكسي عن شخص من بريد إلكتروني أو هاتف أو اسم أول/أخير + شركة — دون الحاجة إلى people_search_id. رصيد واحد لكل تطابق قابل للفوترة.

واجهة People Contact Lookup تجيب على السؤال **"لمن يعود هذا البريد الإلكتروني/الهاتف/الاسم؟"** أعطها معرّفًا، واحصل مقابله على `people_search_id` وملف الشخص المطابق — دون الحاجة إلى تشغيل بحث أولاً.

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/contact/lookup \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "king.lai@pubrio.com" }'
```

## متى تستخدم Contact Lookup

استخدم Contact Lookup عندما **يكون لديك معرّف وتريد إيجاد الشخص**:

* وصلت رسالة إلى بريدك الوارد — من المرسل؟ ما شركته؟ ما منصبه؟
* رن رقم هاتف على خط المبيعات — طابقه بجهة اتصال معروفة
* ملف CSV من العملاء المحتملين يحوي أسماء وشركات دون معرّفات Pubrio — حوّلها جميعًا إلى `people_search_id`
* نموذج تم إرساله يحوي `email + name` — أثرِه ليصبح سجل تواصل كاملًا

إن كان لديك بدلًا من ذلك `people_search_id` (أو رابط LinkedIn) وتريد **البريد الإلكتروني والهاتف الخاصين بذلك الشخص**، استخدم [استبدال الأشخاص](/ar/developer-guides/people-redeem) — فهو الاتجاه المعاكس.

## نوعان من الاستدعاء

| النقطة الطرفية                             | استخدمها عندما                                                           |
| ------------------------------------------ | ------------------------------------------------------------------------ |
| `POST /redeem/people/contact/lookup`       | بحث فردي — معرّف واحد لكل طلب.                                           |
| `POST /redeem/people/contact/lookup/batch` | بحث دفعي — حتى حد الدفعة المسموح به في اشتراكك لكل طلب، معالَج بالتوازي. |

كلتا النقطتين تُرجعان نفس بيانات `match` الوصفية لكل سجل (انظر [بيانات المطابقة الوصفية](#match-metadata) أدناه).

## بداية سريعة

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pubrio.com/redeem/people/contact/lookup \
    -H "pubrio-api-key: $PUBRIO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "email": "king.lai@pubrio.com" }'
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.pubrio.com/redeem/people/contact/lookup", {
    method: "POST",
    headers: {
      "pubrio-api-key": process.env.PUBRIO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "king.lai@pubrio.com" }),
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.pubrio.com/redeem/people/contact/lookup",
      headers={"pubrio-api-key": os.environ["PUBRIO_API_KEY"]},
      json={"email": "king.lai@pubrio.com"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**الاستجابة:**

```json theme={null}
{
  "data": {
    "profile": {
      "credit": 450375,
      "topup_credit": 235236,
      "total_credit_cost": 1
    },
    "peoples": [
      {
        "people_search_id": "e37ccf38-ea8f-422e-9874-cb23b15e8fe4",
        "first_name": "King",
        "last_name": "Lai",
        "people_name": "King Lai",
        "company_name": "Pubrio",
        "domain": "pubrio.com",
        "match": {
          "confidence": "exact",
          "input": { "value": "king.lai@pubrio.com", "type": "email-work" },
          "is_duplicate_input": false
        }
      }
    ]
  }
}
```

## أنماط المطابقة

يمكنك مطابقة شخص بطريقتين:

### مطابقة دقيقة — عبر البريد الإلكتروني أو الهاتف

هذا هو السلوك الافتراضي. مرّر `email` أو `phone`؛ يقوم Pubrio بالمطابقة على قيمة التواصل بعد تطبيعها. هذا يُرجع دائمًا `match.confidence: "exact"` عند التطابق.

```json theme={null}
{ "email": "king.lai@pubrio.com" }
```

```json theme={null}
{ "phone": "+15551234567" }
```

### مطابقة بالتشابه — عبر الاسم + النطاق أو الشركة

إن لم يكن لديك معرّف حاسم، يمكنك اللجوء إلى مطابقة التشابه. مرّر `first_name` و`last_name`، مع إما `domain` أو `company`، واضبط `is_enable_similarity_search: true`.

```json theme={null}
{
  "first_name": "King",
  "last_name": "Lai",
  "domain": "pubrio.com",
  "is_enable_similarity_search": true
}
```

يحاول Pubrio أولًا إيجاد تطابق دقيق للبريد الإلكتروني/الهاتف؛ فإن لم يوجد وكان التشابه مفعّلًا، يرتّب المرشحين حسب قرب الاسم ضمن نطاق الشركة (أو، عند عدم تمرير `domain`، حسب مطابقة اسم الشركة). المطابقات المُرجعة تحمل `match.confidence: "similarity_domain"` أو `"similarity_company"` بحيث يمكنك التصفية حسب درجة اليقين.

يمكنك الجمع بين الاثنين: مرّر بريدًا إلكترونيًا **و**اسمًا + نطاقًا معًا. تطابق البريد الإلكتروني الدقيق يفوز؛ وتصبح حقول الاسم احتياطية فقط إن لم يُحلَّ البريد الإلكتروني.

## بيانات المطابقة الوصفية

يتضمن كل سجل مُرجَع كائن `match` يصف كيفية حدوث المطابقة:

| الحقل                      | القيم                | المعنى                                                                                                        |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `match.confidence`         | `exact`              | تطابق مباشر للبريد الإلكتروني/الهاتف. أعلى درجة يقين.                                                         |
|                            | `similarity_domain`  | تطابق قائم على الاسم ومرتبط بنطاق شركة معروف.                                                                 |
|                            | `similarity_company` | تطابق قائم على الاسم ومرتبط باسم شركة (دون نطاق).                                                             |
| `match.input`              | `{ value, type }`    | يعرض المعرّف الذي أنتج المطابقة، بحيث يمكنك عرض "تمت المطابقة عبر `king.lai@pubrio.com`" في واجهتك.           |
| `match.is_duplicate_input` | boolean              | تكون `true` عندما يظهر نفس المعرّف سابقًا في الدفعة — يُنفَّذ البحث مرة واحدة فقط ولا يُفرَض رسم على التكرار. |

استخدم `match.confidence` للتحكم في الإجراءات اللاحقة: مثلًا، أضِف تلقائيًا إلى تسلسل تواصل فقط المطابقات `exact`؛ ووجّه مطابقات `similarity_*` إلى مراجعة يدوية.

## البحث الدفعي

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

```bash theme={null}
curl -X POST https://api.pubrio.com/redeem/people/contact/lookup/batch \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "peoples": [
      { "email": "king.lai@pubrio.com" },
      { "first_name": "John", "last_name": "Smith", "domain": "example.com" }
    ],
    "is_enable_similarity_search": true
  }'
```

الدفعة متزامنة — تحتوي الاستجابة على جميع السجلات التي تم حلّها بنفس ترتيب المدخلات. المدخلات غير المطابَقة تُحذف من الاستجابة (لا تظهر إطلاقًا ولا يُفرَض عليها رسم).

## تكلفة الرصيد

**رصيد واحد لكل تطابق قابل للفوترة.** وبالتحديد:

* تطابق ناجح (دقيق أو بالتشابه) ← رصيد واحد
* لا يوجد تطابق ← صفر رصيد
* مدخل مكرر ضمن الدفعة ← صفر رصيد (يُحل مرة واحدة، ويُفرَض رسم مرة واحدة)

هذا يجعل Contact Lookup أرخص بمقدار رتبة كاملة من [Redeem](/ar/developer-guides/people-redeem) — فأنت تدفع لقاء **التعرّف** على الشخص، لا لقاء **فتح** بيانات التواصل الخاصة به. إن احتجت بعد التعرّف إلى البريد الإلكتروني/الهاتف أيضًا، استخدم `people_search_id` المُرجَع لعملية redeem.

## أنماط شائعة

<CardGroup cols={2}>
  <Card title="إثراء البريد الوارد" icon="envelope-open">
    ابحث عن المرسل عند كل بريد وارد. اعرض شركته ومنصبه و`people_search_id` الخاص به في نظام CRM أو واجهة الدعم لديك.
  </Card>

  <Card title="تحويل CSV إلى CRM" icon="file-csv">
    حوّل ملف CSV بصفوف `الاسم + الشركة` إلى `people_search_id` قياسية. الصفوف التي لا تطابق مطابقة دقيقة تحصل تلقائيًا على محاولة مطابقة بالتشابه.
  </Card>

  <Card title="إثراء إرسال النماذج" icon="form">
    مرّر `{ email }` من نموذج التسويق لديك. احصل مقابله على الشركة والمنصب ومعرّف Pubrio يمكنك تمريره عبر قواعد التقييم.
  </Card>

  <Card title="مسار البحث ثم الاستبدال" icon="arrow-right-arrow-left">
    تدفق من خطوتين: بحث منخفض التكلفة (رصيد واحد) للتعرّف على الشخص، ثم استبدال كامل (5–10 أرصدة) فقط للمطابقات التي تتجاوز حد يقين معيّن.
  </Card>
</CardGroup>

## الأسئلة الشائعة

<AccordionGroup>
  <Accordion title="هل يُرجع Contact Lookup بريدًا إلكترونيًا وهاتفًا موثَّقين؟">
    لا — يُرجع Contact Lookup ملف الشخص (`people_search_id`، الاسم، الشركة، النطاق، المنصب، إلخ) بالإضافة إلى بيانات المطابقة الوصفية. للحصول على بيانات التواصل الموثَّقة نفسها، مرّر `people_search_id` المُرجَع إلى [Redeem](/ar/developer-guides/people-redeem).
  </Accordion>

  <Accordion title="ما الفرق بين similarity_domain و similarity_company؟">
    `similarity_domain` تعني أننا ربطنا تطابق الاسم بنطاق شركة معروف — وهو الأقوى بين مستويات التشابه. أما `similarity_company` فتعني أننا ربطناه باسم شركة دون نطاق قياسي — وهو أقل موثوقية بعض الشيء، إذ قد تشترك عدة شركات غير مرتبطة في نفس الاسم.
  </Accordion>

  <Accordion title="هل سيتم تحصيل رسوم على المدخلات غير المطابَقة؟">
    لا. تُحذف المدخلات غير المطابَقة بصمت من الاستجابة ولا تُفرَض عليها رسوم.
  </Accordion>

  <Accordion title="ماذا لو أرسلت نفس البريد الإلكتروني مرتين في دفعة واحدة؟">
    يُكتشف التكرار من جهة الخادم، ويُنفَّذ البحث مرة واحدة، ويُفرَض الرسم مرة واحدة. يُوسَم المدخل المكرر بـ `match.is_duplicate_input: true` في الاستجابة.
  </Accordion>

  <Accordion title="ما حد حجم الدفعة؟">
    يُحدَّد السقف في اشتراكك عبر `people_contact_enrichment_bulk_size`. تسمح معظم الخطط بـ 100+ لكل طلب؛ تواصل معنا إن احتجت سقفًا أعلى.
  </Accordion>

  <Accordion title="هل يمكنني البحث عبر رابط LinkedIn؟">
    ليس عبر Contact Lookup. استخدم [Redeem](/ar/developer-guides/people-redeem) مع `linkedin_url` إن كان لديك ملف LinkedIn وتريد الحصول على الحل وبيانات التواصل في استدعاء واحد.
  </Accordion>

  <Accordion title="ماذا يحدث مع أرقام الهواتف الدولية؟">
    يتم مطابقة الهاتف على شكل مطبَّع. الصيغة الدولية (E.164) هي الأكثر موثوقية كمدخل. قد تُطابَق الأرقام بالصيغة المحلية إن أمكن استنتاج الدولة، لكن E.164 (مثل `+15551234567`) يتجنب أي التباس.
  </Accordion>
</AccordionGroup>

## صفحات ذات صلة

<CardGroup cols={2}>
  <Card title="استبدال الأشخاص (Redeem)" icon="key" href="/ar/developer-guides/people-redeem">
    الاتجاه المعاكس: استهلك أرصدة لفتح البريد الإلكتروني والهاتف الخاصين بـ `people_search_id` أو رابط LinkedIn معروف.
  </Card>

  <Card title="People Search" icon="users" href="/ar/api-reference/endpoint/people/search">
    ابحث عن الأشخاص الذين يطابقون معايير تصفية للوظيفة/الشركة/الموقع.
  </Card>

  <Card title="People Lookup" icon="user" href="/ar/api-reference/endpoint/people/lookup">
    احصل على الملف الكامل لشخص واحد من معرّف معروف.
  </Card>

  <Card title="الأسعار" icon="coins" href="/ar/get-started/pricing">
    تكاليف الأرصدة عبر جميع النقاط الطرفية، حسب فئة الخطة.
  </Card>
</CardGroup>