Verifica telefonica API: validazione del codice OTP SMS

curl

curl -X POST https://verification.didit.me/v3/phone/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "code": "123456",
    "voip_number_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.phone.checkCode({
  phone_number: "+14155552671",
  code: "123456",
});
console.log(result);

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

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

import me.didit.Didit;
import me.didit.types.PhoneCheckCodeParams;

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

var result = client.phone().checkCode(PhoneCheckCodeParams.builder()
        .phoneNumber("+14155552671")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->phone->checkCode([
    'phone_number' => '+14155552671',
    'code' => '123456',
]);
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.CheckCodeAsync(new PhoneCheckCodeParams
{
    PhoneNumber = "+14155552671",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "AT&T",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "whatsapp",
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "PHONE_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null,
          "channel": "whatsapp",
          "actual_channel": "whatsapp"
        },
        "fee": 0.0509
      },
      {
        "type": "PHONE_DELIVERY_DELIVERED",
        "timestamp": "2026-06-12T01:23:43.118220+00:00",
        "details": {
          "channel": "whatsapp",
          "status": "delivered"
        },
        "fee": 0
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "PHONE_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

POST

phone

check

curl

curl -X POST https://verification.didit.me/v3/phone/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "code": "123456",
    "voip_number_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.phone.checkCode({
  phone_number: "+14155552671",
  code: "123456",
});
console.log(result);

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

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

import me.didit.Didit;
import me.didit.types.PhoneCheckCodeParams;

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

