Developer API

The public API is one endpoint and GET requests only: the method name goes in the action parameter. The format matches the popular marketplaces, so existing code starts working once you change the base URL.

Access keyGet a key
Keys are issued in your account — sign in or sign up to get one.The key string is shown once, at the moment it is issued. Lost it? Issue a new one and revoke the old.
Base URL
GEThttps://sim-aggregator.org/stubs/handler_api.php
Every method is called at this address; only the action parameter differs.
How a run goes
1getPrices · getServicesListCheck the price and stock for the service and country you need.
2getNumber · getNumberV2Order a number — the reply carries the activation id and the number itself.
3getStatusPoll the status until the code arrives.
4setStatus · 6Finish the activation once the service accepts the code.
—setStatus · 3 · 8Need another code — 3; the number was no use — 8, and the money comes back.
Method summary
MethodKeyParameters
getPriceskey requiredaction, api_key, [country], [service]
getCountrieskey requiredaction, api_key
getServicesListkey requiredaction, api_key, [country]
getBalancekey requiredaction, api_key
getNumberkey requiredaction, api_key, country, service, [duration], [maxPrice], [softId]
getNumberV2key requiredaction, api_key, country, service, [duration], [maxPrice], [softId]
getStatuskey requiredaction, api_key, id
getCurrentActivationsListkey requiredaction, api_key
setStatuskey requiredaction, api_key, id, status

getPrices

key required

Prices and stock by country and service — how many numbers there are and at what price.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getPrices
api_keystringrequiredThe access key from your cabinet
countrystringnoCountry identifier, e.g. 43
servicestringnoService code, e.g. wa
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getPrices&api_key=YOUR_API_KEY&country=43
Response
{
  "43": {
    "wa": { "cost": 0.5, "count": 100 },
    "tg": { "cost": 0.71, "count": 250 }
  }
}
With no parameters the method returns the whole price list — a large reply, so ask for the country and service you need.
What it can answer
BAD_COUNTRYCountry not found
BAD_SERVICEService not found
BAD_KEYThe key was rejected: unknown or revoked

getCountries

key required

The country reference: identifier, names and which modes the country supports.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getCountries
api_keystringrequiredThe access key from your cabinet
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getCountries&api_key=YOUR_API_KEY
Response
{
  "43": { "id": 43, "rus": "DE", "eng": "DE", "chn": "DE",
         "visible": 1, "retry": 1, "rent": 0, "multiService": 0 }
}
The rus, eng and chn fields currently carry the two-letter ISO country code, not the country name.
What it can answer
BAD_KEYThe key was rejected: unknown or revoked

getServicesList

key required

The service reference: the service code and its name.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getServicesList
api_keystringrequiredThe access key from your cabinet
countrystringnoCountry identifier, e.g. 43
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getServicesList&api_key=YOUR_API_KEY
Response
{
  "status": "success",
  "services": [
    { "code": "tg", "name": "Telegram" },
    { "code": "wa", "name": "WhatsApp" }
  ]
}
With the country parameter the list narrows to services actually sold there.
What it can answer
BAD_COUNTRYCountry not found
BAD_KEYThe key was rejected: unknown or revoked

getBalance

key required

The account balance.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getBalance
api_keystringrequiredThe access key from your cabinet
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getBalance&api_key=YOUR_API_KEY
Response
ACCESS_BALANCE:12.50
The reply is a string, not JSON: the amount follows the colon.
What it can answer
BAD_KEYThe key was rejected: unknown or revoked

getNumber

key required

Order a number. The reply carries the activation id and the number.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getNumber
api_keystringrequiredThe access key from your cabinet
countrystringrequiredCountry identifier, e.g. 43
servicestringrequiredService code, e.g. wa
durationstringnoOrder duration: activation — a one-time activation (default); d1, d3, d7 — rent the number for 1, 3 or 7 days
maxPricestringnoPrice ceiling per number. We will not buy above it: instead of an order you get WRONG_MAX_PRICE or NO_NUMBERS
softIdstringnoSoftware identifier, up to 255 characters
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getNumber&api_key=YOUR_API_KEY&country=43&service=wa
Response
ACCESS_NUMBER:12345:380991234567
The reply is the string ACCESS_NUMBER:id:number. You need the id for getStatus and setStatus. Without duration you order a one-time activation. With duration=d1, d3 or d7 the number is rented and shows up in getCurrentActivationsList until the rental ends. If the service has no such duration, the reply is BAD_SERVICE. If maxPrice is set and the rental costs more than that cap, the reply is NO_NUMBERS without the minimum price: WRONG_MAX_PRICE:price comes only for activation.
What it can answer
NO_BALANCEThe balance does not cover the order
NO_NUMBERSNo free numbers for this pair right now
BAD_COUNTRYCountry not found
BAD_SERVICEService not found
BAD_DURATIONUnknown duration value
WRONG_MAX_PRICE:PRICEThe price is above maxPrice; after the colon is the lowest price for this pair (one-time activation only)
BAD_MAX_PRICEmaxPrice is not a number or is not above zero
BAD_KEYThe key was rejected: unknown or revoked
CHANNEL_LIMITThe limit of simultaneous activations is reached
BAD_SOFTWARE_IDInvalid softId
ERROR_APIAn unexpected error on the service side

getNumberV2

key required

