README

PHP SDK for the VirtualSMS Consumer API — SMS verification, phone number rental, and activation management.

Requirements

• PHP 8.0 or higher
• cURL extension
• JSON extension

Installation

composer require virtualsmslabs/php-sdk

Quick Start

<?php

require_once 'vendor/autoload.php';

use VirtualSMS\VirtualSMSClient;
use VirtualSMS\Constants\ActivationStatus;

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

// Check balance
$balance = $client->getBalance();
echo "Balance: $" . $balance->balance . PHP_EOL;

// Order a WhatsApp number in Brazil
$number = $client->getNumber('wa', 73, maxPrice: 2.00);
echo "Number: {$number->phoneNumber} (ID: {$number->activationId})" . PHP_EOL;

// Set status to ready (SMS sent)
$client->setStatus($number->activationId, ActivationStatus::READY);

// Poll for SMS code
$status = $client->getStatus($number->activationId);
if ($status->code !== null) {
    echo "SMS code: {$status->code}" . PHP_EOL;
    // Complete the activation
    $client->setStatus($number->activationId, ActivationStatus::COMPLETE);
}

API Reference

Client Constructor

$client = new VirtualSMSClient(
    string $apiKey,           // Your API key (required)
    string $baseUrl,          // API base URL (default: 'https://api.virtualsms.de')
    ?TransportInterface $transport = null  // Optional custom transport
);

Methods

Account

getBalance(): BalanceResponse

Returns the current account balance.

$balance = $client->getBalance();
echo $balance->balance; // 10.50

Information & Pricing

getCountries(?string $poolProvider = null): array

Returns all available countries.

getServicesList(?int $country = null, ?string $lang = null): array

Returns available services for a country.

getOperators(int $country, ?string $poolProvider = null): array

Returns available mobile operators for a country.

getPrices(?string $service = null, ?int $country = null, ?string $poolProvider = null): array

Returns pricing data organized by country and service.

getPricesExtended(?string $service, ?int $country, ?bool $freePrice, ?string $poolProvider): array

Returns extended pricing with price tiers.

getPricesVerification(?string $service = null, ?string $poolProvider = null): array

Returns pricing in inverted format (service → country).

getNumbersStatus(int $country, ?string $operator = null, ?string $poolProvider = null): array

Returns available phone quantity per service.

getTopCountriesByService(string $service): array

Returns top 10 countries for a service, ranked by purchase share and success rate.

Ordering Numbers

getNumber(string $service, int $country, ...$options): NumberResponse

Orders a phone number. Returns text format response.

$number = $client->getNumber(
    service: 'wa',
    country: 73,
    maxPrice: 2.00,
    operator: 'claro',
    forward: true
);
echo $number->activationId;  // 123
echo $number->phoneNumber;   // 447777777777

Options:

Parameter	Type	Description
maxPrice	float	Maximum price willing to pay
operator	string	Mobile operator filter
phoneException	string	Phone prefixes to exclude (comma-separated)
forward	bool	Enable call forwarding
activationType	int	Activation type: 0=SMS, 1=number, 2=voice
language	string	Language for voice activation
useCashBack	bool	Use cashback balance first
userId	string	End-user ID for tracking
ref	string	Referral ID
poolProvider	string	Pool provider: alpha, prime, gamma, zeta

getNumberV2(string $service, int $country, ...$options): array

Same as getNumber but returns JSON with additional fields. Supports orderId for idempotency.

Activation Management

setStatus(int $id, int $status): string

Changes activation status.

use VirtualSMS\Constants\ActivationStatus;

$client->setStatus($activationId, ActivationStatus::READY);    // 1 - SMS sent
$client->setStatus($activationId, ActivationStatus::RETRY);    // 3 - Request another SMS
$client->setStatus($activationId, ActivationStatus::COMPLETE); // 6 - Finish
$client->setStatus($activationId, ActivationStatus::CANCEL);   // 8 - Cancel

getStatus(int $id): StatusResponse

Returns activation status in text format.

$status = $client->getStatus($activationId);
echo $status->status;  // STATUS_OK, STATUS_WAIT_CODE, STATUS_CANCEL
echo $status->code;     // 123456 (null if not yet received)

getStatusV2(int $id): array

Returns activation status in JSON format with SMS/call details.

getActiveActivations(): array

Returns all currently active activations.

checkExtraActivation(int $id): array

Checks if a number is available for reactivation.

getExtraActivation(int $id): NumberResponse

Creates an extra activation on a previously used number.

Notifications

getNotifications(): array

Returns user notifications including penalties, low balance alerts, and admin messages.

Constants

ActivationStatus

