Phone Carrier Lookup API: Eine Anfrage, ein Ergebnis zum ursprünglichen Netzbetreiber

Ein Leitfaden für Entwickler zu einem API-Aufruf für die Abfrage des ursprünglichen Netzbetreibers einer einzelnen Telefonnummer: Anfrage, Auslesen des Ergebnisses, Fehlerbehandlung und wann auf Mehrfachanfragen umgestellt werden sollte.

Eine Phone Carrier Lookup API nimmt eine Telefonnummer von Ihrem Server entgegen und gibt den Netzbetreiber zurück, dem dieser Nummernblock ursprünglich zugewiesen wurde, sowie weitere Kontextinformationen. Mit CarrierLookup sendet ein vertrauenswürdiges Backend eine E.164-Nummer an POST /api/v1/check mit einem X-API-Key-Header und erhält ein synchrones Ergebnis: ursprünglicher Netzbetreiber, zugrunde liegender Netzbetreiber, Nummerntyp, Ländercode sowie die Region und Stadt der Zuweisung. Der Netzbetreiber entspricht der ursprünglichen Zuweisung, nicht dem Netzwerk nach einer Portierung. Ein abgeschlossenes Ergebnis mit leeren Feldern ist dennoch eine abgeschlossene Abfrage, während eine unbestimmte Prüfung einen Business-Code ungleich Null zurückgibt. Für bis zu 100 Nummern in einem Aufruf wechseln Sie zu POST /api/v1/batch-check.

Was eine Phone Carrier Lookup API zurückgibt

Viele Seiten für die Abfrage von Netzbetreibern vermischen zwei unterschiedliche Fragen: Wem wurde dieser Nummernblock zugewiesen und wer betreibt die Nummer heute? CarrierLookup beantwortet die erste Frage. Das Ergebnis zum Netzbetreiber nennt den Betreiber, dem der Nummernblock gemäß dem nationalen Nummerierungsplan ursprünglich zugewiesen wurde. In Ländern mit Rufnummernportabilität kann ein Teilnehmer die Nummer behalten, während er zu einem anderen Anbieter wechselt, wie der FCC-Leitfaden zur Portierung erläutert. Daher können sich der ursprüngliche Netzbetreiber und der aktuelle Anbieter unterscheiden.

Ein abgeschlossenes Einzelergebnis enthält in verständlicher Form:

• Ursprünglicher Netzbetreiber: der Betreiber, dem der Bereich zugewiesen wurde.
• Zugrunde liegender Netzbetreiber: das Netzwerk hinter diesem Betreiber, sofern ein Wert verfügbar ist.
• Nummerntyp: die Art des Bereichs, wie z. B. Mobilfunk oder Festnetz.
• Ländercode, Region und Stadt: wo der Bereich zugewiesen wurde, nicht wo sich eine Person oder ein Gerät befindet.

Betrachten Sie diese Informationen als Zuweisungskontext für Gruppierungen, Routing-Tests und Überprüfungen. Ein Ergebnis zum Netzbetreiber zeigt nicht an, dass eine Nummer in Betrieb ist, Anrufe oder SMS empfangen kann oder einer bestimmten Person gehört.

Senden einer Nummer an die Carrier Lookup API

Die Route für einzelne Nummern ist eine kurze, synchrone Anfrage. Eine typische Integration folgt fünf Schritten:

1. Bewahren Sie den Schlüssel auf einem vertrauenswürdigen Server auf. Die REST API authentifiziert sich mit einem X-API-Key-Header. Rufen Sie sie von Ihrem Backend oder einem Job-Runner aus auf, niemals aus Browser- oder Mobil-App-Code, wo der Schlüssel kopiert werden könnte.
2. Normalisieren Sie die Eingabe auf E.164. Der ITU-T E.164-Plan definiert das internationale Format. CarrierLookup erwartet ein führendes Pluszeichen, den Ländercode und die Teilnehmernummer ohne Leerzeichen, Bindestriche oder Klammern. Eine britische Nummer, die als 020 7946 0000 geschrieben wird, wird zu +442079460000. Bibliotheken wie libphonenumber können lokale Formate parsen, wenn das Land des Datensatzes bekannt ist.
3. Senden Sie die Anfrage an POST /api/v1/check. Eine Nummer pro Anfrage. Eine separate Länderauswahl ist nicht erforderlich, da der Ländercode Teil der Nummer ist.
4. Warten Sie auf die synchrone Antwort. Das Ergebnis kommt in derselben Antwort zurück; es gibt nichts abzufragen.
5. Speichern Sie das Ergebnis mit einem Abfragedatum. Zuweisungsdaten sind für einen Bereich stabil, aber die Aufzeichnung des Zeitpunkts der Abfrage vereinfacht Audits.

Wenn die Eingabe aufgrund ihres Formats abgelehnt wird, korrigieren Sie die Nummer und senden Sie sie erneut. Eine Ablehnung aufgrund des Formats sagt nichts über den Netzbetreiber aus.

Lesen von abgeschlossenen, leeren und unbestimmten Ergebnissen

Der häufigste Integrationsfehler besteht darin, drei verschiedene Ergebnisse als eines zu behandeln. Unterscheiden Sie zuerst nach dem Business-Code und dann nach den Werten.

Aus der Tabelle ergeben sich zwei Regeln. Zweitens ist eine unbestimmte Prüfung kein erfolgreiches leeres Ergebnis, schreiben Sie daher niemals leere Felder daraus in Ihr CRM. Fehlgeschlagene oder unbestimmte Abfragen werden nicht berechnet, abgeschlossene Abfragen hingegen schon, auch wenn ihre Felder leer sind.

Optionale Felder wie der zugrunde liegende Netzbetreiber, die Region oder die Stadt können bei ansonsten vollständigen Ergebnissen leer sein. Entwerfen Sie Ihr Schema so, dass jedes Feld unabhängig voneinander null sein kann.

Umgang mit Timeouts, Nebenläufigkeit und Guthaben

Die öffentliche API dokumentiert eine kleine Anzahl von Nutzungskontrollen anstelle eines Kontingents pro Minute. Ein Konto verfügt über fünf gemeinsam genutzte In-Flight-Slots für synchrone Anfragen, und es kann jeweils nur eine Mehrfachanfrage gleichzeitig ausgeführt werden. Einzelanfragen haben eine dokumentierte Timeout-Obergrenze von 60 Sekunden. Setzen Sie Ihr HTTP-Client-Timeout daher etwas höher an und nicht nur auf wenige Sekunden.

Praktische Handhabung:

• Warteschlangen statt Überlastung. Wenn Ihr Anmelde- oder Import-Job Spitzen erzeugt, halten Sie einen kleinen Worker-Pool bereit, sodass nicht mehr als fünf Abfragen gleichzeitig laufen.
• Wiederholen Sie unbestimmte Ergebnisse mit zeitlichem Abstand. Verwenden Sie eine Verzögerung und eine Obergrenze für Wiederholungen; wiederholte sofortige Versuche helfen selten.
• Protokollieren Sie den Business-Code und die Nachricht. Sie erklären Fehler weitaus besser als ein reiner HTTP-Status.
• Lesen Sie das Guthaben ab, ohne es zu verbrauchen. GET /api/v1/balance gibt das verbleibende Guthaben kostenlos zurück, was sich für eine Vorabprüfung vor einem großen Job eignet.

Überprüfen Sie für die aktuellen Limits Ihres Kontos die API-Dokumentation, anstatt Annahmen fest zu kodieren; die API veröffentlicht kein festes tägliches Anfrage-Limit.

Wann zu POST /api/v1/batch-check oder einer Datei-Aufgabe gewechselt werden sollte

