Lookup API FAQ

Lookup odpowiada na pytania o odbiorcę, zanim cokolwiek do niego wyślesz. Podaj numer telefonu, a dowiesz się, czym ten numer jest: jaka sieć go obsługuje, w jakim kraju się znajduje, czy zmienił sieć i jaki to typ linii. Podaj adres e-mail, a dowiesz się, czy warto na niego wysyłać.

Dwie rzeczy, po jednej operacji na każdą. Wyszukiwanie numeru telefonu zwraca kraj, sieć obsługującą numer, sieć, która go wydała, czy numer migrował między nimi, oraz typ linii — plus każdą dodatkową właściwość, o którą poprosisz. Wyszukiwanie adresu e-mail zwraca jeden werdykt, ocenę pewności i flagi, na których się opiera.

Każde wyszukiwanie to jedno żądanie i jedna odpowiedź. Nie trzeba niczego tworzyć, odpytywać ani czyścić po zakończeniu. Typowane metody są dostępne w SDK dla Go, TypeScript, Python i PHP, a polecenia bird lookup phone-number i bird lookup email robią to samo z CLI.

Tak. Strona Lookup w panelu uruchamia te same dwie operacje pojedynczo — to najszybszy sposób, by zobaczyć, jak wygląda odpowiedź, zanim zaczniesz na niej budować.

Klucza API z uprawnieniem lookup oraz portfela organizacji, który pokryje opłatę. Rozliczenie jest za zapytanie, bez opłaty za stanowisko, więc nie trzeba najpierw wybierać planu.

Użyj go, gdy chcesz podjąć decyzję, zanim się zaangażujesz: weryfikacja rejestracji, sprawdzenie leada przed podjęciem działania lub routing wiadomości w zależności od typu linii. Otrzymujesz odpowiedź, na podstawie której możesz działać, bez konieczności wcześniejszego wysyłania czegokolwiek.

Za zapytanie. Każde wyszukiwanie jest rozliczane z portfela Twojej organizacji. Wyszukiwanie numeru telefonu jest naliczane raz za wyszukiwanie podstawowe plus jedna opłata za każdą właściwość, która zwróci odpowiedź. Wyszukiwanie adresu e-mail jest naliczane raz za każdy rozwiązany adres. Nie ma opłaty za stanowisko.

Strona cennika Lookup zawiera stawki za wyszukiwanie podstawowe, za każdą właściwość oraz za wyszukiwanie adresu e-mail. Stawki różnią się w zależności od właściwości, ponieważ każda pochodzi z innego źródła danych.

Nie. Opłata za właściwość jest naliczana tylko wtedy, gdy zostanie dostarczona. Właściwość, na którą nie udało się odpowiedzieć, wraca ze statusem informującym o tym i nic nie kosztuje, a wyszukiwanie podstawowe jest nadal dostarczane obok niej.

Nic nie jest naliczane. Błędny numer, adres, który odrzucamy, i źródło danych, z którym nie można się połączyć — wszystko to nic nie kosztuje.

Tak. Każdy rozwiązany adres jest naliczany, w tym niedostarczalny. To jest odpowiedź, o którą prosiłeś, i to ona oszczędza Ci odrzuconej wiadomości.

Nie, jeśli wyślesz Idempotency-Key. Powtórzenie tego samego żądania odtwarza zapisaną odpowiedź zamiast uruchamiać nowe wyszukiwanie. Formularze GET, które umieszczają numer lub adres w URL, nie mogą zawierać klucza idempotentności, więc do automatyzacji używaj POST.

Limit zapytań zaczyna się od 10 żądań na minutę, liczonych na aktywne poświadczenie, więc jeden obciążony klucz nie blokuje innego. Każde wyszukiwanie sięga do zewnętrznego źródła danych i obciąża portfel za odpowiedź — dlatego zaczyna się tam, gdzie zaczynają się limity wysyłki.

Na ten moment nie. Żadna z operacji nie ma formy zbiorczej, więc sprawdzanie całej listy nie jest scenariuszem, na jaki to rozwiązanie jest wymiarowane. Jeśli tego potrzebujesz, poproś nas o podniesienie limitu zamiast go obchodzić.

Uprawnienia lookup na poziomie zapisu. Nie ma poziomu odczytu: każdy endpoint wyszukiwania wymaga zapisu, w tym pobranie wyniku, za który już zapłaciłeś. Właściciele i administratorzy mają je domyślnie, a członkowie nie.

