SMS-Activate compatible

API documentation

API compatible with SMS-Activate

Get API keyProductionWorks with SMS-Activate clients

Overview

Compatibility base URL is /stubs/handler_api.php. The operation is selected via the action parameter. Prices are in USD; balance and catalog match the web UI.

Base URL

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

Alternate

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

Authentication

Enable the key in your profile. Pass it using one of:

Query parameter?api_key=YOUR_API_KEY
HTTP headerAuthorization: Bearer YOUR_API_KEY

Never commit API keys to public repos or ship them in browser code.

Quickstart

Typical flow: balance → order number → poll status → finish.

getBalance
getNumber → ACCESS_NUMBER:id:phone
getStatus until STATUS_OK:code
setStatus&status=6 or finishActivation

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

Response codes

SMS-Activate text errors and HTTP statuses.

BAD_KEY / 401	Invalid or missing API key
NO_BALANCE / 402	Insufficient funds
NO_NUMBERS	No numbers available
BAD_ACTION / 400	Unknown action or bad params
WRONG_MAX_NUMBERS	Active numbers limit reached
STATUS_CANCEL	Activation cancelled
204	Success with empty body (finish/cancel)

Account

GET

getBalance

— Account balance

Returns the current balance as ACCESS_BALANCE:<amount>.

Response

Plain text ACCESS_BALANCE:100.50

ACCESS_BALANCE:100.50

Request example

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

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

Activations

GET

getNumber

— Request a number

Orders a number for service and country. Response: ACCESS_NUMBER:<id>:<number>.

Parameters

Name	Type	Parameters
servicereq.	string	Service code (tg, wa, go…)
countryreq.	number	Country ID
maxPrice	number	Maximum price USD
fixedPrice	string	true — purchase strictly at maxPrice

Response

ACCESS_NUMBER:123456789:79001234567

ACCESS_NUMBER:123456789:79001234567

Request example

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

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

GET

getNumberV2

— Request a number V2

Same as getNumber, but returns a JSON object with activation details.

Parameters

Name	Type	Parameters
servicereq.	string	Service code
countryreq.	number	Country ID

Response

Activation JSON object

{
  "activationId": "635468024",
  "phoneNumber": "79001234567",
  "activationCost": 0.35,
  "currency": 840,
  "countryCode": 0,
  "canGetAnotherSms": true
}

Request example

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

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

GET

getActiveActivations

— Active activations

List of current active activations.

Parameters

Name	Type	Parameters
start	integer	Offset (default 0)
limit	integer	Limit (max 100)

Response

JSON { status, data[] }

{
  "status": "success",
  "data": [
    {
      "activationId": "635468021",
      "serviceCode": "tg",
      "phoneNumber": "79001234567",
      "activationCost": 0.35,
      "activationStatus": "1",
      "currency": 840
    }
  ]
}

Request example

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

curl 'https://virtualsim.io/stubs/handler_api.php?action=getActiveActivations&start=0&limit=20&api_key=YOUR_API_KEY'

GET

getHistory

— Activation history

History for a period (Unix timestamps).

Parameters

Name	Type	Parameters
start	integer	Period start
end	integer	Period end
offset	integer	Offset
size	integer	Limit (max 100)

Response

JSON array

[
  {
    "id": "635468024",
    "date": "2026-02-18 16:11:33",
    "phone": "79001234567",
    "cost": 0.35,
    "status": "4",
    "currency": 840
  }
]

Request example

https://virtualsim.io/stubs/handler_api.php?action=getHistory&start=1700000000&end=1800000000&offset=0&size=50&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getHistory&start=1700000000&end=1800000000&offset=0&size=50&api_key=YOUR_API_KEY'

POST

reactivate

— Reactivate number

Request a previously used phone number again.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID
duration	number	Duration in hours (optional)

Response

Activation JSON

{
  "activationId": "123456",
  "serviceCode": "tg",
  "phoneNumber": "79991234567",
  "activationCost": 15.5,
  "currency": 840,
  "countryCode": 2,
  "canGetAnotherSms": true,
  "status": 4
}

