API de Validation et de Formatage des Numéros de Téléphone

L'API de validation des numéros de téléphone est prise en charge dans 242 pays.

L'API de Validation et de Formatage des Numéros de Téléphone vous permet de traiter facilement les numéros de téléphone saisis par les utilisateurs dans une grande variété de formats. Que l'entrée soit aussi irrégulière que 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309 ou simplement 2128675309, notre API détectera intelligemment la structure et renverra une version standardisée.

Cet outil convertit automatiquement l'entrée fournie au format E.164, qui est le format reconnu mondialement pour les numéros de téléphone internationaux. Par exemple, +1 212 867 5309 est renvoyé sous la forme +12128675309, ce qui le rend adapté aux systèmes d'appel internationaux et aux intégrations.

Au-delà du formatage, l'API offre des fonctionnalités détaillées de validation des numéros de téléphone. Elle vérifie si le numéro est isValid: true — ce qui signifie qu'il est valide selon les plans de numérotation nationaux. Elle propose également une vérification isPossible: true, indiquant si un numéro pourrait potentiellement exister même s'il n'est pas encore attribué. Ceci est utile pour une prévalidation avant enregistrement ou traitement.

Le paramètre numberType permet d’identifier si le numéro est un mobile, fixe ou VoIP. Ceci est particulièrement utile dans les scénarios où vous ne souhaitez autoriser que les mobiles pour les vérifications par SMS ou les lignes fixes pour les contacts professionnels.

Avec la prise en charge de la reconnaissance des indicatifs régionaux, l’API peut également détecter l’origine géographique du numéro. Par exemple, un numéro commençant par l’indicatif 212 est automatiquement associé à New York City (Manhattan). Cette fonctionnalité est parfaite pour les applications nécessitant une segmentation ou une analyse basée sur la localisation.

Chaque numéro est également associé à des métadonnées au niveau du pays, telles que le code de région ISO (ex. : US) et le code numérique du pays (ex. : 1), permettant une logique et des formats d'affichage spécifiques à la région dans vos applications.

✅ Réponse de l’API

Exemple de réponse JSON :

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"États-Unis",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

Essayez vous-même l’API de validation des numéros

Utilisation de base

Envoyez un numéro de téléphone à l'URL suivante :

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

Vous pouvez obtenir votre clé API gratuite quotidienne avec 200 crédits depuis ce lien.

Paramètre Address

L’API prend également en charge un paramètre optionnel address, très utile lorsque le numéro de téléphone est fourni sans indicatif international. Ce champ aide le système à détecter la région souhaitée et à analyser correctement le numéro. Par exemple, si le numéro fourni est 2128675309 sans indicatif, définir address=US, address=United States ou même address=New York peut permettre à l'API de déterminer que le numéro appartient aux États-Unis.

Le paramètre address accepte des entrées dans plusieurs formats, notamment :

• codes ISO 3166-1 alpha-2 comme US, DE ou TR
• Noms de pays comme Allemagne, Turquie ou Amérique
• Noms de villes ou régions comme Berlin, Istanbul ou New York

Bien qu’il soit optionnel, le champ address devient obligatoire si le numéro de téléphone ne commence pas par un signe plus et un indicatif international (ex. : +1, +44, +90). Sans cette information contextuelle, l'API pourrait ne pas être en mesure d'interpréter correctement le format national.

Exemple avec le paramètre address :

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

Champs de Réponse

Valeurs de Type de Numéro

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

API de validation de numéro via une requête POST

Vous pouvez utiliser la méthode POST pour valider un numéro de téléphone pour les États-Unis. Il suffit de fournir le numéro au format E.164, national ou international accompagné du pays/adresse. Votre clé API doit être envoyée comme un jeton Bearer.

Exemple cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number": "+12128675309", "address": "US"}'

Exemple cURL en PHP

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Exemple d’utilisation de fetch en JavaScript

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Exemple avec la bibliothèque requests en Python

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Bibliothèques clientes

