Verify (OTP)

API для создания и проверки одноразовых кодов верификации (OTP) через SMS, Email и другие каналы.

Запросы POST должны содержать заголовок Content-Type: application/json. Проверка кода (verify) также поддерживает метод GET.

---

Создание кода — синхронный

Создаёт код верификации и отправляет его по SMS или Email. Шлюз обрабатывает запрос сразу и возвращает verify_id.

URI: /api/verify.php

Метод: POST

Параметры запроса

authstringобязательный API-ключ из личного кабинета

commandstringобязательный Должно быть verify/create

phonestringобязательный* Номер телефона в любом формате (обязателен, если не указан email)

emailstringобязательный* Email-адрес (обязателен, если не указан phone)

typestringобязательный Тип верификации: sms, hlr, rcs, email, viber

sender_namestring Подпись / бренд в SMS

langstring Язык сообщения: uk, ru, en (по умолчанию en)

code_lengthnumber Длина кода (по умолчанию 8, диапазон 1–10)

code_typestring Тип кода: numeric, alphabetic, alphanumeric, extended (по умолчанию numeric)

service_idnumber ID сервиса верификации

custom_idstring Пользовательский идентификатор для связи с вашей системой

hookstring URL webhook для уведомлений о статусе верификации

Пример запроса

JSON

{
    "auth": "API_KEY",
    "command": "verify/create",
    "phone": "441501234567",
    "type": "sms",
    "sender_name": "MyBrand",
    "lang": "en",
    "code_length": 6,
    "code_type": "numeric",
    "service_id": 1,
    "custom_id": "abcdef1234567",
    "hook": "https://example.com/webhook"
}

cURL

curl -X POST 'https://alphasms.ua/api/verify.php' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "API_KEY",
  "command": "verify/create",
  "phone": "441501234567",
  "type": "sms",
  "sender_name": "MyBrand",
  "lang": "en",
  "code_length": 6,
  "code_type": "numeric",
  "service_id": 1,
  "custom_id": "abcdef1234567",
  "hook": "https://example.com/webhook"
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'API_KEY',
    'command' => 'verify/create',
    'phone' => '441501234567',
    'type' => 'sms',
    'sender_name' => 'MyBrand',
    'lang' => 'en',
    'code_length' => 6,
    'code_type' => 'numeric',
    'service_id' => 1,
    'custom_id' => 'abcdef1234567',
    'hook' => 'https://example.com/webhook',
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://alphasms.ua/api/verify.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python

import requests

payload = {
    "auth": "API_KEY",
    "command": "verify/create",
    "phone": "441501234567",
    "type": "sms",
    "sender_name": "MyBrand",
    "lang": "en",
    "code_length": 6,
    "code_type": "numeric",
    "service_id": 1,
    "custom_id": "abcdef1234567",
    "hook": "https://example.com/webhook",
}

response = requests.post(
    "https://alphasms.ua/api/verify.php",
    json=payload,
    timeout=30,
)

print(response.json())

Node.js

const payload = {
  "auth": "API_KEY",
  "command": "verify/create",
  "phone": "441501234567",
  "type": "sms",
  "sender_name": "MyBrand",
  "lang": "en",
  "code_length": 6,
  "code_type": "numeric",
  "service_id": 1,
  "custom_id": "abcdef1234567",
  "hook": "https://example.com/webhook"
};

