> ## 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 دون إرسال رمز لمرة واحدة، عبر إشارات قابلية التسليم والنطاقات المؤقتة والتسريبات والاحتيال في استدعاء واحد.

استخدم `POST /v3/email/risk/` عندما تحتاج إلى معلومات استخبارية عن البريد الإلكتروني دون أن تطلب من المستخدم إدخال رمز لمرة واحدة.

لا يرسل هذا الطلب أي بريد إلكتروني. بل ينشئ جلسة API، ويثري العنوان، ويطبّق قواعد المخاطر الخاصة بالبريد الإلكتروني لديك، ثم يعيد الكتلة الموحّدة نفسها للبريد الإلكتروني التي يستخدمها التحقق من البريد الإلكتروني، وذلك في استجابة متزامنة واحدة.

عند حفظ الطلب، يمكن لـ Didit أيضاً استخدام البريد الإلكتروني المُقيَّم كدليل مجمّع في **الشبكات**. قد تعرض مخططات الشبكات معلومات استخبارية عالية المخاطر عن البريد الإلكتروني، وسياق التسريبات، وتغطية الملفات الشخصية على وسائل التواصل الاجتماعي للإشارات المشتركة الخاصة بالبريد الإلكتروني، لكنها لا تكشف عنوان البريد الإلكتروني الخام لمؤسسات أخرى.

## تفسير الاستجابة

* `status` هو القرار النهائي لجلسة API هذه. وعادةً ما تكون قيمته `Approved`، لكن تقييم المخاطر قد ينتج `In Review` أو `Declined`.
* `email.is_breached` و`email.is_disposable` و`email.is_undeliverable` إشارات ثابتة بنعم أو لا، تستخدمها في منطق التطبيق.
* `email.breaches` يسرد أحدث التسريبات المعروفة التي يرد فيها العنوان، عند توفر التغطية، مع تاريخ التسريب وفئات البيانات المكشوفة.
* `email.email_intelligence.score` يستخدم مقياساً للمخاطر من 0 إلى 100، حيث يعني الرقم الأعلى مخاطر أعلى. أما `breach_risk_level` (`Low` و`Medium` و`High`) و`no_of_breaches` فهما عرضان مشتقان.
* `email.email_intelligence.reason_codes` يوضح الإشارات المُوحّدة التي أسهمت في النتيجة. وقد تزداد هذه الرموز مع الوقت، لذلك لا ترفض الرموز غير المعروفة.
* `email.email_intelligence` و`email.enrichment` اسمان بديلان للتوافق يشيران إلى الكائن الموحّد نفسه. ويمكن للتكاملات الجديدة قراءة `email.enrichment`.
* `email.matches` يسرد جلسات أخرى في تطبيقك استُخدم فيها العنوان نفسه من مستخدم مختلف. استخدمه لاكتشاف الحسابات المكررة.
* `request_id` هو معرّف جلسة API. احفظه مع `vendor_data` إذا كنت تحتاج إلى ربط النتيجة بعمليات webhook لاحقة أو بنشاط لوحة التحكم.

> [!WARNING]
>
> `email.email_intelligence` و`email.enrichment` حقلان تُوفَّر بياناتهما على أساس أفضل جهد. قد يغيب كلاهما عند اكتمال الاستعلام، إذا لم تُرجَع بيانات استخبارية قابلة للاستخدام لذلك العنوان أو النطاق أو الخطة. ابنِ القواعد أولاً على `is_breached` و`is_disposable` و`is_undeliverable`، وتعامل مع غياب المعلومات الاستخبارية على أنه "غير معروف" وليس "آمن".

## الإضافة الخاصة بالبصمة الاجتماعية

اضبط `enable_social` على `true` لإضافة كتلة `email_social` إلى الاستجابة ضمن `email`. تتضمن هذه الكتلة المنصات الإلكترونية المسجّل عليها عنوان البريد الإلكتروني، مجمّعةً حسب الفئة، مع الإحصاءات الموجزة وأي تفاصيل للملفات الشخصية يعيدها شركاؤنا في البيانات.

