API compatible with SMS-Activate

VirtualSim API

Production ready 2 req/sec per API key Цены в USD

Базовый адрес, ключ и лимиты

Все операции вызываются через один путь. Тип операции задаётся параметром action.

https://virtualsim.io/stubs/handler_api.php?action=getBalance&api_key=YOUR_API_KEY

https://virtualsim.io/stubs/handler_api.php

Параметр	Тип	Обяз.	Описание
action	string	да	Имя операции: `getBalance`, `getNumber`, `getStatus` и т.д.
api_key	string	да*	Ваш ключ из профиля. Можно передать в query или в заголовке `Authorization: Bearer YOUR_API_KEY`.

При неверном ключе вернётся BAD_KEY с HTTP 401. При неизвестном action — BAD_ACTION. Лимит: 2 запроса в секунду на API-ключ.

Поддерживаемые операции

action	Метод	Ответ	Назначение
`getBalance`	GET	text	Текущий баланс: `ACCESS_BALANCE:<amount>`
`getNumber`	GET	text	Заказать номер: `ACCESS_NUMBER:<id>:<number>`
`getNumberV2`	GET	JSON	Заказать номер и получить расширенные поля
`setStatus`	GET	text / JSON	Повтор SMS, завершение или отмена активации
`getStatus`	GET	text	Статус активации: `STATUS_WAIT_CODE`, `STATUS_OK:<code>`
`getStatusV2`	GET	JSON	Структурированный статус и SMS
`getActiveActivations`	GET	JSON	Список активных заказов
`getHistory`	GET	JSON	История активаций
`reactivationPrice`	GET	JSON	Цена повторной активации
`reactivate`	POST	JSON	Повторная активация номера, если доступна
`getCountries`	GET	JSON	Список стран
`getServicesList`	GET	JSON	Список сервисов
`getOperators`	GET	JSON	Список доступных операторов. В VirtualSim используйте `any`.
`getPrices`	GET	JSON	Цены и количество номеров по странам/сервисам
`getTopCountriesByService`	GET	JSON	Топ стран по сервису из текущего каталога
`getTopCountriesByServiceRank`	GET	JSON	То же, совместимый alias
`getAllSms`	GET	JSON	Все SMS по конкретной активации
`finishActivation`	GET	204	Завершить активацию
`cancelActivation`	GET	204	Отменить активацию, если по правилам ещё возможно

GET Request account balance

https://virtualsim.io/stubs/handler_api.php?action=getBalance&api_key=YOUR_API_KEY

Response 200

ACCESS_BALANCE:100.50

GET Request a number

Покупает номер для указанного сервиса и страны. Средства списываются с баланса.

https://virtualsim.io/stubs/handler_api.php?action=getNumber&service=tg&country=0&api_key=YOUR_API_KEY

Параметр	Тип	Обяз.	Описание
service	string	да	Код сервиса из `getServicesList`, например `tg`.
country	number	да	ID страны из `getCountries`.
operator	string	нет	Можно передать `any`. Если указан конкретный оператор, он будет передан поставщику, если тот поддерживает.
maxPrice	number	нет	Максимальная цена покупки.
fixedPrice	string	нет	Строго покупать по `maxPrice`, если поддерживается поставщиком.
ref	string	нет	Реферальная метка.

Response 200

ACCESS_NUMBER:635468024:79991234567

Typical errors

NO_BALANCE
NO_NUMBERS
WRONG_PRICE
WRONG_MAX_NUMBERS

GET Request number V2

То же, что getNumber, но ответ — JSON.

https://virtualsim.io/stubs/handler_api.php?action=getNumberV2&service=tg&country=0&api_key=YOUR_API_KEY

{
  "activationId": "635468024",
  "phoneNumber": "79991234567",
  "activationCost": 0.42,
  "currency": 840,
  "countryCode": 0,
  "canGetAnotherSms": true,
  "activationTime": "2026-05-11T15:52:00Z",
  "activationOperator": "any"
}

GET Change activation status

https://virtualsim.io/stubs/handler_api.php?action=setStatus&id=635468024&status=3&api_key=YOUR_API_KEY

status	Значение	Response
`3`	Запросить повторную SMS	`ACCESS_RETRY_GET` или ответ поставщика
`6`	Завершить активацию	`ACCESS_ACTIVATION`
`8`	Отменить активацию и вернуть средства, если возможно	`ACCESS_CANCEL`

GET Get activation status

https://virtualsim.io/stubs/handler_api.php?action=getStatus&id=635468024&api_key=YOUR_API_KEY

Response examples

STATUS_WAIT_CODE
STATUS_OK:12345
STATUS_CANCEL

V2 JSON

https://virtualsim.io/stubs/handler_api.php?action=getStatusV2&id=635468024&api_key=YOUR_API_KEY

{
  "verificationType": 2,
  "sms": {
    "dateTime": "2026-05-11 15:52:00",
    "code": "12345",
    "text": "12345"
  }
}

Active activations and history

GET getActiveActivations

https://virtualsim.io/stubs/handler_api.php?action=getActiveActivations&api_key=YOUR_API_KEY

