> ## 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.

# المصادقة البيومترية للمستخدمين: البحث بالوجه وقائمة الحظر

> كيفية ربط Didit البيانات البيومترية للوجه بكيانات مستخدمي المورّد: البحث 1:N، واكتشاف التكرار، وفرض قائمة حظر الوجوه، والرفع اليدوي.



موجّه القياسات الحيوية للوجه
        نسخ الموجّه إلى الحافظة



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

\# 2. Upload a base64-encoded face to that profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Blocklisting after a decline

Declining a session adds the face to no blocklist: the User stays `ACTIVE` and no list entry is written, so a later session with the same face is decided by the workflow's own rules, not by a list match. To block a declined subject, upload the face to a face-type list yourself with the Lists API call above — a decline never does it for you.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

الصق في

تُعد القياسات الحيوية للوجه محورية في كل كيان مستخدم. يلتقط Didit الوجه أثناء [كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/overview.md)، ثم يولّد تضميناً متجهياً ويخزّنه لأربع ميزات لاحقة: **البحث بالوجه 1:N**، و**كشف التكرار**، و**فرض قائمة الحظر**، و**إعادة المصادقة البيومترية**.> [!NOTE]
>
> تُستخدم الوجوه المخزّنة مرجعاً لـ[المصادقة البيومترية](https://docs.didit.me/ar/core-technology/biometric-auth/overview.md): أنشئ جلسة مصادقة بيومترية باستخدام `vendor_data` الخاص بالمستخدم، واترك `portrait_image` دون تضمينها، وسيعيد Didit استخدام الوجه المخزّن تلقائياً (أولاً وجه كشف الحيوية المقبول، ثم صورة الشريحة في جواز السفر الإلكتروني، ثم صورة وثيقة الهوية، وأخيراً وجه ملف التعريف المسجّل يدوياً).## كيف ترتبط الوجوه بالمستخدم**1. يُلتقط أثناء كشف الحيوية**عندما يجتاز المستخدم جلسة مع تفعيل كشف الحيوية، يلتقط Didit صورة سيلفي، ويُجري كشف الحيوية السلبي، ويستخرج أكبر وجه، ويولّد تضميناً متجهياً للبحث.**2. يُخزَّن في ملف المستخدم**يُربط الوجه بالجلسة وبالكيان الأب للمستخدم. يظهر عنوان URL للصورة في ملف المستخدم بوصفه `portrait_image`.**3. يُفهرَس للبحث**يُضاف التضمين إلى فهرس البحث. ويمكن للجلسات اللاحقة تنفيذ عمليات بحث 1:N على هذا الفهرس.## البحث بالوجه (1:N)يتيح البحث بالوجه العثور على مستخدم عبر رفع صورة ومطابقتها مع كل وجه مسجّل في تطبيقك.حالات الاستخدام:- **كشف التكرار** عند التسجيل: منع الشخص نفسه من إنشاء حسابين.
- **البحث العكسي**: تحديد المستخدم الذي يظهر في إطار كاميرا مراقبة أو في صورة ضمن تحقيق احتيال.
- **التعرف على العميل المتكرر**: تخطي KYC للعميل العائد.يعمل البحث بالوجه تلقائياً أثناء الجلسات الجديدة عندما يفعّل سير العمل كشف التكرار. كما تُتاح واجهة برمجة تطبيقات مستقلة:- `POST /v3/face-search/` — [البحث المستقل بالوجه](https://docs.didit.me/ar/standalone-apis/face-search.md)## كشف التكراريمكن مقارنة كل وجه جديد بالوجوه المسجّلة الموجودة لرصد التكرارات. يعيّن Didit لكل وجه القيمة `approved_duplicate_status`:| الحالة | المعنى |
| - | - |
| `NOT_DUPLICATED` | لم يُعثر على تطابقات فوق حد التشابه |
| `DUPLICATED` | يطابق الوجه وجهاً واحداً أو أكثر في جلسة مقبولة سابقاً |يمكن ضبط سير العمل ليقوم بما يلي:- **رفض** الجلسات المُعلَّمة بالتكرار تلقائياً.
- **الإحالة للمراجعة**: توجيه الجلسة إلى محلل بشري.
- **التحذير فقط**: السماح بالجلسة مع إضافة وسم مخاطر.اضبط ذلك في الكونسول من *Workflows ← \[سير عملك] ← Face Match / Liveness ← Duplicate detection*.## قائمة حظر الوجوهرفض الجلسة لا يضيف الوجه إلى أي قائمة حظر. لرفض الجلسات المستقبلية بالوجه نفسه، أضفه إلى قائمة الحظر بنفسك: من [صفحة قائمة الحظر](https://docs.didit.me/ar/console/blocklist-users.md) أو عبر [Lists API](https://docs.didit.me/ar/management-api/lists/overview.md). فأي جلسة جديدة تطابق فيها صورة السيلفي الخاصة بكشف الحيوية ذلك الإدخال تُرفض تلقائياً.## رفع وجه مستورد إلى ملف مستخدمإذا كنت تنتقل من مزوّد KYC آخر، يمكنك إنشاء المستخدم أولاً ثم إرفاق صورة وجه موثوقة بملفه. يبقى المستخدم محدداً بواسطة `vendor_data` الخاص بك، لكن endpoint رفع الوجه يستخدم معرّف المستخدم الداخلي في Didit (`didit_internal_id`) لضمان تحديد الهدف بوضوح.**1. أنشئ المستخدم أو استرجعه**استدعِ [`POST /v3/users/create/`](https://docs.didit.me/ar/management-api/users/create) مع `vendor_data` الثابت لديك، أو استدعِ `GET /v3/users/{vendor_data}/` إذا كان المستخدم موجوداً مسبقاً.**2. اقرأ didit\_internal\_id**تتضمن استجابة المستخدم القيمة `didit_internal_id`. واصل استخدام `vendor_data` في نظامك، واستخدم `didit_internal_id` فقط مع endpoints إرفاق الملف الشخصي.**3. ارفع الوجه**استدعِ [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/ar/management-api/users/upload-face) مع صورة وجه مرمّزة بصيغة base64.```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```تُدرج وجوه ملفات التعريف المستوردة في فهرس الوجوه نفسه المستخدم في كشف التكرار والبحث بالوجه. ولا تُضاف تلقائياً إلى قائمة الحظر. لحظر شخص ضار معروف، ارفع الوجه إلى قائمة من نوع الوجه بدلاً من ذلك.> [!WARNING]
>
> ارفع فقط الوجوه التي يحق لك معالجتها بموجب إشعار الخصوصية واتفاقية الترحيل الخاصة بك. واحتفظ بمعرّفات مزوّد المصدر في `metadata` أو `comment` فقط عندما يكون كشفها آمناً لمسؤولي الامتثال لديك.### كيف يحدث الحظر| المُشغِّل | الإجراء |
| - | - |
| الجلسة `DECLINED` | لا يُضاف شيء إلى قائمة الحظر؛ ويبقى المستخدم `ACTIVE` |
| محلل يضيف وجهاً يدوياً إلى قائمة الحظر من الكونسول | يُضاف الوجه، وتُحدَّث حالة المستخدم وفق السياسة |
| إضافة برمجية عبر Lists API | ارفع صورة الوجه إلى قائمة حظر من نوع الوجه |### رفع وجه إلى قائمة الحظرلحظر مستخدم بالوجه برمجياً، ارفع صورة الوجه إلى قائمة حظر من نوع الوجه عبر endpoint [رفع الوجه إلى القائمة](https://docs.didit.me/ar/management-api/lists/upload-face.md) المخصص لذلك. يستخرج Didit التضمين البيومتري ويدرجه في فهرس المطابقة، فأي جلسة مستقبلية تطابق فيها صورة السيلفي ذلك الوجه تُرفض تلقائياً.> [!NOTE]
>
> رفع ملف الوجه الشخصي ورفع الوجه إلى قائمة الحظر عمليتان مختلفتان. استخدم رفع الملف الشخصي لإرفاق وجه مستورد موثوق بمستخدم، لأغراض الأدلة وكشف التكرار والبحث بالوجه. واستخدم [Lists API](https://docs.didit.me/ar/management-api/lists/overview.md) لحظر وجه، بحيث تُرفض الجلسات المطابقة المستقبلية.### إزالة وجه من قائمة الحظرأزل الإدخال من الكونسول عبر *Blocklist ← Faces ← إجراءات الصف ← Remove*، أو استخدم endpoint [حذف الإدخال](https://docs.didit.me/ar/management-api/lists/delete-entry.md).## القوالب البيومترية المحفوظة بعد حذف الجلسةيؤدي حذف الجلسة إلى حذف صورة الوجه، وبشكل افتراضي تضمين الوجه، فيخرج الشخص من اكتشاف التكرار ومن البحث بالوجه. إذا كنت تحذف الجلسات بعد وقت قصير من الموافقة عليها، لكنك ما زلت بحاجة إلى رصد عمليات التسجيل المتكررة، فقم بتفعيل [الاحتفاظ بالقوالب البيومترية](https://docs.didit.me/ar/console/data-retention.md#الاحتفاظ-بالقالب-البيومتري) في التطبيق، أو أرسل `retain_face_embeddings: true` مع طلب الحذف.تحذف Didit بعد ذلك الجلسة وجميع بياناتها كالمعتاد، وتحتفظ بقالب بيومتري واحد للوجه مُدار بشكل منفصل، لا يحتوي على الصورة، ومرتبط بالمستخدم:- يحتوي على القالب الرقمي للوجه والبيانات الوصفية للاحتفاظ فقط. لا يحتوي أبداً على صورة الوجه، أو فيديو الحيوية، أو بيانات المستند، أو حقول الهوية المستخرجة، أو القرار، أو معرّف الجلسة المحذوفة.
- يشارك في اكتشاف التكرار، والبحث بالوجه، والمصادقة البيومترية، وقوائم الوجوه لديك تماماً كوجه في جلسة نشطة. تُعرض النتائج بالقيمة `source: "retained_template"`، و`vendor_user_id` و`vendor_data` الخاصين بالمستخدم، وكذلك `biometric_template_id`.
- وهو بيانات بيومترية ذات `expires_at` محدد. يُحذف عند حذف المستخدم، أو عند حذف أي جلسة تابعة له باستخدام `deletion_instruction: "privacy_erasure"`، أو عند انتهاء صلاحيته، أو عند حذفه يدوياً من **Lists → القوالب البيومترية** أو عبر [Biometric Templates API](https://docs.didit.me/ar/management-api/biometric-templates/overview.md).
- الجلسة التي تُنشأ دون `vendor_data` لا يكون لها مستخدم يُربط به القالب؛ عند حذفها يُبلَّغ عن الحالة `ineligible_no_vendor_user` ويُحذف التضمين مع الجلسة.
- القوالب المحفوظة لا تُضاف إلى قائمة الحظر أبداً. أما إدخال في قائمة حظر الوجه الذي أُنشئ من الجلسة المحذوفة فيحتفظ ببيانات بيومترية مستقلة ودورة حياة مستقلة خاصة به.تظهر القوالب المرتبطة بمستخدم في صفحة المستخدم ضمن **القوالب البيومترية**، مع إجراء الحذف.## ملخص دورة حياة الوجه```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Enrolled --> Blocklisted: Face uploaded to a face-type list
    Declined --> [*]: Nothing blocklisted
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## رفع وجه من وحدة التحكميمكن لمشغلي الامتثال رفع الوجوه يدوياً:1) انتقل إلى *Users → \[user] → Actions → Upload face*.
2) اختر صورة؛ تستخرج Didit أكبر وجه فيها وتخزن سجل وجه جديداً مرتبطاً بالمستخدم.
3) يُسجَّل الوجه لأغراض أدلة الملف الشخصي، واكتشاف التكرار، والبحث بالوجه. استخدم منطقة قائمة الحظر عندما يكون الهدف رفض الجلسات المطابقة مستقبلاً.يكون هذا مفيداً عندما:- تملك صورة شخصية معروفة لعميل جرى التحقق منه عبر قناة غير متصلة بالإنترنت.
- تريد تعبئة قائمة الحظر مسبقاً بالمحتالين المعروفين من قاعدة بيانات الاحتيال لديك.## الخصوصية والاحتفاظ بالبيانات- تضمينات الوجه متجهات عددية وليست صوراً. تُخزَّن الصور نفسها في مساحة تخزين كائنات مشفرة، ويكون الوصول إليها عبر رابط موقّع. تضمين الوجه بيانات بيومترية.
- يتبع الاحتفاظ سياسة [الاحتفاظ بالبيانات](https://docs.didit.me/ar/console/data-retention.md) في تطبيقك. تتبع القوالب البيومترية المحفوظة مدة [الاحتفاظ بالقوالب البيومترية](https://docs.didit.me/ar/console/data-retention.md#الاحتفاظ-بالقالب-البيومتري) الأشد صرامة والمحددة بزمن.
- يؤدي حذف الجلسة إلى حذف الصورة، وبشكل افتراضي التضمين. إذا اشترك تطبيقك في الاحتفاظ بالقوالب البيومترية، فإن حذف الجلسة يُبقي قالباً بلا صورة حتى ينتهي صلاحيته أو يُحذف يدوياً.
- بالنسبة إلى طلب الحق في النسيان وفق GDPR أو CCPA، احذف جلسات الشخص باستخدام `deletion_instruction: "privacy_erasure"` أو احذف المستخدم نفسه: كلا الإجراءين يحذفان كل قالب محفوظ أيضاً. أما إدخالات قائمة حظر الوجوه التي تديرها فتبقى حتى تزيلها.## الخطوات التالية> [card] [البحث بالوجه](https://docs.didit.me/ar/core-technology/face-search/overview.md)
>
> كيف يعمل البحث بالوجه 1:N.> [card] [الحيوية](https://docs.didit.me/ar/core-technology/liveness/overview.md)
>
> كشف الحيوية الذي يلتقط الوجه.> [card] [واجهة برمجة تطبيقات قائمة الحظر](https://docs.didit.me/ar/management-api/lists/upload-face.md)
>
> رفع وجه إلى قائمة حظر.> [card] [القوالب البيومترية](https://docs.didit.me/ar/management-api/biometric-templates/overview.md)
>
> القوالب المحفوظة بعد حذف الجلسة.> [card] [قائمة حظر المستخدمين](https://docs.didit.me/ar/entities/users/blocklist.md)
>
> كيف يعمل حظر المستخدم.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.