Swap a taken number
Picks a new number for an order whose number was taken. It waits again, or is bought now when the verification is already approved.
Scopes: number:write
Authorizations
An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.
Headers
A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.
255The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.
2026-11-07 "2026-11-07"
Path Parameters
Body
^\+[1-9][0-9]{7,14}$Response
Successful Response
The order id.
The number saved.
ISO 3166 alpha-2.
The number type.
waiting, buying, taken, bought, failed, canceled or expired.
Similar numbers, when it was taken.
The label it gets.
Its city.
Who will answer it.
The verification it waits for.
Why it failed or was canceled.
The number once bought.
When the order lapses.
ISO 8601.
When it was bought, failed or canceled.