Phone Carrier Bulk Lookup API: Verificação em lote

Consulta a operadora, a operadora subjacente, o tipo de linha, o código do país, a região e a cidade associados a cada número de celular enviado. Simplifica o agrupamento por operadora e a triagem de números virtuais. A tarefa usa o fluxo de trabalho padrão de processamento em lote assíncrono.

Formato de entrada

Envie um arquivo de texto com um número de telefone por linha. Normalize os valores antes do upload; o formato E.164 é recomendado para telefones.

+14155552671
+13105551234

Envie um país por tarefa. Os números são normalizados de acordo com o país da tarefa (veja country_code abaixo); números de outro país no mesmo arquivo são reescritos para esse país e não retornarão resultados corretos.

Criar uma tarefa

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="globalCarrier"' \
--form 'country_code="US"'

Parâmetros da requisição

Campo	Obrigatório	Descrição
file	sim	Arquivo de texto, um número de telefone por linha.
task_type	sim	globalCarrier. Os tipos de tarefa por país anteriores (usaCarrier, deCarrier, gbCarrier, …) continuam sendo aceitos e apontam para este mesmo produto.
country_code	não	País ISO-3166 alfa-2 dos números do arquivo (US, DE, OM, …). Usado para normalizar números escritos sem código de país. Se omitido, é inferido do arquivo.

A API retorna um ID de tarefa. Guarde esse ID e use-o para consultar o status.

Resposta do upload

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Verificar status da tarefa

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Consulte até que status se torne exported. Não trate pending ou processing como resultado concluído.

Resposta em processamento

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Resposta exportada

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Campos do resultado

Campo	Descrição	Exemplo
number	Número de telefone do arquivo enviado.	+14155552671
number_type	Tipo de linha retornado para o número.	mobile
country_code	country_code value returned for the input.	valor de exemplo
carrier	Carrier value returned for the number.	Exemplo Carrier
underlying_carrier	Carrier value returned for the number.	Exemplo Carrier
region	region value returned for the input.	valor de exemplo
city	Cidade retornada pelo serviço para a entrada.	valor de exemplo

Tratamento do arquivo de resultado

Baixe o arquivo por result_url somente após a tarefa ser exportada. Preserve os nomes das colunas retornados ao processar o arquivo.

Campos da resposta

Campo	Descrição
created_at	Data e hora de criação da tarefa.
updated_at	Data e hora da última atualização de status.
task_id	Identificador exclusivo da tarefa.
status	pending, processing, exported ou failed.
total	Total de valores de entrada processados.
success	Valores processados com sucesso.
failure	Valores cujo processamento falhou.
result_url	URL de download quando a tarefa é exportada.
actual_amount	Valor final liquidado, quando disponível.
estimated_amount	Valor estimado retornado ao criar a tarefa.

Códigos de status

Status	Descrição
200	Solicitação bem-sucedida.
202	Tarefa criada com sucesso e cobrança estimada aplicada.
400	Arquivo inválido, tipo de tarefa não compatível ou poucas entradas válidas.
401	Chave de API ausente ou inválida.
402	Saldo insuficiente.
403	Produto indisponível para sua conta (descontinuado ou restrito à lista de permissões); entre em contato com o suporte.
404	Tarefa não encontrada.
413	O arquivo enviado é grande demais.
500	Erro interno do servidor; tente novamente mais tarde.
503	Produto temporariamente indisponível (pausado para manutenção); nada é cobrado, tente novamente mais tarde.

Observações operacionais

• A tarefa é assíncrona; use o ID da tarefa para consultar o status.
• Verifique os limites de entrada do produto antes do upload.
• As linhas com falha aparecem no resultado exportado e são refletidas nos contadores.
• Os campos acima são baseados no sample atual e podem mudar quando o esquema de exportação upstream mudar.