* `email.email_social.profiles_registered` و`email.email_social.profiles_checked` هما الرقمان الرئيسيان: عدد المنصات التي أُكّد فيها تسجيل عنوان البريد الإلكتروني، من بين المنصات التي جرى تقييمها.
* `email.email_social.registered_platforms` و`email.email_social.not_registered_platforms` يسردان كل منصة مع `category` و`scope` (`global`، أو `local` للمنصات الخاصة بمنطقة معينة).
* `email.email_social.categories` يعرض عدد التسجيلات ونسبتها لكل فئة، و`email.email_social.profiles` يتضمن تفاصيل الملف الشخصي لكل منصة عندما تكشفها المنصة (الاسم، وعنوان الصورة، ونص النبذة، وحالة الخصوصية، وعلامة الحساب التجاري).
* المؤشرات الملخّصة (`digital_footprint_diversity` و`digital_sophistication_index` و`engagement_depth_index` و`subscription_affordability_index`) مركّبات من 0 إلى 10. وقد يكون أي عدد من الأعداد `null` إذا لم يُرجع الفحص بيانات لها.

القيمة `profiles_registered: 0` إجابة حقيقية، وليست فشلاً: فقد جرى فحص المنصات ولم يُعثر على عنوان البريد الإلكتروني في أي منها، وهذه إشارة شائعة إلى هوية مصطنعة. لا يتخذ هذا endpoint أي إجراء بشأنها بمفرده، لذلك استخدم `email_no_social_presence_action` في سير العمل لتحويلها إلى قرار مراجعة أو رفض.

تغيب الكتلة عندما لا يكون `enable_social` مضبوطاً، وكذلك عندما يتعذر إكمال فحص وسائل التواصل الاجتماعي، وفي هذه الحالة لا تُحتسب رسوم الفحص.

## سلوك البيئة التجريبية

تتحقق مفاتيح البيئة التجريبية من الطلب، وتعيد بيانات مقبولة ثابتة وقابلة للتكرار. ولا ترسل أي بريد إلكتروني، ولا تستهلك أرصدة، ولا تنشئ جلسة، ولا تسهم في الشبكات. وعند ضبط `enable_social`، تعيد هذه المفاتيح أيضاً كتلة `email_social` حتمية.

## الفوترة

تكلّف استدعاءات Email Risk API مبلغ \$0.04 بالسعر المعلن، وهو أقل مما ستكلفه عملية التحقق الكاملة من البريد الإلكتروني، لأنه لا يُرسل أي بريد إلكتروني. يصبح الطلب الفعلي قابلاً للفوترة بمجرد بدء الاستعلام، حتى إذا لم تتوفر بعض الحقول بأفضل جهد.

تُفوتر إضافة البصمة الاجتماعية بشكل منفصل: وحدة `email_social` واحدة لكل طلب، تُضاف إلى سعر Email Risk API، متى اكتمل الفحص. ويغطي فحص الرصيد الذي يسبق الاستعلام الأمرين معاً.


## OpenAPI

