Create SIP trunk API

POST

trunk

trunks

curl --request POST \
  --url https://api.bolna.ai/trunk/trunks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Telnyx production",
  "preset": "telnyx",
  "channels": 20,
  "transport": "udp",
  "codecs": "PCMU,PCMA",
  "outbound_leading_plus_enabled": true,
  "auth_username": "bolna-outbound",
  "auth_password": "<carrier-issued password>",
  "gateways": [
    {
      "host": "sip.example.com",
      "port": 5060,
      "priority": 0
    }
  ],
  "ip_acls": [
    "203.0.113.10",
    "198.51.100.0/28"
  ]
}
'

{
  "id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
  "name": "Telnyx production",
  "description": null,
  "preset": "telnyx",
  "is_active": true,
  "inbound_enabled": true,
  "outbound_enabled": true,
  "channels": 20,
  "default_inbound_agent_id": null,
  "auth_username": "bolna-outbound",
  "transport": "udp",
  "codecs": "PCMU,PCMA",
  "outbound_leading_plus_enabled": true,
  "last_inbound_at": null,
  "last_outbound_at": null,
  "converted_from_byot_trunk_id": null,
  "organization_id": "7a1c2e3f-4b5d-4c6e-8f90-a1b2c3d4e5f6",
  "sub_account_id": null,
  "user_id": null,
  "created_at": "2026-10-16T09:12:44.512381+00:00",
  "updated_at": "2026-10-16T09:12:44.512381+00:00",
  "is_deleted": false,
  "deleted_at": null,
  "health": "waiting_for_carrier",
  "active_calls": 0,
  "gateways": [
    {
      "id": "8b1d4e2f-0a3c-4d5e-9f60-7182a3b4c5d6",
      "trunk_id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
      "host": "sip.example.com",
      "resolved_ips": [
        "203.0.113.30"
      ],
      "port": 5060,
      "priority": 0,
      "created_at": "2026-10-16T09:12:44.512381+00:00",
      "updated_at": "2026-10-16T09:12:44.512381+00:00",
      "is_deleted": false,
      "deleted_at": null
    }
  ],
  "ip_acls": [
    {
      "id": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
      "trunk_id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
      "cidr": "203.0.113.10/32",
      "created_at": "2026-10-16T09:12:44.512381+00:00",
      "updated_at": "2026-10-16T09:12:44.512381+00:00",
      "is_deleted": false,
      "deleted_at": null
    },
    {
      "id": "d3e4f5a6-b7c8-4d9e-8f01-2b3c4d5e6f7a",
      "trunk_id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
      "cidr": "198.51.100.0/28",
      "created_at": "2026-10-16T09:12:44.512381+00:00",
      "updated_at": "2026-10-16T09:12:44.512381+00:00",
      "is_deleted": false,
      "deleted_at": null
    }
  ],
  "numbers": []
}

{
  "message": "198.48.0.0/12 is broader than /16"
}

{
  "detail": {
    "code": "gateway_conflict",
    "message": "gateway sip.example.com is used by another trunk; a shared gateway needs carrier credentials on every trunk that uses it"
  }
}

{
  "detail": [
    {
      "loc": [
        "body",
        "channels"
      ],
      "msg": "Input should be less than or equal to 1000",
      "type": "less_than_equal"
    }
  ]
}

This endpoint returns 200, not 201. Send the carrier’s credentials only if it challenges Bolna’s outbound calls; a carrier that authenticates Bolna by IP needs Bolna’s signalling IPs from GET /trunk/pop on its allowlist instead.

Next steps

Add your carrier’s numbers to the trunk.
Point your carrier at the values from GET /trunk/pop.

Authorizations

Authorization

string

header

required

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

Body

application/json

name

string

required

Display name.

Required string length: 1 - 100

Example:

"Telnyx production"

description

string

Free-text note for your own reference.

Maximum string length: 500

preset

enum<string>

The carrier the trunk is for. Stored as a label; the API does not fill any other field from it.

Available options:

plivo,

telnyx,

twilio,

exotel,

vobiz,

vonage,

custom

inbound_enabled

boolean

default:true

Accept inbound calls from the trunk's carrier IPs.

