Skip to main content
POST
Add phone number

Authorizations

Authorization
string
header
required

Use Authorization: Bearer tc_live_xxxxx

Headers

Idempotency-Key
string

Makes a retry safe. A 2xx response is stored for 24 hours per account, and a retry with the same key gets it back with Idempotent-Replay: true instead of running again. Errors aren't stored, so a retry after one runs fresh. The key isn't tied to a path or body: use a new key for every different request. A malformed key gets 400.

Required string length: 8 - 255
Pattern: ^[A-Za-z0-9_-]+$
Example:

"a1b2c3d4-e5f6-7890-abcd-ef0123456789"

Body

application/json
number
string
required

E.164. A number that isn't dialable gets 422.

Pattern: ^\+[1-9]\d{1,14}$
Example:

"+18005551234"

voip_carrier_sid
string<uuid>

One of your carriers. Omit to use the TopCalls carrier.

label
string

Your label

Maximum string length: 100

Response

Phone number added successfully

id
string<uuid>

Phone number UUID

number
string

The number in E.164

voip_carrier_sid
string<uuid>

Carrier the number is on

carrier_name
string

Carrier display name

source
enum<string>

topcalls when you omitted voip_carrier_sid, otherwise byoc.

Available options:
topcalls,
byoc
phone_number_sid
string<uuid>

The number's ID in the phone system

status
enum<string>

Always active. A failed provisioning returns 422 instead.

Available options:
active
label
string | null

Your label

account_id
string<uuid>

Account UUID

created_at
string<date-time>