{
  "status": "success",
  "data": [
    {
      "activationId": "635468024",
      "serviceCode": "tg",
      "phoneNumber": "79991234567",
      "activationCost": 0.42,
      "activationStatus": "1",
      "smsCode": "",
      "smsText": "",
      "countryCode": "0",
      "canGetAnotherSms": "1",
      "currency": 840
    }
  ]
}

GET getHistory

https://virtualsim.io/stubs/handler_api.php?action=getHistory&start=1770000000&end=1770090000&offset=0&size=100&api_key=YOUR_API_KEY

Параметры start, end, offset, size необязательны.

GET Request list of countries

https://virtualsim.io/stubs/handler_api.php?action=getCountries&api_key=YOUR_API_KEY

[
  {
    "id": 0,
    "rus": "Россия",
    "eng": "Russia",
    "chn": "俄罗斯",
    "visible": 1,
    "retry": 1
  }
]

GET Request a list of services

https://virtualsim.io/stubs/handler_api.php?action=getServicesList&country=0&api_key=YOUR_API_KEY

Параметр	Тип	Обяз.	Описание
country	number	нет	Если передан, вернёт сервисы конкретной страны.
lang	string	нет	Совместимый параметр

{
  "status": "success",
  "services": [
    { "code": "tg", "name": "Telegram" },
    { "code": "wa", "name": "WhatsApp" }
  ]
}

GET Get current prices

https://virtualsim.io/stubs/handler_api.php?action=getPrices&service=tg&country=0&api_key=YOUR_API_KEY

Параметр	Тип	Обяз.	Описание
service	string	нет	Код сервиса.
country	number	нет	ID страны. Если не передан, вернутся все страны.

{
  "0": {
    "tg": {
      "cost": 0.42,
      "count": 11540,
      "physicalCount": 11540
    }
  }
}

Operators and top countries

GET getOperators

https://virtualsim.io/stubs/handler_api.php?action=getOperators&country=0&api_key=YOUR_API_KEY

{
  "status": "success",
  "countryOperators": {
    "0": ["any"]
  }
}

GET getTopCountriesByService

https://virtualsim.io/stubs/handler_api.php?action=getTopCountriesByService&service=tg&api_key=YOUR_API_KEY

Также поддерживается alias getTopCountriesByServiceRank.

SMS and activation closing

GET getAllSms

https://virtualsim.io/stubs/handler_api.php?action=getAllSms&id=635468024&api_key=YOUR_API_KEY

{
  "data": [
    { "message": "Your code is 12345", "date": "2026-05-11 15:52:00" }
  ],
  "meta": { "total": 1, "service": "virtualsim" }
}

GET finishActivation / cancelActivation

https://virtualsim.io/stubs/handler_api.php?action=finishActivation&id=635468024&api_key=YOUR_API_KEY

https://virtualsim.io/stubs/handler_api.php?action=cancelActivation&id=635468024&api_key=YOUR_API_KEY

При успехе ответ 204 No Content. Если отмена уже невозможна, вернётся JSON с ошибкой.

Reactivation

GET reactivationPrice

https://virtualsim.io/stubs/handler_api.php?action=reactivationPrice&id=635468024&api_key=YOUR_API_KEY

{
  "data": {
    "price": 0.45,
    "currency": 840
  }
}

POST reactivate

https://virtualsim.io/stubs/handler_api.php?action=reactivate&id=635468024&api_key=YOUR_API_KEY

Повторная активация доступна не для каждого заказа. Если поставщик не поддерживает повтор, вернётся ошибка.

Webhooks

Webhook уведомляет ваш сервер, когда по активации пришла SMS. URL вебхука задаётся в профиле VirtualSim. Метод: POST, Content-Type: application/json. Ваш сервер должен быстро ответить HTTP 200.

{
  "event": "sms.received",
  "activationId": "635468024",
  "service": "tg",
  "country": 0,
  "phoneNumber": "79991234567",
  "text": "Your code is 12345",
  "code": "12345",
  "receivedAt": "2026-05-11 15:52:00 UTC"
}

python_sms_activate.py

import requests

API = "https://virtualsim.io/stubs/handler_api.php"
KEY = "YOUR_API_KEY"

balance = requests.get(API, params={
    "api_key": KEY,
    "action": "getBalance",
}).text

number = requests.get(API, params={
    "api_key": KEY,
    "action": "getNumber",
    "service": "tg",
    "country": 0,
}).text

# ACCESS_NUMBER:id:phone
activation_id = number.split(":")[1]

status = requests.get(API, params={
    "api_key": KEY,
    "action": "getStatus",
    "id": activation_id,
}).text

print(balance, number, status)

GET getBalance

ACCESS_BALANCE:100.50

GET getNumber

ACCESS_NUMBER:635468024:79991234567

GET getStatusV2

{
  "verificationType": 2,
  "sms": {
    "dateTime": "2026-05-11 15:52:00",
    "code": "12345",
    "text": "12345"
  }
}

GET getPrices

{
  "0": {
    "tg": {
      "cost": 0.42,
      "count": 11540,
      "physicalCount": 11540
    }
  }
}