---
title: "Purchase a phone number"
method: POST
path: "/api/v1/customer/purchase"
tags: ["Customer API"]
---

# Purchase a phone number

`POST /api/v1/customer/purchase`

## Request

- Base URL: `https://virtualsms.io`
- URL: `https://virtualsms.io/api/v1/customer/purchase`
- Auth: API key in header `X-API-Key`

Purchase an SMS verification number. Balance is deducted immediately.

After purchase, poll `GET /api/v1/customer/order/{orderId}` every 3-5 seconds for SMS,
or connect to `wss://virtualsms.io/ws/orders` for real-time delivery.

**Cancel/swap policy:** Orders can be cancelled or swapped after a **2-minute hold period**
from the time of purchase. This prevents abuse.

## Request body

- object
  - `service` string, required: Service code (e.g. tg, wa, ig)
  - `country` string, required: ISO country code (e.g. ID, PH, US)

## Response `200`

Number purchased successfully

- object
  - `success` boolean
  - `order_id` string, uuid
  - `phone_number` string
  - `service` string
  - `country` string
  - `price` number, float
  - `status` string
  - `expires_at` string, date-time

## Other responses

- `401`: Invalid or missing API key
- `402`: Insufficient balance

---

[API](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and.md) · [All operations](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and/llms.txt) · [OpenAPI document](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and/revisions/be89af981be1?raw)