outbound_enabled

boolean

default:true

Allow outbound calls from the trunk's numbers.

channels

integer

default:10

Maximum concurrent calls on the trunk, inbound and outbound combined. An inbound call over the limit is refused with SIP 486 Busy Here; an outbound call over it waits in your call queue until a channel is free.

Required range: 1 <= x <= 1000

default_inbound_agent_id

string

Agent that answers inbound calls to any of the trunk's numbers that has no agent_id of its own. Must be one of your agents.

auth_username

string

Username your carrier issued for Bolna's outbound calls, sent when the carrier challenges the INVITE (SIP 401/407). Set together with auth_password, or leave both out when the carrier authenticates Bolna by IP. Must not contain a quote, |, {, }, \ or a control character.

Minimum string length: 1

auth_password

string<password>

Password for auth_username. Stored encrypted; never returned. The same character rules apply.

Minimum string length: 1

transport

enum<string>

default:udp

SIP transport towards your carrier's gateways. tls is rejected.

Available options:

udp,

tcp

outbound_leading_plus_enabled

boolean

default:false

Send the dialled number to the carrier with a leading +. When false, the number is sent as digits only.

codecs

string

default:PCMU,PCMA

Comma-separated codecs offered to the carrier, in order of preference. Any non-empty subset of PCMU and PCMA; values are upper-cased.

gateways

object[]

Carrier SIP hosts that outbound calls are sent to. Leave empty for an inbound-only trunk.

Maximum array length: 8

Show child attributes

ip_acls

string[]

Addresses or CIDR ranges your carrier sends inbound calls from. Public IPv4, no broader than /16. A bare address is stored as a /32.

Maximum array length: 32

Example:

["203.0.113.10", "198.51.100.0/28"]

Response

The created trunk. Bare IP addresses in ip_acls come back as /32 networks.

A SIP trunk with its gateways, carrier IPs, numbers and live status.

string<uuid>

Unique trunk ID.

Example:

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

name

string

Display name.

Example:

"Telnyx production"

description

string | null

Free-text note for your own reference.

preset

enum<string> | null

The carrier the trunk was set up for.

Available options:

plivo,

telnyx,

twilio,

exotel,

vobiz,

vonage,

custom

Example:

"telnyx"

is_active

boolean

When false, the trunk takes no inbound calls and places no outbound calls.

inbound_enabled

boolean

Whether the trunk accepts inbound calls from its carrier IPs.

outbound_enabled

boolean

Whether outbound calls can be placed from the trunk's numbers.

channels

integer

Maximum concurrent calls on the trunk, inbound and outbound combined.

Example:

20

default_inbound_agent_id

string | null

Agent that answers inbound calls to any of the trunk's numbers that has no agent_id of its own.

auth_username

string | null

Username your carrier issued, sent when the carrier challenges an outbound call (SIP 401/407). The password is never returned.

Example:

"bolna-outbound"

transport

enum<string>

SIP transport used towards your carrier's gateways.

Available options:

udp,

tcp

codecs

string

Codecs offered to the carrier, comma-separated, in order of preference.

Example:

"PCMU,PCMA"

outbound_leading_plus_enabled

boolean

When true, the dialled number is sent to the carrier with a leading + (+12025550178); when false, as digits only (12025550178).

last_inbound_at

string<date-time> | null

When the trunk last took an inbound call, updated at most once a minute. null until the first one.

last_outbound_at

string<date-time> | null

When an outbound call was last placed through the trunk, updated at most once a minute. null until the first one.

converted_from_byot_trunk_id

string | null

The legacy SIP trunk this trunk was migrated from, when Bolna migrated it for you. null otherwise.

organization_id

string | null

The organisation that owns the trunk. null for an account outside an organisation.

sub_account_id

string | null

The sub-account the trunk was created under. null for an organisation-level trunk.

user_id

string | null

The owning user, for an account outside an organisation. null for an organisation's trunk.

created_at

string<date-time>

When the trunk was created.

updated_at

string<date-time>

When the trunk's settings last changed.

is_deleted

boolean

true only in the response to a delete.

deleted_at

string<date-time> | null

