> ## 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. # رفع الوجه إلى واجهة برمجة التطبيقات: القوائم البيومترية > ارفع صورة وجه بترميز base64 إلى قائمة حظر أو سماح للوجوه في Didit. يستخرج Didit القياس البيومتري ويستخدمه في مطابقة الوجه لاحقاً. موجّه API لرفع وجه إلى قائمة نسخ الموجّه إلى الحافظة \

\`Upload a face image directly to a Didit face blocklist or allowlist through the Management API.

Endpoint:
POST https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- Add a face to a face blocklist or allowlist when I do not have a verification session to reference. Didit detects the faces in the image, keeps the largest one, stores the image and a crop of that face, computes a biometric face template that new sessions are compared against, and creates the entry.
\- A face blocklist entry declines future sessions whose face matches. A face allowlist entry stops a matching face from triggering the duplicated-face action, but does not override blocklist matches or the other checks.

When NOT to use this:
\- If I am listing a face from an existing verification session, use POST /v3/lists/{list_uuid}/entries/ with reference_session_id instead, so the entry links back to the session.

Path parameter:
\- list_uuid: must be a list with entry_type "face" and list_type "blocklist" or "allowlist". Other lists return 400.

Request body (application/json):
\{
"image": "/9j/4AAQSkZ...",        // required: base64-encoded JPEG or PNG, at most 2 MB once decoded. Do not include a "data:image/..." prefix.
"comment": "Known fraud attempt"  // optional
}

Important constraints:
\- The image must show a clearly visible face. If no face is detected, the API returns 400 and no entry is created. If it shows several faces, Didit uses the largest one.
\- In a sandbox application the image is not analysed or stored: the entry has display_label "Sandbox face entry" and metadata.sandbox true, and matches nothing.

Example call:
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"image": "/9j/4AAQSkZ...", "comment": "Known fraud attempt"}'

Example response (201):
\{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"value": "44444444-5555-6666-7777-888888888888",
"display_label": "Manually uploaded face",
"comment": "Known fraud attempt",
"added_by": "api",
"reference_session_id": null,
"reference_session_number": null,
"reference_session_type": null,
"reference_object_uuid": "44444444-5555-6666-7777-888888888888",
"metadata": { "reference_image_url": "https:///face_reference_image.jpg" },
"created_at": "2026-10-12T10:12:18.904467Z"
}

value and reference_object_uuid are the UUID of the new face. metadata.reference_image_url is a short-lived signed URL (null for a scoped key without media: read).

Failure modes:
\- 400: the list is not a face list ({ "detail": "Face upload is only available for face-type lists." }), the list is a custom face list, image is missing, larger than 2 MB, not valid base64, not a readable JPEG or PNG, or shows no face ({ "image": "No face detected in the image. Please upload a clear photo with a visible face." }).
\- 401: the API key has expired.
\- 403: missing x-api-key (a wrong, revoked or expired key gets 401) ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows: write.
\- 404: list not found in this application ({ "detail": "List not found." }).
\- 503: face analysis is temporarily unavailable; no entry was created, retry later.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- The face template is added to biometric matching. Future sessions matching a blocklisted face are declined. Future sessions matching an allowlisted face skip the duplicated-face action and include an informational allowlist warning.

For the full integration shape, see /integration/integration-prompt.`

