VirtualSMS

https://virtualsms.de/
Admin
VirtualSMS is an SMS activation API service that provides virtual phone numbers for receiving SMS...
Tokens:15,395
Snippets:114
Trust Score:2.1
Update:1 month ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Support is available on Telegram at @virtualsms_bot

================
CODE SNIPPETS
================
### Get Prices Response

Source: https://virtualsms.de/docs/mcp

Example JSON response for the get_prices tool.

```json
{
  "cost": "1.20",
  "count": "552279"
}
```

--------------------------------

### Get Services List API Examples

Source: https://virtualsms.de/docs

Retrieves a list of available services for a specific country.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getServicesList&country=39&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getServicesList&country=39&api_key=YOUR_API_KEY'
);
const { services } = await response.json();
services.forEach(s => console.log(`${s.code}: ${s.name}`));
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getServicesList&country=39&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['services'] as $service) {
    echo "{$service['code']}: {$service['name']}" . PHP_EOL;
}
```

--------------------------------

### Get Account Balance Response

Source: https://virtualsms.de/docs/mcp

Example JSON response for the get_balance tool.

```json
{ "balance": 22.92 }
```

--------------------------------

### Get Countries API Examples

Source: https://virtualsms.de/docs

Retrieves a list of all available countries supported by the platform.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getCountries&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getCountries&api_key=YOUR_API_KEY'
);
const countries = await response.json();
Object.values(countries).forEach(country => {
  console.log(country.eng);
});
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getCountries&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$countries = json_decode($response, true);
foreach ($countries as $country) {
    echo $country['eng'] . PHP_EOL;
}
```

--------------------------------

### Install VirtualSMS SDK

Source: https://virtualsms.de/docs/sdk

Commands to install the VirtualSMS SDK package for each supported language.

```bash
npm install @virtualsmslabs/js-sdk
```

```bash
pip install virtualsmslabs-python-sdk
```

```bash
composer require virtualsmslabs/php-sdk
```

--------------------------------

### Natural Language Workflow Example

Source: https://virtualsms.de/docs/mcp

An example of how an AI assistant interprets a user request to perform the SMS verification workflow.

```text
You: "Order a WhatsApp number in Brazil, then wait for the SMS code"

AI: I'll order a WhatsApp number in Brazil for you.
    [calls order_number(service="wa", country="73")]
    → Got number +5511999999999 (activation #12345)

AI: Now setting it to ready and checking for the SMS code.
    [calls set_activation_status(id=12345, status="1")]
    [calls get_activation_status(id=12345)]
    → STATUS_OK:123456

AI: Your WhatsApp verification code is 123456.
    I've finished the activation.
```

--------------------------------

### Get Operators API Examples

Source: https://virtualsms.de/docs

Retrieves a list of available operators for a specific country, requiring a country ID.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getOperators&country=73&poolProvider=gamma&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getOperators&country=73&poolProvider=gamma&api_key=YOUR_API_KEY'
);
const { countryOperators } = await response.json();
countryOperators.forEach(op => console.log(op));
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getOperators&country=73&poolProvider=gamma&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['countryOperators'] as $operator) {
    echo $operator . PHP_EOL;
}
```

--------------------------------

### Get Notifications Response

Source: https://virtualsms.de/docs/mcp

Example JSON response for the get_notifications tool.

```json
{
  "status": "success",
  "unreadCount": 1,
  "notifications": [
    { "id": 1, "type": "low_balance", "title": "Low Balance" }
  ]
}
```

--------------------------------

### GET ?action=getStatus

Source: https://virtualsms.de/docs

Get the current status of an activation in text format.

```APIDOC
## GET /stubs/handler_api?action=getStatus

### Description
Get current status of an activation as a text response.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getStatus'
- **id** (string) - Required - Activation ID
- **api_key** (string) - Required - API authentication key

### Response
#### Success Response (200)
- **Response** (string) - Returns status strings like STATUS_WAIT_CODE, STATUS_WAIT_RETRY, STATUS_OK:{CODE}, or STATUS_CANCEL.
```

--------------------------------

### Run the MCP Server

Source: https://virtualsms.de/docs/mcp

Execute the MCP server using npx without requiring a global installation.

```bash
npx -y @virtualsmslabs/mcp
```

--------------------------------

### GET ?action=getStatusV2

Source: https://virtualsms.de/docs

Get the current status of an activation in JSON format.

```APIDOC
## GET /stubs/handler_api?action=getStatusV2

### Description
Get current status of an activation as a JSON object.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getStatusV2'
- **id** (string) - Required - Activation ID
- **api_key** (string) - Required - API authentication key

