ProValidPhone

Documentação da API ProValidPhone v1

Endpoints REST em JSON para validar números brasileiros, confirmar posse por código OTP via SMS ou ligação com voz e, opcionalmente, consultar operadora e portabilidade. Base: https://api.provalidphone.com.br. Todas as respostas são JSON em UTF-8. Especificação OpenAPI 3 para Postman e geradores de SDK: https://api.provalidphone.com.br/v1/openapi.json · referência interativa em https://api.provalidphone.com.br/v1/docs/.

Versão da API: v1. Última atualização desta página: 29 de setembro de 2026.

Autenticação

Toda chamada exige uma API key criada no painel. A chave crua (pvp_live_…) é exibida uma única vez na criação; a plataforma guarda apenas o hash SHA-256. Envie a chave em um dos dois headers:

Authorization: Bearer pvp_live_SUACHAVE
# ou
X-API-Key: pvp_live_SUACHAVE

Chave ausente, inválida ou revogada devolve 403 com um campo detail (sem o campo error das demais falhas):

# 403: sem header de autenticação
{ "detail": "As credenciais de autenticação não foram fornecidas." }

# 403: chave inválida ou revogada
{ "detail": "API key invalida ou revogada." }

Cada API key pode ter um nome de projeto (remetente), que aparece no texto do SMS e é repassado ao serviço de voz para a locução da ligação.

Escopos: ao criar a chave você escolhe o que ela pode fazer — validate (validar número), sms (enviar código por SMS), call (enviar código por ligação) e lookup (consultar operadora e portabilidade, em ativação); o padrão é todos. Uma chave sem o escopo do endpoint recebe 403 escopo. Crie chaves separadas por projeto ou ambiente e dê a cada uma só o que precisa.

Saúde da API: GET /v1/health não exige autenticação e devolve { "status": "ok" } — use no seu monitor de disponibilidade.

Validação estrutural

POST /v1/validate

Normaliza e valida um número brasileiro sem enviar nada ao telefone. Não consome cota. Aceita o número como o usuário digitou: com ou sem parênteses, traço, espaço, DDI.

# requisição
curl -X POST https://api.provalidphone.com.br/v1/validate \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"(11) 99999-8888"}'

# resposta 200
{
  "valid": true,
  "phone": "(11) 99999-8888",
  "e164": "+5511999998888",
  "type": "movel",
  "ddd": "11",
  "errors": []
}

type é movel ou fixo. Quando valid é false, errors traz a lista de motivos em português (por exemplo, DDD inválido ou comprimento incorreto), type vem desconhecido e e164 vem null. Números especiais (0800, 0300, 3003, 4004, 190, 192, 193…) voltam com valid false e type especial: são reconhecidos, mas não recebem SMS nem ligação de verificação.

Envio do código (SMS ou voz)

POST /v1/verify/sms e POST /v1/verify/call

Valida o número, gera um código de 6 dígitos e o envia por SMS (/sms) ou por uma ligação que dita o código em voz (/call). Cria uma sessão de verificação e devolve o id para a conferência. Consome 1 verificação da cota quando o provedor aceita o envio.

# SMS: requisição
curl -X POST https://api.provalidphone.com.br/v1/verify/sms \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999998888"}'

# SMS: resposta 201
{
  "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77",
  "status": "pending",
  "channel": "sms",
  "phone": "+5511999998888"
}
# Ligação com voz: mesmo corpo, outro caminho
curl -X POST https://api.provalidphone.com.br/v1/verify/call \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+551132210000"}'

# Ligação com voz: resposta 201
{
  "id": "8a2d5f10-4c7e-4b39-9e61-0d3f7c2a9b54",
  "status": "pending",
  "channel": "call",
  "phone": "+551132210000"
}

Texto do SMS: {Nome do projeto} enviou o codigo: 123456. Na ligação, o nome do projeto é falado e o código é ditado dígito a dígito. O canal de voz aceita celular e telefone fixo. As ligações saem uma por vez: se a linha estiver em uso, a verificação entra numa fila curta e a resposta continua sendo 201 (a ligação sai em seguida, dentro da validade do código). Com a fila cheia, a resposta é 503 canal_ocupado.

