Skip to main content
POST
Ask for a number we don't stock

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"

Body

application/json
country_code
string
required

The country, ISO 3166 alpha-2.

Pattern: ^[A-Z]{2}$
number_type
enum<string>
required

The number type.

Available options:
local,
mobile,
national,
toll_free
area
string | null

A city or area code, if it matters.

Maximum string length: 80
quantity
integer
default:1

How many numbers.

Required range: 1 <= x <= 100
notes
string | null

Anything our team should know.

Maximum string length: 1000

Response

Successful Response

id
string
required

The request id.

country_code
string
required

ISO 3166 alpha-2.

number_type
string
required

The number type asked for.

quantity
integer
required

How many numbers.

status
string
required

Where the request stands.

fulfilled_phone_number_ids
string[]
required

Numbers added to your workspace for it.

created_at
string
required

ISO 8601.

updated_at
string
required

ISO 8601.

area
string | null

The city or area asked for.

notes
string | null

Your notes for our team.

ops_note
string | null

Our team's reply.