Skip to main content

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.

POST /api/v1/customer/swap/{orderId} Replace the phone number on an active order with a different one for the same service / country combination. The original number is released and a new one is allocated. The original price stands — no double-charge. 
curl -X POST https://virtualsms.io/api/v1/customer/swap/ORDER_ID \
  -H "x-api-key: YOUR_API_KEY"

​
When to swap

  • Original number isn’t receiving SMS within a reasonable window
  • Service flagged the original number as already-used (rare for our physical SIMs but possible)
  • You need a different country code mid-flow (no — country can’t change. Cancel and place a new order instead)

​
2-minute hold

Swaps are blocked for the first 2 minutes after purchase to prevent abuse. Inside that window the response is: 
{ "error": "Swap not allowed within 2 minute hold period", "seconds_remaining": 87 }

​
Response

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

​
Notes

  • order_id stays the same — only the number changes
  • expires_at is reset to the original duration from the swap moment
  • If no replacement is available, you’ll get a 404 with {"error":"No replacement available"}. In that case use /customer/cancel/{orderId} for a refund.