ActivationStatus::READY    // 1 - SMS has been sent to the number
ActivationStatus::RETRY    // 3 - Request another SMS code
ActivationStatus::COMPLETE  // 6 - Finish activation
ActivationStatus::CANCEL    // 8 - Cancel activation

PoolProvider

PoolProvider::ALPHA  // 'alpha'
PoolProvider::PRIME  // 'prime'
PoolProvider::GAMMA  // 'gamma'
PoolProvider::ZETA   // 'zeta'

Error Handling

The SDK throws typed exceptions for all API errors. Each error code maps to a specific exception class:

use VirtualSMS\Exceptions\AuthenticationException;
use VirtualSMS\Exceptions\InsufficientBalanceException;
use VirtualSMS\Exceptions\NoNumbersException;
use VirtualSMS\Exceptions\ValidationException;
use VirtualSMS\Exceptions\ActivationException;
use VirtualSMS\Exceptions\RateLimitException;
use VirtualSMS\Exceptions\ServerException;
use VirtualSMS\Exceptions\VirtualSMSException;

try {
    $number = $client->getNumber('wa', 73);
} catch (AuthenticationException $e) {
    // BAD_KEY, BANNED, PURCHASE_RESTRICTED, SERVICE_RESTRICTED
} catch (InsufficientBalanceException $e) {
    // NO_BALANCE
} catch (NoNumbersException $e) {
    // NO_NUMBERS
} catch (ValidationException $e) {
    // WRONG_SERVICE, WRONG_COUNTRY, BAD_ACTION, BAD_STATUS, NO_PRICES, INVALID_PROVIDER
} catch (ActivationException $e) {
    // NO_ACTIVATION, WRONG_ACTIVATION_ID, EARLY_CANCEL_DENIED, RENEW_ACTIVATION_NOT_AVAILABLE
} catch (RateLimitException $e) {
    // CONCURRENT_LIMIT — check $e->retryAfter
} catch (ServerException $e) {
    // ERROR_SQL, unknown errors
}

Error Code Reference

Error Code	Exception	Description
BAD_KEY	AuthenticationException	Invalid API key
BANNED	AuthenticationException	Account banned or IP blocked
PURCHASE_RESTRICTED	AuthenticationException	User restricted from purchasing
SERVICE_RESTRICTED	AuthenticationException	Service restricted for account
NO_BALANCE	InsufficientBalanceException	Insufficient balance
NO_NUMBERS	NoNumbersException	No numbers available
WRONG_SERVICE	ValidationException	Invalid service code
WRONG_COUNTRY	ValidationException	Invalid country ID
BAD_ACTION	ValidationException	Invalid action
BAD_STATUS	ValidationException	Invalid status code
NO_PRICES	ValidationException	No pricing data available
INVALID_PROVIDER	ValidationException	Invalid pool provider
NO_ACTIVATION	ActivationException	Activation not found
WRONG_ACTIVATION_ID	ActivationException	Invalid activation ID
EARLY_CANCEL_DENIED	ActivationException	Cannot cancel within 5 minutes
RENEW_ACTIVATION_NOT_AVAILABLE	ActivationException	Number not available for reactivation
CONCURRENT_LIMIT	RateLimitException	Too many concurrent activations
ERROR_SQL	ServerException	Internal server error

Tracking Headers

The SDK sends anonymous tracking headers with every request for analytics and debugging:

Header	Value	Privacy
X-SDK-Version	1.0.0	SDK version string
X-SDK-Language	php	SDK language
X-SDK-Machine-Id	SHA-256 hash of php_uname() + PHP SAPI (truncated to 32 chars)	Irreversible hash — no hostname or IP exposed
X-SDK-Timestamp	ISO 8601 UTC timestamp	Request time

No personally identifiable information is transmitted. The machine ID is a one-way hash and cannot be reversed to identify the source machine.

Custom Transport

By default, the SDK uses cURL for HTTP requests. You can provide your own transport implementation:

use VirtualSMS\Transport\TransportInterface;
use VirtualSMS\Transport\Response;

class MyTransport implements TransportInterface
{
    public function send(string $url, array $headers = []): Response
    {
        // Your HTTP implementation
        return new Response(200, 'ACCESS_BALANCE:10.50');
    }
}

$client = new VirtualSMSClient('API_KEY', 'https://api.example.com', new MyTransport());

Examples

See the examples/ directory:

• balance.php — Check account balance
• order_number.php — Order a phone number
• full_workflow.php — Complete SMS verification workflow

Testing

composer install
vendor/bin/phpunit

License

MIT — see LICENSE.

Links

• Packagist
• GitHub
• API Documentation
• MCP Integration