When the trunk was deleted.

health

enum<string>

ready: calls have crossed the trunk and the carrier is not failing them.
waiting_for_carrier: no call has crossed the trunk yet.
degraded: the carrier failed three or more recent outbound calls with no answered call since.
disabled: is_active is false.

Available options:

ready,

waiting_for_carrier,

degraded,

disabled

active_calls

integer

Calls holding one of the trunk's channels right now.

Example:

0

gateways

object[]

Carrier SIP hosts outbound calls are sent to.

Show child attributes

ip_acls

object[]

Carrier IPs inbound calls are accepted from.

Show child attributes

numbers

object[]

The trunk's phone numbers, oldest first.

Show child attributes

curl --request POST \
  --url https://api.bolna.ai/trunk/trunks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Telnyx production",
  "preset": "telnyx",
  "channels": 20,
  "transport": "udp",
  "codecs": "PCMU,PCMA",
  "outbound_leading_plus_enabled": true,
  "auth_username": "bolna-outbound",
  "auth_password": "<carrier-issued password>",
  "gateways": [
    {
      "host": "sip.example.com",
      "port": 5060,
      "priority": 0
    }
  ],
  "ip_acls": [
    "203.0.113.10",
    "198.51.100.0/28"
  ]
}
'

{
  "id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
  "name": "Telnyx production",
  "description": null,
  "preset": "telnyx",
  "is_active": true,
  "inbound_enabled": true,
  "outbound_enabled": true,
  "channels": 20,
  "default_inbound_agent_id": null,
  "auth_username": "bolna-outbound",
  "transport": "udp",
  "codecs": "PCMU,PCMA",
  "outbound_leading_plus_enabled": true,
  "last_inbound_at": null,
  "last_outbound_at": null,
  "converted_from_byot_trunk_id": null,
  "organization_id": "7a1c2e3f-4b5d-4c6e-8f90-a1b2c3d4e5f6",
  "sub_account_id": null,
  "user_id": null,
  "created_at": "2026-10-16T09:12:44.512381+00:00",
  "updated_at": "2026-10-16T09:12:44.512381+00:00",
  "is_deleted": false,
  "deleted_at": null,
  "health": "waiting_for_carrier",
  "active_calls": 0,
  "gateways": [
    {
      "id": "8b1d4e2f-0a3c-4d5e-9f60-7182a3b4c5d6",
      "trunk_id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
      "host": "sip.example.com",
      "resolved_ips": [
        "203.0.113.30"
      ],
      "port": 5060,
      "priority": 0,
      "created_at": "2026-10-16T09:12:44.512381+00:00",
      "updated_at": "2026-10-16T09:12:44.512381+00:00",
      "is_deleted": false,
      "deleted_at": null
    }
  ],
  "ip_acls": [
    {
      "id": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
      "trunk_id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
      "cidr": "203.0.113.10/32",
      "created_at": "2026-10-16T09:12:44.512381+00:00",
      "updated_at": "2026-10-16T09:12:44.512381+00:00",
      "is_deleted": false,
      "deleted_at": null
    },
    {
      "id": "d3e4f5a6-b7c8-4d9e-8f01-2b3c4d5e6f7a",
      "trunk_id": "3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21",
      "cidr": "198.51.100.0/28",
      "created_at": "2026-10-16T09:12:44.512381+00:00",
      "updated_at": "2026-10-16T09:12:44.512381+00:00",
      "is_deleted": false,
      "deleted_at": null
    }
  ],
  "numbers": []
}

{
  "message": "198.48.0.0/12 is broader than /16"
}

{
  "detail": {
    "code": "gateway_conflict",
    "message": "gateway sip.example.com is used by another trunk; a shared gateway needs carrier credentials on every trunk that uses it"
  }
}

{
  "detail": [
    {
      "loc": [
        "body",
        "channels"
      ],
      "msg": "Input should be less than or equal to 1000",
      "type": "less_than_equal"
    }
  ]
}

Get started

Voice agents

Telephony

Workflows

Account

Legacy

Create SIP trunk API

Next steps

Authorizations

Body

Response

​Next steps

Authorizations

Body

Response

Next steps