Skip to main content
POST
cURL
e164 must be in E.164 format with the plus. Set destination_key to the called number exactly as your carrier sends it in the SIP Request-URI, without a leading +; for most carriers that is the E.164 digits.

Next steps

  • Assign an agent to answer inbound calls to the number.
  • To call out from the number, set the agent’s telephony provider to trunk with the Update agent API and pass the number as from_phone_number to POST /call.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

trunk_id
string<uuid>
required

The trunk's id

Body

application/json
e164
string
required

The number in E.164 format, a plus then 7 to 15 digits. Used as the caller ID on outbound calls from this number.

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

"+12025550143"

destination_key
string
required

The called number exactly as your carrier puts it in the SIP Request-URI of an inbound call, without a leading +. Required by the API; for most carriers it is the E.164 number's digits (12025550143), which is what the dashboard fills in. An inbound call matches the number on its E.164 form first, then on this key.

Minimum string length: 1
Example:

"12025550143"

agent_id
string | null

Agent that answers inbound calls to this number. Must be one of your agents. Leave out to use the trunk's default_inbound_agent_id.

Response

The added number

id
string<uuid>
Example:

"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9"

trunk_id
string<uuid>
Example:

"3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21"

e164
string
Example:

"+12025550143"

destination_key
string
Example:

"12025550143"

agent_id
string | null

Agent that answers inbound calls to this number. When null, the trunk's default_inbound_agent_id answers.

Example:

"123e4567-e89b-12d3-a456-426614174000"

last_inbound_at
string<date-time> | null

When this number last took an inbound call, updated at most once a minute.

last_outbound_at
string<date-time> | null

When an outbound call was last placed from this number, updated at most once a minute.

created_at
string<date-time>
updated_at
string<date-time>
is_deleted
boolean
deleted_at
string<date-time> | null