> ## 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 دون إرسال رمز لمرة واحدة: شركة الاتصالات، ونوع الخط، ونقل الرقم، والأرقام المؤقتة، والاحتيال.

استخدم `POST /v3/phone/risk/` عندما تحتاج إلى معلومات استخباراتية عن الهاتف قبل تدفق OTP أو بدلاً منه أو خارجه.

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

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

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

* `status` هو القرار النهائي لجلسة API هذه. يكون عادةً `Approved`، ويمكن أن يُنتج تقييم المخاطر القيمتين `In Review` أو `Declined`.
* `phone.full_number` هو الرقم المُوحَّد بصيغة E.164. يقسمان `phone.phone_number_prefix` و`phone.phone_number` الرقم إلى رمز الاتصال الدولي والرقم الوطني.
* `phone.is_disposable` و`phone.is_virtual` إشارتان ثابتتان بنعم أو لا لمنطق التطبيق. يضيف بحث شركة الاتصال الحقلين `carrier.name` و`carrier.type` (`mobile` و`voip` وما شابه).
* يستخدم `phone.phone_intelligence.score` مقياس مخاطر من 0 إلى 100، حيث تعني القيمة الأعلى خطراً أعلى. أما `phone_type_risk` (`Low` و`Medium` و`High`) و`phone_trust_index` (وهو عكس الدرجة) فهما عرضان مشتقان.
* يمثل `phone.phone_intelligence` و`phone.enrichment` اسمين بديلين للحفاظ على التوافق، ويشيران إلى الكائن المُوحَّد نفسه. تستطيع التكاملات الجديدة قراءة `phone.enrichment`.
* يسرد `phone.matches` الجلسات الأخرى في تطبيقك التي استُخدم فيها الرقم نفسه من قِبل مستخدم مختلف. استخدمه لاكتشاف الحسابات المكررة.
* يمثل `request_id` معرّف جلسة API. احفظه مع `vendor_data` إذا احتجت إلى ربط النتيجة بالـ webhooks اللاحقة أو بنشاط وحدة التحكم.

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

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

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

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

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

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

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

تتحقق مفاتيح البيئة التجريبية من صحة الطلب، وتعيد بيانات مقبولة حتمية. لا ترسل رمز OTP، ولا تستهلك الأرصدة، ولا تُنشئ جلسة، ولا تُسهم في **Networks**. ومع ضبط `enable_social`، تعيد أيضاً كائن `phone_social` محدداً مسبقاً.

## الفوترة

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

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