const response = await fetch("https://alphasms.ua/api/verify.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(await response.json());

Ответ

successboolean Результат выполнения запроса

verify_idstring ID верификации (UUID)

Пример ответа:

{
  "success": true,
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
}

Ошибки HTTP: 400 (неверный формат/JSON), 401 (неверный auth), 413 (слишком большое тело запроса).

---

Создание кода — асинхронный

Постановка создания кода в очередь для фоновой обработки. Тело запроса такое же, как при синхронном создании, но поле command необязательно (воркер автоматически устанавливает verify/create).

URI: /v1/verify/create

Метод: POST

Content-Type: application/json

Пример ответа:

{
  "request_id": "cf-ray-1234567890-ABC",
  "success": true
}

verify_id в этом ответе не возвращается. Если запрос отклонён при обработке, причина приходит на URL из поля hook — см. Вебхук. Сам результат проверки получают командой verify.

Коды ошибок HTTP:

Code	Описание
400	Неверный JSON
401	Отсутствует или неверный auth
405	Метод, отличный от POST
413	Слишком большое тело запроса
415	Отсутствует или неверный Content-Type (должен быть application/json)
503	Очередь недоступна

---

Проверка кода

URI: /api/verify.php

Проверяет код, введённый пользователем, и возвращает статус верификации (только синхронный API).

Параметры запроса

authstringобязательный API-ключ из личного кабинета

commandstringобязательный Должно быть verify

phonestringобязательный* Номер телефона (обязателен, если не указан email)

emailstringобязательный* Email-адрес (обязателен, если не указан phone)

codestringобязательный Код для проверки

verify_idstring ID верификации (UUID)

service_idnumber ID сервиса верификации (если не указан verify_id)

custom_idstring Пользовательский идентификатор (если не указаны service_id и verify_id)

Пример запроса (GET)

/api/verify.php?auth=API_KEY&command=verify&phone=380501234567&code=123456&verify_id=14fb5f3d-20be-41ef-b31a-b9f5e499bc7a

Пример запроса (POST, JSON)

JSON

{
    "auth": "API_KEY",
    "command": "verify",
    "phone": "380501234567",
    "code": "123456",
    "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
}

cURL

curl -X POST 'https://alphasms.ua/api/verify.php' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "API_KEY",
  "command": "verify",
  "phone": "380501234567",
  "code": "123456",
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'API_KEY',
    'command' => 'verify',
    'phone' => '380501234567',
    'code' => '123456',
    'verify_id' => '14fb5f3d-20be-41ef-b31a-b9f5e499bc7a',
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://alphasms.ua/api/verify.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python

import requests

payload = {
    "auth": "API_KEY",
    "command": "verify",
    "phone": "380501234567",
    "code": "123456",
    "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a",
}

response = requests.post(
    "https://alphasms.ua/api/verify.php",
    json=payload,
    timeout=30,
)

print(response.json())

Node.js

const payload = {
  "auth": "API_KEY",
  "command": "verify",
  "phone": "380501234567",
  "code": "123456",
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a"
};

const response = await fetch("https://alphasms.ua/api/verify.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(await response.json());

Ответ

successboolean Результат запроса

verify_idstring ID верификации

phonestring Номер телефона

typestring Тип канала: sms, email, hlr, rcs, viber

statusstring Статус верификации (см. ниже)

service_idnumber ID сервиса верификации

Пример успешного ответа:

{
  "success": true,
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a",
  "phone": "441501234567",
  "type": "sms",
  "status": "approved",
  "service_id": 1
}

Возможные значения status:

status	Описание
approved	Код верный, верификация успешна
pending	Код неверный, попытки ещё остались
expired	Код истёк
blocked	Превышен лимит попыток

Коды ошибок HTTP:

• 400 — неверный формат запроса или JSON
• 401 — отсутствует или неверный auth
• 413 — слишком большое тело запроса

---

Вебхук

Если в запросе был передан параметр hook и запрос отклонён при обработке, шлюз отправляет уведомление на этот адрес.

Payload повторяет формат вебхука сообщений: плоский объект со status и причиной в error. Отдельного payload для ошибок нет.

HTTP метод: POST
Content-Type: application/json
X-Signature: sha256(json_body + api_key)

Параметр	Тип	Описание
verify_id	string	Идентификатор верификации
status	string	Всегда REJECTED — запрос отклонён при обработке
error	string	Причина, по которой запрос отклонён
updated	string	Дата и время события Формат: YYYY-MM-DDThh:mm:ss±hh:mm
request_id	string	Идентификатор запроса, который вернул асинхронный API

Пример запроса

{
  "verify_id": "14fb5f3d-20be-41ef-b31a-b9f5e499bc7a",
  "status": "REJECTED",
  "error": "Access denied",
  "updated": "2026-08-21T10:12:33+03:00",
  "request_id": "a1436d496bf11a59"
}

Ответ

В ответе будет получен код 200. Вебхук отправляется один раз, без повторов.

---

Ограничения

• Время жизни кода: по умолчанию 300 секунд (5 минут), диапазон 60–3600 секунд.
• Максимальное число попыток: по умолчанию 5.