Passer au contenu principal
GET
/
v1
API de validation de numéros de téléphone
curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
L’utilisation est très simple : soumettez votre clé API et un numéro de téléphone. L’API indique si le numéro est structurellement valide (selon Google libphonenumber) et, lorsqu’il est valide, les formats E.164 normalisés ainsi que des métadonnées optionnelles telles que le type de ligne, des indications de géocodage et les données opérateur lorsqu’elles sont 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 HLR/SMS 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

https://phonevalidation.cleariflow.com/v1/

​
Ce que signifie valid

validSignification
trueLe numéro est structurellement valide pour sa région détectée (libphonenumber IsValidNumber).
falseLe numéro n’a pas pu être analysé ou ne respecte pas les règles de format régional. format, country, location, type et carrier sont toujours vides ; phone ne contient que les chiffres de votre saisie.
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 : 
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
Réponse valide (phone=14155552671, country=US) : 
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
Réponse non valide (phone=123, country=US) : 
{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

​
Paramètres de requête

​
api_key
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.
​
phone
String
requis
Le numéro de téléphone à valider (contrôle structurel selon libphonenumber).
​
country
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.
​
phone
String
Chiffres E.164 normalisés (sans +) lorsque valid est true. Lorsque valid est false, uniquement les chiffres de votre saisie.
​
valid
Boolean
true lorsque le numéro est structurellement valide selon libphonenumber. Il ne s’agit pas d’une vérification du statut de ligne ou de l’abonné.
​
format
Object
Formats international et local. Chaînes vides lorsque valid est false.
​
format.international
String
Format E.164 avec un + initial. Vide lorsque valid est false.
​
format.local
String
Format national pour la région détectée. Vide lorsque valid est false.
​
country
Object
Pays/territoire détecté. Champs vides lorsque valid est false.
​
country.code
String
Code à deux lettres ISO 3166-1 alpha-2 pour la région détectée.
​
country.name
String
Nom d’affichage en anglais pour country.code.
​
country.prefix
String
Indicatif téléphonique international (p. ex. +1).
​
location
String
Indication de géocodage issue des métadonnées libphonenumber (région, état/province ou ville). Souvent vide en dehors de US/CA. Vide lorsque valid est false.
​
type
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.
​
carrier
String
Nom de l’opérateur issu des métadonnées libphonenumber lorsqu’il est disponible (le plus souvent US/CA). Chaîne vide sinon, y compris 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.
CodeTypeDetails
200OKTout a fonctionné comme prévu.
400Bad requestRequête incorrecte.
401UnauthorizedLa requête n’était pas acceptable. Généralement en raison d’une clé API manquante ou incorrecte.
422Quota reachedLa requête a été interrompue en raison de crédits API insuffisants. (Offres gratuites)
429Too many requestsLa requête a été interrompue car le nombre de requêtes autorisées par seconde a été atteint. Sur les offres gratuites, les requêtes sont limitées à 1 par seconde.
500Internal server errorLa requête n’a pas pu être traitée en raison d’une erreur côté serveur.
503Service unavailableLe serveur n’était pas disponible.

​
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.