> ## 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. # Verifica telefonica API: validazione del codice OTP SMS > Didit valida l'OTP telefonico via POST /v3/phone/check/, con rilevamento di operatore, numero virtuale e usa e getta. Prezzi a consumo, nessun minimo mensile. ## Gestione delle interruzioni del provider Se il provider telefonico non è temporaneamente disponibile, questo endpoint restituisce `502` con un codice stabile leggibile automaticamente: ```json theme={null} { "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. ## OpenAPI ````yaml it/openapi-25.json POST /v3/phone/check/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/check/: post: tags: - Standalone APIs summary: Verifica codice telefonico description: >- Verifica l'OTP recapitato da [`POST /v3/phone/send/`](/it/standalone-apis/phone-send) e ottieni il risultato finale della verifica oltre a informazioni sul numero di telefono: nome dell'operatore e tipo di linea, flag per numero virtuale (VoIP) e usa e getta, e l'utilizzo duplicato del numero tra le tue sessioni. **Come il controllo individua la verifica.** La corrispondenza avviene in base alla tua applicazione e al `phone_number` in formato E.164 — `request_id` non è un input. Viene controllata la verifica in sospeso più recente creata negli ultimi **5 minuti**. Se non ne esiste alcuna (mai inviata, già completata o creata più di 5 minuti prima), l'endpoint restituisce `200` con `status: "Expired or Not Found"`. **Budget di tentativi.** Ogni verifica consente **3 tentativi di inserimento del codice**. I primi due codici errati restituiscono `status: "Failed"` con i tentativi rimanenti e `phone: null`; il terzo codice errato finalizza la verifica come `Declined` con un avviso `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` e restituisce il report telefonico completo. **Esiti.** `Approved` — codice corretto e nessun rischio di rifiuto. `Declined` — terminale: il codice era corretto ma è stato rilevato un rischio di rifiuto (un'azione `DECLINE` indicata sotto, un numero presente in blocklist o ad alto rischio) oppure il budget di tentativi è esaurito. `Failed` — codice errato, tentativi rimanenti. `Expired or Not Found` — nulla da controllare. In caso di `Approved`/`Declined`, `request_id` corrisponde al `request_id` dell'invio (l'ID sessione) e `phone` contiene il report completo (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); in caso di `Failed` ed `Expired or Not Found`, `request_id` è un UUID casuale generato una tantum. **Azioni di rischio.** `duplicated_phone_number_action`, `disposable_number_action` e `voip_number_action` determinano cosa succede quando viene rilevato il rischio corrispondente con un codice corretto: `DECLINE` imposta lo stato finale su `Declined`; `NO_ACTION` (predefinito) registra il rischio in `phone.warnings` senza modificare lo stato. **Fatturazione.** I controlli sono gratuiti — la consegna viene fatturata al momento dell'invio (vedi [Prezzi di Verifica telefonica](/it/getting-started/phone-verification-pricing)). **Persistenza della sessione.** Un controllo finalizzato aggiorna la sessione creata dall'invio (visibile nella Business Console, interrogabile tramite `GET /v3/session/{sessionId}/decision/`) e attiva un webhook `status.updated`. **Sandbox.** Le chiavi API di sandbox ignorano qualsiasi elaborazione: qualunque codice ben formato (4–8 cifre, `123456` compreso) restituisce un payload statico `Approved` con un oggetto `phone` semplificato e piatto (`status`, `phone_number`, `country_code`, `carrier_name`, `line_type`, `flags`); un input non valido restituisce comunque `400`. Nessun dato viene salvato. **Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{"detail": "You do not have permission to perform this action."}`) — questa API non restituisce mai `401`. **Limiti di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API, oltre al limite anti-abuso a monte di 4 tentativi per numero all'ora; il superamento di uno dei due restituisce `429`. **Presenza social.** Imposta `enable_social` su `true` per aggiungere un blocco `phone_social`: le piattaforme online su cui questo numero è registrato, con conteggi per categoria ed eventuali dettagli del profilo disponibili. `profiles_registered: 0` significa che le piattaforme sono state verificate e il numero non è stato trovato su nessuna di esse - una risposta valida e fatturabile. Il blocco è assente quando il modulo aggiuntivo non è stato richiesto o non è stato possibile completare il controllo; in questo caso non viene fatturato. La fatturazione aggiunge un'unità `phone_social` per richiesta al prezzo proprio di questo endpoint. operationId: post_v3phone_check requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- Lo stesso numero di telefono utilizzato nella chiamata corrispondente [`POST /v3/phone/send/`](/it/standalone-apis/phone-send), in formato E.164. Questo è ciò che collega la verifica all'invio. example: '+14155552671' code: type: string minLength: 4 maxLength: 8 pattern: ^[0-9]{4,8}$ description: >- 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. example: '123456' duplicated_phone_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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`. disposable_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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`. voip_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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`. enable_enrichment: type: boolean default: false description: >- 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. example: false phone_intelligence_score_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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`. phone_type_risk_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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`. recent_port_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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`. low_phone_trust_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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`. enable_social: type: boolean default: false description: >- 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. example: true phone_no_social_presence_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 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. required: - phone_number - code examples: Default: summary: Registra eventuali rischi ma non rifiutare mai automaticamente value: phone_number: '+14155552671' code: '123456' Strict risk policy: summary: Rifiuta automaticamente linee VoIP e monouso value: phone_number: '+14155552671' code: '123456' voip_number_action: DECLINE disposable_number_action: DECLINE responses: '200': description: >- 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`. content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationCheckResponse' examples: Approved: summary: >- Codice corretto — report telefonico completo con operatore, ciclo di vita e corrispondenze value: 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' Failed (attempts remaining): summary: >- Codice errato: l'utente può riprovare; request_id qui è un UUID monouso value: request_id: 11111111-2222-3333-4444-555555555555 status: Failed message: 'The verification code is incorrect. Attempts remaining: 2' phone: null vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:21.512340+00:00' Declined (max attempts): summary: 'Terzo codice errato: verifica finalizzata come Rifiutata' value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Declined message: >- The verification code is incorrect. Maximum attempts reached. phone: status: Declined 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: null warnings: - feature: PHONE risk: VERIFICATION_CODE_ATTEMPTS_EXCEEDED additional_data: null log_type: error short_description: Verification code attempts exceeded long_description: >- The system detected that the phone number has exceeded the maximum number of verification code attempts. 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: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:01.118220+00:00' details: code_tried: '111111' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:21.512340+00:00' details: code_tried: '222222' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '333333' status: Failed fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VERIFICATION_CODE_ATTEMPTS_EXCEEDED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Declined (risk policy): summary: >- Codice corretto, ma la linea è VoIP e voip_number_action=DECLINE value: request_id: 7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a status: Declined message: The verification code is correct. phone: status: Declined phone_number_prefix: '+1' phone_number: '5005550006' full_number: '+15005550006' country_code: US country_name: United States carrier: name: CLEC LLC type: voip is_disposable: false is_virtual: true verification_method: sms verification_attempts: 1 verified_at: '2026-06-12T01:24:47.311323Z' warnings: - feature: PHONE risk: VOIP_NUMBER_DETECTED additional_data: null log_type: error short_description: VoIP number detected long_description: >- The system detected that the phone number is a VoIP number, which is not allowed. lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: sms fee: 0.0509 - type: VALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '123456' status: Approved fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VOIP_NUMBER_DETECTED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Expired or Not Found: summary: >- Nessuna verifica in sospeso per questo numero negli ultimi 5 minuti value: request_id: 69cc35c6-280a-47a6-ab8c-4f32abc02ed0 status: Expired or Not Found message: No pending phone verification found in the last 5 minutes. vendor_data: null metadata: null created_at: '2026-06-12T01:24:47.311323+00:00' '400': description: >- Errore di validazione — busta dell'errore di campo di DRF: un array di messaggi per campo non conforme. content: application/json: examples: Invalid code format: summary: '`code` non è composto da 4–8 cifre numeriche' value: code: - Invalid code format. Enter 4 to 8 numeric digits. Invalid phone number: summary: '`phone_number` non è un numero E.164 valido' value: phone_number: - Invalid phone number provided. Invalid action: summary: Le azioni di rischio accettano solo NO_ACTION o DECLINE value: voip_number_action: - '"REVIEW" is not a valid choice.' '403': description: >- Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante; una chiave errata, revocata o scaduta restituisce `401`. I controlli sono gratuiti, pertanto qui non viene eseguito alcun controllo del credito disponibile. content: application/json: examples: Missing or invalid API key: summary: >- Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata value: detail: You do not have permission to perform this action. '429': description: >- Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). Inoltre, a monte si applica un limite anti-abuso di 4 tentativi di verifica per numero di telefono all'ora. La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Nota: le intestazioni `X-RateLimit-*`/`Retry-After` accompagnano solo l'errore 429 relativo al limite di scrittura di 300/min; l'errore 429 relativo al limite per numero di telefono non include intestazioni del limite di frequenza. content: application/json: examples: Per-number cap: summary: >- Più di 4 tentativi di verifica per lo stesso numero nell'ultima ora value: detail: >- Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number. Write rate limit exceeded: summary: Più di 300 richieste di scrittura nel minuto corrente value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '500': description: >- Errore imprevisto a monte durante la verifica del codice non riconducibile a un'interruzione nota del fornitore. È sicuro effettuare un nuovo tentativo; il limite di tentativi viene consumato solo dai controlli completati. content: application/json: examples: Provider error: summary: Impossibile completare la verifica del codice value: detail: Error checking phone verification schema: type: object properties: detail: type: string '502': description: >- Il provider di verifica telefonica è temporaneamente non disponibile: una risposta 5xx, timeout o errore di connessione persistito dopo i nuovi tentativi integrati. È possibile riprovare in sicurezza; il budget di tentativi non viene consumato. content: application/json: examples: Provider outage: summary: Il provider non ha risposto alla richiesta di verifica value: detail: >- Phone verification is temporarily unavailable. Please try again shortly. code: phone_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- 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" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.check_code( phone_number="+14155552671", code="123456", ) 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.checkCode({ phone_number: "+14155552671", code: "123456", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tCode: \"123456\",\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.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); - lang: php label: PHP source: |- phone->checkCode([ 'phone_number' => '+14155552671', 'code' => '123456', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.check_code( phone_number: "+14155552671", code: "123456" ) 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.CheckCodeAsync(new PhoneCheckCodeParams { PhoneNumber = "+14155552671", Code = "123456", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationCheckResponse: type: object properties: request_id: type: string format: uuid description: >- 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: type: string enum: - Approved - Declined - Failed - Expired or Not Found description: >- `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. message: type: string description: >- Spiegazione di facile lettura dell'esito, compreso il numero di tentativi rimanenti dopo un codice errato. phone: type: object nullable: true description: >- Report telefonico completo. Presente (non nullo) solo per gli esiti finalizzati (`Approved`/`Declined`); `null` per `Failed` e assente per `Expired or Not Found`. properties: status: type: string enum: - Approved - Declined - In Review - Not Finished - Expired description: >- Stato finale della verifica telefonica. Corrisponde allo `status` di primo livello per i controlli finalizzati. phone_number_prefix: type: string description: >- Prefisso telefonico internazionale del paese con `+` iniziale (es. `+1`). example: '+1' phone_number: type: string description: Numero nazionale senza prefisso telefonico internazionale. example: '4155552671' full_number: type: string description: Numero completo in formato E.164. example: '+14155552671' country_code: type: string nullable: true description: Paese ISO 3166-1 alpha-2 del numero. example: US country_name: type: string description: Nome completo del paese ricavato da `country_code`. example: United States carrier: type: object description: >- Rete attuale che serve il numero, derivata dalla ricerca dell'operatore eseguita al momento della finalizzazione. properties: name: type: string description: >- Nome dell'operatore telefonico. Stringa vuota quando la ricerca non è riuscita a identificarlo. type: type: string description: >- Tipo di linea restituito dalla ricerca: `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `pager`, `payphone`, `satellite`, `service`, `shared_cost`, `short_codes_commercial`, `calling_cards`, `local_rate`, `universal_access`, `voice_mail`, `other` o `unknown`. is_disposable: type: boolean description: >- `true` quando il numero appartiene a un servizio di numeri temporanei/usa e getta. is_virtual: type: boolean description: >- `true` quando il tipo di linea è virtuale (`voip`, `isp` o `vpn`). verification_method: type: string description: >- Canale che ha effettivamente consegnato l'OTP una volta confermata la consegna (ad es. `whatsapp`, `sms`); fino a quel momento, il canale richiesto. verification_attempts: type: integer description: >- Numero di invii dell'OTP per questa verifica (1, oppure 2 dopo un nuovo tentativo). verified_at: type: string format: date-time nullable: true description: >- Data e ora di inserimento del codice corretto. `null` se la verifica non è mai stata approvata. warnings: type: array description: >- Avvisi di rischio registrati durante la verifica (duplicate, disposable, VoIP, attempts exceeded, blocklist, ecc.). Array vuoto se non ne è presente alcuno. items: type: object properties: feature: type: string description: Funzionalità che ha generato l'avviso. Sempre `PHONE` qui. risk: type: string description: Codice di rischio leggibile dalla macchina. additional_data: type: object nullable: true description: >- Contesto specifico del rischio (ad es. l'ID della sessione duplicata per i rischi di duplicazione). `null` quando il rischio non include dati aggiuntivi. log_type: type: string enum: - error - warning - information description: >- Gravità. I rischi `error` comportano il rifiuto della verifica, `warning` la contrassegna per la revisione, `information` viene registrato senza influire sullo stato. short_description: type: string description: Riepilogo del rischio su una riga leggibile dall'utente. long_description: type: string description: Spiegazione di facile lettura del rischio. lifecycle: type: array description: >- Traccia di audit cronologica della verifica. L'evento `type` è uno tra `PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`, `PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `PHONE_VERIFICATION_APPROVED`, `PHONE_VERIFICATION_DECLINED`, `PHONE_VERIFICATION_IN_REVIEW`, `PHONE_VERIFICATION_EXPIRED`. items: type: object properties: type: type: string description: Tipo di evento. timestamp: type: string format: date-time description: Data e ora in cui si è verificato l'evento. details: type: object nullable: true description: >- Payload specifico dell'evento. Eventi di invio: `{status, reason, channel, actual_channel}` (`actual_channel` viene compilato una volta confermata la consegna). Eventi di consegna: `{channel, status}`. Eventi di inserimento codice: `{code_tried, status}`. Eventi di stato finale: `null`, o `{reason}` se rifiutata o in revisione. fee: type: number description: >- Importo in USD fatturato per questo evento. Diverso da zero solo per gli eventi di invio (il prezzo di consegna); 0 per inserimenti di codici, conferme di consegna ed eventi di stato. matches: type: array description: >- Altre sessioni della tua applicazione (KYC, KYB o API) in cui lo stesso numero di telefono è stato utilizzato da un utente diverso (`vendor_data` differente). Fino a 5 voci; una corrispondenza sintetica della blocklist da voce di elenco compare per prima, se presente (le corrispondenze derivate dalla sessione mantengono l'ordine della query). Array vuoto quando non ci sono corrispondenze. items: type: object properties: session_id: type: string format: uuid description: >- ID sessione dell'altra verifica che ha utilizzato questo numero di telefono. session_number: type: integer description: Numero progressivo di facile lettura di tale sessione. vendor_data: type: string nullable: true description: '`vendor_data` di quella sessione.' verification_date: type: string description: >- Data e ora di creazione di quella sessione (`YYYY-MM-DDTHH:MM:SSZ`). phone_number: type: string description: Il numero di telefono corrispondente. status: type: string description: >- Stato di quella sessione (ad es., `Approved`, `Declined`, `In Progress`). is_blocklisted: type: boolean description: >- Indica se il numero di telefono è presente nella blocklist della tua applicazione. api_service: type: string nullable: true description: >- Per le sessioni di tipo API, l'API standalone che l'ha creata (es. `PHONE_VERIFICATION`); `null` per le normali sessioni di verifica. source: type: string description: >- Dove è stata trovata la corrispondenza. Di solito `session`; un riscontro nella blocklist tramite una voce dell'elenco dell'organizzazione antepone una corrispondenza sintetica con `source: "list_entry"` e `session_id`/`session_number` nulli. phone_social: $ref: '#/components/schemas/PhoneSocialFootprint' phone_intelligence: allOf: - $ref: '#/components/schemas/PhoneIntelligence' description: >- Segnali di intelligence telefonica. Presenti solo quando `enable_enrichment` era `true` nel controllo. vendor_data: type: string nullable: true description: >- `vendor_data` della sessione della verifica corrispondente. `null` in caso di `Expired or Not Found`. metadata: type: object nullable: true description: >- `metadata` della sessione di verifica corrispondente. `null` in caso di `Expired or Not Found`. created_at: type: string format: date-time description: Timestamp della risposta a questo controllo. PhoneSocialFootprint: type: object nullable: true description: >- Impronta social del numero di telefono: le piattaforme online su cui risulta registrato. Presente solo quando è stato impostato `enable_social` e il controllo è stato completato. Ciascun conteggio può essere null se non sono stati restituiti dati al riguardo. `profiles_registered: 0` indica che le piattaforme sono state controllate e il numero di telefono non è stato trovato su nessuna di esse: una risposta valida e fatturabile, nonché un tipico segnale di identità sintetica. properties: profiles_registered: type: integer nullable: true description: Piattaforme in cui il numero di telefono risulta registrato. example: 5 profiles_checked: type: integer nullable: true description: Piattaforme valutate per la registrazione. example: 14 names_found: type: integer nullable: true description: Piattaforme che hanno restituito un nome associato. example: 0 photos_found: type: integer nullable: true description: Piattaforme che hanno restituito una foto del profilo. example: 0 communication_breadth: type: integer nullable: true description: Piattaforme di comunicazione con presenza rilevata. example: 2 digital_footprint_diversity: type: integer nullable: true description: Categorie di piattaforma distinte con presenza rilevata. example: 5 digital_sophistication_index: type: integer nullable: true description: Indicatore composito di maturità digitale, 0-10. example: 5 engagement_depth_index: type: integer nullable: true description: Indicatore della ricchezza del profilo, 0-10. example: 3 subscription_affordability_index: type: integer nullable: true description: Mix di piattaforme gratuite rispetto a quelle a pagamento, 0-10. example: 2 free_platforms: type: integer nullable: true description: Registrazioni su piattaforme gratuite. example: 4 full_paid_platforms: type: integer nullable: true description: Registrazioni su piattaforme a pagamento completo. example: 0 partial_paid_platforms: type: integer nullable: true description: Registrazioni su piattaforme freemium. example: 1 whatsapp_profile_completeness: type: string nullable: true enum: - Basic - Partial - Complete - Not Present - null description: Completezza del profilo WhatsApp. Solo telefono; null per email. example: Partial registered_platforms: type: array description: Piattaforme in cui la registrazione è confermata. items: $ref: '#/components/schemas/SocialFootprintPlatform' not_registered_platforms: type: array description: Piattaforme verificate con esito negativo. items: $ref: '#/components/schemas/SocialFootprintPlatform' categories: type: object description: Numero di registrazioni e percentuale per categoria di piattaforma. additionalProperties: $ref: '#/components/schemas/SocialFootprintCategorySummary' profiles: type: object description: >- Dettagli del profilo per piattaforma, indicizzati per piattaforma, quando la piattaforma li rende disponibili. additionalProperties: $ref: '#/components/schemas/SocialFootprintProfile' PhoneIntelligence: type: object description: >- Blocco normalizzato di phone intelligence. Presente solo quando l'add-on di intelligence è stato eseguito per questa ricerca; se presente, è esposto anche sotto l'alias `enrichment` con valori identici. properties: score: type: number nullable: true description: >- Punteggio di rischio normalizzato da 0 a 100. Più alto è il punteggio, maggiore è il rischio. phone_type_risk: type: string nullable: true description: '`Low`, `Medium` o `High`, derivato dal punteggio.' phone_trust_index: type: number nullable: true description: >- Inverso del punteggio, per le dashboard che preferiscono un valore più alto come migliore. network_stability_index: type: number nullable: true description: Stabilità della rete della linea. is_disposable: type: boolean nullable: true description: '`true` quando il numero sembra essere usa e getta o virtuale.' is_ported: type: boolean nullable: true description: '`true` quando il numero ha cambiato operatore.' is_recently_ported: type: boolean nullable: true description: '`true` quando la portabilità è avvenuta di recente.' carrier_type: type: string nullable: true description: Classificazione della linea rilevata dalla ricerca (es. `mobile`). reason_codes: type: array items: type: object properties: code: type: string description: >- Identificatore Didit stabile del segnale, ad esempio `IR-5AC67A32`. Opaco: usalo per raggruppare e filtrare, non analizzarlo. value: nullable: true description: >- Per un flag di rischio (ad esempio `voip`, `leaked`, `disposable`, `spam_trap`), il suo valore: un booleano, un livello o una data. Null per un codice motivo con punteggio. direction: type: string enum: - risk - trust description: >- Indica se il segnale ha aumentato il rischio o ha aggiunto affidabilità. message: type: string description: Spiegazione di facile lettura del segnale, in inglese. impact_level: type: string nullable: true description: >- Con quale intensità il segnale ha modificato il punteggio, ad esempio `low`, `medium` o `high`. description: >- Segnali che spiegano il punteggio, ciascuno con un codice Didit stabile, una direzione, un messaggio e un livello di impatto. Nel tempo possono comparire nuovi codici, pertanto non rifiutare i codici sconosciuti. SocialFootprintPlatform: type: object properties: platform: type: string description: Identificatore della piattaforma. example: whatsapp category: type: string description: >- Categoria della piattaforma, ad es. MESSAGING, SOCIAL_MEDIA, ECOMMERCE, PROFESSIONAL, EMAIL_PROVIDER. example: MESSAGING scope: type: string enum: - global - local description: >- `global` per piattaforme globali, `local` per quelle specifiche di una regione. example: global SocialFootprintCategorySummary: type: object properties: registered: type: integer nullable: true description: >- Piattaforme in questa categoria in cui la registrazione è confermata. example: 2 ratio: type: number format: float nullable: true description: >- Quota delle piattaforme verificate della categoria con una registrazione, 0.0-1.0. example: 0.6667 SocialFootprintProfile: type: object properties: name: type: string nullable: true description: Nome del profilo, se esposto dalla piattaforma. photo: type: string nullable: true description: URL della foto del profilo, se esposto dalla piattaforma. about: type: string nullable: true description: >- Testo della bio/sezione informazioni del profilo, se esposto dalla piattaforma. privacy_status: type: string nullable: true enum: - PUBLIC - PRIVATE - null description: Visibilità del profilo, se esposta dalla piattaforma. business_account: type: boolean nullable: true description: >- Indica se il profilo è un account aziendale, quando la piattaforma lo rende disponibile. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.