v1REST · JSON

SNSOTP OTP API

REST API для SMS-верификации. Закажите номер для одного из 182 сервисов в одной из 154 стран, получите одноразовый код из заказа и верните полную стоимость, если код не пришел в течение 20 минут.

Каждый эндпоинт принимает параметры как query-параметры (GET) или как поля формы или JSON (POST). Ответы в формате JSON; деньги указываются в USD строкой с двумя десятичными знаками, а время, в формате ISO 8601 в UTC.

Сервер

https://snsotp.com/api/v1

АутентификацияBearer токен

Ваш API-ключ из консоли, отправляемый как Authorization: Bearer sok_...

Аутентификация

Создайте ключ на странице API в консоли. Он начинается с sok_ и показывается только один раз, поэтому сохраните его в переменной окружения. Замена ключа немедленно останавливает старый. Вызовы к /services, /countries и /prices работают без ключа.

Заголовок
Authorization: Bearer sok_your_key_here

Ключ также можно отправить как query-параметр или поле формы key, что помогает инструментам, которые не могут устанавливать заголовки.

Быстрый старт

Закажите номер, передайте его в приложение, затем опрашивайте заказ, пока не появится код. Тот же процесс на четырех языках:

# 1. Order a number for whatsapp in US
curl -X POST https://snsotp.com/api/v1/orders \
  -H "Authorization: Bearer $SNSOTP_KEY" \
  -d service=whatsapp -d country=us

# 2. Read the code (poll every 3 to 5 seconds)
curl https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB \
  -H "Authorization: Bearer $SNSOTP_KEY"

GET/services

Каждый сервис с его кодом и минимальной ценой · без ключа

Каждый сервис, для которого можно заказать номер, с его кодом (используйте его как service в других вызовах), категорией и минимальной ценой по странам. Ключ не требуется.

ЗапросcURL
curl https://snsotp.com/api/v1/services
Ответ200
{
  "services": [
    { "code": "whatsapp", "name": "WhatsApp", "category": "social", "from": "0.09" },
    { "code": "telegram", "name": "Telegram", "category": "social", "from": "0.03" }
  ]
}

GET/countries

Каждая страна с её кодом и кодом набора · без ключа

Каждая страна с ее кодом (ISO 3166 alpha-2 в нижнем регистре, используйте его как country) и телефонным кодом. Ключ не требуется.

ЗапросcURL
curl https://snsotp.com/api/v1/countries
Ответ200
{
  "countries": [
    { "code": "us", "name": "United States", "dial_code": "1" },
    { "code": "gb", "name": "United Kingdom", "dial_code": "44" }
  ]
}

GET/prices

Цены для сервиса, страны или обоих · без ключа

Цена за заказ для одного сервиса в каждой стране, одной страны для каждого сервиса или одной пары. Укажите хотя бы один фильтр. Ключ не требуется.

Параметры

  • servicestring

    Код сервиса, например whatsapp

  • countrystring

    Код страны, например us

ЗапросcURL
curl "https://snsotp.com/api/v1/prices?service=whatsapp&country=us"
Ответ200
{
  "prices": [
    { "service": "whatsapp", "country": "us", "price": "0.93" }
  ]
}

GET/balance

Ваш баланс в USD · ключ требуется

Ваш баланс в USD.

ЗапросcURL
curl https://snsotp.com/api/v1/balance \
  -H "Authorization: Bearer $SNSOTP_KEY"
Ответ200
{
  "balance": "42.50",
  "currency": "USD"
}

POST/orders

Закажите номер для сервиса и страны · ключ требуется

Заказывает номер и списывает его стоимость. Ответ содержит номер полностью (phone) и без телефонного кода (number). Заказ остается открытым в течение 20 минут; если код не пришел за это время, стоимость автоматически возвращается на ваш баланс. Статус ответа 201.

Параметры

  • servicestringобязательно

    Код сервиса из GET /services

  • countrystringобязательно

    Код страны из GET /countries

ЗапросcURL
curl -X POST https://snsotp.com/api/v1/orders \
  -H "Authorization: Bearer $SNSOTP_KEY" \
  -d service=whatsapp -d country=us
Ответ201
{
  "order": {
    "id": "OT-7K2M9QX4PB",
    "service": "whatsapp",
    "country": "us",
    "phone": "+13475550182",
    "number": "3475550182",
    "dial_code": "1",
    "price": "0.93",
    "status": "waiting",
    "code": null,
    "sms": null,
    "codes": [],
    "expires_at": "2026-11-03T12:20:00.000Z"
  },
  "window_minutes": 20
}

GET/orders/{id}

Статус, код и текст SMS одного заказа · ключ требуется

Один заказ с его статусом, последним кодом, последним SMS-текстом и всеми полученными кодами. Опрашивайте каждые 3-5 секунд, пока статус waiting.

Параметры

  • idpathобязательно

    ID заказа из POST /orders

ЗапросcURL
curl https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB \
  -H "Authorization: Bearer $SNSOTP_KEY"
Ответ200
{
  "order": {
    "id": "OT-7K2M9QX4PB",
    "service": "whatsapp",
    "country": "us",
    "phone": "+13475550182",
    "number": "3475550182",
    "price": "0.93",
    "status": "received",
    "code": "284913",
    "sms": "Your WhatsApp code is 284913",
    "expires_at": "2026-11-03T12:20:00.000Z"
  }
}

