Referência

CarrierLookup Referência da API

Todos os endpoints compartilham uma chave de API e um saldo.

Item	Valor
URL base	https://carrierlookup.online
Cabeçalho de autenticação	X-API-Key: sk_your_api_key
Envelope da resposta	{ code, msg, data }

Os preços não são listados aqui; todos os produtos são cobrados por verificação bem-sucedida. Ver preços

Autenticação

Use uma chave de API criada em Configurações e envie-a em todas as solicitações.

Cabeçalho de autenticação

X-API-Key: sk_your_api_key

Mantenha sua chave de API em segredoSempre chame este endpoint a partir do seu servidor. Qualquer pessoa que tenha a chave pode gastar seu saldo.

Verificações síncronas

POST/api/v1/checkPOST/api/v1/batch-check

Envie um número de telefone, ou até 100 em uma única solicitação, e leia o resultado na mesma resposta. Sem polling, sem callbacks. Um resultado indeterminado retorna 422 com code 42200 e não é cobrado. Uma solicitação múltipla mantém a ordem de entrada, cobra cada identificador de forma independente e tem 300 segundos para terminar — se não terminar, a solicitação inteira falha e todas as cobranças são reembolsadas.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto, um dos produtos listados abaixo.
`identifier`	string	Verificação única: um número de telefone. O servidor o normaliza.
`identifiers`	string[]	Verificação múltipla: de 1 a 100 números de telefone. A resposta preserva esta ordem.

Produtos deste grupo

Consulta da operadora originalcarrierDescubra a operadora à qual um número foi originalmente alocado, com tipo de linha e localização.Página do produto

Consulta da operadora original

carriertelefone

Descubra a operadora à qual um número foi originalmente alocado, com tipo de linha e localização.

Verificação única

POST/api/v1/check

Solicitação

curl -X POST "https://carrierlookup.online/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+17253100591",
    "carrier": "T-Mobile",
    "underlying_carrier": "",
    "number_type": "Fixed Line or Mobile",
    "country_code": "US",
    "region": "NV",
    "city": "LAS VEGAS"
  }
}

Campos da resposta

Campo	Tipo	Descrição
`carrier`	string	Operadora à qual o número foi originalmente alocado. Não é a operadora atual após a portabilidade.
`underlying_carrier`	string	Operadora subjacente informada pelo provedor quando difere da alocada; string vazia quando o provedor não a fornece.
`number_type`	string	Tipo de linha informado pelo provedor; vazio quando indisponível.
`country_code`	string	Código ISO do país ao qual o número pertence.
`region`	string	Região de alocação; vazia quando o provedor não a fornece.
`city`	string	Cidade de alocação; vazia quando o provedor não a fornece.

Verificação múltipla

POST/api/v1/batch-check

Solicitação

curl -X POST "https://carrierlookup.online/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifiers": ["+17253100591", "12345"] }'

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "carrier": "T-Mobile",
        "underlying_carrier": "",
        "number_type": "Fixed Line or Mobile",
        "country_code": "US",
        "region": "NV",
        "city": "LAS VEGAS"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`exists`	boolean	Se este número gerou um resultado. false significa que o formato era inválido, o resultado foi indeterminado ou a verificação falhou; quando false, nenhum dos campos abaixo está presente.
`carrier`	string	Operadora à qual o número foi originalmente alocado. Não é a operadora atual após a portabilidade.
`underlying_carrier`	string	Operadora subjacente informada pelo provedor quando difere da alocada; string vazia quando o provedor não a fornece.
`number_type`	string	Tipo de linha informado pelo provedor; vazio quando indisponível.
`country_code`	string	Código ISO do país ao qual o número pertence.
`region`	string	Região de alocação; vazia quando o provedor não a fornece.
`city`	string	Cidade de alocação; vazia quando o provedor não a fornece.

