FAQ da Lookup API

O Lookup responde a perguntas sobre um destinatário antes de lhe enviar uma mensagem. Forneça um número de telefone e ele diz-lhe o que o número é: a rede que o serve, o país, se mudou de rede e que tipo de linha é. Forneça um endereço de email e ele diz-lhe se vale a pena enviar para esse endereço.

Duas coisas, uma operação cada. Uma consulta de número de telefone devolve o país, a rede que serve o número, a rede que o emitiu, se mudou entre as duas e o tipo de linha, além de qualquer propriedade que solicite. Uma consulta de endereço de email devolve um veredito, uma pontuação de confiança e as flags por trás dele.

Cada consulta é um pedido e uma resposta. Não há nada para criar, nada para consultar periodicamente e nada para limpar depois. Métodos tipados estão disponíveis nos SDKs de Go, TypeScript, Python e PHP, e bird lookup phone-number e bird lookup email fazem o mesmo a partir da CLI.

Sim. A página Lookup no painel executa as mesmas duas operações uma de cada vez, o que é a forma mais rápida de ver como é uma resposta antes de construir sobre ela.

Uma chave API com o scope lookup e uma carteira de organização que cubra o custo. O preço é por consulta, sem taxa por utilizador, por isso não há plano para escolher primeiro.

Use-o quando quiser decidir antes de se comprometer: filtrar um registo, avaliar um lead antes de agir sobre ele, ou encaminhar uma mensagem de forma diferente consoante o tipo de linha. Obtém uma resposta sobre a qual pode agir sem enviar nada primeiro.

Por consulta. Cada lookup é cobrado na carteira da sua organização. Uma consulta de número de telefone cobra uma vez pela consulta base, mais uma cobrança por cada propriedade que é respondida. Uma consulta de endereço de e-mail cobra uma vez por endereço respondido. Não há taxa por utilizador.

A página de preços do Lookup lista a tarifa da consulta base, de cada propriedade e de uma consulta de endereço de e-mail. As tarifas variam por propriedade, porque cada uma provém de uma fonte de dados diferente.

Não. Uma propriedade só é cobrada quando é entregue. Uma que não pôde ser respondida volta com um status a indicá-lo e não lhe custa nada, e a consulta base continua a ser servida juntamente com ela.

Nada é cobrado. Um número mal formatado, um endereço que recusamos e uma fonte de dados inacessível não custam nada.

Sim. Cada endereço respondido é cobrado, incluindo os não entregáveis. Essa é a resposta que pediu e é a que lhe poupa um bounce.

Não, se enviar um Idempotency-Key. Uma repetição do mesmo pedido reproduz a resposta armazenada em vez de executar uma nova consulta. Os formulários GET, que colocam o número ou o endereço no URL, não suportam chave de idempotência, por isso use POST para qualquer coisa automatizada.

O limite de taxa de consultas começa em 10 pedidos por minuto, contados por credencial ativa, para que uma chave ocupada não bloqueie outra. Cada consulta acede a uma fonte de dados externa e cobra da sua carteira pela resposta, razão pela qual começa onde começam os limites de envio.

Não atualmente. Nenhuma das operações tem uma forma em lote, por isso verificar uma lista inteira não é o cenário para o qual está dimensionado. Peça-nos para aumentar o limite se for o que precisa, em vez de contorná-lo.

O scope lookup com nível de escrita. Não tem nível de leitura: todos os endpoints de consulta requerem escrita, incluindo obter um resultado pelo qual já pagou. Owners e admins têm-no por predefinição; members não.

Quatro relevantes. E22000 quando o número não é válido em formato internacional, E22003 quando o endereço não é um endereço de email válido, E22001 quando a carteira da organização não cobre a consulta, e E22002 quando o Lookup está temporariamente indisponível. Nenhum deles gera cobrança.

Não. Uma propriedade que falha é devolvida como um status no seu próprio bloco, com a consulta base servida em paralelo. Só a falha da consulta base faz o pedido falhar, e nesse caso falha por completo em vez de devolver uma resposta semi-vazia que teria de inspecionar para descobrir que estava vazia.

A consulta base responde o país do número, a rede que o serve atualmente, a rede que emitiu a sua faixa, se alguma vez mudou de rede e um tipo de linha aproximado. É sempre executada e, se não puder ser respondida, todo o pedido falha em vez de devolver uma resposta meio vazia.

Código de chamada do país primeiro, depois o número nacional. O sinal de mais inicial é opcional e 00 funciona no seu lugar, por isso +31612345678, 31612345678 e 0031612345678 são todos o mesmo número.

Um número escrito para marcação dentro de um país, sem código de país, devolve E22000 em vez de ser adivinhado. Adicionar um código de país a 0612345678 identificaria um número real noutro lugar e cobraria pela consulta desse número.

mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other ou unknown. unknown significa que a plataforma da operadora não tem classificação para a faixa, e other significa que tem uma sem equivalente aqui. Solicite a propriedade classification para o serviço alocado com maior precisão.

network_info é a rede que serve o número atualmente e original_network_info é a rede que emitiu a sua faixa. As duas diferem quando um número foi portado, e flags contém ported nesse caso. Solicite a propriedade porting quando também precisar da data e do registo completo.

