واجهة مخاطر الهاتف: إشارات شركة الاتصالات والاحتيال

curl

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"}
  }'

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{
	PhoneNumber: "+14155552671",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?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());

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));

{
  "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"
}

POST

phone

risk

curl

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"}
  }'

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{
	PhoneNumber: "+14155552671",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?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());

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));

{
  "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"
}

استخدم 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 اللاحقة أو بنشاط وحدة التحكم.

الحقلان 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، وذلك متى اكتمل الفحص. ويغطي فحص الرصيد الذي يسبق البحث الحالتين معاً.

التفويضات

x-api-key

string

header

مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json

phone_number

string

مطلوب

رقم الهاتف المراد احتساب درجة مخاطره. يتم التحقق من صحته وضبطه بتنسيق E.164.

Maximum string length: 20

مثال:

"+14155552671"

country_code

string

تلميح دولة اختياري وفق معيار ISO 3166-1 alpha-2 أو alpha-3 لتغطية البيانات الاستخباراتية.

Maximum string length: 3

مثال:

"US"

signals

object

سياق اختياري للجهاز والشبكة يرصده تطبيقك. جميع الحقول اختيارية. يغذي تمريرها ميزة كشف التطابق عبر الجلسات في Networks.

Show child attributes

vendor_data

string

مرجعك الثابت لهذا الطلب. يتم تخزينه في جلسة API وإعادته في الاستجابة.

metadata

object | null

البيانات الوصفية بتنسيق JSON غير الحساسة الخاصة بك. يتم تخزينها في جلسة API وإعادتها في الاستجابة.

عند التعيين على true، يتم أيضاً البحث عن الأثر الرقمي الاجتماعي للرقم - منصات المراسلة والمنصات الاجتماعية والتجارة الإلكترونية والمهنية المسجل عليها. يُفوتر كوحدة phone_social واحدة لكل طلب بالإضافة إلى سعر هذا الـ endpoint نفسه.

مثال:

true

الاستجابة

اكتمل تقييم المخاطر. افحص status لمعرفة القرار؛ رمز HTTP دائماً ما يكون 200 لعمليات البحث المكتملة.

request_id

string<uuid>

مطلوب

معرّف جلسة API التي تم إنشاؤها لهذا الطلب. احفظه مع vendor_data إذا كنت بحاجة إلى ربط النتيجة بـ webhooks اللاحقة أو نشاط لوحة التحكم.

status

enum<string>

مطلوب

القرار النهائي لجلسة API هذه. عادةً ما يكون Approved؛ يمكن أن ينتج عن تقييم المخاطر In Review أو Declined.

الخيارات المتاحة:

Approved,

In Review,

Declined

created_at

string<date-time>

مطلوب

الطابع الزمني لهذه الاستجابة.

vendor_data

string | null

نسخة مطابقة من vendor_data التي أرسلتها، وتكون null عند عدم إرسال أي منها.

metadata

object | null

نسخة مطابقة من metadata التي أرسلتها، وتكون null عند عدم إرسال أي منها.

phone

object

تقرير الهاتف المعياري، وهو نفس الكتلة المستخدمة في استجابات التحقق من رقم الهاتف.

Show child attributes

آخر تعديل في ٧ نوفمبر ٢٠٢٦

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

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

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

​الفوترة

التفويضات

الجسم

الاستجابة

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

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

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

الفوترة