SMS Activation API Guide & Documentation | SMS Activation - Receive SMS Verification Codes Online

Welcome to the SMS-Activation API.

The API is the interaction protocol between your software and our servers, and it stays compatible with mainstream providers. All requests should be sent to https://www.sms-activation.net/stubs/handler_api.php using GET/POST. Every request must include an API key as the api_key parameter.

Overview

Item	Description
Base URL	`https://www.sms-activation.net/stubs/handler_api.php`
Request Method	`GET`/`POST`
Response Format	Text or JSON
Authentication	`api_key` parameter

All requests must carry the following two common parameters:

Parameter	Type	Required	Description
`api_key`	string	Yes	Your API key. Get it on the API documentation page by clicking "View API Key"
`action`	string	Yes	The API method to call — see the Action overview below

If api_key is invalid or missing, BAD_KEY is returned,
if action does not exist, BAD_ACTION is returned.

Action Overview

Action	Description	Response Type
`getBalance`	Check account balance	Text
`getPrices`	Fetch number prices and stock counts	JSON
`getNumber`	Buy a phone number to receive verification codes	Text
`setStatus`	Update the status of an activation order (confirm / re-request / cancel)	Text
`getActiveActivations`	Get all in-progress activation orders of the account	JSON

1. Check Balance `getBalance`

Returns the current available balance of the account.

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	API key
`action`	string	Yes	Fixed value `getBalance`

Example Request

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance"

Example Response

ACCESS_BALANCE:128.50

Possible Errors

Return Value	Description
`BAD_KEY`	Invalid `api_key`

2. Get Prices `getPrices`

Fetches the unit price and stock count of numbers for each country/service. Can be filtered by service and country.

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	API key
`action`	string	Yes	Fixed value `getPrices`
`service`	string	No	Service code, e.g. `tg` (Telegram); omit to return all services
`country`	number	No	Country code, e.g. `187` (United States); omit to return all countries

Example Request

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices&service=tg&country=187"

Example Response

{
  "187": {
    "tg": {
      "cost": 13.5,
      "count": 5000,
      "physicalCount": 4800
    }
  }
}

The response structure is { countryCode: { serviceCode: { cost, count, physicalCount } } }:

Field	Description
`cost`	Unit price of the number (CNY, already adjusted by your account tier)
`count`	Currently available stock for the country/service
`physicalCount`	Stock count of physical numbers (may be missing for some services)

3. Get Number `getNumber`

Buys a temporary phone number for receiving SMS verification codes of a given service.

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	API key
`action`	string	Yes	Fixed value `getNumber`
`service`	string	Yes	Service code, e.g. `tg`
`country`	number	Yes	Country code, e.g. `187`

Example Request

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=187"

Example Response

ACCESS_NUMBER:38223344:12015550123

The response format is ACCESS_NUMBER:{activationId}:{phoneNumber}. Keep activationId — it is required for later status queries/updates.

Possible Errors

Return Value	Description
`NO_NUMBERS`	No numbers currently available for the service/country
`NO_BALANCE`	Insufficient account balance
`BAD_SERVICE`	Invalid `service` / `country` parameter

4. Update Activation Status `setStatus`

Called after getting a number to tell the system the next step: request another SMS, confirm completion, or cancel the activation.

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	API key
`action`	string	Yes	Fixed value `setStatus`
`id`	string	Yes	The `activationId` returned by `getNumber`
`status`	number	Yes	Target status — see the table below

Status Values

`status`	Meaning
`3`	Request a repeated SMS (wait for the next verification code)
`6`	Confirm the activation is complete
`8`	Cancel this activation (not allowed within 2 minutes after purchase)

status=1 (number ready) is set automatically by the system. After calling getNumber, clients must not — and cannot — set it manually.

Example Request

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=38223344&status=6"

Example Response

ACCESS_ACTIVATION

Possible Errors

Return Value	Description
`BAD_STATUS`	`status` value is outside the allowed range
`WRONG_ACTIVATION_ID`	`id` does not exist or belongs to another account
`EARLY_CANCEL_DENIED`	Cancellation (`status=8`) attempted within 2 minutes of purchase

5. Get Active Activations `getActiveActivations`

Returns details of all activations of the current account that have not finished yet (not confirmed / not cancelled).

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	API key
`action`	string	Yes	Fixed value `getActiveActivations`

Example Request

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getActiveActivations"

Example Response

[
  {
    "activationId": "38223344",
    "phoneNumber": "12015550123",
    "countryCode": 187,
    "countryName": "United States",
    "countryNameCN": "美国",
    "serviceCode": "tg",
    "serviceNameCN": "Telegram",
    "activationStatus": 2,
    "status": 0,
    "activationCost": 13.5,
    "price_cn": 13.5,
    "activationTime": "2026-06-27T08:00:00.000Z",
    "canGetAnotherSms": true,
    "activationOperator": "",
    "discount": "",
    "repeated": "",
    "smsCode": ["123456"],
    "smsText": ["Your Telegram code: 123456"]
  }
]

Field Description

Field	Description
`activationId`	Activation order ID
`phoneNumber`	Assigned phone number
`countryCode` / `countryName`	Country code / country name
`serviceCode` / `serviceNameCN`	Service code / service name
`activationCost` / `price_cn`	Order price
`smsCode`	List of verification codes received
`smsText`	List of full SMS texts received
`canGetAnotherSms`	Whether another SMS can be requested

Error Codes

Error Code	Description
`BAD_KEY`	Invalid `api_key`
`BAD_ACTION`	Invalid `action` parameter
`BAD_SERVICE`	Invalid `service` or `country` parameter
`BAD_STATUS`	Invalid `status` parameter
`NO_NUMBERS`	No numbers currently available for the service/country
`NO_BALANCE`	Insufficient account balance
`WRONG_ACTIVATION_ID`	Activation order ID does not exist or belongs to another account
`EARLY_CANCEL_DENIED`	Cancellation attempted within 2 minutes of purchase