Verify (OTP)

API для створення та перевірки одноразових кодів верифікації (OTP) через SMS, Email та інші канали.

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

---

Створення коду — синхронний

Створює код верифікації та надсилає його через SMS або Email. Шлюз обробляє запит одразу та повертає verify_id. Потрібно вказати або service_id, або sender_name.

URI: https://alphasms.ua/api/verify.php

Метод: POST

Параметри запиту

authstringобов'язковий API-ключ з особистого кабінету

commandstringобов'язковий Має бути verify/create

phonestringобов'язковий* Номер телефону в будь-якому форматі (обов'язковий, якщо не вказано email)

emailstringобов'язковий* Email-адреса (обов'язкова, якщо не вказано phone)

typestringобов'язковий Тип верифікації: sms, hlr, rcs, email, viber

sender_namestringобов'язковий* Підпис / бренд у SMS (обов'язковий, якщо не вказано service_id)

langstring Мова повідомлення: uk, ru, en (за замовчуванням en)

code_lengthnumber Довжина коду (за замовчуванням 8, діапазон 1–10)

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

service_idnumberобов'язковий* ID сервісу верифікації. Видається та налаштовується менеджером (обов'язковий, якщо не вказано sender_name)

custom_idstring Користувацький ідентифікатор для зв'язку з вашою системою

hookstring URL webhook для сповіщень про статус верифікації

Приклад запиту

Sync

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

Async

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://api-async.alphasms.ua/v1/verify/create' \
  -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://api-async.alphasms.ua/v1/verify/create');
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://api-async.alphasms.ua/v1/verify/create",
    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://api-async.alphasms.ua/v1/verify/create", {
  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: https://api-async.alphasms.ua/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: https://alphasms.ua/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. Правила доставки ті самі, що у вебхука про статус: до трьох спроб, успіхом вважається лише код 200, обробник має бути ідемпотентним.

---

Обмеження

• Час життя коду: за замовчуванням 300 секунд (5 хвилин), діапазон 60–3600 секунд.
• Максимальна кількість спроб: за замовчуванням 5.