\
الصق في ارفع صورة وجه مُرمَّزة بصيغة base64 إلى قائمة حظر أو قائمة سماح للوجوه. يكتشف Didit الوجوه في الصورة، ويحتفظ بأكبرها، ويخزّن الصورة وقصاصة لذلك الوجه، ويحسب القالب البيومتري للوجه الذي تُقارن به الجلسات الجديدة. قيمة `value` للإدخال الجديد هي معرّف UUID لهذا الوجه.يتاح ذلك فقط للقوائم التي تحمل `entry_type: face` و`list_type: blocklist` أو `list_type: allowlist`.> [!TIP] > > إذا كنت تضع وجهًا في قائمة الحظر أو قائمة السماح **من جلسة موجودة**، فاستخدم [إنشاء إدخال](https://docs.didit.me/ar/management-api/lists/create-entry.md) مع `reference_session_id` بدلًا من ذلك: يبقى الإدخال مرتبطًا بالجلسة.> [!WARNING] > > يجب أن تحتوي الصورة على وجه واضح الظهور، ألا يتجاوز حجمها 2 ميغابايت بعد فك الترميز. إذا لم يُكتشف أي وجه، يُرجع الطلب الرمز `400` ولا يُنشأ أي إدخال. وإذا كان تحليل الوجه غير متاح مؤقتًا، يُرجع الطلب الرمز `503`: أعد المحاولة لاحقًا.لإزالة الوجه من القائمة، [احذف إدخاله](https://docs.didit.me/ar/management-api/lists/delete-entry.md): يتوقف عن المطابقة مع الجلسات الجديدة. ## OpenAPI ````yaml ar/openapi-25.json POST /v3/lists/{list_uuid}/entries/face-upload/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/lists/{list_uuid}/entries/face-upload/: post: tags: - Lists summary: رفع وجه إلى قائمة description: >- يضيف وجهاً إلى قائمة حظر الوجوه أو قائمة السماح بها من صورة JPEG أو PNG مرمزة بـ base64، وذلك عندما لا تتوفر جلسة تحقق للإشارة إليها. ترصد Didit الوجوه في الصورة، وتستخدم الوجه الأكبر، وتنشئ إدخالاً تكون قيمته `value` و`reference_object_uuid` هما معرّف UUID للوجه الجديد. يؤدي الوجه المدرج في قائمة الحظر إلى رفض الجلسات الجديدة التي يتطابق وجهها معه؛ بينما يتخطى الوجه المدرج في قائمة السماح إجراء الوجه المكرر ولا يتجاوز أبداً أي تطابق مع قائمة الحظر. في تطبيق البيئة التجريبية، لا يتم تحليل الصورة ولا يتطابق الإدخال مع أي شيء. يتطلب مفتاح API محدد النطاق صلاحية `workflows: write`. لإدراج وجه من جلسة موجودة، استخدم [إنشاء إدخال في قائمة](https://docs.didit.me/ar/management-api/lists/create-entry) مع `reference_session_id` بدلاً من ذلك. operationId: upload_list_entry_face parameters: - name: list_uuid in: path required: true description: >- معرّف UUID لقائمة ذات `entry_type: face` و`list_type: blocklist` أو `allowlist`. schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- صورة بصيغة JPEG أو PNG بترميز Base64، وبحجم أقصاه 2 ميغابايت بعد فك الترميز، تُظهر وجهاً واضحاً للعيان. أرسل سلسلة base64 المجردة، دون البادئة `data:image/...;base64,`. comment: type: string default: '' description: ملاحظة اختيارية بنص حر، مثل سبب الإدراج في القائمة. examples: Face image: value: image: /9j/4AAQSkZJRgABAQAAAQABAAD... comment: Known fraud attempt responses: '201': description: تم إنشاء إدخال الوجه. content: application/json: schema: $ref: '#/components/schemas/ComplianceListEntry' examples: Uploaded face: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Manually uploaded face comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: reference_image_url: >- https://media.example.com/faces/reference.jpg?expires=1760263938&signature=3f9a1c created_at: '2026-10-12T10:12:18.904467Z' Sandbox application: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Sandbox face entry comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: sandbox: true created_at: '2026-10-12T10:12:18.904467Z' '400': description: >- القائمة لا تقبل عمليات تحميل صور الوجه، أو أن الصورة مفقودة أو غير صالحة أو كبيرة جداً أو لا تُظهر وجهاً صالحاً للاستخدام. لم يتم إنشاء أي مدخل. content: application/json: examples: Not a face list: value: detail: Face upload is only available for face-type lists. Custom face list: value: detail: >- Face upload is only available for face blocklists and allowlists. Missing image: value: image: - This field is required. Invalid base64: value: image: - Invalid base64 encoding. Too large: value: image: - Image exceeds maximum size of 2 MB. Unreadable image: value: image: Invalid image. Provide a valid base64-encoded JPG or PNG. No face: value: image: >- No face detected in the image. Please upload a clear photo with a visible face. No usable face: value: image: Could not extract face embedding. Try a different image. '401': description: >- انتهت صلاحية مفتاح API محدد النطاق. تُرجع حالات فشل المصادقة الأخرى الرمز `403`. content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- رأس `x-api-key` مفقود (المفتاح الخاطئ أو الملغى أو منتهي الصلاحية يحصل على `401`)، أو أن مفتاح API محدد النطاق يفتقر إلى `workflows: write` أو تم استخدامه من عنوان IP خارج قائمة السماح الخاصة به. content: application/json: examples: Missing or invalid API key: value: detail: You do not have permission to perform this action. Scoped key without workflows access: value: detail: This API key has no write access to workflows. '404': description: >- لا توجد قائمة بهذا المعرّف UUID في التطبيق المرتبط بمفتاح API، أو قد تم حذفها. content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: >- تحليل الوجه غير متاح مؤقتًا. لم يتم إنشاء أي مدخل؛ يُرجى إعادة المحاولة لاحقًا. content: application/json: examples: Unavailable: value: detail: Service temporarily unavailable. Please try again later. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/face-upload/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d "{\"image\": \"$(base64 < face.jpg | tr -d '\n')\", \"comment\": \"Known fraud attempt\"}" - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image="/9j/4AAQSkZJRgABAQAAAQABAAD...", comment="Known fraud attempt", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.lists.entries.uploadFace("11111111-2222-3333-4444-555555555555", { image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n\tComment: didit.String(\"Known fraud attempt\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.ListsEntriesUploadFaceParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.lists().entries().uploadFace("11111111-2222-3333-4444-555555555555", ListsEntriesUploadFaceParams.builder() .image("/9j/4AAQSkZJRgABAQAAAQABAAD...") .comment("Known fraud attempt") .build()); System.out.println(result); - lang: php label: PHP source: >- lists->entries->uploadFace('11111111-2222-3333-4444-555555555555', [ 'image' => '/9j/4AAQSkZJRgABAQAAAQABAAD...', 'comment' => 'Known fraud attempt', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Lists.Entries.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesUploadFaceParams { Image = "/9j/4AAQSkZJRgABAQAAAQABAAD...", Comment = "Known fraud attempt", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: ComplianceListEntry: type: object description: قيمة واحدة في قائمة. required: - uuid - value - display_label - comment - added_by - reference_session_id - reference_session_number - reference_session_type - reference_object_uuid - metadata - created_at properties: uuid: type: string format: uuid description: معرّف المُدخل. استخدمه كـ `entry_uuid` في حذف مُدخل من قائمة. value: type: string description: >- القيمة المدرجة: رقم هاتف بصيغة E.164، أو عنوان بريد إلكتروني، أو رقم مستند، أو عنوان IP أو نطاق CIDR، أو بصمة جهاز، أو عنوان محفظة، أو حساب مصرفي، أو رمز دولة وفق معيار ISO 3166-1 alpha-3، أو `vendor_data`، أو أي سلسلة نصية في قائمة `key`، أو UUID للوجه المخزن في قائمة الوجوه. تُخزن القيم التي ترسلها بأحرف صغيرة، باستثناء أرقام الهواتف ورموز الدول. مطابقة النصوص غير حساسة لحالة الأحرف. display_label: type: string nullable: true maxLength: 512 description: >- تسمية سهلة القراءة. تملؤها Didit للإدخالات المأخوذة من جلسة (على سبيل المثال اسم حامل المستند ورقمه) إذا لم ترسل أياً منها. comment: type: string description: ملاحظة بنص حر. سلسلة فارغة عند عدم التعيين. added_by: type: string nullable: true description: >- من أضاف الإدخال: `api` (مفتاح API)، أو عنوان البريد الإلكتروني لمستخدم لوحة التحكم أو `console`، أو `system` أو `migration` (إدخالات أنشأتها Didit)، أو `rule` (إجراء قاعدة معاملات أو قاعدة مراقبة). reference_session_id: type: string format: uuid nullable: true description: >- جلسة التحقق التي تم أخذ الإدخال منها. `null` عندما تتم إضافة الإدخال حسب القيمة. reference_session_number: type: integer nullable: true description: رقم لتلك الجلسة بنطاق التطبيق، كما يظهر في وحدة التحكم. reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: >- `kyc` لجلسة التحقق من شخص، و`kyb` لجلسة التحقق من شركة، و`null` عندما لا توجد جلسة. reference_object_uuid: type: string format: uuid nullable: true description: >- السجل الذي يمثله الإدخال: سجل الوجه، أو المستند، أو الهاتف، أو البريد الإلكتروني المقروء من الجلسة، أو الوجه الذي تم إنشاؤه عبر تحميل وجه إلى قائمة، أو UUID الذي أرسلته (على سبيل المثال UUID لمعاملة أو `didit_internal_id` الخاص بالمستخدم). metadata: type: object nullable: true additionalProperties: true description: >- سياق إضافي. يحتوي على المفاتيح التي تعينها Didit (المدرجة هنا) مدمجة مع أي `metadata` أرسلتها عند إنشاء الإدخال، وتُعاد كما تم تخزينها. ويكون `null` عند عدم وجود أي منها. properties: reference_image_url: type: string description: >- مدخلات الوجه: عنوان URL قصير الأجل وموقّع، يُصدَر مجددًا مع كل استدعاء؛ ويكون `null` لمفتاح API ذي نطاق محدد بدون `media: read`. غير موجود عندما لا تنتمي أي صورة إلى المدخل. front_image_url: type: string description: >- مدخلات المستند التي تتضمن صورة أمامية للمستند: رابط URL موقّع قصير الأجل، يُصدر مجدداً عند كل استدعاء؛ `null` لمفتاح API ذي نطاق محدد دون صلاحية `media: read`. full_name: type: string description: 'مدخلات المستند المأخوذة من الجلسة: الاسم الكامل لحامل المستند.' issuing_state: type: string description: >- مدخلات المستند المأخوذة من الجلسة: دولة الإصدار بتنسيق ISO 3166-1 alpha-3. document_type: type: string description: >- مدخلات المستند المأخوذة من الجلسة: رمز نوع المستند، على سبيل المثال `P` أو `ID` أو `DL`. region: type: string description: >- مدخلات المستند المأخوذة من الجلسة: الولاية أو المقاطعة المصدرة لمستند صادر إقليمياً، وتكون فارغة عندما لا تنطبق. لا يتم ضبطها بواسطة إضافة عناصر الجلسة إلى قائمة الحظر. document_number: type: string description: 'مدخلات المستند المأخوذة من الجلسة: رقم المستند.' face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: >- مدخلات الوجه المأخوذة من صورة سيلفي ملتقطة مع المستند: أي صورة سيلفي. غير موجودة لوجوه كشف الحيوية. reference_node_id: type: string nullable: true description: >- مدخلات الوجه المأخوذة من صورة سيلفي ملتقطة مع المستند: عقدة التحقق من الهوية التي وردت منها صورة السيلفي. fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: >- مدخلات بصمة الجهاز المأخوذة من جلسة: كيفية استخلاص البصمة. يحدد `persistent_id` جهازاً واحداً؛ بينما يمكن مشاركة `composite_hash` و`legacy_fp` بين أجهزة من نفس الطراز. sandbox: type: boolean description: >- تكون القيمة `true` لمدخل وجه تم رفعه في تطبيق في البيئة التجريبية؛ ولا يطابق هذا المدخل أي شيء. reference_type: type: string enum: - transaction - vendor_user - vendor_business description: >- مُعيَّن بواسطتك: ما يشير إليه `reference_object_uuid`، لتربط لوحة التحكم به مجدداً. reference_id: type: string description: 'مُعيَّن بواسطتك: معرّف السجل المصدر.' created_at: type: string format: date-time description: وقت إضافة المُدخل. responses: RateLimitedWrite: description: >- تم تجاوز حد الكتابة المشترك البالغ 300 طلب في الدقيقة لكل مفتاح API. التزم بالمدة المحددة في `Retry-After` قبل إعادة المحاولة. content: application/json: schema: type: object required: - detail properties: detail: type: string example: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.