# 400: número reprovado na validação estrutural (nada é enviado)
{
  "error": "phone_invalido",
  "errors": ["DDD invalido: 00"]
}

Idempotência: envie o header Idempotency-Key (até 255 caracteres, por exemplo o id do pedido no seu sistema) para reenviar a requisição com segurança em caso de timeout. Com a mesma chave, por 24 horas, a API devolve a mesma resposta e a mesma sessão, com o header Idempotent-Replayed: true, sem enviar outro código. Falhas 5xx não ficam guardadas: com a mesma chave, a nova tentativa envia de novo.

curl -X POST https://api.provalidphone.com.br/v1/verify/sms \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  -H "Idempotency-Key: pedido-48213" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999998888"}'

Código fornecido por você (opcional): se o seu sistema já gera o código (por exemplo, um bot que é o dono do código), envie "code" com exatamente 6 dígitos. Entregamos esse código em vez de gerar um; os limites por hora, a validade de 5 minutos e a conferência por sessão (/v1/verify/check) continuam iguais. Um code fora do formato é recusado com 400 codigo_invalido, antes de qualquer envio. O código nunca fica guardado em texto: só o hash.

# requisição com código fornecido
curl -X POST https://api.provalidphone.com.br/v1/verify/sms \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999998888","code":"482715"}'

# resposta 201 (mesmo formato de sempre)
{ "id": "5b1e0c7a-2f4d-4a8e-9c31-6d2b8f0e1a93", "status": "pending", "channel": "sms", "phone": "+5511999998888" }

# 400: code fora do formato (nada é enviado)
{ "error": "codigo_invalido", "detail": "code deve ter exatamente 6 dígitos." }

A API abstrai os provedores. As respostas dos gateways de SMS e de voz nunca são repassadas ao cliente. Sucesso é sempre { id, status, channel, phone }; falha é sempre { error, detail } com um motivo abstrato, como falha_envio (502, o provedor não aceitou o envio) ou canal_indisponivel (503). A resposta crua do gateway (porta indisponível, erro de rota, etc.) fica apenas nos registros do servidor.

Conferência do código

POST /v1/verify/check

Confere o código digitado pelo usuário para a sessão informada. Não consome cota. Ao acertar, a sessão passa a verified e não aceita novas conferências.

# requisição
curl -X POST https://api.provalidphone.com.br/v1/verify/check \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"id":"3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77","code":"123456"}'

# resposta 200
{ "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77", "valid": true, "status": "verified" }

Valores de status: pending (aguardando), verified (confirmado), failed (tentativas esgotadas) e expired (prazo vencido). Sessões só são visíveis para a conta que as criou; id desconhecido devolve 404.

Status da verificação de um número

GET /v1/verify/status?phone=

Devolve a última verificação daquele número na sua conta, venha ela da sua integração (origin: "api") ou de uma pessoa da sua equipe que enviou o código pelo painel (origin: "painel"). Serve para manter "telefone verificado" em sincronia no seu sistema mesmo quando alguém validou pelo painel. Não consome cota. Só enxerga verificações da conta da API key; conta apenas envios que de fato saíram (ou ligações na fila).

# requisição (o número pode ir em qualquer formato; use URL-encode no "+")
curl -G https://api.provalidphone.com.br/v1/verify/status \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  --data-urlencode "phone=+5511999998888"

# resposta 200
{
  "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77",
  "phone": "+5511999998888",
  "status": "verified",
  "channel": "sms",
  "origin": "painel",
  "created_at": "2026-09-29T10:12:40-03:00",
  "verified_at": "2026-09-29T10:13:05-03:00",
  "expires_at": "2026-09-29T10:17:40-03:00"
}

# 404: a conta nunca verificou este número
{ "error": "sem_verificacao", "detail": "Nenhuma verificação deste número nesta conta." }

status: verified, pending (aguardando o código), expired (prazo vencido sem conferência) ou failed (tentativas esgotadas). Para receber o desfecho sem consultar, use os webhooks, que também trazem origin. A chave precisa poder enviar códigos (escopo SMS ou voz).

Lookup de operadora e portabilidade (opcional, em ativação)

