Rapport de vérification du téléphone : OTP et opérateur

Le rapport de Vérification du téléphone capture l’intégralité du résultat d’une procédure OTP par téléphone : à qui nous avons envoyé le code, quel opérateur et quel canal l’ont traité, combien de tentatives ont été nécessaires, si le numéro est jetable ou VoIP, ainsi que toutes les correspondances inter-sessions avec votre liste de blocage ou les sessions d’autres utilisateurs. Cette page documente la structure JSON renvoyée par l’endpoint de décision afin que vous puissiez analyser les résultats OTP, les métadonnées de l’opérateur et les indicateurs de risque pour chaque numéro vérifié.

Rapport de vérification du téléphone Didit montrant le résultat OTP, les métadonnées de l'opérateur et les indicateurs de risque

Vue d’ensemble

Un rapport téléphonique est généré chaque fois qu’un nœud de workflow exécute la fonctionnalité Vérification du téléphone. Chaque rapport représente une procédure OTP pour un numéro de téléphone et contient :

Le numéro de téléphone décomposé en préfixe, numéro national et format E.164 complet, ainsi que le code pays ISO et le nom du pays.
Les métadonnées de l’opérateur (name, type) obtenues auprès du réseau de destination.
Des indicateurs de risque booléens (is_disposable, is_virtual) issus de l’analyse du type de ligne.
Le canal de livraison effectivement utilisé (verification_method) et le nombre de tentatives d’envoi de l’OTP.
Un journal chronologique lifecycle[] de chaque envoi, nouvelle tentative, événement de livraison et tentative de vérification de code.
Un tableau matches[] faisant ressortir le même numéro sur d’autres sessions — quel que soit le statut, pour le KYC, le KYB et les vérifications d’API autonomes — ou sur votre liste de blocage.
Un tableau warnings[] — événements de risque émis pendant la vérification (voir les avertissements liés à la Vérification du téléphone).
Un node_id qui identifie quel nœud du graphe de workflow a généré le rapport (sessions V3 uniquement).

Dans les flux de vérification hébergés, Didit gère l’échange d’OTP pour vous. Pour les intégrations API directes, le même flux s’effectue en deux appels — POST /v3/phone/send/ pour acheminer le code et POST /v3/phone/check/ pour valider la saisie de l’utilisateur. Un OTP en attente est valide pendant 5 minutes à compter du premier envoi (les nouvelles tentatives ne prolongent pas ce délai). Dans les sessions de workflow, les utilisateurs disposent par défaut de 2 tentatives d’envoi d’OTP (phone_max_retries) et de 2 tentatives de saisie de code (phone_max_check_attempts) — toutes deux configurables par nœud de workflow ; épuiser l’un ou l’autre de ces plafonds finalise l’étape avec le statut Declined et la raison VERIFICATION_CODE_ATTEMPTS_EXCEEDED. L’API téléphonique autonome autorise 3 tentatives de saisie de code par vérification.

Emplacement dans les réponses de l’API

L’endpoint de décision (GET /v3/session/{sessionId}/decision/) renvoie les rapports téléphoniques sous la clé de tableau plurielle phone_verifications. Le tableau contient une entrée par nœud de Vérification du téléphone dans le graphe de workflow — généralement une seule, mais les flux d’authentification renforcée (step-up) peuvent en générer plusieurs.

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "phone_verifications": [
    { "status": "Approved", "node_id": "feature_phone_1", "...": "..." }
  ]
}

Une valeur null signifie qu’aucune étape de Vérification du téléphone n’a encore été exécutée. Parcourez le tableau (plutôt que de lire phone_verifications[0]) lorsque votre workflow peut collecter plusieurs numéros de téléphone.

Schéma

Le schéma champ par champ de référence se trouve sur la page Modèles de données.

interface PhoneVerification {
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  phone_number_prefix: string;       // E.g. "+34"
  phone_number: string;              // National number, no prefix
  full_number: string;               // Full E.164, e.g. "+34600600600"
  country_code: string;              // ISO 3166-1 alpha-2, e.g. "ES"
  country_name: string;
  carrier: {
    name: string;
    type:                              // From LineTypeChoices
      | "mobile" | "fixed_line" | "voip" | "isp" | "vpn"
      | "toll_free" | "premium_rate" | "shared_cost" | "local_rate"
      | "satellite" | "pager" | "payphone" | "voice_mail"
      | "calling_cards" | "service" | "short_codes_commercial"
      | "universal_access" | "other" | "unknown";
  };
  is_disposable: boolean;            // Temporary / burner number
  is_virtual: boolean;               // true when carrier.type is voip, isp or vpn
  verification_method:               // Actual channel that delivered the OTP
    | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo";
  verification_attempts: number;     // OTP send attempts (initial send + resends)
  verified_at: string | null;        // ISO 8601, set when a valid OTP was entered
  warnings: Warning[];               // Risk events emitted during verification
  lifecycle: PhoneLifecycleEvent[];  // OTP send/retry/delivery/check timeline
  matches: PhoneMatch[];             // Cross-session / blocklist matches (max 5)
  node_id: string;                   // Workflow graph node that produced this report
}

