API de consulta de operadora em massa: tipo de linha e operadora

Consulte informações de operadora e tipo de linha de números em massa. Defina task_type como o código de operadora específico do país (por exemplo usaCarrier, deCarrier, idCarrier); use us_carrier_premium para detecção avançada de US/CA. Mesmo fluxo de tarefa em lote dos outros verificadores.

Exemplo para enviar o arquivo de detecção:

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: API-KEY' \
--form 'file=@"./numbers.txt"' \
--form 'task_type="usaCarrier"'

Exemplo para consultar o status da tarefa:

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

Resposta para upload bem-sucedido:

{
    "task_id": "d4g8o46p2jvh04o9uolg",
    "status": "pending",
    "total": 2049,
    "estimated_amount": {
        "amount": "0.500000",
        "currency": "USD"
    },
    "message": "Task created successfully",
    "created_at": "2026-04-28T11:58:08.916446594Z"
}

Resposta para status de processamento:

{
    "created_at": "2026-04-28T08:27:09.933Z",
    "updated_at": "2026-04-28T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "processing",
    "total": 2049,
    "success": 1024,
    "failure": 0
}

Resposta quando a tarefa for concluída (inclui a URL de download):

{
    "created_at": "2026-04-28T08:27:09.933Z",
    "updated_at": "2026-04-28T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "exported",
    "total": 2049,
    "success": 2049,
    "failure": 0,
    "result_url": "https://example-link-to-results.zip",
    "actual_amount": {
      "amount": "2.000000",
      "currency": "USD"
    }
}

URL da requisição para upload de arquivo

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

Parâmetros da requisição para upload de arquivo

Parâmetro	Descrição
file	file, um número de telefone por linha (formato E.164)
task_type	string, defina como usaCarrier

URL da requisição para consultar status

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

Parâmetros da requisição para consultar status

Parâmetro	Descrição
task_id	string, ID da tarefa retornado na criação

Campos do resultado

Campo	Descrição
number	Número de telefone em formato E.164
number_type	Tipo de linha (ex.: móvel, fixo, virtual)
country_code	Código do país
carrier	Nome da operadora
underlying_carrier	Operadora subjacente (host) para números virtuais
region	Região / estado
city	Cidade

Formato da resposta

Campo	Descrição
created_at	Timestamp quando a tarefa foi criada
updated_at	Timestamp da última atualização de status
task_id	Identificador único da tarefa
user_id	ID do usuário
status	pending · processing · exported · failed (reembolsado automaticamente)
total	Total de números de telefone processados
success	Números identificados com sucesso
failure	Números que falharam no processamento
result_url	URL de download quando o status é exported
actual_amount	(Opcional) Valor efetivamente cobrado, disponível após a liquidação da tarefa
estimated_amount	(Resposta de criação) Valor estimado da tarefa; a cobrança final é liquidada na conclusão

Códigos de status

Status	Descrição
200	free, Solicitação bem-sucedida (ex.: consulta de status)
202	charge, Tarefa criada com sucesso; o valor estimado é deduzido
400	free, Solicitação inválida: parâmetros ou formato de arquivo inválidos, tipo de tarefa não suportado ou entradas válidas abaixo do lote mínimo
401	free, Chave de API ausente ou inválida
402	free, Saldo insuficiente
404	free, Tarefa não encontrada
413	free, Arquivo enviado muito grande
500	free, Erro interno do servidor, tente novamente mais tarde