Quickstart

This guide walks through SMS verification via the REST API. VirtualSMS also covers number rentals and matching-country proxies under the same balance: see pricing for every surface.

1. Create an account

2. Top up your balance

Go to Dashboard → Deposit. We accept:

USDT (TRC20, ERC20, BEP20)
Bitcoin, Ethereum, BNB
Minimum deposit: $2.50

3. Get your API key

Go to Settings → API and copy your key.

4. Buy a number

curl -X POST https://virtualsms.io/api/v1/customer/purchase \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "tg", "country": "GB"}'

import requests

r = requests.post(
    "https://virtualsms.io/api/v1/customer/purchase",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"service": "tg", "country": "GB"},
)
order = r.json()
print(order["phone_number"])  # +44...
print(order["order_id"])      # save this - you need it to poll for SMS

const res = await fetch("https://virtualsms.io/api/v1/customer/purchase", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ service: "tg", country: "GB" }),
});
const order = await res.json();
console.log(order.phone_number); // +44...
console.log(order.order_id);     // save this

Response shape:

{
  "success": true,
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "phone_number": "+447911123456",
  "service": "tg",
  "country": "GB",
  "price": 0.50,
  "status": "pending",
  "expires_at": "2026-04-29T12:30:00Z"
}

5. Wait for the SMS

Poll the order status every 3-5 seconds:

curl https://virtualsms.io/api/v1/customer/order/ORDER_ID \
  -H "x-api-key: YOUR_API_KEY"

import time

while True:
    r = requests.get(
        f"https://virtualsms.io/api/v1/customer/order/{order['order_id']}",
        headers={"x-api-key": "YOUR_API_KEY"},
    )
    data = r.json()
    if data.get("messages"):
        msg = data["messages"][0]
        print(f"OTP from {msg['sender']}: {msg['content']}")
        break
    time.sleep(5)

while (true) {
  const r = await fetch(
    `https://virtualsms.io/api/v1/customer/order/${order.order_id}`,
    { headers: { "x-api-key": "YOUR_API_KEY" } },
  );
  const data = await r.json();
  if (data.messages?.length) {
    console.log("OTP:", data.messages[0].content);
    break;
  }
  await new Promise(r => setTimeout(r, 5000));
}

The messages array is empty while waiting and populated once SMS arrives.

Skip the polling: connect to wss://virtualsms.io/ws/orders for real-time SMS delivery. See the WebSocket guide.

Done

Use the phone number on the service, enter the OTP code when it arrives. After a 2-minute hold period you can POST /api/v1/customer/cancel/{order_id} to release a number with no SMS received and get a full refund.

Using an AI agent? Skip all this: use our MCP server and let Claude or any other agent handle the entire flow with one tool call.

Getting Started

Integration

Earn

1. Create an account

2. Top up your balance

3. Get your API key

4. Buy a number

5. Wait for the SMS

Done

​1. Create an account

​2. Top up your balance

​3. Get your API key

​4. Buy a number

​5. Wait for the SMS

​Done

1. Create an account

2. Top up your balance

3. Get your API key

4. Buy a number

5. Wait for the SMS

Done