### Response
#### Success Response (200)
- **status** (string) - The current status
- **code** (string) - The SMS code if available

#### Response Example
{
  "status": "STATUS_OK",
  "code": "123456"
}
```

--------------------------------

### Order Number Implementation

Source: https://virtualsms.de/docs

Examples for purchasing a virtual number using the legacy API endpoint.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getNumber&service=tg&country=39&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getNumber&service=tg&country=39&api_key=YOUR_API_KEY'
);
const data = await response.text();
// Parse: ACCESS_NUMBER:12345:1234567890
const [status, id, phone] = data.split(':');
if (status === 'ACCESS_NUMBER') {
  console.log(`Activation ID: ${id}, Phone: ${phone}`);
}
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getNumber&service=tg&country=39&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

// Parse: ACCESS_NUMBER:12345:1234567890
[$status, $id, $phone] = explode(':', $response);
if ($status === 'ACCESS_NUMBER') {
    echo "Activation ID: {$id}, Phone: {$phone}";
}
```

--------------------------------

### GET ?action=getServicesList

Source: https://virtualsms.de/docs

Retrieves a list of available services for a specific country.

```APIDOC
## GET /stubs/handler_api?action=getServicesList

### Description
Get list of available services for a specific country.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getServicesList'
- **country** (string) - Optional - Country ID
- **api_key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **status** (string) - Success status
- **services** (array) - List of available services

#### Response Example
{
  "status": "success",
  "services": [
    {
      "code": "tg",
      "name": "Telegram"
    }
  ]
}
```

--------------------------------

### Get Numbers Status API Examples

Source: https://virtualsms.de/docs

Retrieves the quantity of available numbers for services, optionally filtered by country, operator, or provider.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getNumbersStatus&country=39&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getNumbersStatus&country=39&api_key=YOUR_API_KEY'
);
const data = await response.json();
console.log(data.tg_39); // 150
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getNumbersStatus&country=39&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['tg_39']; // 150
```

--------------------------------

### Verify Node.js Version

Source: https://virtualsms.de/docs/mcp

Check the installed Node.js version to ensure compatibility with the MCP server requirements.

```bash
node --version
# v18.x.x or higher required
```

--------------------------------

### Retrieve Top Countries by Service

Source: https://virtualsms.de/docs

Examples for fetching top countries for a service using cURL, JavaScript, and PHP.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getListOfTopCountriesByService&service=wa&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getListOfTopCountriesByService&service=wa&api_key=YOUR_API_KEY'
);
const topCountries = await response.json();
topCountries.forEach(item => {
  console.log(`Country ${item.country}: ${item.share}% share, ${item.rate}% success`);
});
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getListOfTopCountriesByService&service=wa&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$topCountries = json_decode($response, true);
foreach ($topCountries as $item) {
    echo "Country {$item['country']}: {$item['share']}% share, {$item['rate']}% success" . PHP_EOL;
}
```

--------------------------------

### GET ?action=getCountries

Source: https://virtualsms.de/docs

Retrieves a list of all available countries and their configuration settings.

```APIDOC
## GET /stubs/handler_api?action=getCountries

### Description
Get list of available countries.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getCountries'
- **api_key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **id** (integer) - Country ID
- **rus/eng/chn** (string) - Country name in different languages
- **visible** (integer) - Visibility status
- **retry** (integer) - Retry support flag
- **rent** (integer) - Rent support flag
- **multiService** (integer) - Multi-service support flag

#### Response Example
{
  "39": {
    "id": 39,
    "rus": "Argentina",
    "eng": "Argentina",
    "chn": "Argentina",
    "visible": 1,
    "retry": 1,
    "rent": 1,
    "multiService": 1
  }
}
```

--------------------------------

### Balance API Responses

Source: https://virtualsms.de/docs

Example responses for successful and failed balance retrieval requests.

```text
ACCESS_BALANCE:10.50
```

```text
BAD_KEY
ERROR_SQL
```

--------------------------------

### Order Number Response

Source: https://virtualsms.de/docs/mcp

Example JSON response for the order_number tool.

```json
{
  "activationId": 12345,
  "phoneNumber": "5511999999999"
}
```

--------------------------------

### GET ?action=getExtraActivation

Source: https://virtualsms.de/docs

Creates an extra/additional activation on a previously used number.

```APIDOC
## GET /stubs/handler_api?action=getExtraActivation

### Description
Create an extra/additional activation on a previously used number.

### Method
GET

### Endpoint
/stubs/handler_api?action=getExtraActivation

### Parameters
#### Query Parameters
- **id** (string) - Required - Original activation ID.
- **api_key** (string) - Required - Your API authentication key.

### Response
#### Success Response (200)
- **Response** (string) - Returns a string in the format ACCESS_NUMBER:{ID}:{PHONE}.
```

