Przegląd Lookup

Lookup odpowiada na pytania o odbiorcę, zanim 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ć.

Oba przypadki to jedno zapytanie i jedna odpowiedź. Nie trzeba niczego tworzyć, odpytywać ani sprzątać po fakcie. Strona Lookup w dashboardzie uruchamia te same dwie operacje pojedynczo, co jest najszybszym sposobem, żeby zobaczyć, jak wygląda odpowiedź, zanim napiszesz jakikolwiek kod.

Ile kosztuje każde zapytanie

Każde zapytanie jest rozliczane z portfela Twojej organizacji i to jest część, którą warto zrozumieć, zanim zaczniesz na tym budować.

Zapytanie o numer telefonu zawsze nalicza jedną opłatę za bazowe zapytanie. Oprócz tego możesz zażądać właściwości, czyli dodatkowych informacji z płatnego źródła danych. Każda żądana właściwość jest rozliczana osobno, ale 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 Cię nie kosztuje.

Zapytanie o adres e-mail jest rozliczane raz za każdy adres, na który uzyskano odpowiedź. Każdy werdykt jest płatny, łącznie z undeliverable: to jest odpowiedź, o którą prosiłeś, i to ona oszczędza Ci zwrotki.

Nic nie jest naliczane, gdy zapytanie się nie powiedzie. Błędny numer, adres, który odrzucamy, lub źródło danych, z którym nie udało się połączyć, nie kosztują nic.

Cennik Lookup podaje stawkę za bazowe zapytanie, za każdą właściwość i za zapytanie o adres e-mail.

Zapytanie o numer ma dwa poziomy

Ten podział to cały projekt zapytania o numer telefonu, więc warto go opisać wprost.

Bazowe zapytanie uruchamia się zawsze. Odpowiada na pytania o obsługującą sieć, sieć, która wydała numer, kraj, czy numer kiedykolwiek zmienił sieć, oraz przybliżony line_type (komórkowy, stacjonarny, VoIP, bezpłatny itd.). Jeśli bazowe zapytanie nie może zostać obsłużone, całe żądanie kończy się błędem zamiast zwracać półpustą odpowiedź, którą musiałbyś sprawdzać, żeby odkryć, że jest pusta.

Właściwości dodajesz ponad bazowe zapytanie, podając je w type. Odpowiadają na bardziej szczegółowe pytania: dokładną przydzieloną usługę zakresu, pełny rekord przeniesienia numeru, czy numer jest w tej chwili aktywny w sieci, czy jest w roamingu, kiedy ostatnio wymieniono SIM i wynik wiarygodności. Właściwość, na którą nie udało się odpowiedzieć, nigdy nie powoduje błędu żądania. Zamiast wartości zwraca status, a bazowe zapytanie i tak jest obsługiwane.

Tylko ok niesie wartość i tylko ok jest rozliczane

Każdy blok właściwości ma status i jego odczytanie nie jest opcjonalne.

ok oznacza, że właściwość została obsłużona, jej wartość jest w odpowiedzi i została naliczona.

unavailable oznacza, że odpowiedź nie dotarła, więc właściwość nic nie wnosi. Nie została naliczona.

inconclusive oznacza, że odpowiedź dotarła, ale nie rozwiązuje właściwości: numer jest poza zasięgiem danych, na których właściwość się opiera, albo źródło zwróciło wartość, której ta właściwość nie raportuje. To realne ustalenie, a nie brak danych, i również nie zostało naliczone.

status to otwarty słownik, więc mogą pojawić się nowe wartości. Rozgałęziaj logikę według ok, a wszystko inne traktuj jak "not answered", a Twój kod pozostanie poprawny niezależnie od tego, jak słownik się rozrośnie.

Wybór między Lookup a walidacją przy wysyłce

Lookup służy do podejmowania decyzji przed podjęciem działania: sprawdzenia numeru lub adresu przy rejestracji, weryfikacji leada, zanim zaczniesz go obsługiwać, albo innego kierowania wiadomości w zależności od tego, jakim typem linii okaże się numer. Każde sprawdzenie kosztuje i daje odpowiedź, na podstawie której możesz działać.

Jeśli chcesz tylko przestać wysyłać na adresy, z których wiadomości już wróciły jako odbite lub które zgłosiły skargę, nie potrzebujesz Lookup. Suppresje robią to automatycznie i za darmo.

Zapytanie o adres e-mail udostępnia też endpoint wsadowy (POST /v1/lookup/email/batch), który sprawdza do 1000 adresów w jednym żądaniu, natomiast zapytanie o numer telefonu sprawdza jeden numer na żądanie. Obie operacje korzystają z grupy limitów lookup; zasady oraz sposób wnioskowania o wyższy limit opisuje strona Limity liczby żądań.

Kolejne kroki

• Sprawdź numer telefonu omawia bazowe zapytanie, każdą właściwość i co każda z nich zwraca.
• Sprawdź adres e-mail omawia werdykty i co zrobić z każdym z nich.
• Dokumentacja API Lookup dokumentuje każde pole.
• Idempotentność wyjaśnia, jak spróbować ponownie wykonać zapytanie bez płacenia za nie dwa razy.