Validieren Sie Telefonnummern und konvertieren Sie sie mit einem API-Aufruf zu E.164

Ihr Anmeldeformular sammelt Telefonnummern aus 40 Ländern. Benutzer geben sie in jedem Format ein vorstellbar: mit Bindestrichen, Leerzeichen, Klammern, Ländercodes, ohne Ländercodes. Du brauchst um diese in das E.164-Format zu normalisieren, bevor Sie sie in Ihrer Datenbank speichern. Ansonsten du Am Ende erhalten Sie fünf verschiedene Darstellungen derselben Nummer, und Ihr SMS-Gateway lehnt ab die Hälfte davon.

Die Botoi-Telefonvalidierungs-API analysiert jede internationale Telefonnummer in eine strukturierte Antwort: eine Gültigkeitsflagge, E.164-Format, nationale Nummer, Ländercode und Ländername. Eine POST-Anfrage, Keine libphonenumber-Installation, kein 300-KB-Bundle-Hit.

Bestätigen Sie eine Telefonnummer in einer Anfrage

Senden Sie eine Telefonnummer an /v1/phone und erhalten Sie ein strukturiertes Ergebnis zurück.

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

Antwort:

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

Die API entfernt Leerzeichen, Bindestriche und Klammern aus der Eingabe und identifiziert das Land anhand der Wählpräfix und gibt sowohl das E.164-Format (zur Speicherung) als auch das nationale Format (zur Anzeige) zurück. Der valid Flag prüft, ob die nationale Nummer zwischen 7 und 15 Ziffern hat deckt den Nummerierungsplan jedes Landes ab.

Beispiele für internationale Formate

Die API verarbeitet Nummern aus über 30 Ländern. Leerzeichen, Bindestriche und Klammern in der Eingabe sind alles vor dem Parsen entfernt.

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

Britische Nummer mit Leerzeichen

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

Antwort:

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

Was passiert bei ungültiger Eingabe?

Zahlen ohne a + Präfixrückgabe valid: false mit einer Erläuterung was die API erwartet.

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

Antwort:

{
  "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."
  }
}

Keine Ausnahmen, keine kryptischen Fehlercodes. Überprüfen data.valid und zeige dem Benutzer a klare Botschaft.

Validierung des Anmeldeformulars

Der häufigste Anwendungsfall: Validieren Sie eine Telefonnummer bei der Formularübermittlung und speichern Sie dann die E.164 Version anstelle dessen, was der Benutzer eingegeben hat. Dadurch bleiben Ihre Datenbank und Ihre SMS sauber Anbieter zufrieden.

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,
  });
});

Die Roheingabe geht an die API. Das E.164-Format kommt zurück. Sie lagern +14155552671 anstatt (415) 555-2671 oder 415.555.2671 oder jede andere Variation. Jedes Downstream-System (Twilio, AWS SNS, Vonage) erwartet E.164, sodass Sie eine Konvertierung vermeiden später Kopfschmerzen.

Normalisieren Sie eine CSV-Datei mit Telefonnummern

Sie haben einen CSV-Export aus einem CRM mit 5.000 Kontakten. Die Telefonspalte ist ein Chaos: einige Nummern haben Ländercodes, manche nicht, manche haben Bindestriche, manche haben Punkte. Dieses Skript liest die CSV, validiert jede Nummer und schreibt eine saubere Version mit E.164-Format und Länderinformationen.

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();

Die Ausgabe-CSV hat vier Spalten: das Originaltelefon, die E.164-Version, das erkannte Land, und ein Gültigkeitsflag. Sie können nach ungültigen Zeilen filtern und diese manuell korrigieren und dann importieren saubere Daten in Ihr System.

Fügen Sie bei großen Dateien eine kleine Verzögerung zwischen den Anfragen hinzu oder stapeln Sie sie mit Promise.all in Gruppen von 5 Personen, um die Tarifgrenzen einzuhalten. Bezahlte Pläne unterstützen einen höheren Durchsatz.

Express-Middleware für die Telefonvalidierung

Diese Middleware validiert die Telefonnummer, bevor Ihr Routenhandler ausgeführt wird. Wenn die Nummer ist ungültig, die Anfrage erhält eine 422-Antwort. Wenn es gültig ist, ersetzt die Middleware die Roheingabe mit dem normalisierten E.164-Format, sodass Ihr Handler immer saubere Daten erhält.

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 });
});

Jede Route, die eine Telefonnummer akzeptiert, erhält dieselbe Validierungslogik. Ihre Datenbank immer speichert E.164. Ihre Routenhandler kümmern sich nie um das Parsen oder Formatieren; sie erhalten eine normalisierte Nummer und ein Ländername.

Warum E.164 wichtig ist

E.164 ist der ITU-T-Standard für die Formatierung internationaler Telefonnummern. Das Format ist einfach: a + Zeichen, die Landesvorwahl und die Teilnehmernummer, ohne Leerzeichen oder Satzzeichen. Beispiel: +14155552671.

• Deduplizierung. Ohne kanonisches Format wird dieselbe Zahl angezeigt wie (415) 555-2671, 415-555-2671, +1 415 555 2671, Und 14155552671. E.164 fasst alle vier zu einer Zeichenfolge zusammen.
• SMS-Zustellung. Twilio, AWS SNS, Vonage, MessageBird und alle wichtigen SMS Gateway erfordert E.164. Wenn Sie Zahlen in einem anderen Format speichern, ist eine Konvertierung erforderlich Schritt vor jedem Senden.
• Datenbankindizierung. Ein einzelnes Format bedeutet Ihre einzigartige Einschränkung für das Telefon Spalte funktioniert. Durch gemischte Formate können Duplikate durchgehen.
• Internationale Unterstützung. E.164 enthält den Ländercode, der von Ihrem System verarbeitet wird Zahlen aus den USA, Großbritannien, Indien und Brasilien ohne Sonderfalllogik.

Wichtige Punkte

• Ein Endpunkt umfasst die Validierung und Formatierung. POST /v1/phone Gibt Gültigkeit, E.164, nationales Format, Ländercode und Ländername in einer einzigen Antwort zurück.
• Keine Bibliothek erforderlich. Überspringen Sie das 300-KB-Paket „libphonenumber“. Ein HTTP-Aufruf ersetzt die Abhängigkeit.
• Shop E.164, Anzeige national. Schreiben e164_format zu Ihrer Datenbank. Zeigen national_format in der Benutzeroberfläche mit der Landesflagge.
• An der Grenze validieren. Fügen Sie die Middleware zu Ihren API-Routen und allem hinzu Das nachgelagerte System erhält saubere Daten.
• Kostenloses Kontingent verfügbar. 5 Anfragen pro Minute ohne API-Schlüssel. Bezahlte Pläne für Produktions-Workloads beginnen bei 9 $/Monat.