Documentação da API ProValidPhone v1

Quatro endpoints REST em JSON para validar números brasileiros e confirmar posse por código OTP via SMS ou ligação com voz. Base: https://api.provalidphone.com.br. Todas as respostas são JSON em UTF-8.

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. 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.

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.

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.

# requisição (mesmo corpo para /sms e /call)
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"}'

# resposta 201
{
  "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77",
  "status": "pending",
  "channel": "sms",
  "phone": "+5511999998888"
}

Texto do SMS: {Nome do projeto} enviou o codigo: 123456. Na ligação, o código é ditado dígito a dígito. Se o número for inválido, a resposta é 400 com error: phone_invalido e nada é enviado.

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.

Códigos de erro

HTTP	`error`	Quando acontece	O que fazer
400	`phone_invalido`	O número não passou na validação estrutural	Mostrar os motivos de `errors` ao usuário e pedir correção
403	autenticação	API key ausente, inválida ou revogada	Conferir o header e a chave no painel
402	`cota`	Cota mensal de verificações atingida	Aguardar a próxima competência ou ampliar o plano
402	`trial`	Período de teste encerrado sem plano ativo	Contratar um plano de produção
403	`suspensa`	Conta suspensa	Entrar em contato com o suporte
404	`sessao_nao_encontrada`	`id` inexistente ou de outra conta	Conferir o `id` devolvido no envio
429	`limite`	Mais de 3 envios na última hora para o mesmo número	Aguardar antes de reenviar; oferecer o outro canal
502	`falha_envio`	O provedor não aceitou o SMS ou a ligação	Tentar novamente ou usar o outro canal
503	`canal_indisponivel`	Canal (SMS ou voz) desativado no momento	Usar o outro canal e tentar mais tarde

Limites e regras do código

Regra	Valor padrão
Tamanho do código	6 dígitos numéricos
Validade do código	5 minutos a partir do envio
Tentativas de conferência por código	5
Envios por hora para o mesmo número	3 (somando SMS e voz)
Cota mensal no período de teste	100 verificações
Armazenamento do código	Apenas hash SHA-256; nunca em texto claro

Fluxo recomendado de integração

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.
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).
Guarde o id da sessão no seu lado e mostre um campo de 6 dígitos com contagem de 5 minutos.
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.
Trate 429 mostrando o tempo de espera e sugerindo o outro canal; nunca reenvie automaticamente em loop.
Persista o número em E.164 (campo e164) para evitar duplicidade na sua base.

Criar conta e gerar API key Ver preços