Skip to main content
POST
Buy a phone number

Authorizations

Authorization
string
header
required

API key (fam_..., created under Settings → API Keys) or an OAuth 2.0 access token (fam_at_...). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as assistants:read, calls:write, campaigns:write, automations:read, dashboards:read, dashboards:write, leads:write, segments:write, loop:read, loop:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read, billing:write, settings:write, platform:read, platform:write; a *:write scope implies the matching *:read. Automation and dashboard endpoints also accept the legacy calls:* scope. Keys without scope restrictions have full access within the workspace's available capabilities.

Body

application/json
number
string
required

The exact E.164 number returned by GET /phone-numbers/available.

country
string
required

ISO-2 country code, e.g. DE.

type
enum<string>
default:local

Number type of the offer. Pass the type returned with the number by GET /phone-numbers/available; defaults to local when omitted.

Available options:
local,
mobile,
national
purchase_token
string

The short-lived token returned with the exact number by GET /phone-numbers/available; pass it unchanged. Required for workspaces that buy numbers from a reseller. Otherwise optional, but when sent it must match the number, country and type.

assistant_id
string<uuid> | null

Optionally assign an assistant that does not already have an inbound phone number. Pending number reservations also count. An existing assignment returns HTTP 409; omit this field or set it to null to assign an assistant later.

Response

A pending phone number and the checkout URL required to activate it.

data
object
required