Skip to content

VirtuMSG API

The API lets your software request numbers and read incoming SMS automatically — the same actions you perform on the website, over HTTPS with JSON responses.

Authenticated requests use your personal API key, sent as a Bearer token.

Amounts are integers in 1/10,000 of the currency unit (4200 = 0.42). Create your API key in Settings and send it as Authorization: Bearer <key>

The technical reference below is in English.

Request a number

API key
POST /api/v1/activations

Buys a number for a service in a country and charges your balance. Send a unique Idempotency-Key header per purchase: repeating a request with the same key returns the same activation instead of charging twice. `price` must equal a current price (see Get current prices); if it changed you get PRICE_CHANGED with the new prices.

Requires your API key in the Authorization: Bearer header (generate it in Settings).

Parameters

  • service* — Service code, e.g. tg (from List services).
  • country* — Country id (from List services).
  • price* — The price you agree to pay, in 1/10,000 units.
  • Idempotency-Key* — Header: 16–64 letters, digits, _ or -.

Possible errors

  • 401 UNAUTHORIZED — Missing, invalid or revoked API key.
  • 429 RATE_LIMITED — Too many requests — wait and retry.
  • 402 INSUFFICIENT_FUNDS — Top up your balance.
  • 409 PRICE_CHANGED — Price moved; `prices` lists current ones.
  • 409 NO_NUMBERS — Out of stock — retry or pick another country.
  • 502 PROVIDER_ERROR — Upstream problem; you were not charged.

Example response

curl -X POST https://your-domain/api/v1/activations \
  -H "Authorization: Bearer rk_live_…" \
  -H "Idempotency-Key: 7f3c9a1e5b2d4f6a8c0e" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"12","price":4200}'

201 { "order": { "id": "…", "phoneNumber": "1…", "status": "active",
      "price": 4200, "currency": "USD", "expiresAt": "…", … } }