--------------------------------

### GET ?action=setStatus

Source: https://virtualsms.de/docs

Change the activation status for a specific activation ID.

```APIDOC
## GET /stubs/handler_api?action=setStatus

### Description
Change activation status for a given activation ID.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'setStatus'
- **id** (string) - Required - Activation ID
- **status** (integer) - Required - Status code (1: Ready, 3: Retry, 6: Finish, 8: Cancel)
- **api_key** (string) - Required - API authentication key

### Response
#### Success Response (200)
- **Response** (string) - Returns status strings like ACCESS_READY, ACCESS_ACTIVATION, or ACCESS_CANCEL.
```

--------------------------------

### GET ?action=getPricesExtended

Source: https://virtualsms.de/docs

Retrieves extended pricing information including price tiers (freePriceMap).

```APIDOC
## GET /stubs/handler_api?action=getPricesExtended

### Description
Get extended prices with price tiers (freePriceMap).

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getPricesExtended'
- **service** (string) - Optional - Service code (e.g., 'wa')
- **country** (string) - Optional - Country ID
- **freePrice** (boolean) - Optional - If true, shows only lowest price tier
- **poolProvider** (string) - Optional - Provider alias (e.g. 'alpha')
- **api_key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **countryId** (object) - Structure: countryId -> serviceCode -> {cnt, physicalCount, freePriceMap, cost}
```

--------------------------------

### GET ?action=getPricesVerification

Source: https://virtualsms.de/docs

Retrieves prices organized by service then country (inverted structure).

```APIDOC
## GET /stubs/handler_api?action=getPricesVerification

### Description
Get prices organized by service then country (inverted structure).

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getPricesVerification'
- **service** (string) - Optional - Service code (e.g., 'wa')
- **poolProvider** (string) - Optional - Provider alias (e.g. 'alpha')
- **api_key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **serviceCode** (object) - Structure: service -> country -> {count, price}
```

--------------------------------

### Order Number V2 Implementation

Source: https://virtualsms.de/docs

Examples for purchasing a virtual number using the V2 JSON API endpoint.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getNumberV2&service=tg&country=39&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getNumberV2&service=tg&country=39&api_key=YOUR_API_KEY'
);
const data = await response.json();
console.log(`ID: ${data.activationId}`);
console.log(`Phone: ${data.phoneNumber}`);
console.log(`Cost: $${data.activationCost}`);
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getNumberV2&service=tg&country=39&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "ID: {$data['activationId']}" . PHP_EOL;
echo "Phone: {$data['phoneNumber']}" . PHP_EOL;
echo "Cost: "."{$data['activationCost']}";
```

--------------------------------

### GET ?action=getBalance

Source: https://virtualsms.de/docs

Retrieves the current account balance for the authenticated user.

```APIDOC
## GET ?action=getBalance

### Description
Get current account balance.

### Method
GET

### Endpoint
https://api.virtualsms.de/stubs/handler_api?action=getBalance

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your unique API authentication key.

### Response
#### Success Response (200)
- **ACCESS_BALANCE** (string) - The current balance in the format 'ACCESS_BALANCE:value'.

#### Response Example
ACCESS_BALANCE:10.50
```

--------------------------------

### GET ?action=getPrices

Source: https://virtualsms.de/docs

Retrieves current prices for services, organized by country ID and service code.

```APIDOC
## GET /stubs/handler_api?action=getPrices

### Description
Get current prices for services.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getPrices'
- **service** (string) - Optional - Service code (e.g., 'wa')
- **country** (string) - Optional - Country ID
- **poolProvider** (string) - Optional - Provider alias (e.g. 'alpha')
- **api_key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **countryId** (object) - Structure: countryId -> serviceCode -> {cost, count}
```

--------------------------------

### GET ?action=getOperators

Source: https://virtualsms.de/docs

Retrieves a list of available operators for a specific country and provider.

```APIDOC
## GET /stubs/handler_api?action=getOperators

### Description
Get list of available operators for a specific country.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getOperators'
- **country** (string) - Required - Country ID
- **poolProvider** (string) - Optional - Provider alias
- **api_key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **status** (string) - Success status
- **countryOperators** (array) - List of operator names

