Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Bearer token via Authorization header

Headers

idempotency-key
string

Idempotency-Key: 1-255 printable ASCII characters. Same key with a different request body is a 422 idempotency_key_reused. A retryable in-flight duplicate is a 409 with Retry-After and x-should-retry: true; a terminal duplicate is a 409 with x-should-retry: false. A replay returns the current resource state with Idempotent-Replayed: true.

Required string length: 1 - 255
Pattern: ^[\x21-\x7E]{1,255}$
Example:

"b3f6a9f0-6f1a-4e9a-9e7a-9c9b6b6a5a3f"

Body

application/json
billingPreference
enum<string>

Use included capacity when available, require included capacity without paid fallback (included_only), or start a paid checkout (rent).

Available options:
included,
included_only,
rent
country
string

Optional ISO 3166-1 alpha-2 country code from GET /numbers/phones/countries.

Required string length: 2
Pattern: ^[a-z]{2}$
Example:

"de"

label
string | null

User-defined display label — NFC-normalized, up to 100 GRAPHEMES (not UTF-16 code units; an emoji/flag may span several). Display-only, never used for routing.

Example:

"Support line"

Response

Number purchase accepted — poll GET /numbers/phones/{id}

data
object
required