> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de validation de numéros de téléphone

> API REST JSON rapide Cleariflow pour la validation structurelle des numéros, normalisation E.164 et détails optionnels sur opérateur, localisation, fuseau horaire et appel.

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.

<Note>
  `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.
</Note>

## 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`

| `valid` | Signification                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`  | Le numéro est structurellement valide pour sa région détectée.                                                                                                                                                                                                                                                                                                                                  |
| `false` | Le numéro n'a pas pu être analysé ou ne respecte pas les règles de format régionales. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical` et `internationally_dialable` sont toujours vides ou false ; `possible` et `invalid_reason` sont renseignés lorsque l'entrée a pu être analysée. `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`) :

<ResponseExample>
  ```json theme={"system"}
  {
    "phone": "14155552671",
    "valid": true,
    "possible": 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": "",
    "carrier_display": "",
    "timezones": ["America/Los_Angeles"],
    "geographical": true,
    "internationally_dialable": true
  }
  ```
</ResponseExample>

**Réponse non valide** (`phone=123`, `country=US`) :

```json theme={"system"}
{
  "phone": "123",
  "valid": false,
  "possible": false,
  "invalid_reason": "too_short",
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": "",
  "carrier_display": "",
  "timezones": null,
  "geographical": false,
  "internationally_dialable": false
}
```

### Paramètres de requête

<ParamField query="api_key" type="String" required>
  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.
</ParamField>

<ParamField query="phone" type="String" required>
  Le numéro de téléphone à valider.
</ParamField>

<ParamField query="country" type="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`).
</ParamField>

### Paramètres de réponse

La réponse de l'API est renvoyée dans un format [JSON](https://www.json.org/json-en.html) universel et léger.

<ResponseField name="phone" type="String">
  Chiffres E.164 normalisés (sans `+`) lorsque `valid` est true. Lorsque `valid` est false, uniquement les chiffres de votre saisie.
</ResponseField>

<ResponseField name="valid" type="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é.
</ResponseField>

<ResponseField name="possible" type="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.
</ResponseField>

<ResponseField name="invalid_reason" type="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.
</ResponseField>

<ResponseField name="format" type="Object">
  Formats `international` et `local`. Chaînes vides lorsque `valid` est false.
</ResponseField>

<ResponseField name="format.international" type="String">
  Format E.164 avec un `+` initial. Vide lorsque `valid` est false.
</ResponseField>

<ResponseField name="format.local" type="String">
  Format national pour la région détectée. Vide lorsque `valid` est false.
</ResponseField>

<ResponseField name="country" type="Object">
  Pays/territoire détecté. Champs vides lorsque `valid` est false.
</ResponseField>

<ResponseField name="country.code" type="String">
  Code à deux lettres [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) pour la région détectée.
</ResponseField>

<ResponseField name="country.name" type="String">
  Nom d'affichage en anglais pour `country.code`.
</ResponseField>

<ResponseField name="country.prefix" type="String">
  [Indicatif téléphonique international](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (p. ex. `+1`).
</ResponseField>

<ResponseField name="location" type="String">
  Indication de géocodage issue (région, état/province ou ville). Souvent vide en dehors de US/CA. Vide lorsque `valid` est false.
</ResponseField>

<ResponseField name="type" 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.
</ResponseField>

<ResponseField name="carrier" type="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.
</ResponseField>

<ResponseField name="carrier_display" type="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é.
</ResponseField>

<ResponseField name="timezones" type="Array">
  Identifiants de fuseau horaire IANA (ex. `America/New_York`). Tableau vide si `valid` est true sans correspondance ; `null` si `valid` est false.
</ResponseField>

<ResponseField name="geographical" type="Boolean">
  Indique si le numéro est associé à une région géographique. Toujours `false` lorsque `valid` est false.
</ResponseField>

<ResponseField name="internationally_dialable" type="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.
</ResponseField>

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

| Code | Type                  | Details                                                                                                                                                            |
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 200  | OK                    | Tout a fonctionné comme prévu.                                                                                                                                     |
| 400  | Bad request           | Requête incorrecte.                                                                                                                                                |
| 401  | Unauthorized          | La requête n'était pas acceptable. Généralement en raison d'une clé API manquante ou incorrecte.                                                                   |
| 422  | Quota reached         | La requête a été interrompue en raison de crédits API insuffisants. (Offres gratuites)                                                                             |
| 429  | Too many requests     | La 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. |
| 500  | Internal server error | La requête n'a pas pu être traitée en raison d'une erreur côté serveur.                                                                                            |
| 503  | Service unavailable   | Le 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.