Lookup-API-FAQ

Lookup beantwortet Fragen über einen Empfänger, bevor Sie an ihn senden. Geben Sie eine Telefonnummer ein, und Lookup sagt Ihnen, was die Nummer ist: das zustellende Netz, das Land, ob sie das Netz gewechselt hat und welche Art von Anschluss es ist. Geben Sie eine E-Mail-Adresse ein, und Lookup sagt Ihnen, ob es sich lohnt, an diese Adresse zu senden.

Zwei Dinge, je eine Operation. Eine Telefonnummern-Abfrage liefert das Land, das zustellende Netz, das ausgebende Netz, ob die Nummer zwischen beiden gewechselt hat, und den Anschlusstyp sowie alle zusätzlich angefragten Eigenschaften. Eine E-Mail-Adressen-Abfrage liefert ein Urteil, einen Confidence-Score und die dahinterliegenden Flags.

Jede Abfrage ist ein Request und eine Antwort. Es gibt nichts anzulegen, nichts abzufragen und nichts aufzuräumen. Typisierte Methoden sind in den Go-, TypeScript-, Python- und PHP-SDKs enthalten, und bird lookup phone-number sowie bird lookup email erledigen dasselbe über die CLI.

Ja. Die Lookup-Seite im Dashboard führt dieselben zwei Operationen einzeln aus – der schnellste Weg, um zu sehen, wie eine Antwort aussieht, bevor Sie darauf aufbauen.

Einen API-Schlüssel mit dem lookup-Scope und ein Organisations-Wallet, das die Kosten decken kann. Die Abrechnung erfolgt pro Abfrage ohne Lizenzgebühr, es gibt also keinen Plan, den Sie vorher wählen müssen.

Nutzen Sie Lookup, wenn Sie vor dem Senden entscheiden wollen: eine Registrierung prüfen, einen Lead vor der Bearbeitung screenen oder eine Nachricht je nach Anschlusstyp anders routen. Sie erhalten eine verwertbare Antwort, ohne zuerst etwas senden zu müssen.

Pro Abfrage. Jede Abfrage wird dem Wallet Ihrer Organisation belastet. Eine Telefonnummern-Abfrage wird einmal für die Basisabfrage berechnet, plus eine Gebühr für jede Eigenschaft, die beantwortet zurückkommt. Eine E-Mail-Adressen-Abfrage wird einmal pro beantworteter Adresse berechnet. Es gibt keine Lizenzgebühr pro Nutzer.

Die Lookup-Preisseite listet den Preis für die Basisabfrage, für jede Eigenschaft und für eine E-Mail-Adressen-Abfrage. Die Preise variieren je nach Eigenschaft, weil jede aus einer anderen Datenquelle stammt.

Nein. Eine Eigenschaft wird nur berechnet, wenn sie geliefert wird. Eine, die nicht beantwortet werden konnte, kommt mit einem entsprechenden Status zurück und kostet Sie nichts – die Basisabfrage wird dennoch daneben ausgeliefert.

Es wird nichts berechnet. Eine fehlerhafte Nummer, eine Adresse, die wir ablehnen, und eine nicht erreichbare Datenquelle kosten nichts.

Ja. Jede beantwortete Adresse wird berechnet, auch unzustellbare. Das ist die Antwort, die Sie angefragt haben, und sie ist es, die Ihnen einen Bounce erspart.

Nicht, wenn Sie einen Idempotency-Key senden. Eine Wiederholung derselben Anfrage gibt die gespeicherte Antwort zurück, statt eine neue Abfrage auszuführen. Die GET-Varianten, die die Nummer oder die Adresse in der URL enthalten, können keinen Idempotency-Key mitführen – verwenden Sie daher POST für alles Automatisierte.

Die Begrenzung der Anfragerate für Lookup startet bei 10 Requests pro Minute, gezählt pro agierendem Credential, sodass ein ausgelasteter Schlüssel keinen anderen blockiert. Jede Abfrage kontaktiert eine externe Datenquelle und belastet Ihr Wallet für die Antwort – deshalb beginnt sie dort, wo auch die Sendelimits beginnen.

Derzeit nicht. Keine der beiden Operationen hat eine Batch-Variante, daher ist die Prüfung einer ganzen Liste nicht das, wofür Lookup ausgelegt ist. Bitten Sie uns, das Limit zu erhöhen, wenn Sie das brauchen, statt es zu umgehen.

Den lookup-Scope auf write-Ebene. Es gibt kein read-Level: Jeder Lookup-Endpunkt erfordert write, auch das Abrufen eines Ergebnisses, das Sie bereits bezahlt haben. Owners und Admins haben ihn standardmäßig, Members nicht.

