Format

Format Insight ist ein grundlegendes Validierungswerkzeug, das überprüft, ob eine Telefonnummer korrekt strukturiert ist und einem Teilnehmer zugeordnet werden kann. Es stellt sicher, dass die Nummer den internationalen Wählstandards entspricht, identifiziert das zugehörige Land und bestimmt die entsprechende Zeitzone. Dieser Einblick bestätigt nicht, ob die Nummer derzeit aktiv ist oder verwendet wird, aber er ist ein wichtiger erster Schritt bei der Beurteilung der technischen Gültigkeit einer globalen Telefonnummer.

Durch die Analyse der Syntax und der Präfixstruktur der Nummer hilft Format Insight zu erkennen, ob die Nummer zu einem gültigen Nummernbereich in einem bestimmten Land gehört. Außerdem werden offensichtlich ungültige oder fehlerhafte Numbers markiert, so dass Unternehmen die Daten bereinigen können, bevor sie sie für betriebliche oder Marketingzwecke verwenden.

Die Integration der Formateinsicht in Ihre Applications kann bei einer Reihe von Szenarien hilfreich sein, z. B:

  • Datenqualität und -bereinigung: Format Insight ist ideal für die Bereinigung historischer Kundendatenbanken. Es filtert falsch formatierte oder eindeutig ungültige Numbers heraus und trägt so zur Einhaltung hoher Datenhygienestandards und zur Verbesserung der allgemeinen Kontaktfähigkeit bei.
  • Echtzeit-Validierung bei der Eingabe: Unternehmen können diesen Einblick in Webformulare oder CRM-Systeme integrieren, um Telefonnummern bereits bei der Eingabe zu überprüfen, das Risiko von Eingabefehlern zu verringern und sicherzustellen, dass nur korrekt formatierte Nummern gespeichert werden.
  • Segmentierung und Lokalisierung: Die Kenntnis des Landes und der Zeitzone, die mit einer Nummer verbunden sind, ermöglicht es Unternehmen, ihre Kommunikation anzupassen, den Einsatz in geeigneten Zeitfenstern zu planen und die lokalen Vorschriften einzuhalten.
  • Optimierung der Kosten: Vermeiden Sie den Kontakt mit ungültigen Numbers, die andernfalls zu fehlgeschlagenen Zustellversuchen, vergeudetem Aufwand und unnötigen Kosten in SMS-, Sprach- oder Betrugspräventions-Workflows führen würden.

Zusammenfassend lässt sich sagen, dass Format Insight eine Methode mit geringer Latenz und hoher Zuverlässigkeit für die Validierung globaler Numbers im großen Maßstab darstellt. Es ist ein wichtiger Baustein in jeder Telefonnummern-Intelligence-Pipeline und bildet die Grundlage für weitergehende Prüfungen, wie z. B. Betreibereinblicke und Netzwerkfunktionen für die Betrugsrisikoanalyse.

Voraussetzungen

Um Identity Insights nutzen zu können, müssen Sie sicherstellen, dass Ihr Account korrekt konfiguriert ist; siehe die Erste Schritte Leitfaden für weitere Informationen über:

  • Erstellen Sie Ihren Account,
  • Erstellen einer Vonage-Anwendung zur Verwendung mit der Identity Insights API,
  • Die verschiedenen verfügbaren Umgebungen und wie Sie Ihren Account für deren Nutzung konfigurieren,
  • Und wie Sie die Dashboard-Einstiegs-UI verwenden, um die API zu nutzen, ohne Code zu schreiben.

In dieser Anleitung wird erklärt, wie man Format Insight programmatisch mit cURL verwendet.

Die Identity Insights API ist über mehrere regionale Endpunkte verfügbar. Die Beispiele in diesem Leitfaden verwenden den EU-Endpunkt, aber Sie finden die vollständige Liste unter Technische Details.

Einen API-Aufruf tätigen

Die Authentifizierung für die Identity Insights API erfolgt über JWTs, ein kompaktes und in sich geschlossenes JSON-Token. Um ein JWT zu generieren, können Sie unser Online-Generatoroder verwenden Sie alternativ die Vonage CLI. Sie benötigen Ihre Anwendungs-ID und Ihren privaten Schlüssel, um das JWT zu erzeugen. Sobald Sie Ihr JWT haben, können Sie eine Anfrage an die API senden.