#### Response Example
{
  "status": "success",
  "countryOperators": ["any", "claro", "vivo"]
}
```

--------------------------------

### Fetch Notifications via API

Source: https://virtualsms.de/docs

Examples for retrieving notifications using cURL, JavaScript Fetch, and PHP cURL.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getNotifications&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getNotifications&api_key=YOUR_API_KEY'
);
const { notifications, unreadCount } = await response.json();
console.log(`Unread: ${unreadCount}`);
notifications.forEach(n => {
  console.log(`[${n.type}] ${n.title}`);
});
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getNotifications&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Unread: {$data['unreadCount']}" . PHP_EOL;
foreach ($data['notifications'] as $n) {
    echo "[{$n['type']}] {$n['title']}" . PHP_EOL;
}
```

--------------------------------

### GET ?action=checkExtraActivation

Source: https://virtualsms.de/docs

Checks if a specific number is available for an additional activation.

```APIDOC
## GET /stubs/handler_api?action=checkExtraActivation

### Description
Check if a number is available for extra/additional activation.

### Method
GET

### Endpoint
/stubs/handler_api?action=checkExtraActivation

### Parameters
#### Query Parameters
- **id** (string) - Required - Original activation ID.
- **api_key** (string) - Required - Your API authentication key.

### Response
#### Success Response (200)
- **status** (string) - Status of the request.
- **cost** (integer) - Cost of the extra activation.
- **service** (string) - Service code.
- **phone** (integer) - Phone number.
- **country** (integer) - Country ID.
```

--------------------------------

### GET ?action=getActiveActivations

Source: https://virtualsms.de/docs

Retrieves a list of all currently active SMS activations.

```APIDOC
## GET /stubs/handler_api?action=getActiveActivations

### Description
Get list of current active activations.

### Method
GET

### Endpoint
/stubs/handler_api?action=getActiveActivations

### Query Parameters
- **api_key** (string) - Required - Your API authentication key.

### Response
#### Success Response (200)
- **status** (string) - Status of the request.
- **activeActivations** (array) - List of active activation objects.
```

--------------------------------

### Get Activation Status (Text)

Source: https://virtualsms.de/docs

Retrieve the current status of an activation as a plain text string.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getStatus&id=12345&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getStatus&id=12345&api_key=YOUR_API_KEY'
);
const data = await response.text();
if (data.startsWith('STATUS_OK')) {
  const code = data.split(':')[1];
  console.log(`SMS Code: ${code}`);
} else if (data === 'STATUS_WAIT_CODE') {
  console.log('Waiting for SMS...');
}
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getStatus&id=12345&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

if (str_starts_with($response, 'STATUS_OK')) {
    $code = explode(':', $response)[1];
    echo "SMS Code: {$code}";
} elseif ($response === 'STATUS_WAIT_CODE') {
    echo 'Waiting for SMS...';
}
```

--------------------------------

### GET ?action=getListOfTopCountriesByService

Source: https://virtualsms.de/docs

Retrieves the top 10 countries for a specific service, including purchase share and success rate metrics based on platform-wide activation data.

```APIDOC
## GET /stubs/handler_api?action=getListOfTopCountriesByService

### Description
Get top 10 countries for a specific service with purchase share and success rate metrics.

### Method
GET

### Endpoint
/stubs/handler_api?action=getListOfTopCountriesByService

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be set to 'getListOfTopCountriesByService'
- **service** (string) - Required - Service code (e.g., 'tg', 'wa')
- **api_key** (string) - Required - Your API authentication key

### Response
#### Success Response (200)
- **country** (string) - Country identifier
- **share** (string) - Percentage of service purchases in this country
- **rate** (string) - Success rate percentage

#### Response Example
[
  {
    "country": "6",
    "share": "29.74",
    "rate": "61.73"
  },
  {
    "country": "73",
    "share": "15.22",
    "rate": "85.40"
  }
]
```

--------------------------------

### GET ?action=getNumber

Source: https://virtualsms.de/docs

Purchase a virtual number for SMS verification with a text-based response format.

```APIDOC
## GET ?action=getNumber

### Description
Purchase a virtual number for SMS verification. Returns a string in the format ACCESS_NUMBER:{ID}:{PHONE}.

### Method
GET

### Endpoint
https://api.virtualsms.de/stubs/handler_api?action=getNumber

