Skip to content

Create a SIP trunk

POST
/v1/organizations/{org}/trunks
curl --request POST \
--url https://api.caller9.app/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/trunks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "default_cid_number_guid": "example", "cid_display_name": "example", "channel_limit": 1, "localization": "US" }'

Provisions a new SIP trunk with generated registration credentials for your PBX. Calls the PBX places through the trunk go out to the PSTN and are billed as trunk minutes; numbers can be routed to the trunk for inbound calls. Requires a paid plan in good billing standing; the Basic plan allows one trunk with at most 5 channels (409 plan_limit with limit trunks, billing or trunk_channels). Requires a full-access key.

org
required
string format: uuid

Organization ID (UUID). Must be the organization that owns the API key.

Media typeapplication/json
object
name
required
string
<= 100 characters
default_cid_number_guid

ID of one of the organization’s numbers to use as the default outbound caller ID.

string | null
cid_display_name

Outbound caller ID name (CNAM). Uppercased, stripped to letters, digits, ., , and spaces, must start with a letter, and truncated to 15 characters; must end up at least 2 characters (empty is allowed). Defaults to the normalized trunk name.

string
<= 64 characters
channel_limit

Maximum concurrent calls. null means unlimited (not allowed on Basic). Basic is capped at 5 and defaults to 5; other plans default to unlimited.

integer | null
>= 1 <= 1000
localization

ISO 3166-1 alpha-2 country code used to interpret numbers the PBX dials in national format.

string
default: US /^[A-Za-z]{2}$/

The created trunk, including its SIP credentials.

Media typeapplication/json
object
trunk
required

A SIP trunk your PBX registers to. Includes registration credentials — sip_password is a secret; store it securely and never log it.

object
guid
required
string
organization_guid
required
string
name
required
string
sip_username
required

SIP registration username.

string
sip_password
required

SIP registration password (secret). Changes when rotated.

string
sip_uri
required

The trunk’s SIP URI (sip:<username>@sip.telnyx.com).

string
default_cid_number_guid
required

ID of the organization number used as the default outbound caller ID.

string | null
cid_display_name
required

Outbound caller ID name (CNAM); empty if unset.

string
channel_limit
required

Maximum concurrent calls; null = unlimited.

integer | null
localization
required

ISO 3166-1 alpha-2 country code (default US).

string
numbers
required

Numbers routed to this trunk for inbound calls, sorted by number.

Array<object>
object
guid
required
string
number
required

E.164 phone number.

string
name
required
string
created_at
required
string format: date-time
updated_at
required
string format: date-time

Example generated

{
"trunk": {
"guid": "example",
"organization_guid": "example",
"name": "example",
"sip_username": "example",
"sip_password": "example",
"sip_uri": "example",
"default_cid_number_guid": "example",
"cid_display_name": "example",
"channel_limit": 1,
"localization": "example",
"numbers": [
{
"guid": "example",
"number": "example",
"name": "example"
}
],
"created_at": "2026-04-15T12:00:00Z",
"updated_at": "2026-04-15T12:00:00Z"
}
}

The request was invalid.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Blocked by the organization’s plan.

Media typeapplication/json
object
error
required
string
Allowed value: plan_limit
limit
required

Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.

string
message
required
string

Example

{
"error": "plan_limit"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.