Order a number — the same as getNumber, but the successful reply is JSON with the price, the country and the activation time.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getNumberV2
api_keystringrequiredThe access key from your cabinet
countrystringrequiredCountry identifier, e.g. 43
servicestringrequiredService code, e.g. wa
durationstringnoOrder duration: activation — a one-time activation (default); d1, d3, d7 — rent the number for 1, 3 or 7 days
maxPricestringnoPrice ceiling per number. We will not buy above it: instead of an order you get WRONG_MAX_PRICE or NO_NUMBERS
softIdstringnoSoftware identifier, up to 255 characters
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getNumberV2&api_key=YOUR_API_KEY&country=43&service=wa
Response
{
  "activationId": 12345,
  "phoneNumber": "380991234567",
  "activationCost": 0.50,
  "currency": 840,
  "countryCode": "43",
  "canGetAnotherSms": "1",
  "activationTime": "2026-07-31 12:00:00",
  "activationOperator": "any"
}
Only the successful reply differs from getNumber. activationTime is in UTC. Refusals arrive the same way as for getNumber — as a plain text string, not JSON.
What it can answer
NO_BALANCEThe balance does not cover the order
NO_NUMBERSNo free numbers for this pair right now
BAD_COUNTRYCountry not found
BAD_SERVICEService not found
BAD_DURATIONUnknown duration value
WRONG_MAX_PRICE:PRICEThe price is above maxPrice; after the colon is the lowest price for this pair (one-time activation only)
BAD_MAX_PRICEmaxPrice is not a number or is not above zero
BAD_KEYThe key was rejected: unknown or revoked
CHANNEL_LIMITThe limit of simultaneous activations is reached
BAD_SOFTWARE_IDInvalid softId
ERROR_APIAn unexpected error on the service side

getStatus

key required

Activation status: still waiting for the code, or the code has arrived.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getStatus
api_keystringrequiredThe access key from your cabinet
idstringrequiredThe activation id from getNumber
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getStatus&api_key=YOUR_API_KEY&id=12345
Response
STATUS_OK:123456
What it can answer
STATUS_WAIT_CODEThe number is issued, no code yet
STATUS_OK:CODECode received, the SMS code is at the end
STATUS_WAIT_RETRY:CODEWaiting for the next code; the tail carries the previous one
STATUS_CANCELThe activation is already closed: cancelled or finished
NO_ACTIVATIONThe activation is unknown or already closed
BAD_KEYThe key was rejected: unknown or revoked

getCurrentActivationsList

key required

Active orders for the key: numbers that are still waiting for a code or have already received it.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: getCurrentActivationsList
api_keystringrequiredThe access key from your cabinet
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getCurrentActivationsList&api_key=YOUR_API_KEY
Response
[
  {
    "numberid": 12345,
    "number": "380991234567",
    "status": 0
  }
]
A flat JSON array. status: 0 — waiting for a code, 3 — code received; closed orders are not listed. No active orders — an empty array [].
What it can answer
BAD_KEYThe key was rejected: unknown or revoked
ERROR_APIAn unexpected error on the service side

setStatus

key required

Change the activation: ask for another code, finish it, or cancel it.

Parameters
ParameterTypeRequiredDescription
actionstringrequiredMethod name: setStatus
api_keystringrequiredThe access key from your cabinet
idstringrequiredThe activation id from getNumber
statusstringrequiredThe new state of the activation: 3, 6 or 8
Request
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=setStatus&api_key=YOUR_API_KEY&id=12345&status=6
Response
ACCESS_ACTIVATION
Finish activations explicitly: a closed order frees the slot, and a cancellation returns the money.
status values
3ask for another code on the same number
6finish the activation: the code was accepted
8cancel the activation; the money returns to your balance
What it can answer
ACCESS_ACTIVATIONThe activation is finished
ACCESS_CANCELThe activation is cancelled and the money is back
ACCESS_RETRY_GETRequest accepted: waiting for the next code on the same number
NO_ACTIVATIONThe activation is unknown or already closed
EARLY_CANCEL_DENIEDToo early to cancel — repeat the request later
BAD_STATUSNot allowed: the activation is already closed, or the code was already delivered and it cannot be cancelled
BAD_KEYThe key was rejected: unknown or revoked
ERROR_APIAn unexpected error on the service side
Common errors
BAD_ACTIONUnknown method name in action
BAD_KEYThe key was rejected: unknown or revoked
NO_BALANCEThe balance does not cover the order
NO_NUMBERSNo free numbers for this pair right now
BAD_COUNTRYCountry not found
BAD_SERVICEService not found
CHANNEL_LIMITThe limit of simultaneous activations is reached
REQUEST_LIMITRequest limit per key exceeded — wait and retry
BAD_SOFTWARE_IDInvalid softId
BAD_STATUSUnsupported status value
ERROR_APIAn unexpected error on the service side
Service codesfull list — getServicesList
waWhatsApp
tgTelegram
vkVK
goGoogle
fbFacebook
lfTikTok
igInstagram
dsDiscord
drOpenAI
aczClaude
Country codesfull list — getCountries
43Germany
15Poland
16United Kingdom
78France
86Italy
56Spain
2Kazakhstan
62Türkiye
187United States
22India
Limits
Requests per key600 per minute (≈10 per second)
Status pollingonce per 2–5 sec per activation