### Parameters
#### Query Parameters
- **service** (string) - Required - Service code (e.g., tg).
- **country** (integer) - Required - Country ID (e.g., 0).
- **maxPrice** (float) - Optional - Max price willing to pay.
- **operator** (string) - Optional - Mobile operator filter.
- **phoneException** (string) - Optional - Phone prefixes to exclude (comma-separated).
- **forward** (integer) - Optional - Enable call forwarding (0 or 1).
- **activationType** (integer) - Optional - Type: 0=SMS, 1=number, 2=voice.
- **language** (string) - Optional - Language for voice activation.
- **useCashBack** (boolean) - Optional - Use cashback balance first.
- **userId** (string) - Optional - End-user ID for statistics/blocking.
- **ref** (string) - Optional - Referral ID for tracking.
- **poolProvider** (string) - Optional - Provider alias (e.g. alpha, gamma).

### Response
#### Success Response (200)
- **Response** (string) - ACCESS_NUMBER:{ID}:{PHONE}
```

--------------------------------

### Get Activation Status (JSON)

Source: https://virtualsms.de/docs

Retrieve the current status of an activation as a JSON object.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getStatusV2&id=12345&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getStatusV2&id=12345&api_key=YOUR_API_KEY'
);
const { status, code } = await response.json();
if (status === 'STATUS_OK') {
  console.log(`SMS Code: ${code}`);
}
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getStatusV2&id=12345&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if ($data['status'] === 'STATUS_OK') {
    echo "SMS Code: {$data['code']}";
}
```

--------------------------------

### GET ?action=getNumberV2

Source: https://virtualsms.de/docs

Purchase a virtual number for SMS verification with a JSON response format.

```APIDOC
## GET ?action=getNumberV2

### Description
Purchase a virtual number for SMS verification. Returns a JSON object containing activation details.

### Method
GET

### Endpoint
https://api.virtualsms.de/stubs/handler_api?action=getNumberV2

### Parameters
#### Query Parameters
- **service** (string) - Required - Service code.
- **country** (integer) - Required - Country ID.
- **maxPrice** (float) - Optional - Max price willing to pay.
- **operator** (string) - Optional - Mobile operator filter.
- **phoneException** (string) - Optional - Phone prefixes to exclude (comma-separated).
- **forward** (integer) - Optional - Enable call forwarding (0 or 1).
- **activationType** (integer) - Optional - Type: 0=SMS, 1=number, 2=voice.
- **language** (string) - Optional - Language for voice activation.
- **useCashBack** (boolean) - Optional - Use cashback balance first.
- **userId** (string) - Optional - End-user ID for statistics/blocking.
- **ref** (string) - Optional - Referral ID for tracking.
- **orderId** (string) - Optional - Order ID for idempotency.
- **poolProvider** (string) - Optional - Provider alias (e.g. alpha, gamma).

### Response
#### Success Response (200)
- **activationId** (integer) - The ID of the activation.
- **phoneNumber** (string) - The purchased phone number.
- **activationCost** (float) - The cost of the activation.
- **countryCode** (string) - The country code.
- **canGetAnotherSms** (boolean) - Whether another SMS can be received.
- **activationTime** (string) - The timestamp of the activation.
```

--------------------------------

### GET ?action=getNotifications

Source: https://virtualsms.de/docs

Retrieves a list of user notifications including penalties, low balance alerts, and other system messages.

```APIDOC
## GET ?action=getNotifications

### Description
Get user notifications (penalties, low balance alerts, etc).

### Method
GET

### Endpoint
https://api.virtualsms.de/stubs/handler_api?action=getNotifications

### Query Parameters
- **api_key** (string) - Required - Your API authentication key.

### Response
#### Success Response (200)
- **status** (string) - The status of the request.
- **notifications** (array) - List of notification objects.
- **unreadCount** (integer) - Total count of unread notifications.

#### Response Example
{
  "status": "success",
  "notifications": [
    {
      "id": 1,
      "type": "penalty",
      "title": "Cancellation Penalty",
      "content": "A 5% penalty...",
      "read": false,
      "createdAt": "2023-..."
    }
  ],
  "unreadCount": 1
}
```

--------------------------------

### GET ?action=getNumbersStatus

Source: https://virtualsms.de/docs

Retrieves the quantity of available numbers for various services, optionally filtered by country, operator, or provider.

```APIDOC
## GET /stubs/handler_api?action=getNumbersStatus

### Description
Get quantity of available numbers for services.

### Method
GET

### Endpoint
/stubs/handler_api

### Parameters
#### Query Parameters
- **action** (string) - Required - Must be 'getNumbersStatus'
- **country** (string) - Optional - Country ID
- **operator** (string) - Optional - Filter by operator
- **poolProvider** (string) - Optional - Provider alias
- **api_key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **{service}_{country}** (integer) - Count of available numbers

#### Response Example
{
  "tg_39": 150,
  "wa_39": 50,
  "go_39": 200
}
```

--------------------------------

### Initialize VirtualSMS Client