var result = client.phone().checkCode(PhoneCheckCodeParams.builder()
        .phoneNumber("+14155552671")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->phone->checkCode([
    'phone_number' => '+14155552671',
    'code' => '123456',
]);
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.CheckCodeAsync(new PhoneCheckCodeParams
{
    PhoneNumber = "+14155552671",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "AT&T",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "whatsapp",
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "PHONE_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null,
          "channel": "whatsapp",
          "actual_channel": "whatsapp"
        },
        "fee": 0.0509
      },
      {
        "type": "PHONE_DELIVERY_DELIVERED",
        "timestamp": "2026-06-12T01:23:43.118220+00:00",
        "details": {
          "channel": "whatsapp",
          "status": "delivered"
        },
        "fee": 0
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "PHONE_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

Gestione delle interruzioni del provider

Se il provider telefonico non è temporaneamente disponibile, questo endpoint restituisce 502 con un codice stabile leggibile automaticamente:

{
  "detail": "The phone verification provider is temporarily unavailable.",
  "code": "phone_provider_unavailable"
}

Considera questa risposta ripetibile. Usa un breve backoff e mostra all’utente un messaggio che informi della temporanea indisponibilità del servizio, invece di chiedergli di modificare un numero di telefono o un codice validi.

Add-on di analisi telefonica

Imposta enable_enrichment su true per eseguire anche l’analisi telefonica sul numero: un punteggio di rischio, il tipo di linea, se il numero è stato portato di recente e un indice di affidabilità. L’add-on viene fatturato $0.05 per richiesta al prezzo di listino, in aggiunta al prezzo della verifica. La richiesta restituisce 403 quando il tuo saldo non è sufficiente a coprirne il costo. Quattro campi determinano l’effetto dei segnali. Ciascuno può essere NO_ACTION (il valore predefinito) o DECLINE, e ciascuno ha effetto solo quando enable_enrichment è true.

Campo	Rifiuta quando
`phone_intelligence_score_action`	Il punteggio di rischio è superiore alla soglia.
`phone_type_risk_action`	Il numero è associato a un tipo di linea ad alto rischio.
`recent_port_action`	Il numero è stato trasferito di recente a un altro operatore.
`low_phone_trust_action`	L’indice di affidabilità è pari o inferiore alla soglia.

Con NO_ACTION, il segnale viene comunque restituito in phone.phone_intelligence, così puoi applicare una regola personalizzata.

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

Lo stesso numero di telefono utilizzato nella chiamata corrispondente POST /v3/phone/send/, in formato E.164. Questo è ciò che collega la verifica all'invio.

Maximum string length: 20

Esempio:

"+14155552671"

code

string

obbligatorio

L'OTP ricevuto dall'utente finale. Deve essere composto da 4–8 cifre numeriche; qualsiasi altro valore restituisce 400 senza consumare un tentativo. Un codice ben formato ma errato restituisce 200 con status: "Failed" e consuma uno dei 3 tentativi.

Required string length: 4 - 8

Pattern: ^[0-9]{4,8}$

Esempio:

"123456"

duplicated_phone_number_action

enum<string>

predefinito:NO_ACTION

Cosa fare quando lo stesso numero è già stato utilizzato da un utente diverso (diverso vendor_data) della tua applicazione. DECLINE imposta lo status finale su Declined; NO_ACTION registra il rischio in phone.warnings e popola phone.matches.

Opzioni disponibili:

NO_ACTION,

DECLINE

disposable_number_action

enum<string>

predefinito:NO_ACTION

Cosa fare quando la ricerca dell'operatore segnala il numero come linea temporanea/usa e getta (phone.is_disposable). DECLINE imposta lo status finale su Declined; NO_ACTION registra il rischio in phone.warnings.

Opzioni disponibili:

NO_ACTION,

DECLINE

voip_number_action

enum<string>

predefinito:NO_ACTION

Cosa fare quando la ricerca dell'operatore restituisce un tipo di linea virtuale — voip, isp o vpn (phone.is_virtual). DECLINE imposta lo status finale su Declined; NO_ACTION registra il rischio in phone.warnings.

Opzioni disponibili:

NO_ACTION,

DECLINE

enable_enrichment

boolean

predefinito:false

Quando è true, esegue anche l'analisi del numero di telefono: un punteggio di rischio, il tipo di linea, l'eventuale portabilità recente e un indice di affidabilità. Fatturato come un'unità phone_intelligence_api per richiesta ($0.05 a prezzo di listino) in aggiunta al prezzo di questo endpoint. La richiesta restituisce 403 quando il tuo saldo non è sufficiente a coprirlo.

Esempio:

false

phone_intelligence_score_action

enum<string>

predefinito:NO_ACTION

Azione quando il punteggio di rischio dell'intelligence telefonica supera la soglia. DECLINE imposta lo status finale su Declined; NO_ACTION registra il segnale senza rifiutare. Ha effetto solo quando enable_enrichment è true.

Opzioni disponibili:

NO_ACTION,

DECLINE

phone_type_risk_action

enum<string>

predefinito:NO_ACTION

Azione quando il numero appartiene a un tipo di linea ad alto rischio. DECLINE imposta lo status finale su Declined; NO_ACTION registra il segnale senza rifiutare. Ha effetto solo quando enable_enrichment è true.

Opzioni disponibili:

NO_ACTION,

DECLINE

recent_port_action

enum<string>

predefinito:NO_ACTION

Azione quando il numero è stato trasferito di recente a un altro operatore. DECLINE imposta lo status finale su Declined; NO_ACTION registra il segnale senza rifiutare. Ha effetto solo quando enable_enrichment è true.

Opzioni disponibili:

NO_ACTION,

DECLINE

low_phone_trust_action

enum<string>

predefinito:NO_ACTION

Azione quando l'indice di affidabilità dell'intelligence telefonica è pari o inferiore alla soglia. DECLINE imposta lo status finale su Declined; NO_ACTION registra il segnale senza rifiutare. Ha effetto solo quando enable_enrichment è true.

Opzioni disponibili:

NO_ACTION,

DECLINE

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

Azione quando il controllo dell'impronta social rileva che il numero non è registrato su nessuna delle piattaforme coperte. Solo NO_ACTION e DECLINE sono accettati su questo endpoint; REVIEW è disponibile sulla chiave di configurazione del workflow con lo stesso nome.

Opzioni disponibili:

NO_ACTION,

DECLINE

Risposta

Verifica completata: anche i codici errati e le verifiche mancanti restituiscono 200; esamina status, non il codice HTTP. phone viene popolato solo per gli esiti definitivi (Approved/Declined), è null per Failed ed è assente per Expired or Not Found.

request_id

string<uuid>

Su Approved/Declined: l'id di sessione della verifica corrispondente — identico al request_id restituito da POST /v3/phone/send/. Su Failed ed Expired or Not Found: un UUID casuale monouso che non può essere cercato in seguito.

status

enum<string>

Approved — codice corretto, nessun rischio di rifiuto. Declined — definitivo: è stato rilevato un rischio che comporta il rifiuto oppure il limite di tentativi (3) è stato esaurito. Failed — codice errato, tentativi rimanenti. Expired or Not Found — nessuna verifica in attesa per questo numero negli ultimi 5 minuti.

Opzioni disponibili:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

Spiegazione di facile lettura dell'esito, compreso il numero di tentativi rimanenti dopo un codice errato.

phone

object | null

Report telefonico completo. Presente (non nullo) solo per gli esiti finalizzati (Approved/Declined); null per Failed e assente per Expired or Not Found.

Show child attributes

vendor_data

string | null

vendor_data della sessione della verifica corrispondente. null in caso di Expired or Not Found.

metadata

object | null

metadata della sessione di verifica corrispondente. null in caso di Expired or Not Found.

created_at

string<date-time>

Timestamp della risposta a questo controllo.

Ultima modifica il 7 novembre 2026

​Gestione delle interruzioni del provider

​Add-on di analisi telefonica

Autorizzazioni

Corpo

Risposta

Gestione delle interruzioni del provider

Add-on di analisi telefonica