Dieses Beispiel zeigt eine cURL-Anfrage für den Format-Einblick, um nützliche Informationen auf der Grundlage der angegebenen Telefonnummer zurückzugeben:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "format": {}
        }
    }'

Die API überprüft dann, ob das Format der Telefonnummer gültig ist, und gibt weitere Informationen zurück, z. B. die Landesvorwahl, Zeitzonen und verschiedene Formate dieser Nummer:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "format": {
        "country_code": "US",
        "country_name": "United States",
        "country_prefix": "1",
        "offline_location": "Georgia",
        "time_zones": [
          "America/New_York"
        ],
        "number_international": "+14040000000",
        "number_national": "(404) 000-0000",
        "is_format_valid": true,
        "status": {
          "code": "NO_COVERAGE",
          "message": "Success"
      }
    }
  }
}

Sie sehen die folgenden Felder im Fenster format Array:

Feld Beschreibung
country_code Zweistelliger Ländercode für phone_number. Dies ist in ISO 3166-1 alpha-2 Format.
country_name Der vollständige Name des Landes, in dem die phone_number registriert ist.
country_prefix Das numerische Präfix für das Land, in dem die phone_number registriert ist.
offline_location Der Standort, an dem die Nummer ursprünglich zugewiesen wurde, basierend auf ihrer Vorwahl. Dies stellt nicht den Echtzeit-Standort des Geräts dar. Der Wert gibt das Herkunftsland oder, falls verfügbar, das spezifische geografische Gebiet an, das mit der Nummer verbunden ist. Nur Festnetz- und Handynummern sind für Offline-Standortdaten geeignet.
time_zones Liste der Zeitzonen, die dem format.offline_location oder eine Einzelelementliste mit dem Standardwert "unbekannte" Zeitzone, wenn keine andere Zeitzone gefunden wurde oder wenn die Nummer ungültig ist. Die Werte für die Zeitzone folgen dem tz-Datenbank Identifikatoren.
number_international Die phone_number aus Ihrer Anfrage, formatiert in internationalem Format E.164 Format.
number_national Die phone_number aus Ihrer Anfrage, formatiert nach den lokalen Konventionen des Landes, zu dem sie gehört.
is_format_valid Bei der Validierung des Telefonnummernformats werden die Länge und die Details der Vorwahl auf verschiedenen Ebenen überprüft, um die Genauigkeit und die Übereinstimmung mit den globalen Nummerierungsstandards sicherzustellen. Ein gültiges Format bedeutet, dass die Nummer von den Betreibern rechtmäßig an die Nutzer vergeben werden kann. Es ist jedoch keine Garantie dafür, dass die Nummer derzeit einem Betreiber zugewiesen ist oder dass sie erreichbar ist.
status Gibt den Status der Informationen an, die für die angegebene Telefonnummer zurückgegeben werden.
code Code, der den Status der Anfrage angibt. Muss einer der folgenden sein:

NO_COVERAGE: Das Land oder das Mobilfunknetz wird von den verfügbaren Anbietern nicht unterstützt.
INVALID_PURPOSE: Der verwendete Zweck ist für diese Einsicht nicht gültig oder zulässig.
UNAUTHORIZED: Die Anfrage konnte für die Kombination aus Antrag, Lieferant und Telefonnummer nicht autorisiert werden.
INTERNAL_ERROR: Bei der Bearbeitung der Anfrage ist ein interner Fehler aufgetreten.
SUPPLIER_ERROR: Der Anbieter hat bei der Bearbeitung der Anfrage einen Fehler gemeldet.
NOT_FOUND: Die Rufnummer konnte für diese Einsicht nicht gefunden werden.
INVALID_NUMBER_FORMAT: Das Format der Telefonnummern ist für die Zuweisung durch die Netzbetreiber an die Benutzer nicht gültig.
PARTIAL_SUCCESS: Einige Antwortattribute wurden weggelassen, weil sie nicht anwendbar oder nicht verfügbar waren.
OK: Alle Insight-Attribute sind verfügbar und in der Antwort enthalten.
message Ausführlichere Statusbeschreibung.

Weitere Lektüre