Validar uma Validação de Telefone

Endpoint

PUT https://api.verifik.co/v2/phone-validations

Confirma o OTP que o usuário recebeu. A Verifik busca a Validação de Telefone mais recente enviada (e não expirada) para esse telefone — incluindo registros manuais / Smart Tools e registros de fluxo de projeto.

Combine com o envio

OTPs independentes são criados com POST /v2/phone-validations/manual. OTPs de app registration usam POST /v2/phone-validations/app-registration.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer {YOUR_ACCESS_TOKEN}

Parâmetros do body

Parameter	Type	Required	Description
phone	string	Yes	O mesmo número nacional usado ao enviar o OTP.
countryCode	string	Yes	Código de discagem começando com +.
otp	number	Yes	Código numérico que o usuário recebeu.
phoneGateway	string	No	sms ou whatsapp — restringe a busca quando ambos os canais foram usados.
project	string	No	Filtro opcional de projeto para registros baseados em fluxo.
projectFlow	string	No	Filtro opcional de fluxo de projeto (preferencial quando disponível).

Exemplos de requisição

cURL

curl -X PUT "https://api.verifik.co/v2/phone-validations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "3001234567",
    "countryCode": "+57",
    "otp": 123456,
    "phoneGateway": "whatsapp"
  }'

Node.js

import axios from "axios";

const { data } = await axios.put(
  "https://api.verifik.co/v2/phone-validations",
  {
    phone: "3001234567",
    countryCode: "+57",
    otp: 123456,
    phoneGateway: "whatsapp",
  },
  {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
    },
  }
);

console.log(data);

Python

import requests

response = requests.put(
    "https://api.verifik.co/v2/phone-validations",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "phone": "3001234567",
        "countryCode": "+57",
        "otp": 123456,
        "phoneGateway": "whatsapp",
    },
)

print(response.json())

PHP

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.verifik.co/v2/phone-validations', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
  ],
  'json' => [
    'phone' => '3001234567',
    'countryCode' => '+57',
    'otp' => 123456,
    'phoneGateway' => 'whatsapp',
  ],
]);

echo $response->getBody();

Resposta de sucesso

{
  "data": {
    "_id": "66f0a1b2c3d4e5f678901234",
    "status": "validated",
    "countryCode": "+57",
    "phone": "3001234567",
    "phoneGateway": "whatsapp",
    "source": "manual",
    "validatedAt": "2026-07-29T22:40:00.000Z"
  }
}

Tempo de vida do OTP

OTPs pendentes são válidos por 10 minutos a partir do último envio/reenvio bem-sucedido (expiresAt na resposta de criação). Depois disso, este endpoint retorna 412 phoneValidation_has_expired. Envie um novo OTP (respeitando o intervalo de reenvio de ~2 minutos, ou use force: true na criação manual) antes de pedir ao usuário para tentar novamente.

Tentativas de OTP

Hoje não há limite de tentativas no servidor. Códigos incorretos retornam 403 otp_does_not_match até o registro expirar ou um novo OTP ser enviado. Aplique bloqueio ou limite de tentativas no seu cliente, se necessário.

Erros comuns

Status	Message	When
403	otp_does_not_match	O código não corresponde ao OTP pendente.
412	phoneValidation_has_expired	O TTL do OTP pendente (~10 minutos) expirou.
409	otp_send_failed	O registro mais recente para este telefone falhou no envio (não é o mesmo que expiração).
409	phone_validation_already_validated	O OTP já foi validado.
404	phone_validation_not_found	Nenhuma Validação de Telefone correspondente para este telefone.
409	MissingParameter	Campos obrigatórios do body ausentes.

Relacionados

• Criar uma Validação de Telefone Manual
• Visão geral de Validações de Telefone