Em ativação. O endpoint já existe e o escopo lookup já pode ser marcado na chave, mas a consulta ao provedor ainda está sendo habilitada para o Brasil: até lá POST /v1/lookup responde 503 lookup_indisponivel para todas as contas. Integre já tratando esse status como recurso opcional. O preço do lookup ainda não foi definido e será publicado em preços antes da liberação. Contexto e usos antifraude na página do lookup.

POST /v1/lookup valida o número e consulta, em um provedor externo de HLR, a operadora atual, se o número foi portado (e de qual operadora veio) e a situação da linha. É sob demanda: só acontece quando você chama, e exige que a API key tenha o escopo lookup (marque ao criar a chave; sem ele, 403 escopo). Não envia nada ao usuário e não consome cota de verificação. A resposta do provedor nunca é repassada: o contrato abaixo é o único formato devolvido.

# requisição
curl -X POST https://api.provalidphone.com.br/v1/lookup \
  -H "Authorization: Bearer pvp_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"(11) 99999-8888"}'

# 200 OK
{
  "valid": true,
  "phone": "(11) 99999-8888",
  "e164": "+5511999998888",
  "type": "movel",
  "ddd": "11",
  "carrier": "Vivo",
  "ported": true,
  "original_carrier": "Claro",
  "line_status": "delivered"
}

# 400: número reprovado na validação estrutural (nenhuma consulta é feita)
{ "error": "phone_invalido", "errors": ["DDD invalido: 00"] }

# 403: a API key não tem o escopo lookup
{ "error": "escopo", "detail": "Esta API key nao tem permissao para este endpoint." }

# 503: consulta de operadora não habilitada na plataforma
{ "error": "lookup_indisponivel", "detail": "Consulta de operadora indisponivel no momento." }

# 502: o provedor não respondeu ou recusou a consulta
{ "error": "falha_lookup", "detail": "O provedor de lookup nao respondeu. Tente novamente." }

Campos: valid, phone, e164, type e ddd como em /v1/validate; carrier (operadora atual; vazio quando o provedor não informa), ported, original_carrier (só quando portado) e line_status (situação reportada pelo provedor, por exemplo delivered para linha alcançável ou undeliverable). Número inválido devolve 400 phone_invalido antes de qualquer consulta; sem provedor habilitado na plataforma, 503 lookup_indisponivel; falha ou recusa do provedor, 502 falha_lookup. O limite geral de requisições por conta (120 por minuto) vale também aqui. Trate o lookup como enriquecimento opcional: validação e OTP funcionam sem ele.

Códigos de erro

HTTPerrorQuando aconteceO que fazer
400phone_invalidoO número não passou na validação estrutural; o corpo traz errors com os motivosMostrar os motivos de errors ao usuário e pedir correção
400codigo_invalidoO campo opcional code não tem exatamente 6 dígitos numéricos. Nada é enviadoMandar 6 dígitos ou omitir o code para gerarmos
400canal_incompativelPedido de SMS para um número que não é celular (fixo não recebe SMS). Recusado antes do envio, sem consumir cotaUsar /v1/verify/call para telefone fixo
403(sem error; só detail)API key ausente, inválida ou revogadaConferir o header e a chave no painel
402cotaCota mensal de verificações atingidaAguardar a próxima competência ou ampliar o plano
402trialPeríodo de teste encerrado sem plano ativoContratar um plano de produção
403suspensaConta suspensaEntrar em contato com o suporte
403cadastroCadastro da conta incompleto (falta confirmar os dados de pagamento); vale para todos os envios da contaConcluir o cadastro no painel; a validação estrutural segue funcionando
403escopoA API key não tem permissão para este endpoint (escopos definidos ao criar a chave)Usar uma chave com o escopo certo ou criar outra no painel
404sessao_nao_encontradaid inexistente ou de outra contaConferir o id devolvido no envio
404sem_verificacao/v1/verify/status: a conta nunca verificou esse númeroTratar como não verificado
409idempotencia_em_andamentoOutra requisição com a mesma Idempotency-Key ainda está sendo processadaAguardar alguns segundos e repetir
422idempotencia_conflitoA Idempotency-Key já foi usada com outro número ou canalGerar uma chave nova para cada verificação
422gatewayO número de destino não pode receber verificação (é uma linha da própria infraestrutura de envio)Usar um telefone real do usuário final; o bloqueio acontece antes do envio
502falha_lookupO provedor de lookup não respondeu ou recusou a consulta (só em /v1/lookup)Tentar novamente; a validação estrutural continua disponível
503lookup_indisponivelConsulta de operadora não está habilitada na plataforma no momento (só em /v1/lookup)Tratar como recurso opcional: seguir com validação e OTP normalmente
429limiteMais de 3 envios na última hora para o mesmo número no mesmo canalAguardar antes de reenviar; oferecer o outro canal
429rate_limitMuitas requisições da conta em pouco tempo; o corpo traz retry_after (segundos) e há o header Retry-AfterEsperar retry_after e repetir, sem loop
502falha_envioO provedor não aceitou o SMS ou a ligação (o motivo técnico fica só no servidor)Tentar novamente ou usar o outro canal
503canal_indisponivelCanal (SMS ou voz) desativado no momentoUsar o outro canal e tentar mais tarde
503canal_ocupadoTodas as linhas do canal estão ocupadas com outros envios (enviamos um por vez em cada linha)Tentar de novo em alguns segundos ou usar o outro canal

