Skip to main content
POST
Provision a Phone Number
Safety and behavior notes
  • The client cap is one included number plus paid slots, with a higher operations override.
  • Acquiring a number from the external carrier can start recurring provider billing.
  • If phone_number is omitted and the pool is empty, the downstream purchase path receives no specific number and no test defines a successful fallback.
  • The mutation returns a broad provider record that can include internal columns and does not have a stable public projection.
  • Do not send sms_workflow_id. The published request intentionally omits it because the runtime does not tenant-validate that field.
  • The effective default allowance is one included number plus paid extra slots; do not assume a default of three.

Authorizations

X-API-Key
string
header
required

API key for authentication. Keys are prefixed with nxr_live_.

Body

application/json
country_code
string
required

Required; uppercased downstream. The handler does not enforce two-letter ISO syntax.

Minimum string length: 1
phone_number
string | null

Specific number to buy/claim. Omit to attempt an atomic pool claim.

workflow_id
string<uuid> | null

Owned workflow to bind for voice. Empty/non-string becomes client scope.

label
string

Provider-friendly label; downstream truncates to 64 characters.

Maximum string length: 64
sms_enabled
boolean
default:false

Only literal true requests SMS. Safe creation may leave SMS unbound.

Response

Successful response.

success
enum<boolean>
required
Available options:
true
number
object
required

Full retell_phone_numbers row returned by INSERT/UPDATE RETURNING *. This is not a stable public projection.

Last modified on September 8, 2026