````yaml ar/openapi-25.json POST /v3/email/risk/
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/email/risk/:
    post:
      tags:
        - Standalone APIs
      summary: احتساب درجة المخاطر لعنوان بريد إلكتروني
      description: >-
        إرجاع إشارات قابلية التسليم، والعناوين المؤقتة، والتسريبات، والتطابق عبر
        الجلسات، وإشارات معلومات المخاطر الموحدة دون إرسال OTP. ينشئ هذا الـ
        endpoint جلسة API ويعيد معرفها كـ `request_id`.


        **القرار.** تعكس القيمة `status` على المستوى الأعلى القيمة
        `email.status`. وتكون عادة `Approved`؛ ويمكن أن يؤدي تقييم المخاطر إلى
        `In Review` أو `Declined`.


        **الأسماء البديلة للتوافق.** تعرض الاستجابات في بيئة الإنتاج كائن
        المعلومات الموحد باسم `email.email_intelligence` و`email.enrichment`.
        وتكون القيم متطابقة. يمكن للتكاملات الجديدة قراءة `email.enrichment`.
        ويغيب كلا المفتاحين عند عدم إرجاع أي بيانات معلومات قابلة للاستخدام.


        **الفوترة.** تستخدم الاستدعاءات في بيئة الإنتاج أسعار Email Risk API.
        ويكون الطلب خاضعاً للفوترة بمجرد بدء عملية البحث، حتى لو كانت بعض الحقول
        التي تعتمد على بذل أقصى جهد غير متوفرة.


        **البيئة التجريبية.** تتحقق مفاتيح البيئة التجريبية من صحة الطلب وتعيد
        بيانات مقبولة محددة مسبقاً دون إرسال بريد إلكتروني، أو استهلاك أرصدة، أو
        إنشاء جلسة، أو المساهمة في Networks.


        **المصادقة.** أرسل مفتاح API الخاص بتطبيقك في `x-api-key`. تُرجع بيانات
        الاعتماد المفقودة أو غير الصالحة `403` - لا تُرجع هذه الـ API أبداً
        `401`.


        **حد المعدل.** ميزانية كتابة مشتركة تبلغ 300 طلب في الدقيقة لكل مفتاح
        API عبر جميع endpoints الخاصة بـ POST/PATCH/DELETE (تمتلك عمليات إنشاء
        المعاملات واستيعاب الأحداث ميزانية منفصلة تبلغ 600).


        **البصمة الاجتماعية.** اضبط `enable_social` على `true` لإضافة كتلة
        `email_social`: المنصات عبر الإنترنت التي تم تسجيل هذا العنوان فيها، مع
        أعداد لكل فئة وأي تفاصيل ملف شخصي متوفرة. تعني `profiles_registered: 0`
        أنه تم فحص المنصات ولم يتم العثور على العنوان في أي منها - وهي إجابة
        صالحة وخاضعة للفوترة. تغيب هذه الكتلة عند عدم طلب هذه الميزة الإضافية أو
        تعذر إكمال الفحص، ولا تتم فوترتها في تلك الحالة. تضيف الفوترة وحدة
        `email_social` واحدة لكل طلب بالإضافة إلى سعر هذا الـ endpoint نفسه.
      operationId: post_v3email_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRiskRequest'
            examples:
              Minimal:
                summary: احتساب درجة لعنوان بالقيم الافتراضية
                value:
                  email: alice@example.com
              Full context:
                summary: احتساب الدرجة مع الإشارات وتلميح الدولة ومعرّفات الارتباط
                value:
                  email: alice@example.com
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: web
                    os_version: '14.4'
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4
                      Safari/605.1.15
                  vendor_data: lead-123
                  metadata:
                    source: signup_prescreen
      responses:
        '200':
          description: >-
            اكتمل تقييم المخاطر. افحص `status` لمعرفة القرار؛ رمز HTTP دائماً ما
            يكون `200` لعمليات البحث المكتملة.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRiskResponse'
              examples:
                Clean address:
                  summary: عنوان قابل للتسليم دون تعرض لأي اختراق
                  value:
                    request_id: 82397be9-5921-4970-a979-2d5b43e08b33
                    status: Approved
                    email:
                      status: Approved
                      email: alice@example.com
                      is_breached: false
                      breaches: []
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      email_intelligence:
                        score: 4
                        deliverable: high
                        breach_risk_level: Low
                        breach_risk_index: 4
                        is_recent_breach: false
                        is_frequent_breached: false
                        is_disposable: false
                        is_free_domain: false
                        is_breached: false
                        no_of_breaches: 0
                        reason_codes: []
                      enrichment:
                        score: 4
                        deliverable: high
                        breach_risk_level: Low
                        breach_risk_index: 4
                        is_recent_breach: false
                        is_frequent_breached: false
                        is_disposable: false
                        is_free_domain: false
                        is_breached: false
                        no_of_breaches: 0
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Breached address:
                  summary: العنوان موجود في اختراقات معروفة
                  value:
                    request_id: d1e5c2a8-6f30-4c1a-8b2d-3e4f5a6b7c8d
                    status: In Review
                    email:
                      status: In Review
                      email: bob@example.org
                      is_breached: true
                      breaches:
                        - name: ExampleBreach2023
                          domain: example.org
                          breach_date: '2023-06-01'
                          breach_emails_count: 1200000
                          description: A data breach affecting example.org accounts.
                          logo_path: https://logos.example.org/example.png
                          data_classes:
                            - email_addresses
                            - passwords
                          is_verified: true
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      email_intelligence:
                        score: 58
                        deliverable: high
                        breach_risk_level: High
                        breach_risk_index: 72
                        is_recent_breach: true
                        is_frequent_breached: true
                        is_disposable: false
                        is_free_domain: true
                        is_breached: true
                        no_of_breaches: 4
                        reason_codes:
                          - code: IR-F784B630
                            direction: risk
                            message: Email's digital footprint diversity is Very Low
                            impact_level: low
                      enrichment:
                        score: 58
                        deliverable: high
                        breach_risk_level: High
                        breach_risk_index: 72
                        is_recent_breach: true
                        is_frequent_breached: true
                        is_disposable: false
                        is_free_domain: true
                        is_breached: true
                        no_of_breaches: 4
                        reason_codes:
                          - code: IR-F784B630
                            direction: risk
                            message: Email's digital footprint diversity is Very Low
                            impact_level: low
                    vendor_data: lead-125
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/EmailRiskValidationError'
        '403':
          $ref: '#/components/responses/RiskPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/email/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "email": "alice@example.com",
                "country_code": "US",
                "vendor_data": "lead-123",
                "metadata": {"source": "signup_prescreen"}
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.email.assess_risk(
                email="alice@example.com",
            )
            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.email.assessRisk({
              email: "alice@example.com",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{\n\tEmail: \"alice@example.com\",\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.EmailRiskRequest;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.email().assessRisk(EmailRiskRequest.builder()
                    .email("alice@example.com")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->email->assessRisk([
                'email' => 'alice@example.com',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.email.assess_risk(email: "alice@example.com")
            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.Email.AssessRiskAsync(new EmailRiskRequest
            {
                Email = "alice@example.com",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    EmailRiskRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: عنوان البريد الإلكتروني المراد احتساب درجة له.
          example: alice@example.com
        country_code:
          type: string
          maxLength: 3
          description: >-
            تلميح دولة اختياري وفق معيار ISO 3166-1 alpha-2 أو alpha-3 لتغطية
            البيانات الاستخباراتية.
          example: US
        signals:
          $ref: '#/components/schemas/RiskSignals'
        vendor_data:
          type: string
          description: >-
            مرجعك الثابت لهذا الطلب. يتم تخزينه في جلسة API وإعادته في
            الاستجابة.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            البيانات الوصفية بتنسيق JSON غير الحساسة الخاصة بك. يتم تخزينها في
            جلسة API وإعادتها في الاستجابة.
        enable_social:
          type: boolean
          default: false
          description: >-
            عند التعيين على true، يتم أيضاً البحث عن الأثر الرقمي الاجتماعي
            للعنوان - منصات البريد الإلكتروني والمنصات الاجتماعية والمهنية
            والتجارة الإلكترونية والترفيه المسجل عليها. يُفوتر كوحدة
            `email_social` واحدة لكل طلب بالإضافة إلى سعر هذا الـ endpoint نفسه.
          example: true
    EmailRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            معرّف جلسة API التي تم إنشاؤها لهذا الطلب. احفظه مع `vendor_data`
            إذا كنت بحاجة إلى ربط النتيجة بـ webhooks اللاحقة أو نشاط لوحة
            التحكم.
        status:
          type: string
          enum:
            - Approved
            - In Review
            - Declined
          description: >-
            القرار النهائي لجلسة API هذه. عادةً ما يكون `Approved`؛ يمكن أن ينتج
            عن تقييم المخاطر `In Review` أو `Declined`.
        vendor_data:
          type: string
          nullable: true
          description: >-
            نسخة مطابقة من `vendor_data` التي أرسلتها، وتكون `null` عند عدم
            إرسال أي منها.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            نسخة مطابقة من `metadata` التي أرسلتها، وتكون `null` عند عدم إرسال
            أي منها.
        created_at:
          type: string
          format: date-time
          description: الطابع الزمني لهذه الاستجابة.
        email:
          type: object
          description: >-
            تقرير البريد الإلكتروني المعياري، وهو نفس الكتلة المستخدمة في
            استجابات التحقق من البريد الإلكتروني.
          required:
            - status
            - email
            - is_breached
            - breaches
            - is_disposable
            - is_undeliverable
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: >-
                القرار لعنوان البريد الإلكتروني هذا. يعكس قيمة `status` في
                المستوى الأعلى.
            email:
              type: string
              description: العنوان الذي تم احتساب درجاته.
              example: alice@example.com
            is_breached:
              type: boolean
              description: ما إذا كان العنوان يظهر في اختراق معروف لبيانات الاعتماد.
            breaches:
              type: array
              description: >-
                ما يصل إلى أحدث 5 اختراقات معروفة تتضمن هذا العنوان. مصفوفة
                فارغة عندما تكون قيمة `is_breached` هي `false`.
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: معرّف الاختراق.
                  domain:
                    type: string
                    description: نطاق الخدمة المخترقة.
                  breach_date:
                    type: string
                    format: date
                    description: تاريخ حدوث الانتهاك.
                  breach_emails_count:
                    type: integer
                    description: العدد الإجمالي للحسابات التي كُشفت في الاختراق.
                  description:
                    type: string
                    description: وصف سهل القراءة للخرق (قد يحتوي على ترميز HTML).
                  logo_path:
                    type: string
                    description: رابط URL لشعار الخدمة المخترقة.
                  data_classes:
                    type: array
                    items:
                      type: string
                    description: >-
                      فئات البيانات المكشوفة، بتنسيق snake_case (مثل
                      `email_addresses` و`passwords`).
                  is_verified:
                    type: boolean
                    description: ما إذا كان قد تم التحقق من صحة الاختراق.
            is_disposable:
              type: boolean
              description: ما إذا كان النطاق ينتمي إلى مزود مؤقت.
            is_undeliverable:
              type: boolean
              description: ما إذا تبيّن تعذّر تسليم العنوان.
            verification_attempts:
              type: integer
              description: >-
                عمليات إرسال رمز لمرة واحدة لهذا العنوان. `0` لعمليات البحث عن
                المخاطر.
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                وقت آخر تحقق من العنوان عبر رمز لمرة واحدة (OTP). تكون القيمة
                `null` لعمليات البحث عن المخاطر.
            warnings:
              type: array
              description: >-
                تحذيرات المخاطر المسجلة لهذا الطلب. مصفوفة فارغة في حال عدم وجود
                أي منها.
              items:
                $ref: '#/components/schemas/RiskWarning'
            lifecycle:
              type: array
              description: >-
                سجل تدقيق زمني للطلب. مصفوفة فارغة لعمليات البحث عن المخاطر دون
                عمليات إرسال.
              items:
                $ref: '#/components/schemas/RiskLifecycleEvent'
            matches:
              type: array
              description: >-
                جلسات أخرى لتطبيقك حيث تم استخدام عنوان البريد الإلكتروني نفسه
                بواسطة مستخدم مختلف (`vendor_data` مختلفة). حتى 5 مدخلات. مصفوفة
                فارغة عند عدم وجود أي تطابقات.
              items:
                $ref: '#/components/schemas/EmailMatchItem'
            email_intelligence:
              $ref: '#/components/schemas/EmailIntelligence'
            enrichment:
              $ref: '#/components/schemas/EmailIntelligence'
            email_social:
              $ref: '#/components/schemas/EmailSocialFootprint'
    RiskSignals:
      type: object
      description: >-
        سياق اختياري للجهاز والشبكة يرصده تطبيقك. جميع الحقول اختيارية. يغذي
        تمريرها ميزة كشف التطابق عبر الجلسات في Networks.
      properties:
        ip:
          type: string
          format: ip
          description: عنوان IPv4 أو IPv6 الذي تم رصده للمستخدم النهائي.
          example: 192.0.2.1
        device_id:
          type: string
          maxLength: 255
          description: >-
            معرّف جهاز ثابت يجمعه تطبيقك (Android `ANDROID_ID`، وiOS
            `identifierForVendor`).
        device_platform:
          type: string
          enum:
            - android
            - ios
            - ipados
            - tvos
            - web
          description: منصة جهاز المستخدم النهائي.
        device_model:
          type: string
          maxLength: 255
          description: طراز الجهاز الذي أبلغ عنه تطبيقك.
        os_version:
          type: string
          maxLength: 64
          description: إصدار نظام التشغيل.
        app_version:
          type: string
          maxLength: 64
          description: إصدار تطبيقك.
        user_agent:
          type: string
          maxLength: 512
          description: وكيل المستخدم (user agent) للمتصفح أو التطبيق.
    RiskWarning:
      type: object
      required:
        - feature
        - risk
        - log_type
        - short_description
        - long_description
      properties:
        feature:
          type: string
          description: الميزة التي أطلقت التحذير.
        risk:
          type: string
          description: رمز مخاطر مقروء آلياً. يمكن إضافة قيم جديدة بمرور الوقت.
        additional_data:
          type: object
          nullable: true
          additionalProperties: true
          description: السياق الخاص بالمخاطر، أو `null`.
        log_type:
          type: string
          enum:
            - error
            - warning
            - information
          description: مستوى الخطورة المستخدم في قواعد اتخاذ القرار.
        short_description:
          type: string
          description: ملخص في سطر واحد مقروء للبشر.
        long_description:
          type: string
          description: تفسير سهل القراءة.
    RiskLifecycleEvent:
      type: object
      required:
        - type
        - timestamp
        - details
        - fee
      properties:
        type:
          type: string
          description: نوع الحدث المقروء آلياً. يمكن إضافة قيم جديدة بمرور الوقت.
        timestamp:
          type: string
          format: date-time
          description: وقت وقوع الحدث.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: الـ payload الخاص بالحدث، أو `null`.
        fee:
          type: number
          description: المبلغ بالدولار الأمريكي المفوتر لهذا الحدث.
    EmailMatchItem:
      type: object
      description: >-
        جلسة أخرى لتطبيقك استخدمت نفس عنوان البريد الإلكتروني مع `vendor_data`
        مختلف.
      properties:
        session_id:
          type: string
          format: uuid
          description: >-
            معرّف الجلسة لعملية التحقق الأخرى التي استخدمت عنوان البريد
            الإلكتروني هذا.
        session_number:
          type: integer
          description: رقم تسلسلي سهل القراءة لتلك الجلسة.
        vendor_data:
          type: string
          nullable: true
          description: '`vendor_data` لتلك الجلسة.'
        verification_date:
          type: string
          description: وقت إنشاء تلك الجلسة (`YYYY-MM-DDTHH:MM:SSZ`).
        email:
          type: string
          description: عنوان البريد الإلكتروني المتطابق.
        status:
          type: string
          description: حالة تلك الجلسة (مثل `Approved`، `Declined`، `In Progress`).
        is_blocklisted:
          type: boolean
          description: >-
            ما إذا كان عنوان البريد الإلكتروني موجوداً في قائمة الحظر الخاصة
            بتطبيقك.
        api_service:
          type: string
          nullable: true
          description: >-
            بالنسبة للجلسات من نوع API، واجهة API المستقلة التي أنشأتها؛ و
            `null` لجلسات التحقق العادية.
        source:
          type: string
          description: >-
            مكان العثور على التطابق. عادةً ما يكون `session`؛ ويستخدم التطابق مع
            قائمة الحظر عبر إدخال في قائمة تابعة للمؤسسة القيمة `list_entry`.
    EmailIntelligence:
      type: object
      description: >-
        كتلة معلومات البريد الإلكتروني المعيارية. تظهر فقط عند تشغيل الوظيفة
        الإضافية للمعلومات لهذا البريد الإلكتروني؛ وعند ظهورها يتم عرضها أيضاً
        بالاسم المستعار `enrichment` بنفس القيم.
      properties:
        score:
          type: number
          nullable: true
          description: درجة مخاطر معيارية من 0 إلى 100. تشير القيمة الأعلى إلى مخاطر أكبر.
        deliverable:
          type: string
          nullable: true
          description: نطاق قابلية التسليم (مثل `high`).
        breach_risk_level:
          type: string
          nullable: true
          description: '`Low` أو `Medium` أو `High`.'
        breach_risk_index:
          type: number
          nullable: true
          description: مؤشر رقمي لمخاطر الاختراق.
        is_recent_breach:
          type: boolean
          nullable: true
          description: تكون القيمة `true` عندما يظهر العنوان في اختراق أمني حديث.
        is_frequent_breached:
          type: boolean
          nullable: true
          description: >-
            تكون القيمة `true` عندما يظهر العنوان في العديد من الاختراقات
            الأمنية.
        is_disposable:
          type: boolean
          nullable: true
          description: تكون `true` عندما يكون النطاق مزود بريد للاستخدام مرة واحدة.
        is_free_domain:
          type: boolean
          nullable: true
          description: تكون `true` عندما يكون النطاق مزود بريد إلكتروني مجاني.
        is_breached:
          type: boolean
          nullable: true
          description: تكون القيمة `true` عندما يظهر العنوان في اختراقات أمنية معروفة.
        no_of_breaches:
          type: number
          nullable: true
          description: عدد الاختراقات المعروفة التي تحتوي على العنوان.
        reason_codes:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: >-
                  معرّف Didit الثابت للإشارة، على سبيل المثال `IR-5AC67A32`. غير
                  قابل للتفسير: قم بالتجميع والتصفية بناءً عليه، ولا تقم بتحليله
                  برمجياً.
              value:
                nullable: true
                description: >-
                  لعلامة المخاطر (على سبيل المثال `voip`، `leaked`،
                  `disposable`، `spam_trap`)، قيمتها: قيمة منطقية أو مستوى أو
                  تاريخ. Null لرمز سبب تم احتساب درجاته.
              direction:
                type: string
                enum:
                  - risk
                  - trust
                description: >-
                  ما إذا كانت الإشارة قد رفعت مستوى المخاطر أو زادت من درجة
                  الثقة.
              message:
                type: string
                description: تفسير سهل القراءة للإشارة، باللغة الإنجليزية.
              impact_level:
                type: string
                nullable: true
                description: >-
                  مدى تأثير الإشارة في تغيير الدرجة، على سبيل المثال `low` أو
                  `medium` أو `high`.
          description: >-
            الإشارات التي تفسر الدرجة، لكل منها رمز Didit ثابت، واتجاه، ورسالة،
            ومستوى تأثير. يمكن أن تظهر رموز جديدة بمرور الوقت، لذا لا ترفض
            الرموز غير المعروفة.
    EmailSocialFootprint:
      type: object
      nullable: true
      description: >-
        البصمة الاجتماعية لعنوان البريد الإلكتروني: المنصات الإلكترونية المسجل
        عليها. تظهر فقط عند تعيين `enable_social` واكتمال الفحص. قد يكون كل عدد
        null عندما لا يتم إرجاع أي بيانات له. تعني `profiles_registered: 0` أنه
        تم فحص المنصات ولم يتم العثور على عنوان البريد الإلكتروني في أي منها -
        وهي إجابة صالحة وخاضعة للفوترة وإشارة شائعة للهوية الاصطناعية.
      properties:
        profiles_registered:
          type: integer
          nullable: true
          description: المنصات التي تم تأكيد تسجيل عنوان البريد الإلكتروني فيها.
          example: 5
        profiles_checked:
          type: integer
          nullable: true
          description: المنصات التي تم تقييمها للتسجيل.
          example: 14
        names_found:
          type: integer
          nullable: true
          description: المنصات التي أرجعت اسماً مرتبطاً.
          example: 0
        photos_found:
          type: integer
          nullable: true
          description: المنصات التي أرجعت صورة للملف الشخصي.
          example: 0
        communication_breadth:
          type: integer
          nullable: true
          description: منصات التواصل التي تم اكتشاف وجود المستخدم فيها.
          example: 2
        digital_footprint_diversity:
          type: integer
          nullable: true
          description: فئات منصات مميزة مع تواجد تم اكتشافه.
          example: 5
        digital_sophistication_index:
          type: integer
          nullable: true
          description: مؤشر النضج الرقمي المركب، من 0 إلى 10.
          example: 5
        engagement_depth_index:
          type: integer
          nullable: true
          description: مؤشر ثراء الملف التعريفي، من 0 إلى 10.
          example: 3
        subscription_affordability_index:
          type: integer
          nullable: true
          description: مزيج المنصات المجانية مقابل المدفوعة، من 0 إلى 10.
          example: 2
        free_platforms:
          type: integer
          nullable: true
          description: التسجيلات على المنصات المجانية.
          example: 4
        full_paid_platforms:
          type: integer
          nullable: true
          description: التسجيلات على المنصات المدفوعة بالكامل.
          example: 0
        partial_paid_platforms:
          type: integer
          nullable: true
          description: التسجيلات على المنصات المجانية جزئيًا.
          example: 1
        whatsapp_profile_completeness:
          type: string
          nullable: true
          enum:
            - Basic
            - Partial
            - Complete
            - Not Present
            - null
          description: >-
            مدى اكتمال الملف التعريفي على WhatsApp. للهاتف فقط؛ وتكون القيمة
            فارغة (null) للبريد الإلكتروني.
          example: Partial
        registered_platforms:
          type: array
          description: المنصات التي تم تأكيد التسجيل فيها.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        not_registered_platforms:
          type: array
          description: المنصات التي تم فحصها وكانت النتيجة سلبية.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        categories:
          type: object
          description: عدد التسجيلات ونسبتها حسب فئة المنصة.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintCategorySummary'
        profiles:
          type: object
          description: >-
            تفاصيل الملف التعريفي لكل منصة، مفهرسة بحسب المنصة، عندما توفرها
            المنصة.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintProfile'
    SocialFootprintPlatform:
      type: object
      properties:
        platform:
          type: string
          description: معرّف المنصة.
          example: whatsapp
        category:
          type: string
          description: >-
            فئة المنصة، مثل MESSAGING أو SOCIAL_MEDIA أو ECOMMERCE أو
            PROFESSIONAL أو EMAIL_PROVIDER.
          example: MESSAGING
        scope:
          type: string
          enum:
            - global
            - local
          description: '`global` للمنصات العالمية، و`local` للمنصات الخاصة بمنطقة معينة.'
          example: global
    SocialFootprintCategorySummary:
      type: object
      properties:
        registered:
          type: integer
          nullable: true
          description: المنصات في هذه الفئة التي تم تأكيد التسجيل فيها.
          example: 2
        ratio:
          type: number
          format: float
          nullable: true
          description: حصة المنصات المفحوصة في الفئة التي تحتوي على تسجيل، 0.0-1.0.
          example: 0.6667
    SocialFootprintProfile:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: اسم الملف التعريفي، إذا وفرته المنصة.
        photo:
          type: string
          nullable: true
          description: رابط الصورة الشخصية للملف التعريفي، إذا وفرته المنصة.
        about:
          type: string
          nullable: true
          description: نص النبذة التعريفية للملف التعريفي، إذا وفرته المنصة.
        privacy_status:
          type: string
          nullable: true
          enum:
            - PUBLIC
            - PRIVATE
            - null
          description: مستوى رؤية الملف التعريفي، إذا وفرته المنصة.
        business_account:
          type: boolean
          nullable: true
          description: ما إذا كان الملف الشخصي حساب شركة، عندما تكشفه المنصة.
  responses:
    EmailRiskValidationError:
      description: فشل التحقق من صحة الطلب.
      content:
        application/json:
          examples:
            Missing email:
              summary: البريد الإلكتروني مفقود
              value:
                email:
                  - This field is required.
            Invalid email:
              summary: بريد إلكتروني غير صالح
              value:
                email:
                  - Enter a valid email address.
            Invalid country hint:
              summary: تلميح الدولة غير صالح
              value:
                country_code:
                  - Ensure this field has no more than 3 characters.
    RiskPermissionDenied:
      description: >-
        مفتاح API مفقود أو غير صالح، أو لا تستطيع المؤسسة تغطية البحث المباشر.
        لا تُرجع هذه API أبداً الرمز `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              summary: لا يوجد رأس `x-api-key`، أو أن المفتاح غير صالح أو ملغى
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              summary: رصيد المؤسسة لا يمكنه تغطية سعر البحث
              value:
                error: You don't have enough credits to perform this request.
    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.