---
title: "SMS Activation API Guide & Documentation | SMS Activation - Receive SMS Verification Codes Online"
description: "API documentation compatible with mainstream SMS-activation protocols: check balance, fetch number prices, buy virtual numbers, and receive verification codes automatically — integrate virtual phone numbers quickly."
canonical_url: "https://www.sms-activation.net/en/api-doc"
locale: en
meta:
  keywords: "SMS activation API,sms verify API,virtual number API,receive SMS online,virtual phone number,verification code API,API integration docs"
  "og:description": "API documentation compatible with mainstream SMS-activation protocols: check balance, fetch number prices, buy virtual numbers, and receive verification codes automatically — integrate virtual phone numbers quickly."
  "og:title": "SMS Activation API Guide & Documentation | SMS Activation - Receive SMS Verification Codes Online"
---

> Index of every page on this site: [llms.txt](https://www.sms-activation.net/llms.txt)

# **SMS Activation API Guide & Documentation**

API documentation compatible with mainstream SMS-activation protocols: check balance, fetch number prices, buy virtual numbers, and receive verification codes automatically — integrate virtual phone numbers quickly.

Welcome to the **SMS-Activation API**.

This API lets your software talk directly to 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](https://www.sms-activation.net/en/api-doc) by clicking "View API Key" |
| `action` | string | Yes | The API method to call — see the [Action overview](#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 |

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://www.sms-activation.net/en#website","@type":"WebSite","inLanguage":"en-US","name":"SMS-Activation","url":"https://www.sms-activation.net/en","translationOfWork":{"@id":"https://www.sms-activation.net/#website"}},{"@id":"https://www.sms-activation.net/en/api-doc#webpage","@type":"WebPage","description":"API documentation compatible with mainstream SMS-activation protocols: check balance, fetch number prices, buy virtual numbers, and receive verification codes automatically — integrate virtual phone numbers quickly.","name":"SMS Activation API Guide & Documentation","url":"https://www.sms-activation.net/en/api-doc","isPartOf":{"@id":"https://www.sms-activation.net/en#website"},"potentialAction":[{"@type":"ReadAction","target":["https://www.sms-activation.net/en/api-doc"]}]}]}
```

## Sitemap

See the full [sitemap](https://www.sms-activation.net/sitemap.md) for all pages.