Source: https://virtualsms.de/docs/sdk

Import and initialize the client using your API key and the base API URL.

```javascript
import { VirtualSMSClient } from "@virtualsmslabs/js-sdk";

const client = new VirtualSMSClient("YOUR_API_KEY", "https://api.virtualsms.de");
```

```python
from virtualsms import VirtualSMSClient

client = VirtualSMSClient("YOUR_API_KEY", "https://api.virtualsms.de")
```

```php
require_once 'vendor/autoload.php';

use VirtualSMS\VirtualSMSClient;

$client = new VirtualSMSClient('YOUR_API_KEY', 'https://api.virtualsms.de');
```

--------------------------------

### SDK Method Reference

Source: https://virtualsms.de/docs/sdk

A comprehensive list of available SDK methods mapped to their respective API actions.

```APIDOC
## SDK Methods

### Account
- `get_balance()` / `getBalance()`: Returns `BalanceResponse` with account balance.

### Information & Pricing
- `get_countries()` / `getCountries()`: Returns available countries.
- `get_services_list()` / `getServicesList()`: Returns services for a country.
- `get_operators()` / `getOperators()`: Returns mobile operators for a country.
- `get_prices()` / `getPrices()`: Returns pricing data (country → service).
- `get_prices_extended()` / `getPricesExtended()`: Returns pricing with price tiers.
- `get_prices_verification()` / `getPricesVerification()`: Returns pricing in inverted format (service → country).
- `get_numbers_status()` / `getNumbersStatus()`: Returns available phone quantity per service.
- `get_top_countries_by_service()` / `getTopCountriesByService()`: Returns top 10 countries for a service.

### Ordering
- `get_number()` / `getNumber()`: Orders a phone number — returns `NumberResponse`.
- `get_number_v2()` / `getNumberV2()`: Orders with JSON response + idempotency support.

### Activation Management
- `set_status()` / `setStatus()`: Changes activation status (Ready, Retry, Complete, Cancel).
- `get_status()` / `getStatus()`: Returns `StatusResponse` with status and SMS code.
- `get_status_v2()` / `getStatusV2()`: Returns JSON status with SMS/call details.
- `get_active_activations()` / `getActiveActivations()`: Returns all currently active activations.
- `check_extra_activation()` / `checkExtraActivation()`: Checks if a number is available for reactivation.
- `get_extra_activation()` / `getExtraActivation()`: Creates extra activation on a used number.

### Notifications
- `get_notifications()` / `getNotifications()`: Returns user notifications and unread count.
```

--------------------------------

### Custom Transport Implementation

Source: https://virtualsms.de/docs/sdk

Demonstrates how to implement a custom transport class and inject it into the VirtualSMSClient constructor for JavaScript, Python, and PHP.

```APIDOC
## Custom Transport Implementation

### Description
Developers can provide a custom transport implementation to the `VirtualSMSClient` to override the default HTTP client behavior. This is achieved by implementing the `Transport` interface (or equivalent) and passing an instance to the client constructor.

### Usage
- **JavaScript**: Implement `Transport` interface with an `async send(url, headers)` method.
- **Python**: Inherit from `Transport` and implement `send(self, url: str, headers: dict) -> Response`.
- **PHP**: Implement `TransportInterface` with a `send(string $url, array $headers = []): Response` method.

### Constructor Signature
`new VirtualSMSClient(apiKey: string, baseUrl: string, transport: Transport)`
```

--------------------------------

### Configure Claude Desktop MCP

Source: https://virtualsms.de/docs/mcp

Edit the configuration file with the literal API key, as environment variable expansion is not supported.

```json
{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["-y", "@virtualsmslabs/mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Verify with MCP Inspector

Source: https://virtualsms.de/docs/mcp

Use the MCP inspector tool to test and debug the server connection.

```bash
npx @modelcontextprotocol/inspector npx -y @virtualsmslabs/mcp
```

--------------------------------

### Configure OpenCode MCP

Source: https://virtualsms.de/docs/mcp

Uses specific syntax for environment variables and requires an array for the command field.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "virtualsms": {
      "type": "local",
      "command": ["npx", "-y", "@virtualsmslabs/mcp"],
      "enabled": true,
      "environment": {
        "VIRTUALSMS_API_KEY": "{env:VIRTUALSMS_API_KEY}"
      },
      "timeout": 10000
    }
  }
}
```

--------------------------------

### Configure VS Code MCP

Source: https://virtualsms.de/docs/mcp

Uses inputs for secure credential prompting stored in the OS credential store.