Pour faciliter encore davantage l'intégration, nous proposons une gamme de bibliothèques clientes officielles et prises en charge par la communauté pour différents langages de programmation. Ces bibliothèques vous permettent d’interagir avec les points de terminaison de GenderAPI — comme l'API de validation de numéro de téléphone — sans avoir à gérer manuellement les requêtes HTTP ou l’analyse JSON. Il suffit de choisir la bibliothèque adaptée à votre environnement, de l’installer et de commencer à envoyer des requêtes avec une configuration minimale.

Vous pouvez consulter la liste des bibliothèques clientes disponibles ainsi que les instructions d’installation à la page suivante :
https://www.genderapi.io/fr/docs-client-libraries

Foire aux questions (FAQ)

1. Qu’est-ce que l’API de validation et de formatage des numéros de téléphone ?

L’API de validation et de formatage des numéros de téléphone est un outil qui vous permet de valider, formater et analyser les numéros de téléphone du monde entier. Elle peut convertir les numéros au format standardisé E.164 et déterminer des métadonnées telles que la région, le type (mobile/fixe), la validité, etc.

2. À quoi sert la validation de numéro de téléphone ?

Elle sert à vérifier si un numéro de téléphone est valide, à le formater pour un usage international, à identifier son type (ex. : mobile, VoIP), à détecter les métadonnées régionales et à garantir une saisie propre et standardisée dans un CRM, un outil marketing ou un formulaire d'inscription.

3. Combien de pays sont pris en charge ?

L’API prend en charge les numéros de 242 pays et territoires dans le monde. Cela garantit une couverture globale pour toute application internationale ou régionale.

4. Quels formats sont pris en charge ?

L’API accepte les numéros dans divers formats, tels que national, international ou E.164. Elle les détecte et les normalise automatiquement.

5. Que se passe-t-il si je ne fournis pas le paramètre de pays ou d’adresse ?

Si le numéro ne commence pas par un « + » et qu’aucun pays/adresse n’est fourni, l’API risque de ne pas pouvoir interpréter correctement le numéro. Il est recommandé d’inclure le paramètre address (par exemple US, United States ou New York).

6. L’API peut-elle détecter le type de numéro ?

Oui. L’API renvoie le champ numberType qui indique si le numéro est un MOBILE, FIXED_LINE, VOIP, etc.

7. Quelle est la différence entre isValid et isPossible ?

isValid signifie que le numéro est officiellement attribué et conforme à toutes les règles régionales. isPossible vérifie si le numéro pourrait théoriquement exister en fonction de sa structure, même s’il n’est pas encore attribué.

8. Quel type de réponse renvoie l’API ?

Une réponse réussie inclut le statut, les variantes de numéros formatés (national, international, E.164), les données régionales, le type de numéro, la consommation de crédits, etc. Consultez la section « Exemple de réponse de l’API » pour un exemple complet.

9. Comment dois-je envoyer ma clé API ?

Pour les requêtes GET, ajoutez la clé sous la forme ?key=YOUR_API_KEY. Pour les requêtes POST, utilisez le jeton Bearer dans l'en-tête comme ceci :
"Authorization: Bearer YOUR_API_KEY".

10. Que signifie une réponse status: false ?

Cela signifie que la requête a échoué. Le champ message contiendra la raison de l’erreur, comme des paramètres manquants, un numéro invalide ou un manque de crédits.

11. Les caractères spéciaux ou les espaces sont-ils autorisés dans les entrées ?

Oui, mais ils doivent être encodés en URL pour les requêtes GET. Par exemple, utilisez %20 à la place d’un espace. Voir la section d’avertissement ci-dessus pour une utilisation correcte.

12. Puis-je utiliser des adresses dans différents formats ou langues ?

Oui. En plus des codes ISO 3166-1 alpha-2 (comme US, DE, TR), le paramètre address accepte également les noms complets de pays ou de villes — même dans différentes langues. L’API utilise une IA intégrée pour détecter et interpréter intelligemment le pays ou la région correcte. Par exemple :

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

Toutes ces entrées seront correctement associées à leurs pays ou régions respectifs par l’API sans aucun problème.