Valeurs de statut

Statut	Signification
`Not Finished`	L’envoi de l’OTP a été initié mais la vérification n’a pas encore été finalisée.
`Approved`	L’utilisateur a saisi un OTP valide et aucun risque entraînant un refus ne correspondait.
`Declined`	Un avertissement de refus automatique s’est déclenché (liste de blocage, risque élevé, tentatives dépassées) ou une action de risque configurée avec `DECLINE` a correspondu.
`In Review`	Une action de risque configurée avec `REVIEW` a orienté l’étape vers un examen manuel.
`Expired`	La fenêtre de 5 minutes de l’OTP s’est écoulée sans code valide — s’applique aux vérifications créées via l’API téléphonique autonome.

Types d’événements du cycle de vie

lifecycle[] est trié par ordre chronologique. Chaque événement comporte type, timestamp, details et, le cas échéant, un fee facturable :

Type d’événement	Émis lorsque
`PHONE_VERIFICATION_MESSAGE_SENT`	Première tentative d’envoi d’OTP sur le canal demandé.
`PHONE_VERIFICATION_RETRY_MESSAGE_SENT`	Envoi d’OTP ultérieur après que l’utilisateur a demandé un renvoi.
`PHONE_VERIFICATION_BLOCKED`	L’envoi a été bloqué (spam, activité suspecte, tentatives répétées, numéro invalide).
`PHONE_DELIVERY_DELIVERED`	L’opérateur a confirmé la livraison sur le canal effectivement utilisé.
`PHONE_DELIVERY_UNDELIVERABLE`	L’opérateur a signalé que le message n’a pas pu être livré.
`VALID_CODE_ENTERED`	L’utilisateur a soumis le bon code OTP.
`INVALID_CODE_ENTERED`	L’utilisateur a soumis un code OTP incorrect (décompté de la limite de saisie de code).
`PHONE_VERIFICATION_APPROVED`	Le statut au niveau de la fonctionnalité a été défini comme `Approved`.
`PHONE_VERIFICATION_DECLINED`	Le statut au niveau de la fonctionnalité a été défini comme `Declined`.
`PHONE_VERIFICATION_IN_REVIEW`	Le statut au niveau de la fonctionnalité a été défini comme `In Review`.
`PHONE_VERIFICATION_EXPIRED`	La fenêtre de l’OTP s’est écoulée sans code valide.

Le payload details dépend de la famille d’événements :

Événements d’envoi (PHONE_VERIFICATION_MESSAGE_SENT, PHONE_VERIFICATION_RETRY_MESSAGE_SENT, PHONE_VERIFICATION_BLOCKED) — { status, reason, channel, actual_channel }. status est Success, Retry ou Blocked ; reason est null sauf si l’envoi a été bloqué (invalid_phone_number, repeated_attempts, suspicious, spam, unknown) ; channel est le canal demandé et actual_channel le canal sur lequel le message a effectivement été livré (par exemple, un envoi WhatsApp qui a basculé sur SMS).
Événements de livraison (PHONE_DELIVERY_DELIVERED, PHONE_DELIVERY_UNDELIVERABLE) — { channel, status } avec status valant delivered ou undeliverable.
Événements de vérification (VALID_CODE_ENTERED, INVALID_CODE_ENTERED) — { code_tried, status } avec status valant Approved, Declined, Failed ou Expired or Not Found.
Événements de statut final — null, sauf pour PHONE_VERIFICATION_DECLINED / PHONE_VERIFICATION_IN_REVIEW, qui contiennent { "reason": "<risk code>" } (par exemple PHONE_NUMBER_IN_BLOCKLIST).

