# Validation et formatage du téléphone avec API v2 > Validez et formatez les numéros de téléphone internationaux ou nationaux avec GenderAPI v2. Voir le contexte national requis, les champs JSON et les frais d'un crédit. Canonical HTML: https://www.genderapi.io/fr/docs/v2/phone-validation Last reviewed: 2026-09-25 ## Valider et formater un numéro de téléphone POST /phone/validate accepte number et le champ facultatif country. Utilisez un numéro de téléphone international commençant par +. Pour un numéro de téléphone national, fournissez un code de pays ISO en majuscules. La réponse contient valid, possible, e164, country et country_calling_code dans data, ainsi que l'objet partagé meta. Cela vérifie la structure du numéro de téléphone, et non si l'abonné existe. Chaque validation terminée coûte 1 crédit, y compris les résultats invalides. La réponse illustrative ci-dessous indique un numéro non valide et est indépendante de l'exemple de demande. Exécutez ces exemples sur votre serveur. Définissez GENDERAPI_API_KEY dans l’environnement de processus sur votre clé API existante. Confirmez que meta.access.mode est api_key : une clé non reconnue peut revenir à l'essai IP. Chaque demande de prédiction est une nouvelle opération facturable, y compris les nouvelles tentatives. Ces exemples ne réessayent pas automatiquement. Vérifiez l'état de facturation avant d'envoyer une autre demande. Les réponses HTTP 4xx et 5xx JSON préservent le corps de l'erreur et renvoient un état de sortie différent de zéro. Vérifiez code, action et meta.usage.billing_status avant de réessayer. | Champ JSON | Type | Règle | | --- | --- | --- | | number | string | Obligatoire, 3 à 32 caractères. ASCII chiffres, espaces, parenthèses et traits d’union, avec un signe + facultatif. Les extensions et les caractères alphabétiques ne sont pas acceptés. | | country | string | Code ISO 3166-1 alpha-2 majuscule. Obligatoire pour un numéro de téléphone national. Facultatif lorsque la valeur number commence par +. Omettez ce champ lorsqu'il n'est pas nécessaire. | **cURL** cURL 7.76+ dans un shell POSIX. Exécutez dans votre terminal. ```bash curl --silent --show-error --fail-with-body --max-time 30 \ --request POST 'https://api.genderapi.io/api/v2/phone/validate' \ --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \ --header 'Content-Type: application/json' \ --data '{ "number": "+905321234567" }' ``` **JavaScript / Node.js** Node.js 22+ ; récupération intégrée. Enregistrez sous example.mjs et exécutez node example.mjs. ```javascript // Server-side Node.js. Save as example.mjs. const apiKey = process.env.GENDERAPI_API_KEY; if (!apiKey) throw new Error("Set GENDERAPI_API_KEY"); const body = { "number": "+905321234567" }; const response = await fetch("https://api.genderapi.io/api/v2/phone/validate", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000), redirect: "error", }); const raw = await response.text(); if (!(response.headers.get("content-type") ?? "").includes("json")) { throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`); } const result = JSON.parse(raw); // Also accepts application/problem+json. if (!response.ok) { console.error(`HTTP ${response.status}`, result); process.exitCode = 1; // A retry is a new operation; inspect billing first. } else { console.log(JSON.stringify(result, null, 2)); // For batches, inspect every item: HTTP 200 may contain item errors. } ``` **Python** Python 3.10+ ; bibliothèque standard. Enregistrez sous example.py et exécutez python3 example.py. ```python import json import os import sys import urllib.error import urllib.request api_key = os.environ.get("GENDERAPI_API_KEY") if not api_key: raise RuntimeError("Set GENDERAPI_API_KEY") body = json.loads("{\"number\":\"+905321234567\"}") class NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None request = urllib.request.Request( "https://api.genderapi.io/api/v2/phone/validate", method="POST", data=json.dumps(body).encode("utf-8"), headers={ "Authorization": "Bearer " + api_key, "Content-Type": "application/json", }, ) opener = urllib.request.build_opener(NoRedirect()) try: response = opener.open(request, timeout=30) except urllib.error.HTTPError as error: response = error # Keep the Problem Details body on non-2xx responses. with response: status = response.status raw = response.read().decode("utf-8") if "json" not in response.headers.get("Content-Type", ""): raise RuntimeError(f"HTTP {status}: expected a JSON response") result = json.loads(raw) print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout) if not 200 <= status < 300: sys.exit(1) # Inspect code, action and billing before retrying. # For batches, inspect every item even when HTTP status is 200. ``` **PHP** PHP 8+ avec l'extension cURL. Enregistrez sous example.php et exécutez php example.php. ```php 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $apiKey, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR), ]); $raw = curl_exec($ch); if ($raw === false) { throw new RuntimeException(curl_error($ch)); } $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: ''; curl_close($ch); if (strpos($contentType, 'json') === false) { throw new RuntimeException("HTTP $status: expected a JSON response"); } $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); $output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL; if ($status < 200 || $status >= 300) { fwrite(STDERR, $output); // Preserve the Problem Details body. exit(1); } echo $output; // For batches, inspect every item; HTTP 200 can contain item errors. ``` **Java** Java 17+ ; client standard HTTP. Enregistrez sous GenderApiExample.java et exécutez java GenderApiExample.java. ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; public class GenderApiExample { private static String requiredEnv(String name) { String value = System.getenv(name); if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name); return value; } public static void main(String[] args) throws Exception { String apiKey = requiredEnv("GENDERAPI_API_KEY"); String body = "{\"number\":\"+905321234567\"}"; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .followRedirects(HttpClient.Redirect.NEVER) .build(); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/phone/validate")) .timeout(Duration.ofSeconds(30)) .header("Authorization", "Bearer " + apiKey) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); if (!response.headers().firstValue("content-type").orElse("").contains("json")) { throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON"); } // JSON text; parse with your application's JSON library when integrating. if (response.statusCode() < 200 || response.statusCode() >= 300) { System.err.println(response.body()); // Includes Problem Details. System.exit(1); } System.out.println(response.body()); // For batches, inspect each item's data or error, including on HTTP 200. } } ``` **C# / .NET** Application console .NET 8+. Utilisez comme Program.cs dans un projet de console, puis exécutez dotnet run. ```csharp using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using System.Text.Json; string RequiredEnv(string name) => !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name)) ? Environment.GetEnvironmentVariable(name)! : throw new InvalidOperationException($"Set {name}"); var apiKey = RequiredEnv("GENDERAPI_API_KEY"); using var handler = new HttpClientHandler { AllowAutoRedirect = false }; using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) }; using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/phone/validate"); request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey); request.Content = new StringContent("{\"number\":\"+905321234567\"}", Encoding.UTF8, "application/json"); using var response = await client.SendAsync(request); var raw = await response.Content.ReadAsStringAsync(); if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false)) throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON"); using var result = JsonDocument.Parse(raw); if (!response.IsSuccessStatusCode) { Console.Error.WriteLine(result.RootElement); // Preserve Problem Details. Environment.ExitCode = 1; } else { Console.WriteLine(result.RootElement); // For batches, inspect every item even on HTTP 200. } ``` **Go** Go 1.22+ ; bibliothèque standard. Enregistrez sous main.go et exécutez go run main.go. ```go package main import ( "encoding/json" "fmt" "io" "net/http" "os" "strings" "time" ) func requiredEnv(name string) string { value := os.Getenv(name) if value == "" { panic("Set " + name) } return value } func run() error { apiKey := requiredEnv("GENDERAPI_API_KEY") body := "{\"number\":\"+905321234567\"}" request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/phone/validate", strings.NewReader(body)) if err != nil { return err } request.Header.Set("Authorization", "Bearer " + apiKey) request.Header.Set("Content-Type", "application/json") client := &http.Client{ Timeout: 30 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }, } response, err := client.Do(request) if err != nil { return err } defer response.Body.Close() raw, err := io.ReadAll(response.Body) if err != nil { return err } if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) { return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode) } if response.StatusCode < 200 || response.StatusCode >= 300 { return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw) } fmt.Println(string(raw)) // For batches, inspect every item even on HTTP 200. return nil } func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling. os.Exit(1) } } ``` ```json { "data": { "valid": false, "possible": false, "e164": null, "country": null, "country_calling_code": null }, "meta": { "request_id": "11111111-1111-4111-8111-111111111111", "duration_ms": 12, "access": { "mode": "ip_trial", "reason": "api_key_missing" }, "usage": { "charged_credits": 1, "remaining_credits": 7, "billing_status": "confirmed", "resets_at": "2026-09-26T12:00:00.000Z", "limit": 10, "period_seconds": 86400 } } } ``` ## Lire les champs de validation du téléphone Les entrées mal formées sont rejetées avec HTTP 422 avant la facturation. Si le format de la demande est correct mais que le numéro de téléphone ne peut pas être analysé, l'opération peut renvoyer HTTP 200 avec les champs de formatage valid: false et null. Cette validation terminée coûte 1 crédit. Un nombre qui peut être analysé mais qui n'est pas valide peut toujours avoir une valeur e164. Vérifiez valid ; un numéro formaté ne constitue pas à lui seul une preuve de validité. | Champ à l'intérieur de data | Signification | | --- | --- | | valid | Indique si le numéro correspond aux règles de validation du plan de numérotation. | | possible | Si le numéro a une longueur plausible pour son plan de numérotation ; plus faible que valide. | | e164 | Numéro formaté international lorsque l'analyse réussit, sinon null. | | country | Région dérivée du numéro, ou null en cas d'indisponibilité ; il ne localise pas l'abonné. | | country_calling_code | Code d'appel international numérique, ou null en cas d'indisponibilité. | ## Authentification et tentatives Envoyez votre clé API existante à l'aide de l'authentification Bearer et de Content-Type : application/json. Les exemples lisent GENDERAPI_API_KEY à partir de l'environnement. Le champ country est obligatoire pour les numéros de téléphone nationaux et facultatif lorsque la valeur number commence par +. - [Authentification](https://www.genderapi.io/fr/docs/v2/authentication) - [Erreurs et tentatives](https://www.genderapi.io/fr/docs/v2/errors-and-retries) - [Crédits et utilisation](https://www.genderapi.io/fr/docs/v2/credits-and-usage)