Porque o número não pertence a nenhum país específico, como acontece com uma faixa não geográfica. Campos sem valor são omitidos em vez de devolvidos como null, por isso cada campo presente na resposta foi resolvido.

Não. Uma consulta nunca contacta o próprio número. Lê dados da operadora e de inteligência do número, e as propriedades presence e roaming consultam a rede onde o número está registado, por isso nada toca e nada chega ao aparelho.

Seis, nomeadas em type. classification para o serviço alocado preciso da faixa, porting para quando o número mudou de rede pela última vez e todos os movimentos registados, presence para saber se está ativo na rede neste momento, roaming para saber se está em roaming e em que rede, sim_swap para quando o SIM foi alterado pela última vez, e score para uma pontuação de credibilidade de 0 a 100.

Sim. classification, porting e score leem dados armazenados e respondem rapidamente. presence, roaming e sim_swap acedem à rede em tempo real, por isso são mais lentas e a sua cobertura varia por operadora. Espere unavailable ou inconclusive para essas três com mais frequência do que para as armazenadas.

ok significa que a propriedade foi respondida, o seu valor está na resposta e foi cobrada. unavailable significa que não chegou resposta e não foi cobrada. inconclusive significa que chegou uma resposta mas não resolve a propriedade, o que é uma constatação real, e também não foi cobrada.

Sim, status é um vocabulário aberto. Ramifique com base em ok e trate tudo o resto como não respondido, e o seu código permanece correto independentemente de como o vocabulário crescer.

porting fornece a data e o histórico completo, enquanto o flag ported da consulta base apenas indica se alguma mudança aconteceu. classification resolve o line_type para o serviço alocado exato, a partir de uma fonte diferente com um vocabulário mais amplo, e é reportado separadamente para que possa sempre distinguir os dois.

Porque a rede não disponibilizou um valor exato. sim_swap devolve min_days e max_days em vez de last_swapped_at quando apenas uma faixa de recência é conhecida. porting faz algo semelhante: define last_ported_at_is_approximate quando um registo indica o período de uma mudança, mas não o dia.

Não. Significa que o registo foi consultado e não contém nenhuma mudança para este número, o que é uma constatação sobre o número e não uma lacuna na resposta. É o status no bloco que indica se a verificação foi de facto executada.

Como um sinal entre vários. Varia de 0 para baixa credibilidade a 100 para alta, é um valor composto e não pode ser derivado das outras propriedades. Avalie-o em conjunto com o resto da resposta, em vez de se basear apenas nele.

Se o endereço aceita emails. Uma única chamada devolve um veredito em result, uma pontuação de delivery_confidence, as flags que descrevem o tipo de endereço e uma correção quando o endereço parece ter um erro de digitação.

valid significa que o endereço existe e aceita emails — pode enviar. neutral significa que não foi possível confirmar de nenhuma forma, normalmente porque o domínio recetor responde da mesma maneira a todos os destinatários. risky significa que provavelmente aceita emails, mas tem maior probabilidade de devolver ou gerar reclamações. undeliverable significa que não aceita emails. typo significa que o endereço parece ter um erro de digitação.

reason indica qual dos três problemas existe: invalid_syntax para um endereço mal formatado, invalid_domain quando o domínio não aceita emails de todo, e invalid_recipient quando o domínio aceita emails mas esta caixa de correio não existe.

Ofereça did_you_mean a quem digitou o endereço original em vez de enviar para ele sem confirmação. A correção é uma sugestão, e o endereço pretendido pode não ser nenhum dos dois.

Vai de 0, certeza de que não será entregue, a 100, certeza de que será. A mesma pontuação pode estar associada a vereditos diferentes por razões diferentes, por isso leia-a em conjunto com result e não em substituição dele. É o campo a usar quando quer um único limiar para todos os vereditos, incluindo vereditos adicionados no futuro.

Não, e a diferença é importante. O campo valid é mais restrito: indica se o endereço está bem formatado e se o seu domínio está configurado para receber emails. Nada diz sobre a caixa de correio, por isso um endereço com um domínio funcional mas sem essa caixa de correio será true nesse campo e undeliverable em result.

role significa que o endereço designa uma função e não uma pessoa, como support@ ou info@, pelo que respostas e consentimento são ambíguos e reclamações são mais prováveis. disposable indica um fornecedor de endereços descartáveis, por isso o endereço normalmente deixará de existir. free_provider indica um fornecedor de email gratuito como Gmail ou Outlook.com, o que só é relevante quando se esperava um endereço empresarial.

Envie o endereço simples, exatamente como o tem registado. Um formato com nome de exibição — com um nome à frente e o endereço entre parênteses angulares — é rejeitado em vez de desembrulhado, porque desembrulhá-lo consultaria um endereço que não foi enviado por si. A parte antes do arroba é passada tal como está, e alterar as maiúsculas e minúsculas pode alterar o delivery_confidence que recebe.

Não. As supressões fazem isso automaticamente e sem custos, para endereços que já devolveram ou geraram reclamações. Use o Lookup para endereços para os quais ainda não enviou, no momento do registo ou antes de agir sobre um lead.