GET/orders

Ваши открытые заказы (или все с status=all) · ключ требуется

Ваши открытые заказы, сначала новые. Добавьте status=all для недавних заказов во всех статусах.

Параметры

  • statusstring

    open (по умолчанию) или all

  • limitnumber

    от 1 до 100, по умолчанию 50

ЗапросcURL
curl "https://snsotp.com/api/v1/orders?status=open" \
  -H "Authorization: Bearer $SNSOTP_KEY"
Ответ200
{
  "orders": [
    { "id": "OT-7K2M9QX4PB", "service": "whatsapp", "status": "received", "code": "284913" }
  ]
}

POST/orders/{id}/resend

Ещё один код на тот же номер · ключ требуется

Запрашивает еще один код на тот же номер после первого кода, в пределах временного окна, без дополнительной платы. Затем инициируйте новое SMS в приложении; waiting_for_resend будет true, пока оно не придет.

Параметры

  • idpathобязательно

    ID заказа

ЗапросcURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/resend \
  -H "Authorization: Bearer $SNSOTP_KEY"
Ответ200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "received", "waiting_for_resend": true }
}

POST/orders/{id}/finish

Закройте заказ после использования кода · ключ требуется

Закрывает заказ, который получил код, после его использования. Завершение необязательно: открытые заказы закрываются автоматически по окончании окна.

Параметры

  • idpathобязательно

    ID заказа

ЗапросcURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/finish \
  -H "Authorization: Bearer $SNSOTP_KEY"
Ответ200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "finished" }
}

POST/orders/{id}/cancel

Отмените до получения кода, полный возврат средств · ключ требуется

Отменяет заказ до получения кода и немедленно возвращает полную стоимость на ваш баланс. После получения кода отмена возвращает has_code.

Параметры

  • idpathобязательно

    ID заказа

ЗапросcURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/cancel \
  -H "Authorization: Bearer $SNSOTP_KEY"
Ответ200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "canceled", "refunded": "0.93" }
}

Статус заказа

значения статуса
  • waitingНомер готов, но SMS еще не пришло. Отмена возможна.
  • receivedПришел хотя бы один код. code и sms содержат последний.
  • finishedЗакрыт после получения кода, путем завершения или по окончании окна.
  • refundedКод не пришел в течение 20 минут. Полная стоимость возвращена на ваш баланс.
  • canceledОтменен до получения кода. Полная стоимость возвращена на ваш баланс.

Ошибки

Ошибки используют HTTP-статус и тело с устойчивым кодом и читаемым сообщением.

HTTP-статус и коды
  • 400missing_filter, bad_jsonОтсутствует обязательное значение или тело запроса не может быть прочитано.
  • 401no_key, bad_keyКлюч отсутствует, неверен или удален.
  • 402no_balanceНедостаточно средств на балансе для этого заказа. Пополните баланс в консоли.
  • 404unknown_service, unknown_country, not_sold, not_foundКод или заказ не существует, или пара не продается.
  • 409too_many_open, has_code, not_ready, no_numbersДействие не соответствует состоянию заказа или сейчас нет свободных номеров (ничего не списывается).
  • 429rate_limitedБолее 300 запросов в минуту с одним ключом.
Тело ошибки402
{
  "error": {
    "code": "no_balance",
    "message": "Not enough credit. Add credit in the console."
  }
}

Лимиты запросов

  • 300 запросов в минуту на один ключ. При превышении этого лимита API отвечает 429 rate_limited до конца минуты.
  • До 20 открытых заказов на аккаунт. Завершите или отмените один, чтобы открыть другой.
  • Проверяйте статус заказа каждые 3-5 секунд; коды обычно приходят в течение минуты.

Формат SMS активации

Скрипты, написанные для формата handler_api.php, работают с тем же API-ключом: измените базовый адрес на https://snsotp.com/stubs/handler_api.php и сохраните действия. Коды сервисов и стран такие же, как в REST API.

Действия

  • getBalance

    ACCESS_BALANCE:42.50

  • getServicesList

    Список сервисов в JSON

  • getCountries

    Карта стран в JSON

  • getPricesservice, country (опционально)

    JSON {country: {service: {cost, count}}}

  • getNumberservice, country

    ACCESS_NUMBER:<id>:<phone>

  • getStatusid

    STATUS_WAIT_CODE, STATUS_OK:<code>, STATUS_WAIT_RETRY:<code>, STATUS_CANCEL

  • setStatusid, status 1 / 3 / 6 / 8

    ACCESS_READY, ACCESS_RETRY_GET, ACCESS_ACTIVATION, ACCESS_CANCEL

ЗапросcURL
curl "https://snsotp.com/stubs/handler_api.php\
?api_key=$SNSOTP_KEY&action=getNumber\
&service=telegram&country=gb"

ACCESS_NUMBER:OT-3QF8ZK2W7M:447700900182

Значения setStatus: 1 готов, 3 другой код, 6 завершить, 8 отменить с полным возвратом средств.

Документация API OTP: SMS-верификация REST API | SNSOTP