```json
{
  "servers": {
    "virtualsms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@virtualsmslabs/mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "${input:virtualsmsApiKey}"
      }
    }
  },
  "inputs": [
    {
      "id": "virtualsmsApiKey",
      "type": "promptString",
      "description": "VirtualSMS API Key",
      "password": true
    }
  ]
}
```

--------------------------------

### Configure Cursor MCP

Source: https://virtualsms.de/docs/mcp

Supports environment variable expansion and external .env files.

```json
{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["-y", "@virtualsmslabs/mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "${env:VIRTUALSMS_API_KEY}"
      },
      "envFile": "${workspaceFolder}/.env"
    }
  }
}
```

--------------------------------

### Configure Cline MCP

Source: https://virtualsms.de/docs/mcp

Requires the literal API key and allows pre-approval of tools via the autoApprove array.

```json
{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["-y", "@virtualsmslabs/mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

--------------------------------

### Catch Specific API Errors

Source: https://virtualsms.de/docs/sdk

Demonstrates how to catch and handle specific SDK exceptions using try-catch blocks in different programming languages.

```javascript
import {
  VirtualSMSClient,
  AuthenticationException,
  InsufficientBalanceException,
  NoNumbersException,
  RateLimitException,
} from "@virtualsmslabs/js-sdk";

try {
  const number = await client.getNumber("wa", 73);
} catch (e) {
  if (e instanceof InsufficientBalanceException) {
    // Top up balance
  } else if (e instanceof NoNumbersException) {
    // Try different service or country
  } else if (e instanceof RateLimitException) {
    // Wait e.retryAfter seconds
  } else if (e instanceof AuthenticationException) {
    // Check API key or account status
  }
}
```

```python
from virtualsms import (
    VirtualSMSClient,
    AuthenticationException,
    InsufficientBalanceException,
    NoNumbersException,
    RateLimitException,
)

try:
    number = client.get_number("wa", 73)
except InsufficientBalanceException:
    # Top up balance
    pass
except NoNumbersException:
    # Try different service or country
    pass
except RateLimitException as e:
    # Wait e.retry_after seconds
    pass
except AuthenticationException:
    # Check API key or account status
    pass
```

```php
use VirtualSMS\Exceptions\AuthenticationException;
use VirtualSMS\Exceptions\InsufficientBalanceException;
use VirtualSMS\Exceptions\NoNumbersException;
use VirtualSMS\Exceptions\RateLimitException;

try {
    $number = $client->getNumber('wa', 73);
} catch (InsufficientBalanceException $e) {
    // Top up balance
} catch (NoNumbersException $e) {
    // Try different service or country
} catch (RateLimitException $e) {
    // Wait $e->retryAfter seconds
} catch (AuthenticationException $e) {
    // Check API key or account status
}
```

--------------------------------

### Handling Typed Exceptions

Source: https://virtualsms.de/docs/sdk

This section demonstrates how to catch specific exceptions such as InsufficientBalanceException, NoNumbersException, RateLimitException, and AuthenticationException when calling SDK methods.

```APIDOC
## Error Handling

### Description
The SDK provides typed exceptions for various API error scenarios. Developers should catch these specific classes to implement appropriate recovery logic.

### Exception Mapping
- **AuthenticationException**: BAD_KEY, BANNED, PURCHASE_RESTRICTED, SERVICE_RESTRICTED
- **InsufficientBalanceException**: NO_BALANCE
- **NoNumbersException**: NO_NUMBERS
- **ValidationException**: WRONG_SERVICE, WRONG_COUNTRY, BAD_ACTION, BAD_STATUS, NO_PRICES, INVALID_PROVIDER
- **ActivationException**: NO_ACTIVATION, WRONG_ACTIVATION_ID, EARLY_CANCEL_DENIED, RENEW_ACTIVATION_NOT_AVAILABLE
- **RateLimitException**: CONCURRENT_LIMIT (includes `retry_after` property)
- **ServerException**: ERROR_SQL, unknown errors
```

--------------------------------

### Configure Claude Code MCP

Source: https://virtualsms.de/docs/mcp

Use the CLI to register the server or manually edit the .mcp.json configuration file.

```bash
claude mcp add virtualsms \
  --env VIRTUALSMS_API_KEY=your_api_key_here \
  -- npx -y @virtualsmslabs/mcp
