Swap Number

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

{ "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.