Vier relevante. E22000, wenn die Nummer kein gültiges internationales Format hat. E22003, wenn die Adresse keine gültige E-Mail-Adresse ist. E22001, wenn das Wallet der Organisation die Abfrage nicht decken kann. E22002, wenn Lookup vorübergehend nicht verfügbar ist. Keine davon wird Ihnen berechnet.

Nein. Eine fehlschlagende Eigenschaft wird als Status in ihrem eigenen Block zurückgegeben, während die Basisabfrage daneben ausgeliefert wird. Nur wenn die Basisabfrage selbst fehlschlägt, schlägt der Request fehl – und dann vollständig, statt eine halbgefüllte Antwort zurückzugeben, die Sie erst inspizieren müssten, um festzustellen, dass sie leer war.

Die Basisabfrage liefert das Land der Nummer, das aktuell zuständige Netz, das Netz, das den Nummernbereich vergeben hat, ob die Nummer jemals das Netz gewechselt hat, und einen groben Leitungstyp. Sie wird immer ausgeführt, und wenn sie nicht beantwortet werden kann, schlägt die gesamte Anfrage fehl, anstatt eine halb leere Antwort zurückzugeben.

Zuerst die Landesvorwahl, dann die nationale Nummer. Das führende Plus ist optional, und 00 funktioniert als Ersatz – +31612345678, 31612345678 und 0031612345678 bezeichnen also dieselbe Nummer.

Eine Nummer, die für die Inlandswahl ohne Landesvorwahl geschrieben ist, gibt E22000 zurück, statt geraten zu werden. Würde man eine Landesvorwahl vor 0612345678 setzen, würde das eine reale Nummer anderswo bezeichnen – und Ihnen diese Abfrage in Rechnung stellen.

mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other oder unknown. unknown bedeutet, dass die Carrier-Plattform keine Klassifizierung für den Bereich führt, und other bedeutet, dass sie eine führt, die hier keine Entsprechung hat. Fragen Sie die Eigenschaft classification ab, um den zugewiesenen Dienst mit feinerer Auflösung zu erhalten.

network_info ist das Netz, das die Nummer aktuell bedient, und original_network_info ist das Netz, das den Bereich vergeben hat. Die beiden unterscheiden sich, sobald eine Nummer portiert wurde, und flags enthält in diesem Fall ported. Fragen Sie die Eigenschaft porting ab, wenn Sie auch das Datum und den vollständigen Datensatz benötigen.

Weil die Nummer keinem einzelnen Land zugehört, wie es bei einem nicht-geografischen Nummernbereich der Fall ist. Felder ohne Wert werden weggelassen statt als null zurückgegeben, sodass jedes in der Antwort vorhandene Feld tatsächlich aufgelöst wurde.

Nein. Eine Abfrage kontaktiert die Nummer selbst niemals. Sie liest Carrier- und Nummern-Informationsdaten, und die Eigenschaften presence und roaming befragen das Netz, in dem die Nummer registriert ist – es klingelt also nichts, und auf dem Gerät kommt nichts an.

Sechs, benannt in type. classification für den exakt zugewiesenen Dienst des Bereichs, porting für den Zeitpunkt des letzten Netzwechsels und jeden bisherigen Wechsel, presence für die Frage, ob die Nummer gerade im Netz aktiv ist, roaming für die Frage, ob sie roamt und in welchem Netz, sim_swap für den Zeitpunkt des letzten SIM-Wechsels und score für einen Glaubwürdigkeitswert von 0 bis 100.

Ja. classification, porting und score lesen gespeicherte Daten und antworten schnell. presence, roaming und sim_swap greifen auf das Live-Netz zu, sind daher langsamer, und ihre Abdeckung variiert je nach Betreiber. Erwarten Sie bei diesen dreien häufiger unavailable oder inconclusive als bei den gespeicherten.

ok bedeutet, die Eigenschaft wurde beantwortet, ihr Wert ist in der Antwort enthalten, und sie wurde berechnet. unavailable bedeutet, es kam keine Antwort, und sie wurde nicht berechnet. inconclusive bedeutet, es kam eine Antwort, aber sie löst die Eigenschaft nicht auf – das ist ein reales Ergebnis, und es wurde ebenfalls nicht berechnet.

Ja, status ist ein offenes Vokabular. Verzweigen Sie auf ok und behandeln Sie alles andere als nicht beantwortet – dann bleibt Ihr Code korrekt, egal wie das Vokabular wächst.

porting liefert Ihnen das Datum und die vollständige Historie, während das Flag ported der Basisabfrage nur angibt, ob jemals ein Wechsel stattfand. classification löst line_type zum exakt zugewiesenen Dienst auf, aus einer anderen Quelle mit einem breiteren Vokabular, und wird separat ausgegeben, damit Sie die beiden immer unterscheiden können.