Die Route für einzelne Nummern eignet sich für ereignisgesteuerte Arbeit: eine Formularübermittlung, ein neuer CRM-Datensatz, ein Support-Mitarbeiter, der einen Kontakt überprüft. Sobald ein Job regelmäßig mehrere Nummern gleichzeitig verarbeitet, erhöht ein Aufruf pro Nummer den Overhead.

• POST /api/v1/batch-check akzeptiert 1 bis 100 E.164-Nummern in einer synchronen Anfrage, und die Nummern können aus verschiedenen Ländern stammen. Die Ergebnisse werden in der gleichen Reihenfolge wie die Eingabe zurückgegeben, sodass Sie jede Zeile nach Position zuordnen können. Jede Zeile enthält ein exists-Flag; false bedeutet kein normales Ergebnis für diese Zeile, nicht, dass die Nummer ungültig oder nicht verbunden ist. Wenn eine Mehrfachanfrage ein Timeout hat, schlägt die gesamte Anfrage ohne Teilergebnisse fehl und der reservierte Betrag wird vollständig zurückerstattet. Halten Sie Batches daher moderat und wiederholen Sie den Batch.
• Das Dashboard akzeptiert bis zu 500 Nummern für eine synchrone Mehrfachabfrage ohne Code.
• Bulk-Datei-Aufgaben eignen sich für ganze Listen: ein asynchroner Upload einer TXT- oder CSV-Datei für ein ausgewähltes Land, der so lange abgefragt wird, bis eine einzelne CSV-Datei bereit ist. Es gelten produktbezogene Limits; siehe API-Dokumentation.

Dieselben Abfragen stehen KI-Assistenten auch über den offiziellen MCP-Endpunkt zur Verfügung, der Einzel- und Mehrfachprüfungen abdeckt, jedoch keine Datei-Aufgaben.

FAQ

Wie können Teams ein leeres Netzbetreiber-Ergebnis von einer fehlgeschlagenen Abfrage unterscheiden?

Überprüfen Sie den Business-Code, bevor Sie Werte lesen. Ein Erfolgscode mit leeren Netzbetreiberfeldern ist eine abgeschlossene Abfrage und sollte als nicht verfügbar gespeichert werden. Ein Code ungleich Null bedeutet, dass die Prüfung unbestimmt war oder fehlgeschlagen ist; es sollte nichts als Ergebnis geschrieben werden, und der Datensatz kann später erneut versucht oder zur Überprüfung weitergeleitet werden. Die Trennung dieser beiden Pfade verhindert, dass gute Datensätze als fehlende Daten markiert werden.

Zeigt die Carrier Lookup API das Netzwerk an, das eine Nummer heute verwendet?

Nein. Der Netzbetreiber-Wert ist der Betreiber, dem der Nummernblock ursprünglich zugewiesen wurde. Nachdem ein Teilnehmer die Nummer portiert hat, bleibt dieser ursprüngliche Betreiber im Ergebnis gleich, selbst wenn der Dienst woandershin umgezogen ist. Teams, die Zuweisungskontext für Gruppierungen, Routing-Tests oder Überprüfungen benötigen, können ihn direkt verwenden; er sollte nicht als das aktuell versorgende Netzwerk oder als Kontaktierbarkeit behandelt werden.

Sollte ein Frontend die Carrier Lookup API direkt aufrufen?

Das sollte es nicht. Der X-API-Key-Header gewährt Zugriff auf das Kontoguthaben, daher gehören Aufrufe auf einen vertrauenswürdigen Server. Ein gängiges Muster ist, dass das Frontend die Telefonnummer an Ihr eigenes Backend übermittelt, welches sie auf E.164 normalisiert, POST /api/v1/check aufruft, das Ergebnis speichert und nur das zurückgibt, was die Schnittstelle anzeigen muss.

Mehr erfahren

Wählen Sie die Produktinformationen, die zum nächsten Schritt in Ihrem Workflow passen.

• Produktdokumentation ansehen →
• Mit dem Team sprechen →