Cztery istotne. E22000, gdy numer nie jest prawidłowy w formacie międzynarodowym, E22003, gdy adres nie jest prawidłowym adresem e-mail, E22001, gdy portfel organizacji nie może pokryć kosztu wyszukiwania, oraz E22002, gdy Lookup jest tymczasowo niedostępny. Żaden z nich nie generuje opłaty.

Nie. Właściwość, która nie mogła zostać pobrana, wraca jako status w swoim własnym bloku, a podstawowe wyszukiwanie jest serwowane obok niej. Tylko błąd podstawowego wyszukiwania powoduje błąd żądania — i wtedy kończy się ono całkowicie zamiast zwracać na wpół pustą odpowiedź, którą trzeba by sprawdzić, żeby odkryć, że jest pusta.

Podstawowe wyszukiwanie zwraca kraj numeru, sieć aktualnie go obsługującą, sieć, która wydała jego zakres, czy kiedykolwiek zmienił sieć, oraz ogólny typ linii. Wykonuje się zawsze — jeśli nie może zwrócić odpowiedzi, całe żądanie kończy się błędem zamiast zwracać częściowo pustą odpowiedź.

Najpierw kod kraju, potem numer krajowy. Początkowy plus jest opcjonalny, a 00 działa jako jego zamiennik — +31612345678, 31612345678 i 0031612345678 to ten sam numer.

Numer zapisany w formacie do wybierania wewnątrz jednego kraju, bez kodu kraju, zwraca błąd E22000 zamiast być zgadywany. Dodanie kodu kraju do 0612345678 wskazałoby prawdziwy numer w innym miejscu i obciążyło Cię opłatą za jego wyszukanie.

mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other lub unknown. unknown oznacza, że platforma operatora nie ma klasyfikacji dla danego zakresu, a other oznacza, że posiada klasyfikację, która nie ma tutaj odpowiednika. Użyj właściwości classification, aby uzyskać dokładniejszą informację o przydzielonej usłudze.

network_info to sieć aktualnie obsługująca numer, a original_network_info to sieć, która wydała jego zakres. Te dwie wartości różnią się po przeniesieniu numeru, a flags zawiera wówczas ported. Użyj właściwości porting, jeśli potrzebujesz również daty i pełnego rekordu.

Ponieważ numer nie należy do żadnego konkretnego kraju, jak to bywa w przypadku zakresów niegeograficznych. Pola bez wartości są pomijane zamiast zwracane jako null, więc każde pole obecne w odpowiedzi zostało rozwiązane.

Nie. Wyszukiwanie nigdy nie kontaktuje się z samym numerem. Odczytuje dane operatora i dane analityczne numeru, a właściwości presence i roaming odpytują sieć, w której numer jest zarejestrowany — nic więc nie dzwoni i nic nie trafia na urządzenie.

Sześć, określonych w type. classification — precyzyjna przydzielona usługa zakresu, porting — kiedy numer ostatnio zmienił sieć i cała historia przeniesień, presence — czy numer jest aktualnie aktywny w sieci, roaming — czy korzysta z roamingu i w jakiej sieci, sim_swap — kiedy ostatnio zmieniono kartę SIM, oraz score — ocena wiarygodności od 0 do 100.

Tak. classification, porting i score odczytują zapisane dane i zwracają wyniki szybko. presence, roaming i sim_swap odpytują sieć na żywo, więc są wolniejsze, a ich pokrycie zależy od operatora. W przypadku tych trzech spodziewaj się statusów unavailable lub inconclusive częściej niż w przypadku zapisanych.

ok oznacza, że właściwość została rozwiązana, jej wartość jest w odpowiedzi i została naliczona. unavailable oznacza, że nie otrzymano odpowiedzi i nie została naliczona. inconclusive oznacza, że odpowiedź nadeszła, ale nie rozwiązuje właściwości — to realne ustalenie — i również nie została naliczona.

Tak, status to otwarty słownik. Rozgałęziaj logikę na ok, a wszystko inne traktuj jako brak odpowiedzi — wtedy Twój kod pozostanie poprawny niezależnie od rozszerzania słownika.