```

```json
{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["-y", "@virtualsmslabs/mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "${VIRTUALSMS_API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Access Placeholder Logo

Source: https://virtualsms.de/docs/assets

Use this URL for services that do not have a dedicated logo available in the assets kit.

```text
https://raw.githubusercontent.com/VirtualSMSLabs/assets-kit/refs/heads/main/app_logos/coming_soon.webp
```

--------------------------------

### get_prices

Source: https://virtualsms.de/docs/mcp

Retrieves pricing and availability for a specific service and country.

```APIDOC
## get_prices

### Description
Checks price and availability for a given service and country code.

### Parameters
- **service** (string) - Required - The service code (e.g., "wa" for WhatsApp).
- **country** (string) - Required - The country ID.
```

--------------------------------

### Access Service Logos via CDN

Source: https://virtualsms.de/docs/assets

Construct a direct URL to a service logo by replacing the placeholder with the service's standardCode.

```text
https://raw.githubusercontent.com/VirtualSMSLabs/assets-kit/refs/heads/main/app_logos/{standardCode}.webp
```

--------------------------------

### Check Account Balance

Source: https://virtualsms.de/docs/sdk

Verify the current account balance using the VirtualSMS client. Requires a valid API key.

```javascript
import { VirtualSMSClient, VirtualSMSException } from "@virtualsmslabs/js-sdk";

const client = new VirtualSMSClient("YOUR_API_KEY");

try {
  const balance = await client.getBalance();
  console.log(`Balance: $${balance.balance.toFixed(2)}`);
} catch (e) {
  console.log(`Error: ${e.message} (code: ${e.errorCode})`);
}
```

```python
from virtualsms import VirtualSMSClient
from virtualsms.exceptions import VirtualSMSException

client = VirtualSMSClient("YOUR_API_KEY")

try:
    balance = client.get_balance()
    print(f"Balance: ${balance.balance:.2f}")
except VirtualSMSException as e:
    print(f"Error: {e} (code: {e.error_code})")
```

```php
use VirtualSMS\VirtualSMSClient;
use VirtualSMS\Exceptions\VirtualSMSException;

$client = new VirtualSMSClient('YOUR_API_KEY');

try {
    $balance = $client->getBalance();
    echo "Balance: $" . number_format($balance->balance, 2) . PHP_EOL;
} catch (VirtualSMSException $e) {
    echo "Error: " . $e->getMessage() . " ({$e->errorCode})" . PHP_EOL;
}
```

--------------------------------

### Create Extra Activation

Source: https://virtualsms.de/docs

Initiates an additional activation on a previously used number. Returns a plain text response in the format ACCESS_NUMBER:{ID}:{PHONE}.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getExtraActivation&id=12345&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getExtraActivation&id=12345&api_key=YOUR_API_KEY'
);
const data = await response.text();
const [status, newId, phone] = data.split(':');
if (status === 'ACCESS_NUMBER') {
  console.log(`New activation ID: ${newId}, Phone: ${phone}`);
}
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getExtraActivation&id=12345&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

[$status, $newId, $phone] = explode(':', $response);
if ($status === 'ACCESS_NUMBER') {
    echo "New activation ID: {$newId}, Phone: {$phone}";
}
```

--------------------------------

### get_balance

Source: https://virtualsms.de/docs/mcp

Retrieves the current account balance.

```APIDOC
## get_balance

### Description
Checks the current account balance to ensure sufficient funds for operations.

### Parameters
None
```

--------------------------------

### get_balance

Source: https://virtualsms.de/docs/mcp

Retrieves the current account balance.

```APIDOC
## get_balance

### Description
Returns the current account balance.

### Response
- **balance** (number) - Current account balance.
```

--------------------------------

### getBalance()

Source: https://virtualsms.de/docs/sdk

Retrieves the current account balance.

```APIDOC
## getBalance()

### Description
Retrieves the current account balance for the authenticated user.

### Method
SDK Method

### Returns
- **balance** (object) - Contains the balance amount.
```

--------------------------------

### Retrieve Verification Service Prices

Source: https://virtualsms.de/docs

Fetches pricing data structured by service, then by country.

```bash
curl "https://api.virtualsms.de/stubs/handler_api?action=getPricesVerification&service=tg&api_key=YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.virtualsms.de/stubs/handler_api?action=getPricesVerification&service=tg&api_key=YOUR_API_KEY'
);
const data = await response.json();
// Get Telegram prices by country
Object.entries(data.tg).forEach(([countryId, info]) => {
  console.log(`Country ${countryId}: $${info.price} (${info.count} available)`);
});
```

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.virtualsms.de/stubs/handler_api?action=getPricesVerification&service=tg&api_key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
// Get Telegram prices by country
foreach ($data['tg'] as $countryId => $info) {
    echo "Country {$countryId}: \${$info['price']} ({$info['count']} available)" . PHP_EOL;
}
```
Tokens:
Raw