Request example

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

curl -X POST 'https://virtualsim.io/stubs/handler_api.php?action=reactivate&id=123456789&duration=24&api_key=YOUR_API_KEY'

GET

reactivateOptions

— Reactivation options

Cost options for number reactivation.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

JSON options

{
  "data": {
    "options": [
      { "price": 0.42, "duration": { "unit": "hour", "value": 24 } }
    ]
  }
}

Request example

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

curl 'https://virtualsim.io/stubs/handler_api.php?action=reactivateOptions&id=123456789&api_key=YOUR_API_KEY'

Status & SMS

GET

setStatus

— Change activation status

3 — request another SMS, 6 — complete, 8 — cancel (refund).

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID
statusreq.	integer	3 \| 6 \| 8

Response

ACCESS_RETRY_GET / ACCESS_ACTIVATION / ACCESS_CANCEL

ACCESS_RETRY_GET

Request example

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

curl 'https://virtualsim.io/stubs/handler_api.php?action=setStatus&id=123456789&status=8&api_key=YOUR_API_KEY'

GET

getStatus

— Get activation status

STATUS_WAIT_CODE, STATUS_OK:<code>, STATUS_CANCEL, etc.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

Plain-text status

STATUS_OK:12345

Request example

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

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

GET

getStatusV2

— Get status V2

Structured JSON with SMS/call payload.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

Status JSON

{
  "verificationType": 2,
  "sms": {
    "dateTime": "2026-02-18T16:11:33+00:00",
    "code": "12345",
    "text": "Your code is 12345"
  }
}

Request example

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

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

GET

getAllSms

— All SMS for activation

All received SMS/OTP messages for an activation ID.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

JSON { data, meta }

{
  "data": [
    {
      "code": "12345",
      "text": "Your code is 12345",
      "service": "tg",
      "type": "sms"
    }
  ],
  "meta": { "total": 1, "service": "tg" }
}

Request example

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

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

GET

finishActivation

— Finish activation

Completes the activation (HTTP 204).

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

204 No Content

(empty body)

Request example

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

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

GET

cancelActivation

— Cancel activation

Cancel purchase with refund if SMS was not received (HTTP 204).

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

204 No Content

(empty body)

Request example

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

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

Catalog

GET

getCountries

— List of countries

All available countries in the catalog.

Response

JSON array of countries

[
  { "id": 0, "eng": "Russia", "rus": "Россия", "visible": 1 }
]

Request example

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

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

GET

getServicesList

— List of services

Services available for a country.

Parameters

Name	Type	Parameters
country	number	Country ID
lang	string	en \| ru \| …

Response

JSON { status, services }

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

Request example

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

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

GET

getPrices

— Current prices

Prices and stock by country/service.

Parameters

Name	Type	Parameters
service	string	Service code
country	number	Country ID

Response

JSON with cost/count

{
  "0": {
    "tg": { "cost": 0.35, "count": 1200, "physicalCount": 800 }
  }
}

Request example

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

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

GET

getTopCountriesByService

— Top countries by service

Ranked countries by stock and price for a service.

Parameters

Name	Type	Parameters
servicereq.	string	Service code

Response

JSON array

[{ "tg": [{ "country": 0, "price": 0.35, "count": 1200 }] }]

Request example

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

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

Rent

GET

serviceCountRent

— Rent prices by duration

Rent prices and stock (service=full) by duration tiers.

Parameters

Name	Type	Parameters
servicereq.	string	Usually full
country	number	Country ID

Response

JSON country → duration → price

{
  "0": {
    "24": { "count": 120, "price": 1.2, "retail_price": 1.2 },
    "48": { "count": 80, "price": 2.1, "retail_price": 2.1 }
  }
}

Request example

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

curl 'https://virtualsim.io/stubs/handler_api.php?action=serviceCountRent&service=full&country=0&api_key=YOUR_API_KEY'

GET

getRentServicesAndCountries

— Rent services for country

Rent services and prices for a country and duration.

Parameters

