Referência

NumDetect Referência da API

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

Item	Valor
URL base	https://numdetect.com
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 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

Validação de número de telefonenumber_validation_batchUma lista limpa é o começo da próxima campanha. Verifique sinais de validade e ativação para encontrar registros que merecem revisão e use o resultado estruturado na limpeza de listas, em atualizações do CRM e em verificações antes do contato, para que cada ação comece com dados mais claros.Página do produto
Atividade do númeronumber_activity_batchFaça o próximo acompanhamento começar com um sinal de atividade. Encontre atividade recente em uma lista completa de números, separe registros inativos de números que merecem revisão e use o resultado para planejar reativação, segmentação e prioridades de contato.Página do produto
Usuários de alto valornumber_high_value_batchEncontre os registros que merecem revisão primeiro. Combina características de dispositivos de alto padrão com atividade de rede recente para retornar um sinal true/false de potencial usuário de alto valor, para priorizar atendimento, programas de membros e campanhas; é um sinal de detecção, não prova de renda ou de compra.Página do produto
E-commerce ativonumber_ecommerce_batchComece a próxima campanha comercial com um público mais focado. Encontre sinais de atividade de e-commerce disponíveis, monte segmentos de público e remarketing em torno de registros que merecem revisão e mantenha o limite claro: o resultado não é um pedido, uma intenção de compra nem um registro de atividade em plataforma.Página do produto
Consulta global de operadoracarrier_batchTransforme uma lista de telefones em contexto pronto para roteamento. Acrescente operadora, operadora subjacente, tipo de linha, país, região e cidade a registros internacionais e use o resultado enriquecido para roteamento, análise regional, segmentação e atualizações do CRM.Página do produto

Validação de número de telefone

number_validation_batchtelefone500–500.000 por tarefa

Uma lista limpa é o começo da próxima campanha. Verifique sinais de validade e ativação para encontrar registros que merecem revisão e use o resultado estruturado na limpeza de listas, em atualizações do CRM e em verificações antes do contato, para que cada ação comece com dados mais claros.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "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 em dígitos simples com o código do país, sem sinal de mais nem espaços (ex.: 17253100591), e a chave estável para associar resultados a um cliente, lead ou registro do CRM. Mantenha-o para rastrear a lista de origem e gravar os resultados em massa; o campo por si só não comprova que o número pode ser contatado.
`activated`	true	O sinal de ativação retornado por esta verificação. Use-o para encontrar registros que merecem revisão antes do contato, organizar filas de limpeza e apoiar a segmentação do CRM; combine-o com dados de consentimento, origem e interação em vez de tratá-lo como garantia de conexão ou entrega. Os valores são true ou false.

Atividade do número

number_activity_batchtelefone500–500.000 por tarefa

Faça o próximo acompanhamento começar com um sinal de atividade. Encontre atividade recente em uma lista completa de números, separe registros inativos de números que merecem revisão e use o resultado para planejar reativação, segmentação e prioridades de contato.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "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 em dígitos simples com o código do país, sem sinal de mais nem espaços (ex.: 17253100591), usado para gravar o resultado de atividade em uma lista, cliente ou registro de lead. Ele serve apenas para associação e rastreabilidade; não inclui horário de atividade, frequência nem detalhes de interação.
`activated`	true	Um sinal de atividade disponível que pode ajudar as equipes a priorizar a revisão, criar rótulos de público e planejar a cadência de reativação. Não é uma contagem de dias ativos, frequência nem um horário de observação específico; um sinal ausente não significa que alguém nunca responderá. Os valores são true ou false.

Usuários de alto valor

number_high_value_batchtelefone500–500.000 por tarefa

Encontre os registros que merecem revisão primeiro. Combina características de dispositivos de alto padrão com atividade de rede recente para retornar um sinal true/false de potencial usuário de alto valor, para priorizar atendimento, programas de membros e campanhas; é um sinal de detecção, não prova de renda ou de compra.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "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 em dígitos simples com o código do país (ex.: 12017200001), usado para associar o sinal de alto valor ao registro enviado e acompanhá-lo em um CRM ou fila de revisão. Ele não fornece identidade, modelo do dispositivo nem outros dados de perfil pessoal.
`activated`	true	Um sinal auxiliar true/false derivado de características de dispositivos de alto padrão e de atividade de rede recente. Pode ajudar equipes de programas de membros, atendimento e marketing a definir prioridades de revisão, mas não confirma renda, patrimônio, capacidade de compra nem gasto real.

E-commerce ativo

number_ecommerce_batchtelefone500–500.000 por tarefa

