Validate a Phone Validation

Endpoint

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

Confirms the OTP the user received. Verifik looks up the latest sent (and not expired) Phone Validation for that phone — including manual / Smart Tools records and project-flow records.

Pair with send

Standalone OTPs are created with POST /v2/phone-validations/manual. App registration OTPs use POST /v2/phone-validations/app-registration.

Headers

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

Body parameters

Parameter	Type	Required	Description
phone	string	Yes	Same national number used when sending the OTP.
countryCode	string	Yes	Dial code starting with +.
otp	number	Yes	Numeric code the user received.
phoneGateway	string	No	sms or whatsapp — narrows the lookup when both channels were used.
project	string	No	Optional project filter for flow-based records.
projectFlow	string	No	Optional project-flow filter (preferred when available).

Request examples

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();

Success response

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

OTP lifetime

Pending OTPs are valid for 10 minutes from the last successful send/resend (expiresAt on the create response). After that, this endpoint returns 412 phoneValidation_has_expired. Send a new OTP (respecting the ~2-minute resend cooldown, or use force: true on manual create) before asking the user to try again.

OTP attempts

There is no server-side attempt limit today. Wrong codes return 403 otp_does_not_match until the record expires or a new OTP is sent. Enforce lockout or attempt caps in your client if needed.

Common errors

Status	Message	When
403	otp_does_not_match	Code does not match the pending OTP.
412	phoneValidation_has_expired	The pending OTP TTL (~10 minutes) has elapsed.
409	otp_send_failed	Latest record for this phone failed to send (not the same as expiry).
409	phone_validation_already_validated	OTP was already validated.
404	phone_validation_not_found	No matching Phone Validation for this phone.
409	MissingParameter	Required body fields missing.

Related

• Create a Manual Phone Validation
• Phone Validations overview