Validez les numéros de téléphone et convertissez-les en E.164 avec un seul appel API

Votre formulaire d'inscription collecte les numéros de téléphone de 40 pays. Les utilisateurs les saisissent dans tous les formats imaginable : avec des tirets, des espaces, des parenthèses, des codes pays, sans codes pays. Vous avez besoin de les normaliser au format E.164 avant de les stocker dans votre base de données. Sinon, tu vous retrouvez avec cinq représentations différentes du même numéro, et votre passerelle SMS rejette la moitié d'entre eux.

L'API de validation de téléphone botoi analyse n'importe quel numéro de téléphone international en une réponse structurée : un indicateur de validité, un format E.164, un numéro national, un code de pays et un nom de pays. Une requête POST, pas d'installation de libphonenumber, pas de bundle de 300 Ko.

Valider un numéro de téléphone en une seule requête

Envoyer un numéro de téléphone à /v1/phone et obtenez un résultat structuré.

curl -X POST https://api.botoi.com/v1/phone \\
  -H "Content-Type: application/json" \\
  -d '{"phone": "+14155552671"}'

Réponse:

{
  "success": true,
  "data": {
    "phone": "+14155552671",
    "valid": true,
    "country_code": "+1",
    "country": "United States / Canada",
    "e164_format": "+14155552671",
    "national_format": "4155552671"
  }
}

L'API supprime les espaces, les tirets et les parenthèses de l'entrée, identifie le pays à partir du préfixe de numérotation et renvoie à la fois le format E.164 (pour le stockage) et le format national (pour l'affichage). Le valid Le drapeau vérifie que le numéro national comporte entre 7 et 15 chiffres, ce qui couvre le plan de numérotation de chaque pays.

Exemples de formats internationaux

L'API gère les numéros de plus de 30 pays. Les espaces, tirets et parenthèses dans l'entrée sont tous dépouillés avant l'analyse.

Country              Input                    E.164               Country code
──────────────────   ───────────────────────  ──────────────────  ────────────
United States        +1 (415) 555-2671        +14155552671        +1
United Kingdom       +44 20 7946 0958         +442079460958       +44
India                +91 98765 43210          +919876543210       +91
Germany              +49 30 1234567           +49301234567        +49
Japan                +81 3-1234-5678          +81312345678        +81
Brazil               +55 11 91234-5678        +5511912345678      +55
Australia            +61 2 1234 5678          +61212345678        +61
Singapore            +65 6123 4567            +6561234567         +65

Numéro britannique avec espaces

curl -X POST https://api.botoi.com/v1/phone \\
  -H "Content-Type: application/json" \\
  -d '{"phone": "+44 20 7946 0958"}'

Réponse:

{
  "success": true,
  "data": {
    "phone": "+44 20 7946 0958",
    "valid": true,
    "country_code": "+44",
    "country": "United Kingdom",
    "e164_format": "+442079460958",
    "national_format": "2079460958"
  }
}

Que se passe-t-il en cas de saisie invalide

Des nombres sans + retour du préfixe valid: false avec une note expliquant ce que l'API attend.

curl -X POST https://api.botoi.com/v1/phone \\
  -H "Content-Type: application/json" \\
  -d '{"phone": "555-1234"}'

Réponse:

{
  "success": true,
  "data": {
    "phone": "555-1234",
    "valid": false,
    "country_code": null,
    "country": null,
    "e164_format": null,
    "national_format": null,
    "note": "Phone number should start with \\"+\\" followed by a country code for reliable detection."
  }
}

Aucune exception, aucun code d'erreur énigmatique. Vérifier data.valid et montre à l'utilisateur un message clair.

Validation du formulaire d'inscription

Cas d'utilisation le plus courant : valider un numéro de téléphone lors de la soumission du formulaire, puis stocker le E.164 version au lieu de ce que l'utilisateur a tapé. Cela garde votre base de données propre et vos SMS fournisseur heureux.

async function validatePhone(phone) {
  const res = await fetch("https://api.botoi.com/v1/phone", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone }),
  });
  return res.json();
}

// Signup form handler
document.querySelector("#signup-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const phoneInput = document.querySelector("#phone").value.trim();

  const { data } = await validatePhone(phoneInput);

  if (!data.valid) {
    showError("Enter a valid phone number with country code (e.g. +1 415 555 2671)");
    return;
  }

  // Store the E.164 version, not the raw input
  await createAccount({
    phone: data.e164_format,
    country: data.country,
  });
});

L'entrée brute est envoyée à l'API. Le format E.164 revient. Vous stockez +14155552671 au lieu de (415) 555-2671 ou 415.555.2671 ou toute autre variante. Chaque système en aval (Twilio, AWS SNS, Vonage) attend E.164, vous évitez donc la conversion des maux de tête plus tard.

Normaliser un CSV de numéros de téléphone

Vous disposez d'un export CSV depuis un CRM de 5 000 contacts. La colonne téléphonique est en désordre : quelques numéros ont des codes de pays, certains n'en ont pas, certains ont des tirets, certains ont des points. Ce script lit le CSV, valide chaque numéro et écrit une version propre au format E.164 et aux informations sur le pays.

