전화번호 검증 확인

Endpoint

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

사용자가 받은 OTP를 확인합니다. Verifik는 해당 전화번호에 대해 가장 최근의 sent(그리고 만료되지 않은) Phone Validation을 조회합니다 — 수동 / Smart Tools 레코드와 프로젝트 플로우 레코드를 모두 포함합니다.

전송과 함께 사용

단독 OTP는 POST /v2/phone-validations/manual로 생성합니다. 앱 등록 OTP는 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	OTP를 보낼 때 사용한 것과 동일한 국내 번호입니다.
countryCode	string	Yes	+로 시작하는 다이얼 코드입니다.
otp	number	Yes	사용자가 받은 숫자 코드입니다.
phoneGateway	string	No	sms 또는 whatsapp — 두 채널을 모두 사용한 경우 조회 범위를 좁힙니다.
project	string	No	플로우 기반 레코드를 위한 선택적 프로젝트 필터입니다.
projectFlow	string	No	선택적 프로젝트 플로우 필터입니다(가능한 경우 권장).

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

대기 중인 OTP는 마지막 성공적인 전송/재전송으로부터 10분 동안 유효합니다(생성 응답의 expiresAt). 그 이후에는 이 엔드포인트가 412 phoneValidation_has_expired를 반환합니다. 사용자에게 다시 시도하도록 요청하기 전에 새 OTP를 전송하세요(약 2분 재전송 쿨다운을 준수하거나, 수동 생성 시 force: true 사용).

OTP attempts

현재 서버 측 시도 횟수 제한은 없습니다. 잘못된 코드는 레코드가 만료되거나 새 OTP가 전송될 때까지 403 otp_does_not_match를 반환합니다. 필요하면 클라이언트에서 잠금 또는 시도 상한을 적용하세요.

Common errors

Status	Message	When
403	otp_does_not_match	코드가 대기 중인 OTP와 일치하지 않습니다.
412	phoneValidation_has_expired	대기 중인 OTP TTL(약 10분)이 경과했습니다.
409	otp_send_failed	이 전화번호의 최신 레코드가 전송에 실패했습니다(만료와는 다름).
409	phone_validation_already_validated	OTP가 이미 검증되었습니다.
404	phone_validation_not_found	이 전화번호에 일치하는 Phone Validation이 없습니다.
409	MissingParameter	필수 본문 필드가 누락되었습니다.

Related

• 수동 전화번호 검증 생성
• 전화번호 검증 개요