SIM Aggregator API - Documentation

Registration and API key

To use the API you must:

1. Register an account at sim-aggregator.com.
2. Obtain an API key in your profile settings (account settings section).

The API key grants access to paid operations (ordering numbers, checking status, etc.). Keep your key secret and do not share it with third parties.

Base URL

All API requests are sent to the endpoint:

https://api.sim-aggregator.com/stubs/handler_api.php

The GET method is supported. The method name is passed in the action parameter.

getPrices

Get current prices and the number of available activations by country and service.

Request: does not require an API key.

Parameters

Example request

https://api.sim-aggregator.com/stubs/handler_api.php?action=getPrices

Response (JSON)

Structure: { "Country_Code": { "Service_Code": { "cost": "Price", "count": Quantity } } }

{
  "1": {
    "wa": { "cost": "0.50", "count": 100 },
    "tg": { "cost": "0.71", "count": 250 }
  },
  "0": {
    "wa": { "cost": "0.45", "count": 50 }
  }
}

getCountries

Returns the list of supported countries with identifiers and names (Russian, English, Chinese).

Request: does not require an API key.

Parameters

Example request

https://api.sim-aggregator.com/stubs/handler_api.php?action=getCountries

Response (JSON)

Object: country ID → { id, rus, eng, zh, visible, retry, rent, multiService }.

{
  "43": { "id": 43, "rus": "Германия", "eng": "Germany", "zh": "德国", "visible": 1, "retry": 1, "rent": 0, "multiService": 0 },
  "15": { "id": 15, "rus": "Польша", "eng": "Poland", "zh": "波兰", "visible": 1, "retry": 1, "rent": 0, "multiService": 0 }
}

getServicesList

Returns the list of services with code and display name.

Request: does not require an API key.

Parameters

Example request

https://api.sim-aggregator.com/stubs/handler_api.php?action=getServicesList

Response (JSON)

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

getBalance

Returns the current account balance.

Parameters

Example request

https://api.sim-aggregator.com/stubs/handler_api.php?action=getBalance&key=YOUR_API_KEY

Success response (text)

ACCESS_BALANCE:12.50

Format: ACCESS_BALANCE: balance amount (decimal).

Possible errors

getNumber

Order a number for receiving SMS.

Parameters

Example request

https://api.sim-aggregator.com/stubs/handler_api.php?action=getNumber&key=YOUR_API_KEY&country=43&service=wa

Success response (text)

ACCESS_NUMBER:12345:380991234567

Format: ACCESS_NUMBER: Activation ID : phone number with country code.

Possible errors

setStatus

Change order status (request another SMS, finish or cancel activation).

Parameters

status values

Example request

https://api.sim-aggregator.com/stubs/handler_api.php?action=setStatus&key=YOUR_API_KEY&activationId=12345&status=6

Responses

getStatus

Check current order status (whether SMS and code have been received).

Parameters

Example request

https://api.sim-aggregator.com/stubs/handler_api.php?action=getStatus&key=YOUR_API_KEY&activationId=12345

Responses

Example success response with code

STATUS_OK:123456

Common errors

Methods summary

Country codes and the list of services are available on the website or from the getPrices, getCountries, getServicesList response.

Country codes

Use the country parameter in API requests with the following numeric IDs. This list matches CountryMap in the API.

Service codes

Use the service code to order the required service