Formato das falhas de negócio: { "error": "cota", "detail": "Cota mensal atingida." }. Nos erros 402, 403 (conta suspensa), 429, 502 e 503 o campo id pode vir junto quando a sessão chegou a ser criada. Envios recusados por qualquer um desses motivos não consomem cota.

Limites e regras do código

RegraValor padrão
Tamanho do código6 dígitos numéricos
Validade do código5 minutos a partir do envio
Tentativas de conferência por código5
Envios por hora para o mesmo número3 em cada canal (SMS e voz contados separadamente; toda tentativa conta, mesmo com falha do provedor)
Requisições por conta120 por minuto no total; 30 por minuto em /v1/verify/sms e /v1/verify/call
Guarda da Idempotency-Key24 horas
Cota mensal no período de teste100 verificações
Armazenamento do códigoApenas hash SHA-256; nunca em texto claro

Webhooks de resultado

Cadastre uma URL https pública no painel (menu Webhooks) e receba um POST JSON a cada desfecho de verificação, sem precisar consultar a API. Eventos: verification.verified (código conferido), verification.failed (tentativas esgotadas), verification.expired (ninguém conferiu no prazo) e ping (botão "Enviar teste").

# corpo do POST
{
  "event": "verification.verified",
  "created_at": "2026-09-24T10:15:02-03:00",
  "data": {
    "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77",
    "status": "verified",
    "channel": "sms",
    "phone": "+5511999998888",
    "attempts": 1,
    "origin": "api",
    "verified_at": "2026-09-24T10:15:02-03:00"
  }
}

origin diz quem pediu o código: api (sua integração) ou painel (uma pessoa da sua equipe). verified_at vem preenchido em verification.verified e é null nos demais eventos.

Assinatura: cada entrega traz X-ProValidPhone-Timestamp (Unix) e X-ProValidPhone-Signature: v1=<hex>, o HMAC-SHA256 de "{timestamp}.{corpo cru}" com o segredo do webhook (whsec_…, mostrado uma vez no painel). Recalcule e compare antes de confiar no conteúdo, e recuse timestamps com mais de 5 minutos.

# Python: conferir a assinatura
import hashlib, hmac, time

def assinatura_ok(corpo_cru: bytes, ts: str, assinatura: str, segredo: str) -> bool:
    if abs(time.time() - int(ts)) > 300:
        return False
    esperado = hmac.new(segredo.encode(), f"{ts}.".encode() + corpo_cru, hashlib.sha256).hexdigest()
    return hmac.compare_digest("v1=" + esperado, assinatura)

Entrega: qualquer resposta 2xx conta como recebida. Outras respostas, timeout ou erro de rede são repetidos até 5 vezes com espera crescente (1, 2, 4, 8 minutos…). Redirecionamentos não são seguidos. Cada POST traz também X-ProValidPhone-Event (nome do evento) e X-ProValidPhone-Delivery (id da entrega) — use o segundo para ignorar duplicatas. O histórico das entregas aparece no painel.

