# 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.

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/pt-br/documentacao/guides/lookup/phone-numbers.ts.md) · [Python](/pt-br/documentacao/guides/lookup/phone-numbers.py.md) · [Go](/pt-br/documentacao/guides/lookup/phone-numbers.go.md) · [PHP](/pt-br/documentacao/guides/lookup/phone-numbers.php.md) · [CLI](/pt-br/documentacao/guides/lookup/phone-numbers.cli.md) · [MCP](/pt-br/documentacao/guides/lookup/phone-numbers.mcp.md) · [cURL](/pt-br/documentacao/guides/lookup/phone-numbers.curl.md)

## 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`](/docs/api/errors/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.

| Propriedade      | O que responde                                                                     |
| ---------------- | ---------------------------------------------------------------------------------- |
| `classification` | O serviço alocado exato da faixa: tarifa premium, satélite, M2M, telefone público. |
| `porting`        | Quando o número mudou de rede pela última vez e todas as mudanças registradas.     |
| `presence`       | Se o número está ativo na rede no momento.                                         |
| `roaming`        | Se está em roaming e em qual rede.                                                 |
| `sim_swap`       | Quando o SIM foi trocado pela última vez.                                          |
| `score`          | Uma pontuação de credibilidade de 0 a 100.                                         |

`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.

```json
{
  "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](/docs/guides/idempotency).

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

| Código                              | O que aconteceu                                                                                 |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| [`E22000`](/docs/api/errors/E22000) | O número não é um número de telefone válido em formato internacional. Nada foi cobrado.         |
| [`E22001`](/docs/api/errors/E22001) | A carteira da organização não cobre a consulta. Recarregue e tente novamente. Nada foi cobrado. |
| [`E22002`](/docs/api/errors/E22002) | A consulta está temporariamente indisponível. Tente novamente com backoff. Nada foi cobrado.    |

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](/docs/guides/lookup/email-addresses) é a outra metade do Lookup.
- [Referência API do Lookup](/docs/api/reference/create-phone-number-lookup) documenta cada campo e cada bloco de propriedade.
- [Limites de requisições](/docs/guides/rate-limits) cobre o bucket `lookup` usado por essas chamadas.
- [Pesquisa de número de telefone: verifique um número antes de enviar](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) é um vídeo que executa uma consulta e adiciona as verificações de rede ao vivo.

## Related resources

- [Phone number lookup](/lookup-api) (product)

[Get an implementation brief](/learn/workspace?topic=lookup-phone)