API rischio telefonico: operatore e segnali di frode

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

Usa POST /v3/phone/risk/ quando ti serve l’intelligence sul numero di telefono prima, al posto o al di fuori di un flusso OTP. Non invia alcun codice all’utente. Crea una sessione API, arricchisce il numero, applica le tue regole di rischio sul telefono e restituisce, in un’unica risposta sincrona, lo stesso blocco normalizzato del numero di telefono usato da Phone Verification. Quando la richiesta viene salvata, Didit può anche usare il numero di telefono valutato come evidenza aggregata in Reti. I grafi delle reti possono mostrare intelligence sul telefono ad alto rischio e informazioni su portabilità e tipo di linea relative a segnali di telefono condivisi, ma non rivelano il numero di telefono grezzo ad altre organizzazioni.

Interpreta la risposta

status è la decisione finale per questa sessione API. Di norma è Approved; la valutazione del rischio può produrre In Review o Declined.
phone.full_number è il numero normalizzato in formato E.164. phone.phone_number_prefix e phone.phone_number lo suddividono nel prefisso internazionale e nel numero nazionale.
phone.is_disposable e phone.is_virtual sono segnali stabili di sì/no per la logica della tua applicazione. La ricerca dell’operatore aggiunge carrier.name e carrier.type (mobile, voip e simili).
phone.phone_intelligence.score usa una scala di rischio da 0 a 100, dove un numero più alto indica un rischio più alto. phone_type_risk (Low, Medium, High) e phone_trust_index (l’inverso del punteggio) sono viste derivate.
phone.phone_intelligence e phone.enrichment sono alias di compatibilità con lo stesso oggetto normalizzato. Le nuove integrazioni possono leggere phone.enrichment.
phone.matches elenca le altre sessioni della tua applicazione in cui lo stesso numero è stato usato da un utente diverso. Usalo per il rilevamento di account duplicati.
request_id è l’ID della sessione API. Memorizzalo insieme a vendor_data se ti serve collegare il risultato ai webhook successivi o all’attività in console.

phone.phone_intelligence e phone.enrichment sono campi non garantiti. Una ricerca completata può ometterli entrambi quando non viene restituito alcun dato di intelligence utilizzabile per quel numero, quel paese o quel piano. Costruisci le regole prima di tutto sui campi normalizzati stabili e considera l’assenza di dati di intelligence come “sconosciuta”, non come “sicura”.

Imposta enable_social su true per aggiungere alla risposta, sotto phone, un blocco phone_social: le piattaforme online su cui questo numero di telefono è registrato, raggruppate per categoria, con i conteggi di sintesi e gli eventuali dettagli del profilo restituiti dai nostri partner di dati.

phone.phone_social.profiles_registered e phone.phone_social.profiles_checked sono i numeri principali: le piattaforme in cui il numero di telefono risulta registrato, rispetto a quelle valutate.
phone.phone_social.registered_platforms e phone.phone_social.not_registered_platforms elencano ogni piattaforma con la sua category e il suo scope (global, oppure local per le piattaforme specifiche di una regione).
phone.phone_social.categories riporta, per ogni categoria, il conteggio e il rapporto delle registrazioni, mentre phone.phone_social.profiles contiene i dettagli del profilo per piattaforma quando una piattaforma li espone (nome, URL della foto, testo descrittivo, stato della privacy, indicatore di account aziendale).
Gli indici di sintesi (digital_footprint_diversity, digital_sophistication_index, engagement_depth_index, subscription_affordability_index) sono indici compositi su una scala da 0 a 10. Ogni conteggio può essere null quando il controllo non ha restituito dati per quel conteggio.

profiles_registered: 0 è una risposta reale, non un errore: le piattaforme sono state controllate e il numero di telefono non è stato trovato su nessuna di esse, il che è un segnale comune di identità sintetica. Questo endpoint non agisce da solo su questo dato: usa phone_no_social_presence_action in un workflow per trasformarlo in un esito Review o Decline. Il blocco è assente quando enable_social non è impostato, e anche quando il controllo social non può essere completato: in tal caso non viene fatturato.

Comportamento in sandbox

Le chiavi sandbox convalidano la richiesta e restituiscono dati deterministici con esito approvato. Non inviano un OTP, non consumano crediti, non creano una sessione e non contribuiscono a Reti. Con enable_social impostato, restituiscono anche un blocco phone_social deterministico.

Fatturazione

Le chiamate all’API Phone Risk costano $0.04 al prezzo di listino, meno di una Phone Verification completa perché non viene inviato alcun OTP. Una richiesta in ambiente di produzione è fatturabile dal momento in cui inizia la ricerca, anche quando alcuni campi non garantiti non sono disponibili. L’add-on sull’impronta social viene fatturato separatamente: un’unità phone_social per richiesta, in aggiunta al prezzo dell’API Phone Risk, ogni volta che il controllo viene completato. Il controllo del credito effettuato prima della ricerca copre entrambi.

Autorizzazioni

x-api-key

string

header

obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json

phone_number

string

obbligatorio

Numero di telefono da valutare. Viene validato e normalizzato in formato E.164.

Maximum string length: 20

Esempio:

"+14155552671"

country_code

string

Suggerimento facoltativo sul paese ISO 3166-1 alpha-2 o alpha-3 per la copertura dell'intelligence.

Maximum string length: 3

Esempio:

"US"

signals

object

Contesto facoltativo di dispositivo e rete rilevato dalla tua applicazione. Tutti i campi sono facoltativi. Fornirli alimenta il rilevamento delle corrispondenze tra sessioni in Reti.

Show child attributes

vendor_data

string

Il tuo riferimento stabile per questa richiesta. Memorizzato nella sessione API e restituito nella risposta.

metadata

object | null

I tuoi metadati JSON non sensibili. Memorizzati nella sessione API e restituiti nella risposta.

Se true, cerca anche l'impronta social del numero: le piattaforme di messaggistica, social, e-commerce e professionali su cui è registrato. Fatturato come un'unità phone_social per richiesta in aggiunta al prezzo di questo endpoint.

Esempio:

true

Risposta

La valutazione del rischio è completata. Ispeziona status per la decisione; il codice HTTP è sempre 200 per le ricerche completate.

request_id

string<uuid>

obbligatorio

ID della sessione API creata per questa richiesta. Memorizzalo con vendor_data se hai bisogno di correlare il risultato con i webhook successivi o con l'attività nella console.

status

enum<string>

obbligatorio

Decisione finale per questa sessione API. Di norma Approved; la valutazione del rischio può produrre In Review o Declined.

Opzioni disponibili:

Approved,

In Review,

Declined

created_at

string<date-time>

obbligatorio

Timestamp di questa risposta.

vendor_data

string | null

Eco del vendor_data inviato, null se non ne hai inviato alcuno.

metadata

object | null

Eco del metadata inviato, null se non ne hai inviato alcuno.

phone

object

Report normalizzato del telefono, lo stesso blocco utilizzato dalle risposte di Verifica telefonica.

Show child attributes

Ultima modifica il 7 novembre 2026

​Interpreta la risposta

​Add-on sull’impronta social

​Comportamento in sandbox

​Fatturazione

Autorizzazioni

Corpo

Risposta

Interpreta la risposta

Add-on sull’impronta social

Comportamento in sandbox

Fatturazione