Exemplos em Python, Node e PHP

O fluxo completo (enviar o código e conferir) com a biblioteca HTTP padrão de cada linguagem. Troque pvp_live_SUACHAVE pela chave gerada no painel.

Python (requests)
import requests

BASE = "https://api.provalidphone.com.br"
HEADERS = {"Authorization": "Bearer pvp_live_SUACHAVE"}

# 1. enviar o código por SMS (use /v1/verify/call para ligação)
r = requests.post(f"{BASE}/v1/verify/sms", json={"phone": "+5511999998888"}, headers=HEADERS, timeout=15)
if r.status_code != 201:
    erro = r.json()  # {"error": "...", "detail": "..."} ou {"detail": "..."} no 403
    raise RuntimeError(erro.get("error") or erro.get("detail"))
sessao_id = r.json()["id"]

# 2. conferir o código digitado pelo usuário
r = requests.post(f"{BASE}/v1/verify/check", json={"id": sessao_id, "code": "123456"}, headers=HEADERS, timeout=15)
resultado = r.json()
print(resultado["valid"], resultado["status"])  # True verified
Node.js (fetch nativo, 18+)
const BASE = "https://api.provalidphone.com.br";
const headers = {
  "Authorization": "Bearer pvp_live_SUACHAVE",
  "Content-Type": "application/json",
};

// 1. enviar o código por SMS (use /v1/verify/call para ligação)
const envio = await fetch(`${BASE}/v1/verify/sms`, {
  method: "POST", headers, body: JSON.stringify({ phone: "+5511999998888" }),
});
const sessao = await envio.json();
if (envio.status !== 201) throw new Error(sessao.error || sessao.detail);

// 2. conferir o código digitado pelo usuário
const check = await fetch(`${BASE}/v1/verify/check`, {
  method: "POST", headers, body: JSON.stringify({ id: sessao.id, code: "123456" }),
});
const resultado = await check.json();
console.log(resultado.valid, resultado.status); // true verified
PHP (cURL)
<?php
$base = "https://api.provalidphone.com.br";
$headers = ["Authorization: Bearer pvp_live_SUACHAVE", "Content-Type: application/json"];

function chamar(string $url, array $corpo, array $headers): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => json_encode($corpo),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
    ]);
    $resposta = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    return [$status, $resposta];
}

// 1. enviar o código por SMS (use /v1/verify/call para ligação)
[$status, $sessao] = chamar("$base/v1/verify/sms", ["phone" => "+5511999998888"], $headers);
if ($status !== 201) {
    throw new RuntimeException($sessao["error"] ?? $sessao["detail"]);
}

// 2. conferir o código digitado pelo usuário
[$status, $resultado] = chamar("$base/v1/verify/check", ["id" => $sessao["id"], "code" => "123456"], $headers);
var_dump($resultado["valid"], $resultado["status"]); // bool(true) "verified"

Fluxo recomendado de integração

  1. Chame /v1/validate assim que o usuário digitar o número e mostre o erro na hora se valid for false. Isso evita envio para número impossível.
  2. Opcional (em ativação): nos fluxos de risco, chame /v1/lookup antes do envio e aplique a sua regra (por exemplo, não enviar quando line_status indicar linha não alcançável). Trate 502 e 503 como "sem informação" e siga o fluxo normal.
  3. Ofereça SMS como padrão e a ligação com voz como alternativa visível (útil para fixo e quando o SMS não chega).
  4. Guarde o id da sessão no seu lado e mostre um campo de 6 dígitos com contagem de 5 minutos.
  5. Em /v1/verify/check, trate valid: false com status: pending como código errado (ainda há tentativas) e failed ou expired como sessão encerrada, oferecendo novo envio.
  6. Trate 429 mostrando o tempo de espera e sugerindo o outro canal; nunca reenvie automaticamente em loop.
  7. Persista o número em E.164 (campo e164) para evitar duplicidade na sua base.

Criar conta e gerar API key Ver preços