> ## Documentation Index
> Fetch the complete documentation index at: https://virtualsms.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get your first virtual phone number in under 2 minutes.

<a href="https://god.gw.postman.com/run-collection/54876613-9b8478c6-b270-4694-ae06-545dd193e790?action=collection%2Ffork&collection-url=entityId%3D54876613-9b8478c6-b270-4694-ae06-545dd193e790%26entityType%3Dcollection%26workspaceId%3D9dd25cbf-c96e-494a-b010-74020fa15695" target="_blank" rel="noopener">
  <img src="https://run.pstmn.io/button.svg" alt="Run in Postman" />
</a>

This guide walks through [SMS verification](https://virtualsms.io/verifications) via the REST API. VirtualSMS also covers number rentals and matching-country proxies under the same balance: see [pricing](https://virtualsms.io/pricing) for every surface.

## 1. Create an account

Sign up at [virtualsms.io](https://virtualsms.io): free, no credit card required.

## 2. Top up your balance

Go to [Dashboard → Deposit](https://virtualsms.io/deposit). We accept:

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

## 3. Get your API key

Go to [Settings → API](https://virtualsms.io/settings?tab=api) and copy your key.

## 4. Buy a number

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```python Python theme={null}
  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
  ```

  ```javascript Node.js theme={null}
  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
  ```
</CodeGroup>

Response shape:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://virtualsms.io/api/v1/customer/order/ORDER_ID \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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)
  ```

  ```javascript Node.js theme={null}
  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));
  }
  ```
</CodeGroup>

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

<Tip>
  Skip the polling: connect to `wss://virtualsms.io/ws/orders` for real-time SMS delivery. See the [WebSocket guide](/docs/guides/webhooks).
</Tip>

## 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.

<Tip>
  Using an AI agent? Skip all this: use our [MCP server](/docs/guides/mcp-server) and let Claude or any other agent handle the entire flow with one tool call.
</Tip>