Verificações assíncronas

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Envie um arquivo e receba um ID de tarefa imediatamente; depois, consulte esse ID até que seja concluído com sucesso. A resposta de sucesso inclui result_url, o link para baixar o resultado. Existem apenas duas ações: enviar e consultar. Não consulte com frequência maior que uma vez a cada 30 segundos.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto em massa, um dos produtos listados abaixo.
`country`	string	Código ISO 3166-1, como `US`. Obrigatório para tarefas de números: cada número deve incluir o código do país e pertencer a este país (os números que não atendem a isso são excluídos e não são cobrados); também define o roteamento. Em multipart, deve vir antes de `file`.
`file`	file	Um `.txt` ou `.csv` com um identificador por linha, até `max_file_bytes` (20MB por padrão).
`Idempotency-Key`	header	Opcional, até 128 caracteres. Reenviar a mesma chave retorna a tarefa original em vez de criar uma segunda.

Produtos deste grupo

Consulta global de operadoracarrier_batchEnvie um arquivo inteiro de números: operadora, operadora subjacente, tipo de linha, país, região e cidade de cada um — os mesmos campos da consulta de operadora em tempo real.Página do produto

Consulta global de operadora

carrier_batchtelefone1.000–500.000 por tarefa

Envie um arquivo inteiro de números: operadora, operadora subjacente, tipo de linha, país, região e cidade de cada um — os mesmos campos da consulta de operadora em tempo real.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

curl -X POST "https://carrierlookup.online/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F file=@numbers.txt

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar a tarefa

GET/api/v1/bulk-tasks/{id}

Solicitação

curl "https://carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`carrier`	T-Mobile	Operadora à qual o número foi originalmente alocado. Não é a operadora atual após a portabilidade.
`underlying_carrier`		Operadora subjacente informada pelo provedor quando difere da alocada; vazia quando o provedor não a fornece.
`number_type`	Fixed Line or Mobile	Tipo de linha informado pelo provedor, como Fixed Line or Mobile; vazio quando indisponível.
`country_code`	US	Código ISO do país ao qual o número pertence.
`region`	CA	Região de alocação; vazia quando o provedor não a fornece.
`city`	LOS ANGELES	Cidade de alocação; vazia quando o provedor não a fornece.

Saldo

GET/api/v1/balance

Lê o saldo atual da conta em micros de USD. Somente leitura: não cria registro de verificação nem cobra nada.

Saldo

GET/api/v1/balance

Solicitação

curl "https://carrierlookup.online/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concorrência, tempos limite e comportamento de novas tentativas

As consultas de operadora são síncronas. Use o code retornado para decidir se aceita o resultado ou tenta novamente mais tarde.

Campo	Descrição
`5 solicitações simultâneas por usuário`	As verificações únicas e múltiplas compartilham este limite, e uma solicitação múltipla conta como uma solicitação, independentemente de quantos números ela contenha. Além disso, apenas uma verificação múltipla por conta é executada por vez; uma segunda é rejeitada até que a primeira termine. Atingir qualquer um dos limites retorna o code 42901 imediatamente, sem cobrança, com um cabeçalho Retry-After — reenvie assim que uma solicitação em andamento terminar.
`60s para única, 300s para múltipla`	Exceder o tempo limite retorna o code 50400, sem cobrança. Uma verificação múltipla que excede o tempo falha por completo — sem resultados parciais, e o valor total é reembolsado.
`Uma verificação múltipla aceita até 100 números`	Os resultados preservam a ordem e a quantidade do envio. Uma verificação múltipla por conta é executada por vez; envie o próximo lote depois que o anterior retornar.

Códigos de erro

Código	Descrição
`40000`	Tipo de serviço não suportado ou campos da solicitação conflitantes
`40001`	Corpo JSON inválido
`40002`	Número inválido
`40100`	Chave de API ausente ou inválida
`40200`	Saldo insuficiente
`42200`	Não foi possível determinar o número neste momento. Nenhum dado é retornado e a solicitação não é cobrada
`42900`	Uma cota de uso foi esgotada ou há pedidos não concluídos demais
`42901`	Todas as cinco vagas de solicitações simultâneas estão ocupadas ou já há uma verificação múltipla em execução nesta conta; envie depois que uma solicitação em andamento terminar. A solicitação rejeitada não é cobrada e traz um cabeçalho Retry-After
`50303`	O serviço está no limite da capacidade agora; sem cobrança. Aguarde os segundos de Retry-After e reenvie a mesma solicitação
`50400`	A verificação não terminou dentro do tempo limite e não é cobrada; tente novamente. O tempo esgotado de um lote faz o lote inteiro falhar e reembolsa o valor total
`50300`	Manutenção do serviço de consulta