## OpenAPI

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


        **القرار.** يعكس الحقل `status` من المستوى الأعلى حالة `phone.status`.
        وتكون قيمته عادةً `Approved`؛ كما يمكن لتقييم المخاطر أن يُسفر عن `In
        Review` أو `Declined`.


        **الأسماء البديلة للتوافقية.** تُظهر الاستجابات الحية كائن الاستخبارات
        الموحد باسم `phone.phone_intelligence` و`phone.enrichment` على حد سواء.
        وتكون القيم متطابقة تماماً. يمكن لعمليات التكامل الجديدة قراءة
        `phone.enrichment`. ويغيب كلا المفتاحين عند عدم إرجاع أي بيانات
        استخباراتية قابلة للاستخدام.


        **الفوترة.** تستخدم الاستدعاءات الحية تسعير Phone Risk API. ويخضع الطلب
        للفوترة بمجرد بدء عملية البحث، حتى لو تعذّر توفير بعض الحقول رغم بذل
        أفضل جهد.


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


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


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


        **البصمة الاجتماعية.** اضبط `enable_social` على `true` لإضافة كتلة
        `phone_social`: المنصات الإلكترونية المسجل عليها هذا الرقم، مع أعداد لكل
        فئة وأي تفاصيل ملف شخصي متاحة. وتعني `profiles_registered: 0` أنه تم فحص
        المنصات ولم يتم العثور على الرقم في أي منها - وهي استجابة صالحة وخاضعة
        للفوترة. تغيب هذه الكتلة إذا لم يتم طلب الميزة الإضافية أو تعذر إكمال
        الفحص، ولا تتم فوترتها في تلك الحالة. تُضيف الفوترة وحدة `phone_social`
        واحدة لكل طلب علاوة على السعر الخاص بهذا الـ endpoint نفسه.
      operationId: post_v3phone_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneRiskRequest'
            examples:
              Minimal:
                summary: احتساب درجة لرقم بالقيم الافتراضية
                value:
                  phone_number: '+14155552671'
              Full context:
                summary: احتساب الدرجة مع الإشارات وتلميح الدولة ومعرّفات الارتباط
                value:
                  phone_number: '+14155552671'
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: ios
                    device_model: iPhone17,2
                    os_version: 18.0.1
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0
                      Mobile/15E148 Safari/604.1
                  vendor_data: lead-123
                  metadata:
                    source: signup_prescreen
      responses:
        '200':
          description: >-
            اكتمل تقييم المخاطر. افحص `status` لمعرفة القرار؛ رمز HTTP دائماً ما
            يكون `200` لعمليات البحث المكتملة.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneRiskResponse'
              examples:
                Clean mobile number:
                  summary: رقم هاتف محمول مُنقّى مع تغطية معلوماتية
                  value:
                    request_id: 4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62
                    status: Approved
                    phone:
                      status: Approved
                      phone_number_prefix: '+1'
                      phone_number: '4155552671'
                      full_number: '+14155552671'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: Example Mobile
                        type: mobile
                      is_disposable: false
                      is_virtual: false
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                      enrichment:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Number in review:
                  summary: رقم مؤقت أو افتراضي تم وضع علامة عليه للمراجعة
                  value:
                    request_id: 8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f
                    status: In Review
                    phone:
                      status: In Review
                      phone_number_prefix: '+44'
                      phone_number: '7700900123'
                      full_number: '+447700900123'
                      country_code: GB
                      country_name: United Kingdom
                      carrier:
                        name: Example VoIP
                        type: voip
                      is_disposable: true
                      is_virtual: true
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                      enrichment:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                    vendor_data: lead-124
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/PhoneRiskValidationError'
        '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/phone/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "phone_number": "+14155552671",
                "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.phone.assess_risk(
                phone_number="+14155552671",
            )
            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.phone.assessRisk({
              phone_number: "+14155552671",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{\n\tPhoneNumber: \"+14155552671\",\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.PhoneRiskRequest;

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

            var result = client.phone().assessRisk(PhoneRiskRequest.builder()
                    .phoneNumber("+14155552671")
                    .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->phone->assessRisk([
                'phone_number' => '+14155552671',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.phone.assess_risk(phone_number: "+14155552671")
            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.Phone.AssessRiskAsync(new PhoneRiskRequest
            {
                PhoneNumber = "+14155552671",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    PhoneRiskRequest:
      type: object
      required:
        - phone_number
      properties:
        phone_number:
          type: string
          maxLength: 20
          description: >-
            رقم الهاتف المراد احتساب درجة مخاطره. يتم التحقق من صحته وضبطه
            بتنسيق E.164.
          example: '+14155552671'
        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، يتم أيضاً البحث عن الأثر الرقمي الاجتماعي
            للرقم - منصات المراسلة والمنصات الاجتماعية والتجارة الإلكترونية
            والمهنية المسجل عليها. يُفوتر كوحدة `phone_social` واحدة لكل طلب
            بالإضافة إلى سعر هذا الـ endpoint نفسه.
          example: true
    PhoneRiskResponse:
      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: الطابع الزمني لهذه الاستجابة.
        phone:
          type: object
          description: >-
            تقرير الهاتف المعياري، وهو نفس الكتلة المستخدمة في استجابات التحقق
            من رقم الهاتف.
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: القرار لرقم الهاتف هذا. يعكس قيمة `status` في المستوى الأعلى.
            phone_number_prefix:
              type: string
              description: رمز الاتصال بالدولة مسبوقاً بـ `+` (مثل `+1`).
              example: '+1'
            phone_number:
              type: string
              description: الرقم الوطني بدون رمز الاتصال الدولي للدولة.
              example: '4155552671'
            full_number:
              type: string
              description: الرقم الكامل بتنسيق E.164.
              example: '+14155552671'
            country_code:
              type: string
              nullable: true
              description: دولة الرقم وفق المعيار ISO 3166-1 alpha-2.
              example: US
            country_name:
              type: string
              description: اسم الدولة الكامل المشتق من `country_code`.
              example: United States
            carrier:
              type: object
              nullable: true
              description: >-
                الشبكة الحالية التي تخدم الرقم. تكون `null` عندما يتعذر على
                البحث تحديد شركة الاتصالات.
              properties:
                name:
                  type: string
                  description: >-
                    اسم شركة الاتصالات. سلسلة نصية فارغة إذا لم يتمكن البحث من
                    تحديدها.
                type:
                  type: string
                  description: >-
                    نوع الخط الوارد من البحث: `mobile`، أو `fixed_line`، أو
                    `voip`، أو `isp`، أو `vpn`، أو `toll_free`، أو
                    `premium_rate`، وما شابه ذلك.
            is_disposable:
              type: boolean
              description: >-
                تكون `true` عندما ينتمي الرقم إلى خدمة أرقام مؤقتة أو مخصصة
                للاستخدام لمرة واحدة.
            is_virtual:
              type: boolean
              description: >-
                تكون `true` عندما يكون نوع الخط افتراضيًا (`voip` أو `isp` أو
                `vpn`).
            verification_method:
              type: string
              nullable: true
              description: >-
                قناة OTP لعملية التحقق الأساسية. تكون `null` لعمليات البحث عن
                المخاطر، والتي لا ترسل رمزاً أبداً.
            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/PhoneMatchItem'
            phone_intelligence:
              $ref: '#/components/schemas/PhoneIntelligence'
            enrichment:
              $ref: '#/components/schemas/PhoneIntelligence'
            phone_social:
              $ref: '#/components/schemas/PhoneSocialFootprint'
    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: المبلغ بالدولار الأمريكي المفوتر لهذا الحدث.
    PhoneMatchItem:
      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`).
        phone_number:
          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`.
    PhoneIntelligence:
      type: object
      description: >-
        كتلة معلومات الهاتف المعيارية. تظهر فقط عند تشغيل الوظيفة الإضافية
        للمعلومات لعملية البحث هذه؛ وعند ظهورها يتم عرضها أيضاً تحت الاسم
        المستعار `enrichment` بنفس القيم.
      properties:
        score:
          type: number
          nullable: true
          description: درجة مخاطر معيارية من 0 إلى 100. تشير القيمة الأعلى إلى مخاطر أكبر.
        phone_type_risk:
          type: string
          nullable: true
          description: '`Low` أو `Medium` أو `High`، مشتقة من الدرجة.'
        phone_trust_index:
          type: number
          nullable: true
          description: >-
            معكوس الدرجة، للوحات التحكم التي تفضل أن تكون القيمة الأعلى هي
            الأفضل.
        network_stability_index:
          type: number
          nullable: true
          description: استقرار شبكة الخط.
        is_disposable:
          type: boolean
          nullable: true
          description: >-
            تكون `true` عندما يبدو الرقم مخصصاً للاستخدام لمرة واحدة أو
            افتراضياً.
        is_ported:
          type: boolean
          nullable: true
          description: تكون `true` عندما يكون الرقم قد غيّر مشغّل شبكة الجوال.
        is_recently_ported:
          type: boolean
          nullable: true
          description: تكون `true` عندما تكون عملية نقل الرقم قد تمت مؤخراً.
        carrier_type:
          type: string
          nullable: true
          description: تصنيف الخط الوارد من البحث (مثل `mobile`).
        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 ثابت، واتجاه، ورسالة،
            ومستوى تأثير. يمكن أن تظهر رموز جديدة بمرور الوقت، لذا لا ترفض
            الرموز غير المعروفة.
    PhoneSocialFootprint:
      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:
    PhoneRiskValidationError:
      description: فشل التحقق من صحة الطلب.
      content:
        application/json:
          examples:
            Missing phone number:
              summary: رقم الهاتف مفقود
              value:
                phone_number:
                  - This field is required.
            Invalid phone number:
              summary: رقم هاتف غير صالح
              value:
                phone_number:
                  - Invalid phone number provided.
            Invalid signal IP:
              summary: عنوان IP للإشارة غير صالح
              value:
                signals:
                  ip:
                    - Enter a valid IPv4 or IPv6 address.
    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.