Consultar um número de telefone

Uma chamada responde o que um número é. Tudo aqui precisa de uma chave API com o escopo lookup.

Executar uma consulta base

Envie o número e nada mais. A consulta base é sempre cobrada uma vez, e sempre responde o país, a rede que serve o número, a rede que emitiu o número e um tipo de linha aproximado.

const answer = await bird.lookup.phoneNumber({
  phone_number: "+31612345678",
  type: ["classification", "score"],
});
console.log(answer.country_code, answer.line_type);
// Only a block whose status is ok carries a value, and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);

answer = client.lookup.phone_number(
    phone_number="+31612345678", type=["classification", "score"]
)
print(answer.country_code, answer.line_type)
# Only a block whose status is ok carries a value, and only that one is billed.
if answer.score is not None and answer.score.status == "ok":
    print(answer.score.value)

answer, err := client.Lookup.PhoneNumber(context.Background(), bird.LookupPhoneNumberParams{
	PhoneNumber: "+31612345678",
	Type:        []bird.LookupProperty{"classification", "score"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*answer.CountryCode, *answer.LineType)
// Only a block whose status is ok carries a value, and only that one is billed.
if answer.Score != nil && *answer.Score.Status == "ok" {
	fmt.Println(*answer.Score.Value)
}

$answer = $bird->lookup->phoneNumber(
    (new PhoneNumberLookupRequest())
        ->setPhoneNumber('+31612345678')
        ->setType(['classification', 'score']),
);
echo $answer->getCountryCode(), ' ', $answer->getLineType();
// Only a block whose status is ok carries a value, and only that one is billed.
if ($answer->getScore()?->getStatus() === 'ok') {
    echo $answer->getScore()->getValue();
}

bird lookup phone-number \
  --phone-number +31612345678 \
  --type classification \
  --type presence

curl -X POST "https://us1.platform.bird.com/v1/lookup/phone-number" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+31612345678",
    "type": [
      "classification",
      "presence"
    ]
  }'

Como escrever o número

Envie o código de chamada do país e depois o número nacional. O + inicial é opcional e 00 funciona no lugar dele, então +31612345678, 31612345678 e 0031612345678 são todos o mesmo número.

Um número escrito para discagem dentro de um único país, sem código de país, é rejeitado em vez de adivinhado. 0612345678 retorna E22000, porque adicionar um código de país identificaria um número real em outro lugar e você seria cobrado pela consulta.

O que a consulta base responde

country_code é o país do número, ausente quando o número não pertence a um único país, como acontece com uma faixa não geográfica.

network_info é a rede que atende o número hoje, e original_network_info é a rede que emitiu a faixa dele. Os dois diferem quando o número foi portado e, nesse caso, flags contém ported.

line_type é o tipo de linha do 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; other significa que tem uma sem equivalente aqui. Para o serviço alocado com maior precisão, solicite a propriedade classification. Ela responde a partir de uma fonte diferente com um vocabulário mais amplo e é reportada separadamente para que você sempre consiga distinguir as duas.

Adicionar propriedades

Informe as propriedades desejadas em type. Cada uma é cobrada separadamente e somente quando entregue.

classification, porting e score leem dados armazenados e retornam rapidamente. presence, roaming e sim_swap consultam a rede ao vivo, então são mais lentos e a cobertura varia por operadora. Espere unavailable ou inconclusive para esses com mais frequência do que para os armazenados.

Duas propriedades respondem perguntas que a consulta base já aborda, com maior resolução. porting fornece a data e o histórico completo, enquanto o flag ported da consulta base apenas diz se alguma mudança já ocorreu. classification resolve line_type para o serviço alocado exato.

Leia o status antes do valor

Todo bloco de propriedade traz um status, e somente ok traz um valor.

{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "unavailable"
  }
}

Nessa resposta, você foi cobrado pela consulta base e por classification. Você não foi cobrado por score.

Leia status primeiro e trate qualquer coisa diferente de ok como "not answered". É um vocabulário aberto, então um valor que você não reconhece é um status futuro, não um erro.

Dois blocos reportam um intervalo em vez de um valor exato quando a rede não libera um. sim_swap retorna min_days e max_days em vez de last_swapped_at quando apenas uma faixa de recência é conhecida. porting define last_ported_at_is_approximate quando um registro contém o período de uma mudança, mas não o dia exato.

Um campo parece negativo mas é uma constatação positiva: porting.ported definido como false significa que o registro foi consultado e não contém nenhuma mudança para esse número, não que nada pôde ser verificado. Essa distinção é a função de status.

Tentar novamente sem pagar duas vezes

Uma consulta é cobrada, então uma solicitação repetida não deve comprar uma segunda resposta. Envie um Idempotency-Key e uma repetição da mesma solicitação reproduz a resposta armazenada em vez de executar uma nova consulta. Veja Idempotência.

A forma GET dessa operação, que coloca o número na URL, não pode carregar uma chave de idempotência. Use a forma POST para qualquer automação.

Erros

Uma propriedade com falha não é um erro. Ela retorna como um status no bloco dela, e a consulta base é entregue junto.

Próximos passos

• Consultar um endereço de e-mail é a outra metade do Lookup.
• Referência API do Lookup documenta cada campo e cada bloco de propriedade.
• Limites de requisições cobre o bucket lookup usado por essas chamadas.
• Pesquisa de número de telefone: verifique um número antes de enviar é um vídeo que executa uma consulta e adiciona as verificações de rede ao vivo.