import { readFileSync, writeFileSync } from "fs";
import { parse } from "csv-parse/sync";
import { stringify } from "csv-stringify/sync";

const records = parse(readFileSync("contacts.csv"), { columns: true });

async function normalizePhone(phone) {
  const res = await fetch("https://api.botoi.com/v1/phone", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone }),
  });
  const { data } = await res.json();
  return data;
}

async function processContacts() {
  const results = [];

  for (const row of records) {
    const data = await normalizePhone(row.phone);
    results.push({
      name: row.name,
      original_phone: row.phone,
      e164: data.valid ? data.e164_format : "INVALID",
      country: data.country || "Unknown",
      valid: data.valid,
    });
  }

  writeFileSync("contacts_normalized.csv", stringify(results, { header: true }));
  const invalid = results.filter((r) => !r.valid);
  console.log(\`Processed \\\${results.length} contacts. \\\${invalid.length} invalid.\`);
}

processContacts();

Le CSV de sortie comporte quatre colonnes : le téléphone d'origine, la version E.164, le pays détecté, et un indicateur de validité. Vous pouvez filtrer les lignes non valides et les corriger manuellement, puis importer le nettoyer les données dans votre système.

Pour les fichiers volumineux, ajoutez un petit délai entre les requêtes ou regroupez-les avec Promise.all par groupe de 5 pour rester dans les limites tarifaires. Les forfaits payants prennent en charge un débit plus élevé.

Middleware express pour la validation téléphonique

Ce middleware valide le numéro de téléphone avant l'exécution de votre gestionnaire d'itinéraire. Si le numéro est invalide, la requête reçoit une réponse 422. Si c'est valide, le middleware remplace l'entrée brute avec le format E.164 normalisé afin que votre gestionnaire reçoive toujours des données propres.

import express from "express";

const app = express();
app.use(express.json());

async function validatePhoneMiddleware(req, res, next) {
  const phone = req.body.phone;

  if (!phone) {
    return res.status(400).json({ error: "Phone number is required" });
  }

  const apiRes = await fetch("https://api.botoi.com/v1/phone", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone }),
  });
  const { data } = await apiRes.json();

  if (!data.valid) {
    return res.status(422).json({
      error: "Invalid phone number",
      detail: "Provide an international number starting with + and a country code",
    });
  }

  // Replace raw input with normalized E.164 format
  req.body.phone = data.e164_format;
  req.body.phoneCountry = data.country;
  next();
}

app.post("/users", validatePhoneMiddleware, async (req, res) => {
  // req.body.phone is now in E.164 format
  const user = await db.users.create({
    email: req.body.email,
    phone: req.body.phone,        // "+14155552671"
    phoneCountry: req.body.phoneCountry, // "United States / Canada"
  });

  res.status(201).json({ id: user.id });
});

Chaque itinéraire qui accepte un numéro de téléphone reçoit la même logique de validation. Votre base de données toujours stocke E.164. Vos gestionnaires d'itinéraire ne s'occupent jamais de l'analyse ou du formatage ; ils reçoivent un numéro normalisé et un nom de pays.

Pourquoi E.164 est important

E.164 est la norme ITU-T pour le formatage des numéros de téléphone internationaux. Le format est simple : un + signe, l'indicatif du pays et le numéro d'abonné, sans espaces ni ponctuation. Exemple: +14155552671.

• Déduplication. Sans format canonique, le même numéro apparaît comme (415) 555-2671, 415-555-2671, +1 415 555 2671, et 14155552671. E.164 regroupe les quatre en une seule chaîne.
• Envoi de SMS. Twilio, AWS SNS, Vonage, MessageBird et tous les principaux SMS La passerelle nécessite E.164. Si vous stockez des nombres dans un format différent, vous avez besoin d'une conversion étape avant chaque envoi.
• Indexation de base de données. Un format unique, c'est votre contrainte unique au téléphone la colonne fonctionne. Les formats mixtes laissent passer les doublons.
• Soutien international. E.164 inclut l'indicatif du pays, afin que votre système gère Numéros américains, britanniques, indiens et brésiliens sans logique de cas particulier.

Points clés

• Un point de terminaison couvre la validation et le formatage. POST /v1/phone renvoie la validité, E.164, le format national, le code du pays et le nom du pays dans une seule réponse.
• Aucune bibliothèque requise. Ignorez le bundle libphonenumber de 300 Ko. Un appel HTTP remplace la dépendance.
• Magasin E.164, affichage national. Écrire e164_format à votre base de données. Montrer national_format dans l'interface utilisateur avec le drapeau du pays.
• Validez à la frontière. Ajoutez le middleware à vos routes API et chaque le système en aval reçoit des données propres.
• Niveau gratuit disponible. 5 requêtes par minute sans clé API. Forfaits payants pour les charges de travail de production commencent à 9 $/mois.