Documentação da API API v1

Autenticação

Crie uma chave na página de chaves de API e depois substitua o marcador abaixo no seu próprio terminal. Os exemplos são apenas texto; copiá-los não envia nada.

# API origin: https://api.numdetect.com
export NUMDETECT_API_KEY='YOUR_API_KEY'

• Envie Authorization: Bearer <key> em toda requisição. Requisições JSON também precisam de Content-Type: application/json. Não são necessários cookies, cabeçalho CSRF nem cabeçalho Origin.
• Uma chave pode ler produtos, executar verificações avulsas e em lote, ler seus resultados e ler o histórico do seu saldo. Configurações da conta, chaves e recargas são gerenciadas apenas no painel com login ativo.
• Você pode criar até 10 chaves, por exemplo uma por sistema, e excluir qualquer uma delas na hora.

Guarde as chaves no ambiente do seu servidor. Não coloque chaves em URLs, capturas de tela, logs compartilhados nem arquivos de código-fonte versionados.

Produtos

Leia o catálogo atual antes de escolher os IDs de produto. A resposta lista todos os produtos à venda com seu tipo de entrada, preços, mínimo de lote e países com suporte.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/products" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

single e bulk indicam se o produto está disponível no momento para aquele tipo de verificação. countries é ["*"] para todos os países, uma lista de códigos de país, ou vazio para produtos de e-mail. Os preços são USD micros por verificação.

Verificação avulsa

POST /api/v1/checks recebe um número de telefone ou um endereço de e-mail e uma lista de IDs de produto. A requisição aguarda até que todos os produtos respondam (até cerca de 45 segundos) e devolve a verificação concluída.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+12025550147","products":["whatsapp","telegram"]}'

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","products":["apple_email","spotify_email"]}'

Escreva os números de telefone com o código de país +. Para um número sem ele, adicione "country": "GB" (um código de país ISO) à requisição.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks/$CHECK_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Verificação em lote

POST /api/v1/bulk-jobs envia um arquivo como dados de formulário multipart. O arquivo é dividido em uma lista por país, e cada país é verificado por cada produto que você escolher.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F "products=whatsapp,telegram" \
  -F "input_kind=phone" \
  -F "max_cost=50000000" \
  -F "column=0" \
  -F "header=true"

• file: CSV UTF-8 ou texto simples, de até 100 MB e 1.000.000 de linhas. As demais colunas são mantidas e devolvidas no arquivo de resultados.
• input_kind é phone ou email. column é a coluna, começando em 0, com os números (padrão 0); header=true ignora a primeira linha.
• country (opcional) é usado para números de telefone escritos sem código de país. Números que começam com + ou 00 mantêm o próprio país.
• max_cost é o máximo que você aceita pagar, em USD micros. A tarefa é recusada, e nada é cobrado, se o custo for maior ou se o seu saldo for insuficiente.

Status e resultados do lote

Leia a tarefa até status ser completed, failed ou cancelled. Listas grandes podem demorar, então consulte a cada um ou dois minutos, ou use um webhook.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Baixar o arquivo de resultados

Quando result_ready é true, GET /result devolve um link de download válido por 10 minutos. O link em si não precisa de chave. Peça um novo link sempre que precisar baixar de novo.

url=$(curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" | jq -r .url)
curl --fail --silent --show-error --output result.csv "$url"

result.csv mantém todas as linhas originais na ordem original e acrescenta numdetect_status (valid, duplicate ou invalid), numdetect_country e uma coluna por produto com yes, no, unknown, unsupported, failed ou cancelled.

Cancelar uma tarefa em andamento

Os países que ainda não foram verificados são interrompidos, e o valor reservado deles volta ao seu saldo.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Webhooks

Defina uma URL de webhook na página de configurações da conta para ser avisado quando uma tarefa em lote terminar. Enviamos um POST HTTPS por tarefa concluída:

{
  "type": "bulk_job.finished",
  "data": {
    "id": "10000000-0000-4000-8000-000000000003",
    "status": "completed",
    "total_rows": 1000,
    "valid_rows": 982,
    "charged": 245500,
    "completed_at": "2026-11-11T08:30:00Z"
  }
}

Cada requisição traz os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. A assinatura é v1, seguida do HMAC-SHA256 em Base64 de "<webhook-id>.<webhook-timestamp>.<body>", usando seu segredo de assinatura (whsec_…, Base64 após o prefixo). Compare-a antes de confiar no corpo.

Responda com qualquer status 2xx. Entregas com falha são tentadas de novo algumas vezes, com alguns minutos de intervalo. Trate webhook-id como único, pois uma entrega repetida pode chegar duas vezes.

Tarifas e saldo

Uma verificação avulsa cobra seu preço por cada produto com resposta definitiva. Respostas unknown e failed são grátis.

Uma tarefa em lote reserva seu custo quando você a envia: para cada país e produto, max(números válidos, o mínimo de lote do produto) × o preço de lote. Uma lista concluída é cobrada integralmente, inclusive as linhas desconhecidas. Uma lista que falha ou é cancelada volta ao seu saldo. Linhas duplicadas e inválidas, e países que um produto não suporta, são grátis.

Os valores são USD micros inteiros: 1 USD = 1.000.000 de micros.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/balance-logs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

POST /checks e POST /bulk-jobs precisam de um cabeçalho Idempotency-Key (até 128 caracteres). Use uma chave nova para cada requisição nova. Se uma resposta se perder, envie a mesma requisição de novo com a mesma chave: você recebe o primeiro resultado em vez de uma segunda cobrança.

Erros

Os erros usam {error: {code, message, request_id}}. Baseie-se no code estável, não na mensagem, e inclua request_id ao falar com o suporte.

Obtenha sua chave de APIVerificações em loteConfigurações de webhooksCobrança