Weil das Netz keinen exakten Wert freigegeben hat. sim_swap gibt min_days und max_days statt last_swapped_at zurück, wenn nur ein Aktualitätsband bekannt ist. porting macht etwas Ähnliches: Es setzt last_ported_at_is_approximate, wenn ein Register den Zeitraum eines Wechsels erfasst, aber nicht den Tag.

Nein. Es bedeutet, dass das Register abgefragt wurde und keinen Wechsel für diese Nummer verzeichnet hat – das ist ein Ergebnis über die Nummer, keine Lücke in der Antwort. Der Status des Blocks sagt Ihnen, ob die Prüfung überhaupt ausgeführt wurde.

Als ein Signal unter mehreren. Er reicht von 0 für geringe Glaubwürdigkeit bis 100 für hohe, ist ein Gesamtwert, und Sie können ihn nicht aus den anderen Eigenschaften ableiten. Wägen Sie ihn gegen den Rest der Antwort ab, statt allein danach zu entscheiden.

Ob die Adresse E-Mails annimmt. Ein Aufruf liefert ein Urteil in result, einen delivery_confidence-Score, die Flags, die die Art der Adresse beschreiben, und eine Korrektur, wenn die Adresse wie ein Tippfehler aussieht.

valid bedeutet, die Adresse existiert und nimmt E-Mails an – also senden. neutral bedeutet, sie konnte in keine Richtung bestätigt werden, meist weil die empfangende Domain bei jedem Empfänger gleich antwortet. risky bedeutet, sie nimmt wahrscheinlich E-Mails an, hat aber ein höheres Bounce- oder Beschwerderisiko als üblich. undeliverable bedeutet, sie nimmt keine E-Mails an. typo bedeutet, die Adresse sieht falsch geschrieben aus.

reason gibt an, welcher von drei Fehlern vorliegt: invalid_syntax bei einer fehlerhaften Adresse, invalid_domain wenn die Domain überhaupt keine E-Mails annimmt, und invalid_recipient wenn die Domain E-Mails annimmt, dieses Postfach aber nicht existiert.

Bieten Sie did_you_mean der Person an, die die ursprüngliche Adresse eingetippt hat, statt ungefragt an diese Adresse zu senden. Die Korrektur ist eine Vermutung, und die gemeinte Adresse kann eine ganz andere sein.

Der Score reicht von 0 (sicher nicht zustellbar) bis 100 (sicher zustellbar). Derselbe Score kann aus unterschiedlichen Gründen unter verschiedenen Urteilen stehen – lesen Sie ihn daher zusammen mit result, nicht anstelle davon. Er ist das Feld, auf das Sie sich stützen sollten, wenn Sie einen einzigen Schwellenwert über alle Urteile hinweg wollen, einschließlich künftig hinzukommender.

Nein, und der Unterschied ist wichtig. Das valid-Feld ist enger gefasst: Es sagt, ob die Adresse wohlgeformt ist und ob ihre Domain überhaupt für den E-Mail-Empfang eingerichtet ist. Es sagt nichts über das Postfach aus – eine Adresse mit funktionierender Domain, aber nicht existierendem Postfach ist dort true und in result undeliverable.

role bedeutet, die Adresse benennt eine Funktion statt einer Person, z. B. support@ oder info@, sodass Antworten und Einwilligungen mehrdeutig und Beschwerden wahrscheinlicher sind. disposable bedeutet einen Wegwerf-Adressen-Anbieter – die Adresse wird in der Regel bald nicht mehr existieren. free_provider bedeutet einen Consumer-Postfach-Anbieter wie Gmail oder Outlook.com, was nur dann ein Signal ist, wenn Sie eine geschäftliche Adresse erwartet haben.

Senden Sie eine nackte Adresse, genau so, wie Sie sie gespeichert haben. Eine Display-Name-Form, mit einem Namen davor und der Adresse in spitzen Klammern, wird abgelehnt statt ausgepackt, weil das Auspacken eine Adresse abfragen würde, die Sie nicht gesendet haben. Der Teil vor dem @-Zeichen wird unverändert weitergegeben, und eine Änderung der Groß-/Kleinschreibung kann den delivery_confidence-Wert beeinflussen, den Sie zurückerhalten.

Nein. Suppressions erledigen das automatisch und kostenlos – für Adressen, die bereits gebounced sind oder Beschwerden ausgelöst haben. Nutzen Sie Lookup für Adressen, an die Sie noch nicht gesendet haben: bei der Registrierung oder bevor Sie auf einen Lead reagieren.