---
title: "Swap for a different number"
method: POST
path: "/api/v1/customer/swap/{orderId}"
tags: ["Customer API"]
---

# Swap for a different number

`POST /api/v1/customer/swap/{orderId}`

## Request

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

Swap the current number for a different one with the same service and country.
The old order is cancelled (refunded) and a new order is created automatically.

**2-minute hold:** Same as cancel - swaps cannot be initiated within the first 2 minutes
of purchase. The 425 response tells you exactly how many seconds to wait.

Use swap when the number isn't receiving SMS - it gives you a fresh number without
leaving your app and re-purchasing manually.

## Path parameters

- `orderId` string, uuid, required

## Response `200`

Number swapped successfully

- object
  - `success` boolean
  - `old_order_id` string, uuid
  - `new_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
- `404`: Order not found
- `425`: Too early to swap - 2-minute hold period active

---

[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)