fee sur un événement d’envoi correspond au prix total de cet envoi : le prix de l’opérateur ou de WhatsApp plus les frais Didit de $0.02, ou uniquement les frais Didit de $0.02 pour un code WhatsApp envoyé depuis votre propre numéro WhatsApp Business. Il s’agit du prix estimé jusqu’à ce que la livraison soit confirmée, puis du montant réel facturé. Seuls les envois Blocked sont garantis gratuits : tout autre envoi est facturé lorsque la vérification est finalisée ou expire, même si la livraison n’a jamais été confirmée ou si le message n’a pas pu être livré. Les événements de livraison, de vérification et de statut comportent toujours fee: 0.

Correspondances inter-sessions

matches[] enregistre les autres sessions de la même application où le même numéro a été détecté — dans les vérifications KYC et KYB et les vérifications effectuées via l’API autonome, quel que soit leur statut — ainsi que les correspondances de liste de blocage configurées dans les listes de la management-api. Les sessions partageant le vendor_data de la session actuelle sont exclues (le même utilisateur final n’est pas mis en correspondance avec lui-même), et le tableau est limité à 5 entrées. Lorsque le numéro figure sur votre liste de blocage mais qu’aucune des sessions correspondantes n’est sur liste de blocage, une entrée synthétique avec source: "list_entry" (tous les champs de session étant à null) est ajoutée au début du tableau.

interface PhoneMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  phone_number: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}

Exemples

Approuvé — OTP WhatsApp, opérateur mobile

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "600600600",
  "full_number": "+34600600600",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Orange", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:12:39.684292Z",
  "warnings": [],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:12:30.580554Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.0509
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2025-08-24T09:12:31.000000Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:12:39.662157Z",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2025-08-24T09:12:39.684292Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "feature_phone_1"
}

Refusé — numéro VoIP sur liste de blocage

L’utilisateur a saisi un OTP valide, mais la finalisation a détecté le numéro sur la liste de blocage de l’application (refus automatique) et a signalé son type de ligne VoIP (voip_number_action laissé à NO_ACTION, ce qui est donc enregistré comme information). Comme aucune session correspondante n’est sur liste de blocage, la correspondance avec la liste de blocage apparaît sous la forme d’une correspondance synthétique list_entry.

{
  "status": "Declined",
  "phone_number_prefix": "+1",
  "phone_number": "5551234567",
  "full_number": "+15551234567",
  "country_code": "US",
  "country_name": "United States",
  "carrier": { "name": "VoIP Carrier", "type": "voip" },
  "is_disposable": false,
  "is_virtual": true,
  "verification_method": "sms",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:11:10.221340Z",
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "PHONE_NUMBER_IN_BLOCKLIST",
      "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null },
      "log_type": "error",
      "short_description": "Phone number in blocklist",
      "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:11:00.000000Z",
      "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" },
      "fee": 0.0509
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:11:10.221340Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_DECLINED",
      "timestamp": "2025-08-24T09:11:10.350000Z",
      "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "phone_number": "+15551234567",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ],
  "node_id": "feature_phone_1"
}

Pages associées

Aperçu de la vérification du téléphone — comportement de la fonctionnalité, tarifs, canaux pris en charge.
Avertissements de la vérification du téléphone — l’ensemble des codes de risque, déclencheurs de refus et actions configurables.
Modèles de données — vérification du téléphone — schéma champ par champ de référence.
API téléphonique autonome — endpoints POST /v3/phone/send/ et POST /v3/phone/check/.
Management API — Listes — gérer la liste de blocage des numéros de téléphone qui alimente matches[] avec source: list_entry.

Authentification

Vérification

Surveillance

Plateforme

Rapport de vérification du téléphone : OTP et opérateur

Vue d’ensemble

Emplacement dans les réponses de l’API

Schéma

Valeurs de statut

Types d’événements du cycle de vie

Correspondances inter-sessions

Exemples

Approuvé — OTP WhatsApp, opérateur mobile

Refusé — numéro VoIP sur liste de blocage

Pages associées

​Vue d’ensemble

​Emplacement dans les réponses de l’API

​Schéma

​Valeurs de statut

​Types d’événements du cycle de vie

​Correspondances inter-sessions

​Exemples

​Approuvé — OTP WhatsApp, opérateur mobile

​Refusé — numéro VoIP sur liste de blocage

​Pages associées

Vue d’ensemble

Emplacement dans les réponses de l’API

Schéma

Valeurs de statut

Types d’événements du cycle de vie

Correspondances inter-sessions

Exemples

Approuvé — OTP WhatsApp, opérateur mobile

Refusé — numéro VoIP sur liste de blocage

Pages associées