Comece a próxima campanha comercial com um público mais focado. Encontre sinais de atividade de e-commerce disponíveis, monte segmentos de público e remarketing em torno de registros que merecem revisão e mantenha o limite claro: o resultado não é um pedido, uma intenção de compra nem um registro de atividade em plataforma.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Resposta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "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 em dígitos simples com o código do país, sem sinal de mais nem espaços (ex.: 17253100591), usado para conectar o sinal de atividade comercial a registros de clientes, leads ou públicos. Permite que as equipes de marketing cruzem o resultado com seus próprios dados de consentimento, navegação, pedidos e programa de membros; não contém informações de pedidos nem de produtos.
`activated`	true	Um sinal de atividade comercial disponível que pode focar a revisão de públicos, a preparação de listas de remarketing e o planejamento de testes de conteúdo. Não representa um pedido, valor de transação, intenção de compra nem uma atividade específica em plataforma. Os valores são true ou false.

Consulta global de operadora

carrier_batchtelefone500–500.000 por tarefa

Transforme uma lista de telefones em contexto pronto para roteamento. Acrescente operadora, operadora subjacente, tipo de linha, país, região e cidade a registros internacionais e use o resultado enriquecido para roteamento, análise regional, segmentação e atualizações do CRM.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

curl -X POST "https://numdetect.com/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": 509,
    "total": 509,
    "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://numdetect.com/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": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "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 em dígitos simples com o código do país, sem sinal de mais nem espaços (ex.: 17253100591), e a chave de associação para gravar o contexto de operadora, linha e geografia na lista de origem. Mantenha suas próprias colunas de origem ao lado dele para que as equipes de roteamento, atendimento e CRM possam rastrear a verificação, tratar duplicatas e atualizar o cliente ou lead correto. Ele identifica um registro; não prova que o número está acessível.
`carrier`	T-Mobile	O nome da operadora voltado ao cliente, quando identificável. Pode enriquecer registros do CRM, apoiar o roteamento de atendimento, ajudar a revisar a composição dos números e mostrar como uma lista se distribui entre operadoras. Use-o como contexto operacional, e não como prova de acessibilidade ou de uso atual. Um valor vazio significa que nenhum nome utilizável foi retornado nesta verificação; não prova que não exista operadora.
`underlying_carrier`		A operadora da rede subjacente, quando identificável, útil para entender contextos de revendedores, operadoras virtuais e números portados. Pode ser diferente da operadora voltada ao cliente, e essa diferença pode ajudar as equipes a investigar questões de roteamento ou de titularidade. Não é um status da rede celular em tempo real nem um sinal de conexão em tempo real.
`number_type`	Fixed Line or Mobile	O tipo de linha retornado, como mobile, fixed line ou outra categoria identificável. Use-o para separar registros de celular e de telefone fixo, planejar o roteamento de atendimento, verificar a adequação do canal e adicionar um segmento útil ao CRM. Não é um resultado de conexão; mantenha um valor vazio ou desconhecido para revisão em vez de tratá-lo como falha.
`country_code`	US	O código de país ou território retornado, para agrupar listas internacionais, aplicar regras de roteamento e de negócio por país e montar relatórios regionais. Ele descreve o contexto de numeração, não o país atual, a localização física ou a nacionalidade de uma pessoa. Casos de uso internacional e de números virtuais devem ser conferidos com seus próprios dados de clientes.
`region`	CA	O contexto de região, estado ou província, quando disponível. Pode apoiar a análise de cobertura de mercado, o agrupamento regional de listas, a distribuição de atendimento e os relatórios operacionais. Ele vem do contexto do número e da rede, e não da localização atual; portanto, não deve ser lido como a área atual do usuário. Valores ausentes ou de outra região exigem a revisão normal do negócio.
`city`	LOS ANGELES	O contexto em nível de cidade, quando disponível. Pode melhorar relatórios regionais, revelar a composição da lista, apoiar operações localizadas e preencher um campo ausente do CRM. A alocação de números, a portabilidade, os números virtuais e diferenças entre fontes podem afetar a precisão em nível de cidade; por isso, decisões importantes devem ser conferidas com registros fornecidos pelo usuário ou com registros de negócio existentes.

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://numdetect.com/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

Os envios de tarefas em massa são aceitos antes do início do processamento. Use o status da tarefa retornado para decidir se continua consultando ou se trata uma falha.

Campo	Descrição
`5 solicitações simultâneas por usuário`	Um envio de tarefa usa uma vaga de solicitação. Se a conta não tiver vaga disponível, a API retorna 42901 com Retry-After; aguarde e envie o arquivo novamente.
`Consulte em vez de esperar`	O envio de uma tarefa retorna imediatamente. Consulte o status no máximo uma vez a cada 30 segundos enquanto ela estiver em processamento.
`O tamanho da tarefa depende do produto`	Cada produto tem seu próprio tamanho mínimo e máximo de arquivo, indicado na seção de tarefas.

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`	A tarefa enviada não pôde ser aceita na forma atual
`42900`	Uma cota de uso foi esgotada ou há pedidos não concluídos demais
`42901`	Todas as vagas de solicitação estão ocupadas; 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 indicados em Retry-After e reenvie a mesma solicitação
`50400`	A solicitação não terminou dentro do tempo limite e não é cobrada; tente novamente
`50300`	Manutenção do serviço de validação