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

> عبر واجهة Didit البرمجية، أدر قوالب الوجه البيومترية المحفوظة دون صور بعد حذف الجلسة: اعرضها وعدّها وصفِّها وافحصها واحذفها.



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



      
      

\<pre>

\`Manage the biometric templates my Didit application retains after deleting verification sessions.

What a biometric template is:
When an application opts in (face_retention_policy: "retain_until_user_deleted", or retain_face_embeddings: true on a delete call), deleting a KYC session deletes the session and all of its data but keeps ONE image-free face biometric template anchored to the session's User. The template keeps duplicate-face, multi-account, biometric-authentication, and list matching working for that person. It contains the numeric face template plus retention metadata only — never the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id. It is biometric data: not anonymous, not transient, and not deleted with the session. It has a finite expires_at.

Endpoints (base https://verification.didit.me, header x-api-key: YOUR_API_KEY; API keys only — Console user tokens get 403):
\- GET  /v3/biometric-templates/            — paginated list (limit/offset). Filters: vendor_data (substring, case-insensitive), vendor_user_uuid, status, source_type, retained_from, retained_to (ISO 8601), ordering (retained_at | -retained_at | expires_at | -expires_at; default -retained_at). Purged templates are not listed.
\- GET  /v3/biometric-templates/count/      — {"count": n} with the same filters.
\- GET  /v3/biometric-templates/{uuid}/     — one template.
\- DELETE /v3/biometric-templates/{uuid}/   — purge one template. 200 {"uuid": "...", "outcome": "purged" | "already_purged"}.
\- POST /v3/biometric-templates/delete/     — bulk purge. Body: {"template_uuids": ["..."]} OR {"delete_all": true} plus optional filters (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to) that narrow delete_all. 200 {"results": [{"uuid": "...", "outcome": "purged" | "already_purged"}]}.

Template object:
\{
"uuid": "<template id>",
"vendor_user_uuid": "<User id>",
"vendor_data": "<the User's current vendor_data, resolved live>",
"source_type": "session_delete" | "automatic_retention" | "backfill",
"provenance_reference": "<opaque UUID, not the deleted session id>",
"retention_policy": "delete_with_session" | "retain_until_user_deleted",
"retention_override": true | false | null,
"retained_at": "<ISO 8601>",
"expires_at": "<ISO 8601>",
"retained_by": "<principal id: application UUID for API keys, Console member id, or service:...>",
"retained_by_type": "API_KEY" | "CONSOLE_USER" | "SYSTEM",
"instruction_class": "operational_session_delete" | "privacy_erasure",
"instruction_source": "api" | "console" | "automatic_retention" | "backfill" | "privacy_erasure" | "explicit_template_purge" | "vendor_user_delete" | "expiry" | "reconciliation" | "migration" | "system",
"instruction_id": "<your instruction_id or a Didit-generated one>",
"held_out_of_use": false,
"status": "pending" | "active" | "expired" | "held_out_of_use" | "purge_pending" | "purge_failed" | "purged",
"purged_at": null | "<ISO 8601>"
}
Only status "active" templates that are not held_out_of_use, not past expires_at, and whose User still exists take part in matching.

Purge points (all remove the template from matching and delete the stored template):
\- DELETE /v3/biometric-templates/{uuid}/ or POST /v3/biometric-templates/delete/
\- POST /v3/users/delete/ for the owning User
\- any session deletion for that User sent with deletion_instruction: "privacy_erasure"
\- automatic expiry at expires_at
Switching the application policy back to delete_with_session does NOT purge existing templates — purge them explicitly.

Failure modes:
\- 400 — {"template_uuids": ["This field is required unless delete_all is true."]} on bulk purge without a selector; invalid filter values.
\- 403 — {"detail": "You do not have permission to perform this action."} (Console user token, or key not allowed).
\- 404 — {"detail": "Biometric template not found."} on GET of an unknown or purged template.
\- 503 — {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} The template moves to status purge_failed and is already excluded from matching; repeat the purge.

Every retain and purge attempt, including failures, is recorded on Didit's audit trail with the acting principal, instruction class, instruction_source, instruction_id, and outcome.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

الصق في

افتراضياً، يؤدي حذف جلسة التحقق أيضاً إلى حذف تضمين الوجه الذي كان يُستخدم في [البحث بالوجه 1:N](https://docs.didit.me/ar/core-technology/face-search/overview.md) والكشف عن الوجوه المكررة لتلك الجلسة. ويمكن للتطبيقات التي تحتاج إلى استمرار الكشف عن الوجوه المكررة بعد حذف الجلسة أن تفعّل **الاحتفاظ بالقالب البيومتري**. عندها تحذف Didit الجلسة وجميع بياناتها كالمعتاد، ثم تحتفظ بقالب بيومتري للوجه منفصل يُدار بشكل مستقل، لا يحتوي على صور، ومرتبط بـ[المستخدم](https://docs.didit.me/ar/entities/users/overview.md) الخاص بالجلسة.تتيح لك واجهة برمجة تطبيقات القوالب البيومترية أن ترى بدقة القوالب التي يحتفظ بها تطبيقك، ولماذا، وحتى متى، وأن تحذفها نهائياً في أي وقت. ويظهر كل قالب أيضاً في Business Console ضمن **Lists → Biometric templates**، وفي الملف الشخصي للمستخدم المالك.> [!WARNING]
>
> القالب البيومتري المحتفَظ به بيانات بيومترية. فهو ليس مجهول الهوية، وليس مؤقتاً، ولا يُحذف مع الجلسة. يبقى حتى تنتهي صلاحيته المجدولة، أو يحين موعد نهائي أسبق يفرضه القانون المعمول به، أو يُحذف المستخدم، أو يُقدَّم طلب بمحو البيانات لأسباب تتعلق بالخصوصية، أو يُنفَّذ حذف نهائي صريح. فعّل الاحتفاظ فقط عندما تغطيه تعليمات المتحكم بالبيانات وإشعار الخصوصية لديك.## كيف يُنشأ القالب| المُشغِّل | `source_type` | مصدر التعليمات |
| - | - | - |
| تحذف جلسة في تطبيق مفعّل للاحتفاظ، أو ترسل `retain_face_embeddings: true` في [Delete Session](https://docs.didit.me/ar/sessions-api/delete-session.md) أو [Batch Delete Sessions](https://docs.didit.me/ar/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` أو `console` |
| تنتهي [فترة الاحتفاظ بالبيانات](https://docs.didit.me/ar/console/data-retention.md) العامة لتطبيقك فتنتهي معها جلسة في تطبيق مفعّل للاحتفاظ | `automatic_retention` | `instruction_source: automatic_retention` |
| عملية استكمال تُنفذها Didit بناءً على تعليماتك للجلسات التي حُذفت قبل أن تفعّل الاحتفاظ | `backfill` | `instruction_source: backfill` |يتطلب الاحتفاظ ربط الجلسة بمستخدم. فالجلسة التي تُنشأ دون `vendor_data` لا ترتبط بمستخدم، ولذلك لا يمكنها الاحتفاظ بقالب. وفي هذه الحالة يُبلغ الحذف عن `ineligible_no_vendor_user`، ويُحذف تضمين الوجه مع الجلسة.## ما الذي يحتويه القالب| يُحتفظ به | لا يُحتفظ به أبداً |
| - | - |
| القالب الرقمي للوجه المستخدم في المطابقة | صورة الوجه، وفيديو اختبار الحيوية، وصور المستندات، واقتطاعات الصور الشخصية، وأي وسائط أخرى |
| معرّف `uuid` جديد عشوائي للقالب، و`provenance_reference` مبهم | معرّف الجلسة المحذوفة أو رقمها أو قرارها أو حقول الهوية المستخلصة منها أو حمولات الميزات |
| المستخدم المالك (`vendor_user_uuid`)؛ ويُستخرج `vendor_data` من المستخدم عند قراءة القالب، ولا يُنسخ أبداً | حالة القائمة السوداء، والمطابقات السابقة، وتصنيفات الاحتيال، وادعاءات الهوية عبر المؤسسات |
| `retained_at` و`expires_at` و`retention_policy` و`retention_override` و`instruction_class` و`instruction_source` و`instruction_id` و`retained_by` و`retained_by_type` | عناوين البريد الإلكتروني للجهات الفاعلة |القوالب محصورة بالمستأجر، ولا تُستخدم إلا بناءً على تعليماتك داخل تطبيقك: للكشف عن الوجوه المكررة وكشف الحسابات المتعددة، و[المصادقة البيومترية](https://docs.didit.me/ar/core-technology/biometric-auth/overview.md)، ولقوائم الوجوه الخاصة بك. ولا تُستخدم أبداً لتدريب النماذج، أو للتحليلات، أو للمطابقة عبر المؤسسات، أو لإشارات [Networks](https://docs.didit.me/ar/console/networks.md) المشتركة، أو لمعالجة الاحتيال المستقلة التي تجريها Didit.## كائن القالب```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```| الحقل | النوع | الوصف |
| - | - | - |
| `uuid` | UUID | معرّف القالب. يُولَّد عشوائياً، ولا يُشتق من الجلسة المحذوفة أو من وجهها. |
| `vendor_user_uuid` | UUID | المستخدم المالك. |
| `vendor_data` | string أو null | القيمة الحالية لـ `vendor_data` الخاصة بالمستخدم، وتُستخرج عند قراءة القالب. |
| `source_type` | enum | `session_delete` أو `automatic_retention` أو `backfill`. |
| `provenance_reference` | UUID | مرجع مبهم يربط القالب بسجل التدقيق الخاص به. وهو ليس معرّف الجلسة المحذوفة، ولا يمكن تحويله إليه عبر الواجهة البرمجية. |
| `retention_policy` | enum | سياسة التطبيق وقت الاحتفاظ: `delete_with_session` أو `retain_until_user_deleted`. |
| `retention_override` | boolean أو null | قيمة `retain_face_embeddings` المرسلة مع الحذف، أو `null` عندما طُبّقت السياسة. |
| `retained_at` | datetime | وقت إنشاء القالب. |
| `expires_at` | datetime | وقت انتهاء صلاحية القالب وحذفه تلقائياً. وتكون هذه القيمة مضبوطة دائماً. |
| `retained_by` | string | الجهة التي أصدرت التعليمة: معرّف التطبيق لمفاتيح API، أو معرّف عضو Console لإجراءات Console، أو معرّف `service:` للاحتفاظ التلقائي. ولا يكون عنوان بريد إلكتروني أبداً. |
| `retained_by_type` | enum | `API_KEY` أو `CONSOLE_USER` أو `SYSTEM`. |
| `instruction_class` | enum | `operational_session_delete` أو `privacy_erasure`. |
| `instruction_source` | enum | `api` أو `console` أو `automatic_retention` أو `backfill` أو `privacy_erasure` أو `explicit_template_purge` أو `vendor_user_delete` أو `expiry` أو `reconciliation` أو `migration` أو `system`. |
| `instruction_id` | string | قيمة `instruction_id` التي أرسلتها مع الحذف، أو معرّف تولّده Didit عندما لا ترسله. |
| `held_out_of_use` | boolean | تكون `true` فقط أثناء سريان حجز قانوني. ويُستبعد القالب المحجوز من كل عمليات المطابقة. راجع [الحجز القانوني](#الحجوزات-القانونية). |
| `status` | enum | حالة دورة الحياة، انظر أدناه. |
| `purged_at` | datetime أو null | وقت الحذف النهائي للقالب. |### الحالة| `status` | المعنى | هل يدخل في المطابقة؟ |
| - | - | - |
| `pending` | القالب قيد الإنشاء. وإذا أعاد الحذف الذي أنشأه الاستجابة `503`، فكرر الحذف لإكماله. | لا |
| `active` | يشارك القالب في المطابقة حتى `expires_at`. | نعم، ما لم تكن `held_out_of_use` تساوي `true`، أو كان `expires_at` قد مضى |
| `expired` | مضى `expires_at`، والحذف التلقائي قيد التنفيذ. | لا |
| `held_out_of_use` | يسري حجز قانوني على القالب. | لا |
| `purge_pending` | الحذف النهائي قيد التنفيذ. | لا |
| `purge_failed` | تعذّر إتمام الحذف النهائي لأن أحد مخازن البيانات البيومترية غير متاح. كرر الحذف النهائي؛ ويظل القالب مستبعداً من المطابقة في الأثناء. | لا |
| `purged` | القالب محذوف. يظهر فقط في استجابة الحذف النهائي باسم `already_purged`، والقوالب المحذوفة نهائياً لا تظهر في القوائم، وتعيد `404` عند طلب التفاصيل. | لا |## كيف تُستخدم القوالب في المطابقةيشارك القالب `active` في المطابقة نفسها التي يشارك فيها وجه الجلسة المباشرة: الكشف التلقائي عن التكرار أثناء الجلسات الجديدة، و[واجهة برمجة التطبيقات للبحث بالوجه](https://docs.didit.me/ar/standalone-apis/face-search.md) المستقلة، و[المصادقة البيومترية](https://docs.didit.me/ar/core-technology/biometric-auth/overview.md)، وقوائم الوجوه لديك. يُبلَّغ عن التطابق مع قالب محفوظ بالقيمة `source: "retained_template"`، مع `vendor_user_id` و`vendor_data` الخاصين بالمستخدم المالك، و`biometric_template_id`. لا يتضمن هذا التطابق أبدًا معرّف جلسة، أو صورة مطابقة، أو تفاصيل هوية، أو حالة، لأن الجلسة التي أنتجت الوجه لم تعد موجودة. راجع [تقرير البحث بالوجه](https://docs.didit.me/ar/core-technology/face-search/report-face-search.md).لا يُضاف القالب المحفوظ إلى قائمة الحظر أبدًا. إذا كان وجه الجلسة المحذوفة موجودًا في قائمة حظر للوجوه، فإن إدخال القائمة يحتفظ بإدخال بيومتري مستقل خاص به ودورة حياة مستقلة. إزالة إدخال القائمة تحذف إدخال قائمة الحظر، وحذف القالب لا يمس القائمة.## نقاط الحذف النهائيتؤدي كل النقاط التالية إلى إزالة القالب من المطابقة وحذف القالب المخزَّن:| نقطة الحذف | الطريقة |
| - | - |
| الحذف الصريح | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/ar/management-api/biometric-templates/purge) أو [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/ar/management-api/biometric-templates/batch-purge)، أو **Lists → Biometric templates** في Console |
| حذف المستخدم | تحذف [`POST /v3/users/delete/`](https://docs.didit.me/ar/management-api/users/delete) كل قالب مرتبط بالمستخدم قبل حذف المستخدم |
| المحو لأغراض الخصوصية | أي حذف لجلسة تعود إلى ذلك المستخدم ويُرسَل مع `deletion_instruction: "privacy_erasure"` يحذف كل قالب مرتبط بالمستخدم، بغض النظر عن سياسة التطبيق |
| الانتهاء | يحذف Didit القالب تلقائيًا بمجرد مرور الوقت المحدد في `expires_at` |إعادة سياسة التطبيق إلى `delete_with_session` توقف إنشاء قوالب جديدة، لكنها **لا** تحذف القوالب الموجودة. احذفها صراحةً.تحذف عملية الحذف النهائي القالب المخزَّن أولًا، ثم تضع علامة على القالب بأنه حُذف نهائيًا. لذلك، إذا أعادت عملية الحذف النهائي الرمز `503`، يبقى القالب في الحالة `purge_failed`، ويكون مستبعدًا من المطابقة بالفعل، ويمكن تكرار العملية بأمان. ويعيد تكرار الحذف النهائي لقالب حُذف نهائيًا بالفعل الرمز `already_purged`.## سجل التدقيقيُسجَّل كل محاولة احتفاظ وكل محاولة حذف نهائي، بما فيها الإخفاقات والنتائج غير المؤهلة، مع الجهة الفاعلة (`retained_by` أو الجهة المنفذة للحذف ونوعها)، و`instruction_class`، و`instruction_source`، و`instruction_id`، و`provenance_reference`، والنتيجة. أرسل `instruction_id` الخاص بك في عمليات الحذف حتى تتمكن من مطابقة سجل التدقيق لدى Didit مع سجل المحو لديك. لا تتضمن إدخالات التدقيق أبدًا صورًا أو متجهات أو حقول هوية أو عناوين بريد إلكتروني.## الحجوزات القانونيةالحجز القانوني استثناء، وليس وضع احتفاظ. لا يفرض Didit حجوزات من تلقاء نفسه، ولا يمكن أن يترتب الحجز إلا على تعليمات موثقة بموجب اتفاقية معالجة البيانات الخاصة بك، أو على أمر ملزم صادر عن سلطة مختصة. طوال مدة سريان الحجز يُوسم القالب بالحالة `held_out_of_use`، فيُستبعد من كل أنواع المطابقة ومن الاسترجاع الروتيني، ولا يمكن البحث فيه أبدًا. لا توجد واجهة برمجية لإنشاء الحجوزات أو رفعها. تواصل مع ممثل Didit لديك إذا تلقيت أمرًا يؤثر في القوالب المحفوظة.## الأذونات والمصادقةتقبل endpoints الخاصة بالقوالب البيومترية مفاتيح API الخاصة بالتطبيق فقط (`x-api-key`). تُرفض رموز مستخدمي Business Console بالرمز `403`. يدير مستخدمو Console القوالب من خلال **Lists → Biometric templates** بالصلاحيات `lists` الخاصة بهم.## نقاط endpoint| Endpoint | الطريقة | الغرض |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/ar/management-api/biometric-templates/list) | GET | قائمة مقسّمة إلى صفحات مع عوامل التصفية |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/ar/management-api/biometric-templates/count) | GET | العدد بعوامل التصفية نفسها |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ar/management-api/biometric-templates/get) | GET | قالب واحد |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ar/management-api/biometric-templates/purge) | DELETE | حذف قالب واحد نهائيًا |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/ar/management-api/biometric-templates/batch-purge) | POST | الحذف النهائي بقائمة معرّفات أو بالتصفية |## ذو صلة- [حذف الجلسة](https://docs.didit.me/ar/sessions-api/delete-session.md)
- [حذف الجلسات دفعةً واحدة](https://docs.didit.me/ar/management-api/sessions/batch-delete.md)
- [الاحتفاظ بالبيانات](https://docs.didit.me/ar/console/data-retention.md#الاحتفاظ-بالقالب-البيومتري)
- [الوجوه والبيانات البيومترية](https://docs.didit.me/ar/entities/users/faces-and-biometrics.md)


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