API Reference

Authentication

Every request (except public endpoints) requires your API key passed as the key query parameter. Keep it secret — treat it like a password.

# Pass your key as a query parameter on every request
curl -G "https://v-numbers.com/api/v2/order" \
  -d "key=YOUR_API_KEY" \
  -d "country=us" \
  -d "service=telegram"

Quick start

The typical flow is three steps: order a number, poll until the SMS arrives, then cancel if it never comes.

# 1. Order a number
curl -G "https://v-numbers.com/api/v2/order" \
  -d "key=$VN_KEY" \
  -d "country=us" \
  -d "service=telegram"

# → { "orderId": "hold_8Kp2", "number": "+1 (873) 283-5759", "price": 24 }

# 2. Poll for the SMS code (repeat every 5-10s, up to 20 min)
curl -G "https://v-numbers.com/api/v2/getStatus" \
  -d "key=$VN_KEY" \
  -d "orderId=hold_8Kp2"

# → { "status": "sms received", "sms_code": "482916" }

# 3. If no SMS arrives, cancel (no charge)
curl -G "https://v-numbers.com/api/v2/cancelOrder" \
  -d "key=$VN_KEY" \
  -d "orderId=hold_8Kp2"

Order a number

Reserves a real virtual phone number for the given country and service. Returns an orderId you use to poll for the SMS code. The number stays active for up to 20 minutes — if no SMS arrives you are not charged.

Query parameters

Response

{
  "orderId":          "hold_8Kp2",
  "number":           "+1 (873) 283-5759",
  "country_id":       "us",
  "service_id":       "telegram",
  "price":            24,
  "cancelable_after": "2026-06-03T10:21:00.000Z"
}

price is in cents (24 = $0.24). You are only charged when an SMS is successfully received.

Get status

Polls the status of an active order. Call this every 5–10 seconds after placing an order. Once status is "sms received", the code is in sms_code.

Query parameters

Possible status values

Response — waiting

{
  "status":       "waiting",
  "sms_code":     null,
  "sms_text":     null,
  "is_retriable": false
}

Response — sms received

{
  "status":       "sms received",
  "sms_code":     "482916",
  "sms_text":     "Your Telegram code: 482916. Do not share it.",
  "is_retriable": true
}

Cancel order

Cancels an active order. No charge is applied if no SMS was received before cancellation. You can only cancel orders that are currently in HOLD status.

Query parameters

Response

{
  "message": "Order canceled successfully"
}

Retry order

Requests a second SMS on a completed order. Only available on orders where is_retriable is true in the status response. Useful when the service sends a second OTP.

Query parameters

Response

{
  "message": "Retry requested — new SMS on the way"
}

Poll /api/v2/getStatus again after calling retry — the new code arrives as "retry received".

Get price

Returns the current price and availability for a specific country/service combination before placing an order.

Query parameters

Response

{
  "price":       24,
  "available":   15420,
  "successRate": 98
}

price is in cents. available is the current pool size. successRate is a 0–100 integer.

There is also a public version at /api/public/getPrice that requires no API key.

Get prices (all countries)

Returns the price and availability for a single service across every country in one request — no need to call getPrice per country. Countries with no numbers in stock are omitted, and results are sorted cheapest-first.

Query parameters

Response

[
  { "country": "ph", "price": 18, "available": 8412 },
  { "country": "us", "price": 24, "available": 52 },
  { "country": "gb", "price": 31, "available": 2100 },
  ...
]

price is in cents. available is the current pool size for that country.

List countries

Returns all available countries. No authentication required.

Response

[
  { "country_id": "us", "name": "United States" },
  { "country_id": "gb", "name": "United Kingdom" },
  { "country_id": "in", "name": "India" },
  ...
]

List services

Returns all available services. No authentication required.

Response

[
  { "service_id": "telegram",   "name": "Telegram" },
  { "service_id": "whatsapp",   "name": "WhatsApp" },
  { "service_id": "instagram",  "name": "Instagram" },
  ...
]

List orders

Returns your order history. Optionally filter by status.

Query parameters

Response

{
  "data": [
    {
      "orderId":    "hold_8Kp2",
      "number":     "+1 (873) 283-5759",
      "status":     "DONE",
      "service":    "telegram",
      "country":    "us",
      "amount":     24,
      "sms_code":   "482916",
      "created_at": "2026-06-03T10:01:00.000Z"
    }
  ]
}

Get balance

Returns your current credit balance, the amount held for active orders, and the net available balance. All values are in cents and mirrored as USD strings for convenience.

Query parameters

Response

{
  "balance":       1250,
  "on_hold":       48,
  "available":     1202,
  "balance_usd":   "12.50",
  "on_hold_usd":   "0.48",
  "available_usd": "12.02"
}

on_hold is the sum of all currently active orders. Credits are deducted from available when you place an order and released back if no SMS arrives.

Errors

All errors return a JSON body with a message or error field explaining the problem.

Example error response

HTTP/1.1 402 Payment Required

{
  "message": "Insufficient credits"
}