Name	Type	Parameters
countryreq.	number	Country ID
durationreq.	number	Duration in hours

Response

JSON services

{
  "services": {
    "full": { "quantity": 120, "price": 1.2, "retail_price": 1.2 }
  }
}

Request example

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

curl 'https://virtualsim.io/stubs/handler_api.php?action=getRentServicesAndCountries&country=0&duration=24&api_key=YOUR_API_KEY'

GET

getRentNumber

— Rent a number

Order a rental number for the given duration (hours).

Parameters

Name	Type	Parameters
servicereq.	string	full — unassigned number
countryreq.	number	Country ID
durationreq.	number	2,4,12,24,48,72,96,120,144,168

Response

Rent activation JSON

{
  "activationId": "123456",
  "phoneNumber": "79001234567",
  "activationCost": 1.2,
  "currency": 840,
  "countryCode": 0,
  "canGetAnotherSms": true
}

Request example

https://virtualsim.io/stubs/handler_api.php?action=getRentNumber&service=full&country=0&duration=24&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getRentNumber&service=full&country=0&duration=24&api_key=YOUR_API_KEY'

GET

prolongOptions

— Extension cost

Rent extension price options.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

JSON options

{
  "data": {
    "options": [
      { "price": 1.43, "duration": { "unit": "hour", "value": 24 } }
    ]
  }
}

Request example

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

curl 'https://virtualsim.io/stubs/handler_api.php?action=prolongOptions&id=123456789&api_key=YOUR_API_KEY'

POST

prolong

— Extend rent

Extends a rental activation by the given hours.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID
durationreq.	number	Hours to extend

Response

Activation JSON

{
  "activationId": "123456",
  "phoneNumber": "79001234567",
  "activationCost": 1.43,
  "currency": 840
}

Request example

https://virtualsim.io/stubs/handler_api.php?action=prolong&id=123456789&duration=24&api_key=YOUR_API_KEY

curl -X POST 'https://virtualsim.io/stubs/handler_api.php?action=prolong&id=123456789&duration=24&api_key=YOUR_API_KEY'

GET

prolongHistory

— Extension history

Extension history for a rental activation.

Parameters

Name	Type	Parameters
idreq.	integer	Activation ID

Response

JSON data[]

{
  "data": [
    {
      "userPrice": 1.43,
      "hours": 24,
      "createDate": "2026-02-19T10:37:46+00:00",
      "payerType": "client"
    }
  ]
}

Request example

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

curl 'https://virtualsim.io/stubs/handler_api.php?action=prolongHistory&id=123456789&api_key=YOUR_API_KEY'

Webhooks

Receive inbound SMS via push instead of polling. Configure with REST /api/v1/setSmsWebhook. Always reply with HTTP 200.

Method: POST, Content-Type: application/json
Configure: POST https://virtualsim.io/api/v1/setSmsWebhook
Read: GET https://virtualsim.io/api/v1/getSmsWebhook

Sample webhook body

{
  "activationId": "635468024",
  "phoneNumber": "79001234567",
  "service": "tg",
  "text": "Your code is 12345",
  "code": "12345"
}

REST API /api/v1

Modern JSON API with the same business logic. Bearer API key or cookie session.

GET /getBalancehttps://virtualsim.io/api/v1/getBalance

POST /orderNumberhttps://virtualsim.io/api/v1/orderNumber

GET /getStatushttps://virtualsim.io/api/v1/getStatus?id=ACTIVATION_ID

POST /setStatushttps://virtualsim.io/api/v1/setStatus

GET /getPriceshttps://virtualsim.io/api/v1/getPrices?service=tg&country=0

GET /getCountrieshttps://virtualsim.io/api/v1/getCountries

GET /getServiceshttps://virtualsim.io/api/v1/getServices

GET /getActiveActivationshttps://virtualsim.io/api/v1/getActiveActivations

GET /getSmsWebhookhttps://virtualsim.io/api/v1/getSmsWebhook

POST /setSmsWebhookhttps://virtualsim.io/api/v1/setSmsWebhook