Skip to main content
POST
Swap a taken number

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string
required

A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.

Maximum string length: 255
Kallabot-Version
enum<string>

The 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.

Available options:
2026-11-07
Example:

"2026-11-07"

Path Parameters

order_id
string
required

Body

application/json
e164
string
required
Pattern: ^\+[1-9][0-9]{7,14}$

Response

Successful Response

id
string
required

The order id.

e164
string
required

The number saved.

country_code
string
required

ISO 3166 alpha-2.

number_type
string
required

The number type.

status
string
required

waiting, buying, taken, bought, failed, canceled or expired.

alternatives
OrderAlternative · object[]
required

Similar numbers, when it was taken.

label
string | null

The label it gets.

locality
string | null

Its city.

agent
LineAgent · object | null

Who will answer it.

bundle
LineBundle · object | null

The verification it waits for.

failure
string | null

Why it failed or was canceled.

phone_number_id
string | null

The number once bought.

expires_at
string | null

When the order lapses.

created_at
string | null

ISO 8601.

decided_at
string | null

When it was bought, failed or canceled.