> ## 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. # Vérification du téléphone : API d'envoi de code SMS > POST /v3/phone/send/ de Didit envoie un code SMS à usage unique. Nouvel essai auto si numéro bloqué, validité 5 min, sans minimum mensuel. ## Nommer votre marque dans le SMS Les codes SMS portent le nom d'expéditeur des SMS de votre application, défini dans la Business Console, sans frais supplémentaires : > 123456 est votre code de vérification pour **Acme Bank** Pour envoyer un code avec un autre nom, transmettez `options.sms_sender_name` (de 1 à 30 caractères : lettres, chiffres, espaces et ' & - ! uniquement, et non uniquement des chiffres) : ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` Un nom ne respectant pas ces règles renvoie `400` et aucun code n'est envoyé. Les codes WhatsApp utilisent un message fixe et ne sont pas personnalisés ; connectez votre propre numéro WhatsApp Business dans la Business Console pour les envoyer sous le nom de votre entreprise. Voir [Envoyer des codes WhatsApp depuis votre propre numéro](https://docs.didit.me/fr/core-technology/phone-verification/overview.md#envoyer-des-codes-whatsapp-depuis-votre-propre-numéro). Consultez [Messages de vérification personnalisés](https://docs.didit.me/fr/core-technology/phone-verification/overview.md#messages-de-vérification-personnalisés-avec-votre-marque) pour savoir quel nom figure sur un code et connaître la limite quotidienne de nouveaux noms. ## Gérer les pannes du fournisseur Si le fournisseur de téléphonie est temporairement indisponible, cet endpoint renvoie `502` avec un code stable lisible par machine : ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Considérez cette réponse comme indiquant qu'une nouvelle tentative est possible. Appliquez un court délai avant de réessayer, et affichez à l'utilisateur un message indiquant un service temporairement indisponible, au lieu de lui demander de modifier un numéro de téléphone ou un code valides. ## OpenAPI ````yaml fr/openapi-25.json POST /v3/phone/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/send/: post: tags: - Standalone APIs summary: Envoyer le code par téléphone description: >- Envoyez un code à usage unique (OTP) à un numéro de téléphone via WhatsApp, SMS ou un autre canal pris en charge, puis vérifiez-le avec [`POST /v3/phone/check/`](/fr/standalone-apis/phone-check). **Comment fonctionnent l'envoi et la vérification.** L'état de la vérification est associé à votre application et au `phone_number` au format E.164 — l'appel de vérification ne prend pas de `request_id`. Chaque nouvel envoi crée une vérification en attente valable pendant **5 minutes** : appelez la vérification avec le même numéro et le code reçu par l'utilisateur avant la fermeture de la fenêtre. Appeler à nouveau l'envoi pour le même numéro alors qu'une vérification est en attente renvoie un code pour cette même vérification (`status: "Retry"`, même `request_id`). Au maximum une nouvelle tentative est associée de cette façon (deux envois au total) ; un envoi supplémentaire démarre une nouvelle vérification avec un nouveau `request_id`. La fenêtre de 5 minutes est calculée à partir du premier envoi et n'est pas prolongée par les nouvelles tentatives. **Canaux de livraison.** `options.preferred_channel` sélectionne le canal (`whatsapp` par défaut ; `sms`, `telegram`, `voice`, `rcs`, `viber` et `zalo` sont également pris en charge). Lorsque le canal préféré n'est pas disponible pour le pays ou le numéro de destination, la livraison bascule automatiquement vers le SMS — l'envoi indique toujours `Success`, et le canal réellement utilisé est indiqué dans la réponse de vérification (`phone.verification_method` et les événements `lifecycle`). **Personnalisation de marque.** Les codes SMS comportent le nom d'expéditeur SMS de votre application, configuré dans la Business Console, sans frais supplémentaires. Transmettez `options.sms_sender_name` pour signer un code avec un autre nom, ou `options.use_white_label_customization: true` pour utiliser par défaut votre nom public en marque blanche lorsqu'aucun nom d'expéditeur n'est défini. Les codes WhatsApp utilisent un message fixe ; associez votre propre numéro WhatsApp Business dans la Business Console pour les envoyer depuis le nom et le numéro de votre entreprise ; ces envois sont facturés uniquement au tarif Didit. **Statuts d'envoi.** `Success` — OTP envoyé pour une nouvelle vérification ; `Retry` — OTP renvoyé pour la vérification en attente ; `Blocked` — la couche antifraude a refusé l'envoi (voir `reason`, par ex. `repeated_attempts`, `suspicious`, `spam`). Un envoi `Blocked` finalise immédiatement la vérification avec le statut `Declined` et un avertissement de risque élevé, de sorte qu'une vérification ultérieure renvoie `Expired or Not Found`. **Facturation.** Le prix dépend du pays de destination et du canal par lequel le message est effectivement envoyé — consultez [Tarifs de la Vérification du téléphone](/fr/getting-started/phone-verification-pricing). Seuls les envois `Blocked` sont garantis gratuits : toute autre tentative d'envoi non facturée est débitée lors de la finalisation ou de l'expiration de la vérification, même si la livraison n'a jamais été confirmée ou si le prestataire de livraison a signalé le message comme non distribuable. Les vérifications sont toujours gratuites. Par mesure de lutte contre les abus, la vérification du téléphone est désactivée jusqu'à la première recharge de votre organisation (`403`). **Persistance de session.** Chaque nouvelle vérification est conservée sous la forme d'une session de type API : `request_id` est un véritable identifiant de session que vous pouvez transmettre à `GET /v3/session/{sessionId}/decision/`, la vérification apparaît dans la Business Console et les webhooks `status.updated` sont déclenchés au fur et à mesure de sa progression. **Sandbox.** Les clés API sandbox contournent la livraison et la facturation : après validation de la requête (une saisie mal formée renvoie toujours `400`), l'endpoint renvoie un payload statique `Success` avec un `request_id` aléatoire ; aucun message n'est envoyé et rien n'est conservé. Utilisez le code `123456` lors de la vérification sandbox. **Authentification.** Envoyez la clé API de votre application dans l'en-tête `x-api-key`. Des identifiants manquants ou invalides renvoient `403` (`{"detail": "You do not have permission to perform this action."}`) — cette API ne renvoie jamais `401`. **Limites de débit.** Budget d'écriture partagé de 300 requêtes/min par clé API sur tous les endpoints POST/PATCH/DELETE, plus un plafond anti-abus de 4 tentatives d'envoi par numéro de téléphone et par heure ; tout dépassement renvoie `429`. operationId: post_v3phone_send requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- Numéro de téléphone du destinataire au format E.164 — avec un `+` initial et l'indicatif du pays (par ex., `+14155552671`). Les numéros sont validés et normalisés au format E.164 ; les numéros invalides ou impossibles à analyser renvoient une erreur `400` avec une erreur sur le champ `phone_number`. example: '+14155552671' options: type: object description: >- Options de livraison de l'OTP. Tous les champs sont facultatifs. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: Nombre de chiffres dans l'OTP. locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- Paramètre régional BCP-47 utilisé pour localiser le message de vérification (par ex. `en-US`, `fr`, `es`). Les formats non valides renvoient `400`. example: en-US preferred_channel: type: string enum: - whatsapp - sms - telegram - voice - rcs - viber - zalo default: whatsapp description: >- Canal de livraison préféré. Si le canal est indisponible pour le pays ou le numéro de destination, le message bascule automatiquement sur SMS — l'envoi indique toujours `Success`. use_white_label_customization: type: boolean default: false description: >- Lorsque la valeur est `true`, l'envoi est en marque blanche : si votre application ne dispose pas de nom d'expéditeur SMS, le SMS mentionne à la place votre nom public en marque blanche ("123456 est votre code de vérification pour Acme Bank"). Votre nom d'expéditeur SMS, lorsqu'il est défini, est utilisé avec ou sans cet indicateur. S'applique aux messages SMS, y compris lors d'un repli par SMS depuis un autre canal ; les codes WhatsApp sont envoyés avec un message fixe et ne comportent pas d'image de marque. Valeur par défaut : `false`. sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: "Le nom affiché dans le SMS de ce code («\_123456 est votre code de vérification pour Acme Bank\_»), au lieu du nom d'expéditeur SMS de votre application. Gratuit. 1 à 30 caractères\_: lettres, chiffres, espaces et ' & - ! uniquement, pas uniquement des chiffres, avec des espaces simples entre les mots\_; toute autre valeur renvoie `400` et aucun code n'est envoyé. En cas d'omission, de valeur `null` ou vide, le nom d'expéditeur SMS de votre application est utilisé. Chaque application peut commencer à utiliser jusqu'à deux nouveaux noms par jour (UTC)\_; au-delà, le code est envoyé avec le nom de votre application. S'applique aux messages SMS, y compris lors d'un basculement par SMS depuis un autre canal\_; les codes WhatsApp ne comportent pas de marque." pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- Signaux d'appareil et de réseau optionnels concernant l'utilisateur final, transmis à la couche antifraude pour améliorer la détection de trafic abusif ou automatisé. Tous les champs sont optionnels. properties: ip: type: string description: >- Adresse de l'appareil de l'utilisateur final. IPv4 ou IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identifiant unique de l'appareil de l'utilisateur final. Android : `ANDROID_ID` ; iOS : `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plateforme de l'appareil de l'utilisateur final. device_model: type: string maxLength: 255 description: Modèle de l'appareil de l'utilisateur final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Version du système d'exploitation de l'appareil de l'utilisateur final. example: 18.0.1 app_version: type: string maxLength: 64 description: Version de votre application. example: 1.2.34 user_agent: type: string maxLength: 512 description: >- Agent utilisateur du navigateur ou de l'application de l'utilisateur final. example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 vendor_data: type: string description: >- Identifiant optionnel contrôlé par l'appelant (votre identifiant utilisateur interne, un e-mail, un UUID, etc.) persisté sur la session et renvoyé dans la réponse d'envoi, la réponse de vérification de correspondance, les webhooks et la Business Console. Utilisez-le pour corréler le `request_id` de Didit avec votre dossier utilisateur. metadata: type: object nullable: true description: >- Objet JSON libre optionnel conservé sur la session et renvoyé dans la réponse d'envoi, la réponse de vérification de correspondance, les webhooks et la Business Console. required: - phone_number examples: WhatsApp (default): summary: >- OTP à 6 chiffres via WhatsApp, avec basculement automatique vers les SMS value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Forcer la livraison par SMS avec un code à 4 chiffres value: phone_number: '+34699999999' options: preferred_channel: sms code_size: 4 locale: es With fraud signals: summary: >- Transmettez les signaux de l'appareil pour renforcer le filtrage antifraude value: phone_number: '+14155552671' signals: ip: 192.0.2.1 device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: ios device_model: iPhone17,2 os_version: 18.0.1 app_version: 1.2.34 vendor_data: user-1234 responses: '200': description: >- Envoi pris en compte. Examinez `status` : `Success` et `Retry` indiquent qu'un code est en cours d'envoi ; `Blocked` signifie que la couche antifraude a refusé et que la vérification est déjà finalisée en tant que `Declined`. `request_id` est l'identifiant de session persistant (même identifiant lors d'un `Retry`). content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: OTP envoyé pour une nouvelle vérification value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Deuxième envoi pour le même numéro dans la fenêtre de 5 minutes — même request_id value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Blocked: summary: >- Refus anti-fraude — vérification finalisée avec le statut Declined, rien n'est facturé value: request_id: 0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3 status: Blocked reason: repeated_attempts vendor_data: user-1234 metadata: null '400': description: >- Erreur de validation. Une entrée malformée renvoie l'enveloppe d'erreur de champ de DRF (un tableau de messages par champ en cause, imbriqué sous `options` pour les erreurs d'option). Un numéro dont l'analyse réussit mais qui est rejeté au moment de l'envoi (inaccessible ou type de ligne non éligible tel qu'un code court) renvoie plutôt une enveloppe `{"detail": ...}`. content: application/json: examples: Invalid phone number (field error): summary: Le numéro n'est pas au format E.164 valide value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number` non inclus dans le corps' value: phone_number: - This field is required. Invalid options: summary: >- `code_size` hors limites, `locale` malformée, `preferred_channel` inconnu value: options: code_size: - Ensure this value is less than or equal to 8. locale: - Ensure this field has no more than 5 characters. preferred_channel: - '"carrier_pigeon" is not a valid choice.' Number rejected at send time: summary: >- Format E.164 valide mais le numéro ne peut pas recevoir d'OTP value: detail: Invalid phone number provided. Ineligible line type: summary: >- Le type de ligne ne peut pas recevoir d'OTP (par exemple, numéro court) value: detail: Invalid phone line type provided. '403': description: "Permission refusée. Renvoyé lorsque l'en-tête `x-api-key` est manquant (`{\"detail\": ...}`)\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Également renvoyé avant tout envoi lorsque l'organisation n'a jamais rechargé son solde (protection anti-abus) ou lorsque son solde ne permet pas de couvrir le prix d'envoi vers la destination (`{\"error\": ...}`)." content: application/json: examples: Missing or invalid API key: summary: Aucun en-tête `x-api-key`, ou la clé est non valide/révoquée value: detail: You do not have permission to perform this action. Top-up required: summary: >- La vérification du téléphone reste désactivée jusqu'à la première recharge de l'organisation value: detail: >- To protect against abuse, phone verification is disabled until your first top-up. Not enough credits: summary: >- Le solde de l'organisation ne peut pas couvrir le prix d'envoi value: error: You don't have enough credits to perform this request. '429': description: >- Limite de débit dépassée. Les endpoints POST/PATCH/DELETE partagent un budget de 300 requêtes d'écriture par minute par clé API (la création de transactions et l'ingestion d'événements disposent d'un budget distinct de 600). De plus, un plafond anti-abus de 4 tentatives de vérification par numéro de téléphone par heure s'applique en amont. La réponse contient les en-têtes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` et `Retry-After`. Remarque : les en-têtes `X-RateLimit-*`/`Retry-After` accompagnent uniquement l'erreur 429 de la limite d'écriture de 300/min ; l'erreur 429 du plafond par numéro ne comporte aucun en-tête de limitation de débit. content: application/json: examples: Per-number cap: summary: >- Plus de 4 tentatives de vérification pour le même numéro au cours de la dernière heure 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: >- Plus de 300 requêtes d'écriture au cours de la minute actuelle 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: >- Échec inattendu lors de la création de la vérification ne correspondant pas à une panne connue du fournisseur. Peut être réessayé en toute sécurité. content: application/json: examples: Provider error: summary: La livraison de l'OTP n'a pas pu être initiée value: detail: Error creating phone verification schema: type: object properties: detail: type: string '502': description: >- Le fournisseur de vérification du téléphone est temporairement indisponible - une réponse 5xx, un délai d'attente dépassé ou une erreur de connexion persistante après les tentatives automatiques intégrées. Vous pouvez réessayer en toute sécurité ; rien n'est facturé et aucune tentative n'est décomptée. content: application/json: examples: Provider outage: summary: Le fournisseur n'a pas répondu à la requête d'envoi 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/send/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "options": { "code_size": 6, "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.send_code( phone_number="+14155552671", options={ "locale": "en-US", "preferred_channel": "whatsapp", }, vendor_data="user-1234", ) 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.sendCode({ phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\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.PhoneSendCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().sendCode(PhoneSendCodeParams.builder() .phoneNumber("+14155552671") .options(PhoneSendCodeParams.Options.builder() .locale("en-US") .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of("whatsapp")) .build()) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->sendCode([ 'phone_number' => '+14155552671', 'options' => [ 'locale' => 'en-US', 'preferred_channel' => 'whatsapp', ], 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.send_code( phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234" ) 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.SendCodeAsync(new PhoneSendCodeParams { PhoneNumber = "+14155552671", Options = new PhoneSendCodeParamsOptions { Locale = "en-US", PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel("whatsapp"), }, VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationSendResponse: type: object properties: request_id: type: string format: uuid description: >- ID de session de la vérification. Un envoi `Retry` renvoie le même `request_id` que l'envoi initial. Cet identifiant apparaît dans la Business Console, est renvoyé à nouveau par un `POST /v3/phone/check/` finalisé, et peut être transmis à `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Blocked description: >- `Success` — OTP envoyé pour une nouvelle vérification. `Retry` — OTP renvoyé pour la vérification en attente créée par un envoi précédent. `Blocked` — la couche antifraude a refusé l'envoi ; la vérification est immédiatement finalisée comme `Declined` et rien n'est facturé. reason: type: string nullable: true description: >- Raison pour laquelle un envoi a été `Blocked` (par exemple `repeated_attempts`, `suspicious`, `spam`). `null` pour `Success` et `Retry`. vendor_data: type: string nullable: true description: >- Écho des `vendor_data` stockées sur la session (depuis le premier envoi). metadata: type: object nullable: true description: >- Écho des `metadata` stockées sur la session (depuis le premier envoi). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.