Vai al contenuto principale
POST
curl

Assegna il nome del tuo brand nell’SMS

I codici SMS riportano il nome del mittente SMS della tua applicazione, impostato nella Business Console, senza costi aggiuntivi:
123456 è il tuo codice di verifica per Acme Bank
Per inviare un codice con un nome diverso, passa options.sms_sender_name (da 1 a 30 caratteri: sono ammesse solo lettere, cifre, spazi e i caratteri ’ & - !, e non può trattarsi solo di cifre):
Un nome che non rispetta queste regole restituisce 400 e nessun codice viene inviato. I codici WhatsApp usano un messaggio fisso e non sono personalizzati con il brand; per inviarli dal nome della tua azienda, collega il tuo numero WhatsApp Business nella Business Console. Vedi Invia i codici WhatsApp dal tuo numero. Vedi Messaggi di verifica personalizzati per sapere quale nome compare in un codice e il limite giornaliero per i nuovi nomi.

Gestisci le interruzioni del provider

Se il provider telefonico non è disponibile temporaneamente, questo endpoint restituisce 502 con un codice stabile leggibile dalle macchine:
Considera questa risposta idonea a un nuovo tentativo. Usa un breve backoff e mostra all’utente un messaggio che informa della temporanea indisponibilità del servizio, invece di chiedergli di modificare un numero di telefono o un codice validi.

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 del destinatario in formato E.164 — con + iniziale e prefisso internazionale (es. +14155552671). I numeri vengono validati e normalizzati in E.164; i numeri non analizzabili o non validi restituiscono 400 con un errore nel campo phone_number.

Maximum string length: 20
Esempio:

"+14155552671"

options
object

Opzioni di consegna dell'OTP. Tutti i campi sono facoltativi.

signals
object

Segnali opzionali di dispositivo e rete relativi all'utente finale, inoltrati al livello antifrode per migliorare il rilevamento del traffico abusivo o automatizzato. Tutti i campi sono opzionali.

vendor_data
string

Identificatore opzionale controllato dal chiamante (il tuo ID utente interno, un'email, un UUID, ecc.) memorizzato nella sessione e restituito nella risposta di invio, nella risposta di verifica della corrispondenza, nei webhook e nella Business Console. Usalo per correlare il request_id di Didit con il record del tuo utente.

metadata
object | null

Oggetto JSON a struttura libera opzionale memorizzato nella sessione e restituito nella risposta di invio, nella risposta del controllo di corrispondenza, nei webhook e nella Business Console.

Risposta

Invio confermato. Ispeziona status: Success e Retry indicano che un codice è in arrivo; Blocked indica che il livello antifrode ha rifiutato e la verifica è già finalizzata come Declined. request_id è l'ID di sessione persistente (stesso ID in caso di Retry).

request_id
string<uuid>

ID sessione della verifica. Un invio Retry restituisce lo stesso request_id dell'invio originale. Questo id compare nella Business Console, viene restituito nuovamente da un POST /v3/phone/check/ finalizzato e può essere passato a GET /v3/session/{sessionId}/decision/.

status
enum<string>

Success — OTP inviato per una nuova verifica. Retry — OTP inviato nuovamente per la verifica in sospeso creata da un invio precedente. Blocked — il livello antifrode ha rifiutato l'invio; la verifica viene immediatamente finalizzata come Declined e non viene addebitato nulla.

Opzioni disponibili:
Success,
Retry,
Blocked
reason
string | null

Il motivo per cui un invio è stato Blocked (ad es. repeated_attempts, suspicious, spam). null su Success e Retry.

vendor_data
string | null

Eco del vendor_data memorizzato nella sessione (dal primo invio).

metadata
object | null

Eco dei metadata memorizzati nella sessione (dal primo invio).

Ultima modifica il 7 novembre 2026