수동 전화번호 검증 생성

Endpoint

POST https://api.verifik.co/v2/phone-validations/manual

단독 Phone Validation을 생성하고 SMS 또는 WhatsApp으로 OTP를 전송합니다. project 또는 projectFlow는 필요하지 않습니다. 이 엔드포인트는 Smart Tools → WhatsApp / SMS Messages에서 사용하는 것과 동일합니다.

전송에 성공한 후 전화번호 검증 확인으로 이어가세요.

청구

메시지가 전송되기 전에 국가별 SMS/WhatsApp 요금으로 크레딧을 확인합니다. OTP가 실제로 전달되었을 때(sent: true)만 청구됩니다.

Headers

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

Body parameters

Parameter	Type	Required	Description
`phone`	string	Yes	국내 번호만(공백은 제거됨). 여기에 다이얼 코드를 포함하지 마세요.
`countryCode`	string	Yes	`+`로 시작하는 다이얼 코드(예: `+57`). 항상 전송하고, 사용자에게 전화번호와 함께 표시하세요(예: `+57 3001234567`).
`phoneGateway`	string	Yes	`sms` 또는 `whatsapp`.
`title`	string	No	템플릿의 회사 / 발신자 이름(1–15자). 기본값은 클라이언트 이름입니다. WhatsApp `flow2` 및 SMS 문구에 사용됩니다.
`language`	string	No	템플릿 언어(`en`, `es`, …). `whatsappTemplate`이 `flow2`일 때 `flow2_en` / `flow2_es`를 선택합니다.
`whatsappTemplate`	string	No	WhatsApp 전용. `authentication`(기본값) 또는 `flow2`. SMS에서는 무시됩니다.
`force`	boolean	No	`true`이면 동일 전화번호 + 게이트웨이의 약 2분 재전송 쿨다운을 우회합니다. 명시적인 "재전송" 작업에 사용하세요.
`ipAddress`	string	No	감사(audit)를 위한 선택적 클라이언트 IP.

WhatsApp templates

`whatsappTemplate`	Meta template	Notes
`authentication` (default)	`authentication`	본문의 OTP + 버튼 URL 파라미터.
`flow2`	`flow2_es` / `flow2_en`	브랜드 헤더/본문(`title`을 섹션으로) + 코드 + 액션. 언어로 변형을 선택합니다.

{
  "phone": "3001234567",
  "countryCode": "+57",
  "phoneGateway": "whatsapp",
  "title": "Company ABC",
  "language": "es",
  "whatsappTemplate": "flow2"
}

Request examples

cURL
Node.js
Python
PHP

curl -X POST "https://api.verifik.co/v2/phone-validations/manual" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "3001234567",
    "countryCode": "+57",
    "phoneGateway": "whatsapp",
    "title": "Company ABC",
    "language": "en"
  }'

import axios from "axios";

const { data } = await axios.post(
  "https://api.verifik.co/v2/phone-validations/manual",
  {
    phone: "3001234567",
    countryCode: "+57",
    phoneGateway: "whatsapp",
    title: "Company ABC",
    language: "en",
  },
  {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
    },
  }
);

console.log(data);

import requests

response = requests.post(
    "https://api.verifik.co/v2/phone-validations/manual",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "phone": "3001234567",
        "countryCode": "+57",
        "phoneGateway": "whatsapp",
        "title": "Company ABC",
        "language": "en",
    },
)

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.verifik.co/v2/phone-validations/manual', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
  ],
  'json' => [
    'phone' => '3001234567',
    'countryCode' => '+57',
    'phoneGateway' => 'whatsapp',
    'title' => 'Company ABC',
    'language' => 'en',
  ],
]);

echo $response->getBody();

Success response

{
  "data": {
    "_id": "66f0a1b2c3d4e5f678901234",
    "client": "66f0a1b2c3d4e5f678900000",
    "source": "manual",
    "type": "validation",
    "status": "sent",
    "countryCode": "+57",
    "phone": "3001234567",
    "phoneGateway": "whatsapp",
    "phoneData": {
      "title": "Company ABC"
    },
    "language": "en",
    "expiresAt": "2026-07-29T22:50:00.000Z",
    "sent": true,
    "new": true
  },
  "signature": "...",
  "id": "a1b2c"
}

OTP lifetime and resend

Rule	Default	Notes
OTP TTL	10 minutes	성공적인 전송 시 `data.expiresAt`으로 반환됩니다. 이 시간이 지나면 검증이 `412` `phoneValidation_has_expired`를 반환합니다.
Resend cooldown	~2 minutes	동일 클라이언트 + 전화번호 + `phoneGateway`에 대해 약 2분 이내 두 번째 전송은 `409` `otp_recently_sent`를 반환합니다(새 메시지 없음).
Force resend	`"force": true`	2분 쿨다운을 우회하여 즉시 새 코드를 보낼 수 있습니다(예: UI "재전송"). 성공적인 전송/재전송마다 `expiresAt`이 +10분으로 재설정됩니다.

UI 안내

대상을 countryCode + 국내 phone 형식으로 표시하세요(예: +57 3001234567). expiresAt으로 만료 카운트다운을 구동하고, 2분 쿨다운 후(또는 force: true로 항상) "재전송"을 활성화하세요.

Common errors

Status	Message / code	When
403	`insufficient_credits`	선불 잔액이 해당 국가 SMS/WhatsApp 요금보다 낮습니다. 아무것도 전송되지 않습니다.
409	`otp_recently_sent`	쿨다운: 이 전화번호 + 게이트웨이에 대해 약 2분 이내에 OTP가 이미 전송되었습니다(`force`가 `true`가 아님).
409	`otp_not_sent`	제공자 전송 실패(메시지가 수락되지 않음). 쿨다운과는 다릅니다.
409	`MissingParameter`	필수 본문 필드 누락 또는 `countryCode`가 `+digits` 형식이 아님.
403	Forbidden	계정에서 Communication SMS/WhatsApp 기능을 사용할 수 없습니다.

Next step

PUT /v2/phone-validations로 코드를 검증하세요.

Endpoint​

Headers​

Body parameters​

WhatsApp templates​

Request examples​

Success response​

OTP lifetime and resend​

Common errors​

Next step​