VirtualSMS API Documentation

Official API documentation for VirtualSMS — SMS verification with real physical SIM cards across 145+ countries and 2500+ services.

Interactive Docs

virtualsms.io/docs — Full reference with code examples (Python, Node.js, cURL)

virtualsms.io/api — OpenAPI explorer

Authentication

All authenticated endpoints require an API key passed as a header:

X-API-Key: vms_your_api_key_here

Get your API key at virtualsms.io/settings?tab=api.

For sms-activate / DaisySMS compatibility, the API key may also be passed as a query parameter:

?api_key=vms_your_api_key_here

Heads up (2026-04-29): Earlier versions of this README documented Authorization: Bearer — that header is accepted by the legacy /api/v1/orders surface only. The modern /api/v1/customer/* endpoints (recommended for all new integrations) require X-API-Key. Standardize on X-API-Key for new code.

Base URL

https://virtualsms.io/api/v1

Endpoints

Public (no auth)

Method	Endpoint	Description
GET	/api/v1/price?service={code}&country={iso}	Price for a specific service/country combo

Customer (X-API-Key required)

Method	Endpoint	Description
GET	/api/v1/customer/services	List all available services
GET	/api/v1/customer/countries	List available countries (filterable by ?service=)
GET	/api/v1/customer/balance	Current account balance in USD
GET	/api/v1/customer/profile	Account profile (email, totals, API key count)
GET	/api/v1/customer/transactions	Paginated transaction history
POST	/api/v1/customer/purchase	Purchase a number ({service, country})
GET	/api/v1/customer/order/{id}	Order status + received SMS
POST	/api/v1/customer/swap/{id}	Get a replacement number for an active order
POST	/api/v1/customer/cancel/{id}	Cancel and refund a pending order

Webhooks (X-API-Key required)

Subscribe an HTTPS endpoint to receive real-time events. See Webhooks reference for full payload shapes, signature verification, and retry policy.

Method	Endpoint	Description
GET	/api/v1/customer/webhooks	List your webhook subscriptions
POST	/api/v1/customer/webhooks	Create a subscription (returns secret once)
GET	/api/v1/customer/webhooks/{id}	Fetch one subscription
PATCH	/api/v1/customer/webhooks/{id}	Update url / events / threshold / active / paused
DELETE	/api/v1/customer/webhooks/{id}	Delete a subscription
POST	/api/v1/customer/webhooks/{id}/test	Fire a synthetic test event
GET	/api/v1/customer/webhooks/{id}/deliveries	List recent deliveries (last 100)

Legacy (sms-activate compatible)

For drop-in replacement of DaisySMS / sms-activate clients:

https://virtualsms.io/stubs/handler_api.php?api_key=KEY&action=getNumber&service=tg&country=16

Supported actions: getNumber, getStatus, setStatus, getBalance, getServices, getCountries, getPrices. See docs for full reference.

Quick Example

# Check balance
curl -H "X-API-Key: vms_your_key" \
  https://virtualsms.io/api/v1/customer/balance
# -> {"success": true, "balance": 25.50}

# Buy a Telegram number in the UK
curl -X POST \
  -H "X-API-Key: vms_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"GB"}' \
  https://virtualsms.io/api/v1/customer/purchase
# -> {"success": true, "order_id": "...", "phone_number": "+44...", "price": 0.50, ...}

# Poll for SMS (every 3-5s) or use WebSocket wss://virtualsms.io/ws/orders
curl -H "X-API-Key: vms_your_key" \
  https://virtualsms.io/api/v1/customer/order/ORDER_ID
# -> {"success": true, "status": "completed", "messages": [{"sender":"Telegram","content":"...","received_at":"..."}]}

Cancel / swap policy

Orders can be cancelled or swapped after a 2-minute hold period from the time of purchase. Cancellation requests inside that window return 425 Too Early with the seconds remaining.

Rate limits

• 60 req/min per API key on /api/v1/customer/*
• 10 req/min per API key on certain bot/programmatic endpoints
• 429 Too Many Requests returned when exceeded

SDKs and Integrations

• MCP Server (AI agents): github.com/virtualsms-io/mcp-server — Claude, Cursor, Codex, Windsurf
• PHP SDK: github.com/virtualsms-io/virtualsms-php-sdk
• Code examples: github.com/virtualsms-io/examples — Python, Node.js, cURL

Features

• Real SIM cards — physical hardware modems on European/US carriers, not VoIP
• 145+ countries supported, 60+ typically in live stock
• 2500+ services (WhatsApp, Telegram, Google, Instagram, banking, gaming, marketplaces)
• Pay per use — $2 minimum top-up, no subscription
• Crypto + card payments (USDT, BTC, ETH, BNB, LTC via NOWPayments)
• Real-time SMS via WebSocket: wss://virtualsms.io/ws/orders
• Outbound webhooks for sms.received, order.cancelled, order.expired, order.swapped, balance.low — HMAC-SHA256 signed, 5-attempt exponential retry, configurable from your dashboard or /api/v1/customer/webhooks API. See webhooks.md.

Links

• virtualsms.io — site
• virtualsms.io/docs — full docs
• virtualsms.io/blog — guides and updates
• virtualsms.io/services — service catalog

Changelog

2026-04-29 — Documented /api/v1/customer/webhooks (5-event canonical set, HMAC signing, retry policy). New webhooks.md reference. Surface in README + Features list.

2026-04-29 — Corrected auth header (X-API-Key, not Bearer), updated endpoint list to match canonical client (/customer/*), removed dead endpoint (/activations 404s on live), added /price, /profile, /transactions, /swap to public listing.

License

MIT