Skip to main content
GET
API de validation de numéros de téléphone
L’utilisation est simple : envoyez votre clé API et un numéro de téléphone. L’API indique si le numéro est structurellement valide et, s’il est valide, renvoie des formats E.164 normalisés ainsi que des métadonnées optionnelles : type de ligne, géocodage, opérateur, fuseaux horaires et indicatifs d’appel lorsque disponibles.
valid: true signifie que le numéro respecte les règles de format régional (longueur, préfixe, syntaxe). Cela ne confirme pas que la ligne est active, attribuée à un abonné ou joignable. Pour le statut de ligne en temps réel, il faut un carrier lookup, qui dépasse le cadre de cette API.

Premiers pas

REST

L’API de validation de numéros de téléphone, comme toutes les API Cleariflow, est organisée autour de REST. Elle est conçue pour utiliser des URL prévisibles orientées ressources et des codes de statut HTTP pour signaler les erreurs.

HTTPS

L’API de validation de numéros de téléphone exige que toutes les communications soient sécurisées avec TLS 1.2 ou supérieur.

Versions de l’API

Toutes les API Cleariflow sont versionnées. L’API de validation de numéros de téléphone est actuellement en version 1.

Votre clé API

Votre clé API est votre clé d’authentification unique pour l’API de validation de numéros de téléphone Cleariflow. Notez que chaque API Cleariflow possède une clé API unique ; vous aurez donc besoin de clés différentes pour accéder à la validation téléphonique et à la validation d’e-mail, par exemple. Pour authentifier vos requêtes, ajoutez votre clé API à l’URL de base.

URL de base

Ce que signifie valid

Les numéros fictifs 555 américains et d’autres plages structurellement valides mais non attribuées peuvent toujours renvoyer valid: true. carrier et location sont renseignés principalement à partir des métadonnées US/CA et sont souvent vides ailleurs.

Point de terminaison de validation

L’API exige votre clé API unique et le numéro de téléphone à vérifier :
Réponse valide (phone=14155552671, country=US) :
Réponse non valide (phone=123, country=US) :

Paramètres de requête

String
requis
Votre clé API unique. Notez que chaque utilisateur dispose de clés API uniques pour chacune des API Cleariflow ; votre clé Phone Validation ne fonctionnera donc pas pour votre API de géolocalisation IP, par exemple.
String
requis
Le numéro de téléphone à valider.
String
Indication optionnelle ISO 3166-1 alpha-2 pour les numéros au format national sans + initial. Par exemple, country=US aide à analyser 4155552671. Les numéros avec un préfixe international sont analysés à partir de leur indicatif pays ; le country.code détecté dans la réponse peut différer de cette indication (p. ex. GG pour certaines plages mobiles +44).

Paramètres de réponse

La réponse de l’API est renvoyée dans un format JSON universel et léger.
String
Chiffres E.164 normalisés (sans +) lorsque valid est true. Lorsque valid est false, uniquement les chiffres de votre saisie.
Boolean
true lorsque le numéro est structurellement valide. Il ne s’agit pas d’une vérification du statut de ligne ou de l’abonné.
Boolean
Contrôle de longueur souple (). true lorsque les chiffres et la longueur pourraient correspondre à un vrai numéro, même si valid est false.
String
Présent lorsque valid est false. Une des valeurs : not_a_number, possible, possible_local_only, invalid_country_code, too_short, invalid_length, too_long, unknown. Omis lorsque valid est true.
Object
Formats international et local. Chaînes vides lorsque valid est false.
String
Format E.164 avec un + initial. Vide lorsque valid est false.
String
Format national pour la région détectée. Vide lorsque valid est false.
Object
Pays/territoire détecté. Champs vides lorsque valid est false.
String
Code à deux lettres ISO 3166-1 alpha-2 pour la région détectée.
String
Nom d’affichage en anglais pour country.code.
String
String
Indication de géocodage issue (région, état/province ou ville). Souvent vide en dehors de US/CA. Vide lorsque valid est false.
String
Type de ligne lorsque valid est true : Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special ou Unknown. Toujours Unknown lorsque valid est false.
String
Nom de l’opérateur issu lorsqu’il est disponible (le plus souvent US/CA). Chaîne vide sinon, y compris lorsque valid est false.
String
Nom d’opérateur sûr pour l’affichage utilisateur (numéro valide et région sans portabilité mobile). Vide si valid est false ou si l’opérateur ne peut pas être affiché en toute sécurité.
Array
Identifiants de fuseau horaire IANA (ex. America/New_York). Tableau vide si valid est true sans correspondance ; null si valid est false.
Boolean
Indique si le numéro est associé à une région géographique. Toujours false lorsque valid est false.
Boolean
Indique si le numéro peut être composé depuis l’extérieur de sa région d’origine. Toujours false lorsque valid est false.

Import en masse (CSV)

Bonnes pratiques lors de l’import en masse d’un fichier CSV :
  • Assurez-vous que la première colonne contient les numéros de téléphone à analyser.
  • Supprimez les lignes vides du fichier.
  • N’incluez qu’un seul numéro de téléphone par ligne.
  • La taille maximale autorisée du fichier est de 50 000 lignes.

Codes de réponse et d’erreur

Lorsqu’une requête échoue pour une raison quelconque, une erreur est également renvoyée au format JSON. Les erreurs comprennent un code et une description, détaillés ci-dessous.

Autres remarques

Note sur la facturation à l’usage : chaque numéro de téléphone soumis compte comme un crédit utilisé. Les crédits sont également comptés par requête, et non par réponse réussie. Ainsi, si vous soumettez une requête pour le numéro (non valide) « kasj8929hs », cela compte toujours pour 1 crédit.