> ## 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. # البحث بالوجه 1:N: كشف التكرار عبر API > تتيح Didit البحث بالوجه بين المستخدمين الموثقين لكشف التكرار والمحتالين المحظورين مجاناً مع التحقق من الهوية، باستجابة في أقل من 2 ثانية. تُعد ميزة البحث بالوجه ميزة قوية تتيح لك البحث عن وجه محدد عبر جميع جلسات التحقق من الهوية المقبولة لديك. وتساعد هذه الإمكانية في تحديد الحسابات المكررة، ومنع الاحتيال، وتعزيز تدابير الأمان الخاصة بك. موجِّه تكامل البحث بالوجه نسخ الموجّه إلى الحافظة \

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\
الصق في يتناول درس Academy حول قراءة نتيجة التحقق ميزة البحث بالوجه وقوائم الحظر عند الدقيقة 6:53.[البحث بالوجه وقوائم الحظر — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![سير عمل البحث بالوجه 1:N من Didit المدمج مع كشف الحيوية لاكتشاف الحسابات المكررة والحسابات المدرجة في قائمة الحظر](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## التكامل التلقائي للبحث بالوجه> يُجرى البحث بالوجه تلقائياً أثناء عمليات كشف الحيوية في جلسات التحقق لاكتشاف المستخدمين المكررين والتحقق من الوجوه المدرجة في قائمة الحظر.### الاكتشاف التلقائي للتكرارعندما يكمل المستخدم كشف الحيوية أثناء التحقق من الهوية:- تُقارن بياناته البيومترية للوجه تلقائياً بجميع المستخدمين الذين تم التحقق منهم سابقاً - يحدد النظام الحسابات المكررة المحتملة بناءً على التشابه الوجهي - يتم وضع علامة على حالات التطابق وفقاً لحدود التشابه التي قمت بتهيئتها - يمكنك مراجعة المستخدمين المكررين المحتملين واتخاذ إجراء بشأنهم### التكامل مع قائمة الحظريتكامل البحث بالوجه بسلاسة مع [ميزة قائمة الحظر](https://docs.didit.me/ar/management-api/lists/overview.md):- أثناء التحقق، يتم فحص الوجوه تلقائياً مقابل قائمة الحظر الخاصة بك - إذا تم العثور على تطابق مع وجه مدرج في قائمة الحظر، يتم رفض التحقق تلقائياً - يمنع ذلك المستخدمين المثيرين للمشاكل الذين تم تحديدهم سابقاً من إنشاء حسابات جديدة - يساعد في الحفاظ على نزاهة عملية التحقق لديك### صورة السيلفي الملتقطة أثناء تصوير المستندأثناء قيام المستخدم بتصوير مستنده، تلتقط الكاميرا الأمامية صورة سيلفي له (Silent Capture). وفي كل مرة يتم فيها تقييم المستند، تخضع صورة السيلفي هذه لنفس بحث 1:N الذي تخضع له صورة سيلفي الحيوية:- تتم مقارنتها بقائمة حظر الوجوه لديك وبالمستخدمين المقبولين بالفعل في تطبيقك، مع نفس حدود التشابه ونفس الأسبقية مثل بحث كشف الحيوية. - يؤدي التطابق مع قائمة الحظر إلى إطلاق `FRONT_CAMERA_FACE_IN_BLOCKLIST` (دائماً Declined) أو `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (دائماً Review). كما يؤدي التطابق مع مستخدم مقبول إلى إطلاق `FRONT_CAMERA_DUPLICATED_FACE` أو `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`، بالإضافة إلى `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` عندما يكون ذلك المستخدم المقبول قد تم التحقق منه باسم مختلف، و`FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` عندما يُظهر مستند هوية ذلك المستخدم تاريخ ميلاد مختلفاً. راجع [تحذيرات التحقق من الهوية](https://docs.didit.me/ar/core-technology/id-verification/warnings-id-verification.md). - تُدرج حالات التطابق في تفاصيل الجلسة، في بطاقة التحقق من الهوية، وتُعاد في `id_verifications[].document_selfie_face_matches` ضمن [قرار الجلسة](https://docs.didit.me/ar/sessions-api/retrieve-session.md). وهي تستخدم نفس تنسيق الإدخال مثل `liveness_checks[].matches`. ويكون الحقل `null` للجلسات القديمة أو عندما لم يُجرَ البحث، ومصفوفة فارغة عندما يعمل ولا يجد أي تطابق. يُعد `match_image_url` رابط URL موقّع مسبقاً تنتهي صلاحيته. - يُستخدم فقط الوجه الأكبر في صورة السيلفي، وفقط عندما تكون أداة الكشف واثقة من أنه وجه. ويتم البحث في صورة سيلفي واحدة لكل مستند: صورة السيلفي الملتقطة للجهة الأمامية، أو صورة السيلفي الملتقطة للجهة الخلفية عندما لا تحتوي صورة السيلفي للجهة الأمامية على وجه واضح. - تتم مقارنة صورة السيلفي فقط. ولا يتم تخزين قالبها البيومتري أبداً، وبالتالي لا تُطابق الجلسات اللاحقة معها أبداً. لحظر شخص من صورة سيلفي لجلسة ما، أضفه إلى قائمة حظر الوجوه لديك من صفحة الجلسة.يتوفر للبحث مفتاح تبديل وإجراءات خاصة به في خطوة **التحقق من الهوية**، ضمن علامة تبويب **القواعد** الخاصة بالخطوة (**البحث بالوجه بالتقاط صامت**)، أو عبر `document_selfie_face_search_enabled` وإجراءات `document_selfie_duplicated_face_*` في [تكوين ميزات سير العمل](https://docs.didit.me/ar/management-api/workflows/feature-configs.md#ocr-/-التحقق-من-الهوية). يكون البحث مفعلاً افتراضياً؛ ويكون الإجراء الافتراضي للوجه المكرر هو Approve (مع استمرار الإبلاغ عن التحذير) وتكون عمليات الفحص المتبادل للاسم والمستند مضبوطة افتراضياً على Review، تماماً مثل نظيراتها في كشف الحيوية. يتطلب البحث توفر صورة السيلفي، لذا فهو يعمل فقط عند تفعيل Silent Capture. يؤدي إيقاف تشغيل البحث بالوجه في خطوة كشف الحيوية إلى إيقاف هذا البحث أيضاً: فهذا التعطيل يُعد خياراً متعلقاً بوجه الشخص، وبالتالي يغطي كل صورة سيلفي في الجلسة.### قاعدة عدم تطابق المستندتضع قاعدة **عدم تطابق المستند** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` لصورة سيلفي الحيوية، و`FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` لـ Silent Capture) علامة على الوجه المكرر فقط عندما يُظهر مستند هوية المستخدم المطابق تاريخ ميلاد مختلفاً. إذا قدم الشخص نفسه مستنداً مختلفاً، مثل جواز سفر بعد بطاقة هوية، فلن يتم وضع علامة عليه. كذلك لا يتم وضع علامة على المستند المجدد. لا يتم أبداً وضع علامة على جلستين تشتركان في نفس رقم المستند من نفس الدولة.### إيقاف تشغيل البحث بالوجه التلقائييكون البحث بالوجه التلقائي مفعلاً افتراضياً لكل خطوة من خطوات كشف الحيوية. إذا كانت سياسة الخصوصية لديك تتطلب ذلك، يمكنك إيقاف تشغيله لكل سير عمل من علامة تبويب **القواعد** في خطوة **كشف الحيوية** في Business Console (الوضع البسيط والمتقدم)، أو باستخدام `face_search_enabled: false` في عقدة `LIVENESS` أو `AGE_ESTIMATION` في [تكوين ميزات سير العمل](https://docs.didit.me/ar/management-api/workflows/feature-configs.md#كشف-الحيوية).عند إيقاف تشغيل المفتاح، تستمر صورة سيلفي الحيوية في الحصول على درجة الحيوية وتتم مقارنتها بنسبة 1:1 مع الصورة الشخصية في المستند في مطابقة الوجه، لكنها لا تصل أبداً إلى فهرس الوجوه:- لا يتم إجراء أي بحث، وبالتالي لا تحصل الجلسة على قرار بشأن التكرار أو قائمة الحظر أو قائمة السماح، ويبقى `liveness_checks[].matches` فارغاً. ولا تجد قواعد **وجه مكرر** و**عدم تطابق الاسم** و**عدم تطابق المستند** وقواعد الوجوه عبر المؤسسات أي معطيات للعمل عليها وتكون مخفية في لوحة التحكم. - لا يتم تخزين أي قالب بيومتري لصورة السيلفي، لذا لا يمكن مطابقة الجلسات اللاحقة مع هذه الجلسة، ولا يوجد شيء يمكن لـ [الاحتفاظ بالقالب البيومتري](https://docs.didit.me/ar/console/data-retention.md#الاحتفاظ-بالقالب-البيومتري) الإبقاء عليه بعد حذف الجلسة. - لا تُستخدم صورة السيلفي لتحديد شخص بيومتري مشترك لعمليات الفحص عبر المؤسسات. - لا يتم البحث أيضاً في صورة السيلفي الملتقطة أثناء التقاط المستند (لا توجد مخاطر قائمة حظر أو تكرار خاصة بـ `FRONT_CAMERA_*`): فالتعطيل يغطي كل صورة سيلفي في الجلسة. كما يمكن لمفتاح خطوة التحقق من الهوية نفسه (انظر أعلاه) إيقاف تشغيل هذا البحث بمفرده.**الخطوة التي ينتمي إليها المفتاح.** يوجد المفتاح في الخطوة التي تلتقط صورة السيلفي، لذا فإن خطوة **كشف الحيوية** أو **تقدير العمر** مسؤولة عن إعدادها الخاص. أما خطوة **مطابقة الوجه** فليس لها مفتاح خاص بها: عندما يعيد المستخدم التقاط صورة السيلفي هناك - بعد أن تطلب منه إعادة تنفيذ تلك الخطوة، على سبيل المثال - فإن إعادة الالتقاط تتبع إعداد خطوة كشف الحيوية، وبالتالي فإن التعطيل يُبقي صورة السيلفي الجديدة خارج الفهرس أيضاً. إذا تفرع سير العمل لديك إلى أكثر من خطوة لكشف الحيوية، فإن الإعداد المطبق هو الإعداد الموجود على الفرع الذي مرت به الجلسة بالفعل، ويتبع فحص الوجوه عبر المؤسسات هذه الخطوة نفسها.تحتفظ مسارات سير العمل الحالية بالسلوك الحالي حتى تختار إلغاء تفعيله. ينطبق التغيير على الجلسات التي تبدأ بعد حفظ سير العمل؛ وتبقى القوالب المخزنة بواسطة جلسات سابقة في الفهرس حتى يتم حذف تلك الجلسات أو إزالتها نهائياً. لا يؤثر هذا المفتاح على [Face Search API](https://docs.didit.me/ar/standalone-apis/face-search.md) المستقل، والذي تستدعيه بشكل صريح.> [!WARNING] > > يتم فرض قائمة حظر الوجوه الخاصة بك أثناء التحقق من خلال نفس البحث بنسبة 1:N. عند إيقاف تشغيل البحث بالوجه في خطوة كشف الحيوية، لن يتم رصد الشخص المدرج في قائمة الحظر في تلك الخطوة ولا من خلال صورة السيلفي الملتقطة أثناء التقاط المستند؛ ومع إيقاف تشغيل البحث بالوجه في الالتقاط الصامت في خطوة التحقق من الهوية، لا يتم رصده من خلال صورة السيلفي تلك.### الوصول عبر APIتتوفر وظائف البحث بالوجه أيضاً من خلال [API](https://docs.didit.me/ar/standalone-apis/face-search.md) الخاص بنا، مما يتيح لك:- إرسال عمليات البحث بالوجه برمجياً - دمج إمكانات مطابقة الوجه في تطبيقاتك الخاصة - بناء عمليات سير عمل مخصصة لاكتشاف الاحتيال - إنشاء أنظمة مؤتمتة لاكتشاف التكرار## الميزات الرئيسية- **دقة عالية**: توفر الخوارزميات البيومترية المتقدمة نتائج مطابقة موثوقة - **حدود قابلة للتكوين**: تخصيص حساسية التطابق بناءً على مدى تحملك للمخاطر - **مسح شامل**: البحث عبر جميع المستخدمين الذين تم التحقق منهم لديك - **نتائج سريعة**: معالجة عمليات البحث بسرعة حتى مع قواعد بيانات المستخدمين الضخمة - **التركيز على الخصوصية**: تستخدم المطابقة قوالب وجوه رقمية مقتصرة على تطبيقك؛ ولا يغادر الفهرس مساحة مؤسستك مطلقاً### حدود قابلة للتكوينيمكنك تخصيص حساسية البحث عن طريق تعيين حدود مختلفة لدرجات التشابه:> [!NOTE] > > يمكن تعديل هذه الحدود بناءً على مدى تحملك للمخاطر ومتطلبات الأمان الخاصة بك.## كيف يعمل**1. استخراج الوجه**عند بدء البحث، يقوم النظام بمعالجة الصورة المرجعية:| العملية | الوصف | | - | - | | **استخراج الميزات** | عزل ملامح الوجه من الصورة المرجعية | | **التسوية** | توحيد بيانات الوجه لإجراء مقارنة متسقة | | **التحقق من الجودة** | فحص جودة الصورة ووضوح الوجه | | **الترميز المتجهي** | إنشاء تمثيل متجهي رياضي للوجه |**2. خوارزمية المقارنة**يبحث النظام عبر كامل قاعدة بياناتك للجلسات التي تم التحقق منها:- مقارنة متجه الوجه المرجعي مع **كل وجه مسجل في تطبيقك**: وجوه الجلسات، والوجوه المحملة إلى ملفات تعريف المستخدمين، وقوائم الوجوه الخاصة بك، وأي قوالب بيومترية محتفظ بها - استخدام بنية شبكة عصبية متقدمة محسنة للسرعة والدقة - دعم وضعي بحث: **الأكثر تشابهاً** (قائمة مرتبة) و**المدرج في قائمة الحظر أو المقبول** (مصفى حسب الحالة) - معالجة قواعد البيانات الكبيرة بسرعة باستخدام الفهرسة المحسنة**3. احتساب درجة التشابه**لكل مقارنة، يتم إنشاء نسبة تشابه:| نطاق الدرجة | التفسير | | :-: | - | | **90%+** | تطابق قوي — على الأرجح هو نفس الشخص | | **70–89%** | تطابق محتمل — قد يتطلب مراجعة يدوية | | **أقل من 70%** | على الأرجح أفراد مختلفون |تحدد حدود التطابق التي قمت بتكوينها النتائج التي يتم تمييزها بعلامة تنبيه.**4. تسليم النتائج**يُرجع النظام مجموعة نتائج شاملة:- **قائمة مرتبة** من حالات التطابق المحتملة مصنفة حسب درجة التشابه - **تفاصيل التطابق** بما في ذلك معرّف الجلسة وتاريخ التحقق وبيانات المزود - **نسبة التشابه** لكل تطابق - **صور المطابقة** المتاحة للمراجعة البصرية - **حالة قائمة الحظر** لتوضيح ما إذا كان الوجه المطابق مدرجاً في قائمة الحظر## الجلسات المحذوفة والقوالب البيومترية المحتفظ بهايؤدي حذف الجلسة إلى حذف تضمين الوجه الخاص بها افتراضياً، وبالتالي يُزال الشخص من الفهرس ويمكنه التحقق مرة أخرى دون علامة تكرار. يمكن للتطبيقات التي تحذف الجلسات بعد وقت قصير من الموافقة ولكنها لا تزال بحاجة إلى اكتشاف عمليات التسجيل المتكررة تفعيل [الاحتفاظ بالقوالب البيومترية](https://docs.didit.me/ar/console/data-retention.md#الاحتفاظ-بالقالب-البيومتري). تحتفظ Didit بعد ذلك بقالب بيومتري واحد خالٍ من الصور مرتبط بالمستخدم بعد حذف الجلسة، ويشارك هذا القالب في البحث بالوجه والاكتشاف التلقائي للتكرار تماماً مثل وجه جلسة نشطة.يتم الإبلاغ عن أي تطابق مع قالب محتفظ به مع `source: "retained_template"`، بالإضافة إلى `vendor_user_id` و`vendor_data` الخاصين بالمستخدم المالك، و`biometric_template_id`. ولا يتضمن أي معرّف جلسة أو صورة المطابقة أو تفاصيل هوية أو حالة جلسة، لأن الجلسة التي أنتجت الوجه لم تعد موجودة. لا يتم إدراج القوالب المحتفظ بها في قائمة الحظر مطلقاً؛ وتحتفظ إدخالات قائمة حظر الوجوه بسجلها البيومتري المستقل الخاص بها.يبقى القالب حتى تاريخ انتهاء صلاحيته المجدول، أو حذف المستخدم، أو طلب محو البيانات لأسباب تتعلق بالخصوصية، أو إزالته نهائياً بشكل صريح عبر [Biometric Templates API](https://docs.didit.me/ar/management-api/biometric-templates/overview.md) أو **Lists → Biometric templates** في Console.## نسبة التشابهنسبة التشابه هي المقياس الأساسي المستخدم لتحديد التطابقات المحتملة:- **نسبة عالية (عادة 90% فما فوق)**: تشير إلى احتمالية قوية بأن الوجوه تعود لنفس الشخص. - **نسبة متوسطة (70-89%)**: تشير إلى تطابقات محتملة قد تتطلب مزيداً من المراجعة. - **نسبة منخفضة (أقل من 70%)**: تشير على الأرجح إلى أفراد مختلفين.يمكن تكوين الحد الدقيق لما يُعتبر "تطابقاً" بناءً على متطلبات الأمان الخاصة بك. يؤدي رفع الحد إلى تقليل الإيجابيات الكاذبة ولكنه قد يزيد من السلبيات الكاذبة.## حالات الاستخدام- **منع الاحتيال**: التعرف على المستخدمين الذين يحاولون إنشاء حسابات متعددة - **KYC معزز**: إضافة طبقة إضافية من التحقق إلى عملية KYC الخاصة بك - **الامتثال التنظيمي**: استيفاء متطلبات اكتشاف الحسابات المكررة - **التحكم في الوصول**: التحقق من أصالة المستخدم للمناطق عالية الأمان - **إنفاذ القانون**: مساعدة الجهات المصرح لها في التعرف على الأشخاص محل الاهتمام This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.