porting podaje datę i pełną historię, podczas gdy flaga ported z wyszukiwania podstawowego informuje jedynie, czy przeniesienie kiedykolwiek miało miejsce. classification rozwiązuje line_type do dokładnej przydzielonej usługi, z innego źródła i z szerszym słownikiem, i jest raportowana osobno, dzięki czemu zawsze możesz je odróżnić.

Ponieważ sieć nie udostępniła dokładnej wartości. sim_swap zwraca min_days i max_days zamiast last_swapped_at, gdy znany jest jedynie przedział czasu. porting działa podobnie: ustawia last_ported_at_is_approximate, gdy rejestr odnotowuje okres przeniesienia, ale nie konkretny dzień.

Nie. Oznacza to, że rejestr został zapytany i nie odnotowuje żadnego przeniesienia tego numeru — to ustalenie dotyczące numeru, a nie luka w odpowiedzi. To status bloku mówi, czy sprawdzenie w ogóle się wykonało.

Jako jeden z kilku sygnałów. Skala wynosi od 0 (niska wiarygodność) do 100 (wysoka wiarygodność). Jest to wskaźnik złożony, którego nie da się wyprowadzić z pozostałych właściwości. Rozpatruj go w kontekście całej odpowiedzi, zamiast opierać decyzje wyłącznie na nim.

Czy adres przyjmie pocztę. Jedno wywołanie zwraca werdykt w result, ocenę delivery_confidence, flagi opisujące rodzaj adresu oraz korektę, gdy adres wygląda na literówkę.

valid oznacza, że adres istnieje i przyjmuje pocztę — można wysyłać. neutral oznacza, że nie udało się tego potwierdzić w żadną stronę, zwykle dlatego, że domena odbierająca odpowiada tak samo na każdego odbiorcę. risky oznacza, że prawdopodobnie przyjmuje pocztę, ale ma większe niż zwykle ryzyko odrzucenia lub skargi. undeliverable oznacza, że adres nie przyjmuje poczty. typo oznacza, że adres wygląda na błędnie wpisany.

reason wskazuje, który z trzech problemów wystąpił: invalid_syntax w przypadku źle sformatowanego adresu, invalid_domain gdy domena w ogóle nie przyjmuje poczty, oraz invalid_recipient gdy domena przyjmuje pocztę, ale ta skrzynka nie istnieje.

Zaproponuj did_you_mean osobie, która wpisała oryginał, zamiast wysyłać na ten adres bez pytania. Korekta to zgadywanie, a zamierzony adres może nie być żadnym z nich.

Przyjmuje wartości od 0, czyli pewność niedostarczenia, do 100, czyli pewność dostarczenia. Ten sam wynik może znajdować się pod różnymi werdyktami z różnych powodów, więc czytaj go razem z result, a nie zamiast niego. To pole, na którym warto się oprzeć, gdy potrzebujesz jednego progu dla wszystkich werdyktów, w tym tych dodanych w przyszłości.

Nie, i ta różnica ma znaczenie. Pole valid jest węższe: mówi, czy adres jest poprawnie sformatowany i czy jego domena jest skonfigurowana do odbioru poczty. Nie mówi nic o skrzynce, więc adres z działającą domeną, ale nieistniejącą skrzynką będzie miał tam wartość true, a w result — undeliverable.

role oznacza, że adres wskazuje funkcję, a nie osobę, np. support@ lub info@, więc odpowiedzi i zgody są niejednoznaczne, a skargi bardziej prawdopodobne. disposable oznacza dostawcę jednorazowych adresów, więc adres zwykle przestanie istnieć. free_provider oznacza konsumencką usługę pocztową, np. Gmail czy Outlook.com, co jest sygnałem tylko wtedy, gdy oczekiwano adresu firmowego.

Wyślij sam adres, dokładnie tak, jak go przechowujesz. Format z nazwą wyświetlaną — z imieniem z przodu i adresem w nawiasach kątowych — jest odrzucany zamiast rozpakowywany, ponieważ rozpakowanie oznaczałoby wyszukanie adresu, którego nie wysłałeś. Część przed znakiem @ jest przekazywana bez zmian, a zmiana wielkości liter może zmienić zwracany wynik delivery_confidence.

Nie. Supresy robią to automatycznie i bezpłatnie w przypadku adresów, które już odbiły lub zgłosiły skargę. Użyj Lookup dla adresów, na które jeszcze nie wysyłałeś — przy rejestracji lub zanim zaczniesz działać na podstawie leada.