Manage Trunks

SIP trunks

A trunk holds your carrier’s SIP details: its SIP URL, credentials and the addresses it sends calls from. Map your numbers to a trunk and Unpod returns the origin endpoint - where your carrier sends calls for those numbers. Setting up your first trunk? Follow the Quick Start. This page covers each operation on its own. The samples read your credentials (UNPOD_BASE_URL, UNPOD_PLATFORM_TOKEN, UNPOD_ORG_HANDLE) from the environment.

List trunks

from unpod import Client

with Client() as client:
    for t in client.telephony.trunks.list():
        print(t.id, t.name, t.sip_url, t.transport, t.active)

curl -s "https://unpod.ai/api/v2/platform/telephony/trunks/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE"

Returns your org’s trunks, newest first. auth_password is masked. See List Trunks.

Get a trunk

from unpod import Client

TRUNK_ID = 21  # your trunk id

with Client() as client:
    trunk = client.telephony.trunks.get(TRUNK_ID)
    print(trunk.name, trunk.sip_url, trunk.allowed_ips)

TRUNK_ID=21  # your trunk id
curl -s "https://unpod.ai/api/v2/platform/telephony/trunks/$TRUNK_ID/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE"

A trunk your org doesn’t own returns 404. See Get Trunk.

Create a trunk

from unpod import Client

with Client() as client:
    trunk = client.telephony.trunks.create(
        "my-trunk",
        "sip:carrier.example.com",
        username="<sip-username>",
        password="<sip-password>",
        transport="tcp",
        port="5060",
        source_ips=["203.0.113.10", "198.51.100.0/24"],
    )
    print(trunk.id)

curl -s -X POST "https://unpod.ai/api/v2/platform/telephony/trunks/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-trunk",
    "sip_url": "sip:carrier.example.com",
    "auth_username": "<sip-username>",
    "auth_password": "<sip-password>",
    "transport": "tcp",
    "port": "5060",
    "source_ips": ["203.0.113.10", "198.51.100.0/24"]
  }'

Python	API field	Required	Meaning
`name`	`name`	Yes	Your label for the trunk
`sip_url`	`sip_url`	Yes	Carrier SIP URL or host
`username`, `password`	`auth_username`, `auth_password`	No	SIP auth credentials. The password is masked on every read
`transport`	`transport`	No	`tcp` (default), `udp` or `tls`
`port`	`port`	No	SIP port as a string (default `5060`)
`source_ips`	`source_ips`	No	Addresses your carrier sends calls from. CIDR ranges allowed. Read back as `allowed_ips`

Keep the returned id (data.id in the cURL response): you need it to map numbers, get or delete the trunk. The API has no call to update a trunk. See Create Trunk.

Map numbers to a trunk

Mapping takes number ids, not E.164 numbers. Only a NOT_ASSIGNED number can be mapped; detach an ASSIGNED number first (Detach a number). Read each number’s id from your org’s number list, GET /telephony/numbers/?include_assigned=true. The SDK’s numbers.list() doesn’t return the id yet - step 3 of the Quick Start shows a Python lookup. For numbers already on your org, client.telephony.overview() returns the same id as number_id - a pure-SDK way to find the ids to unmap.

from unpod import Client

TRUNK_ID = 21        # your trunk id
NUMBER_IDS = [501]   # NOT_ASSIGNED ids from your org's number list

with Client() as client:
    mapped = client.telephony.trunks.attach_numbers(TRUNK_ID, NUMBER_IDS)
    print(mapped.origin_endpoint.ingress)
    print(mapped.origin_endpoint.accepted_source_ips)
    for r in mapped.numbers:
        print(r.number_id, r.number, r.ok, r.error)

TRUNK_ID=21  # your trunk id
curl -s -X POST \
  "https://unpod.ai/api/v2/platform/telephony/trunks/$TRUNK_ID/attach-numbers/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"number_ids": [501]}'

The response has the origin endpoint: ingress is where your carrier sends calls, dids lists the numbers this request mapped, and accepted_source_ips are the addresses Unpod accepts them from. Each eligible number gets a row in numbers with its own ok and error; ids that aren’t an active NOT_ASSIGNED number are left out. If no id is eligible, the request fails with 400 No valid unassigned numbers found. (the SDK raises httpx.HTTPStatusError). See Attach Numbers to Trunk.

Unmap numbers

from unpod import Client

TRUNK_ID = 21  # your trunk id

with Client() as client:
    result = client.telephony.trunks.detach_numbers(TRUNK_ID, [501])
    for r in result.numbers:
        print(r.number_id, r.ok, r.error)

TRUNK_ID=21  # your trunk id
curl -s -X POST \
  "https://unpod.ai/api/v2/platform/telephony/trunks/$TRUNK_ID/detach-numbers/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"number_ids": [501]}'

Unmapping releases the number back to NOT_ASSIGNED. A number that isn’t on this trunk reports ok: false with Number is not mapped to this trunk. If no number unmaps, the request fails with 400 (the SDK raises httpx.HTTPStatusError). See Detach Numbers from Trunk.

Inbound config for a whole trunk

To send the trunk’s inbound calls to your app, set the inbound config on each of its numbers with set_did. It needs the Call API switched on for your org (otherwise 403 call_api_disabled).

from unpod import Client
from unpod.telephony import InboundConfig

NUMBERS = ["+15551234567"]  # the numbers mapped to the trunk (origin_endpoint.dids)

with Client() as client:
    inbound = client.telephony.inbound
    for number in NUMBERS:
        inbound.set_did(number, InboundConfig(
            answer_url="https://your-app.example.com/incoming",
        ))
        print(inbound.get_did(number))

# set (+ becomes %2B in the URL)
curl -s -X PUT "https://unpod.ai/api/v2/platform/sbc/v1/dids/%2B15551234567/inbound" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"answer_url": "https://your-app.example.com/incoming"}'

# read
curl -s "https://unpod.ai/api/v2/platform/sbc/v1/dids/%2B15551234567/inbound" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE"

A number that isn’t one of your org’s returns 404. set_trunk / PUT /sbc/v1/trunks/{name}/inbound take the trunk’s internal Unpod name, which this API doesn’t return yet: the name you gave the trunk returns 404. For every config field and how to answer the call, see For a whole SIP trunk.

Delete a trunk

Delete detaches every number on the trunk back to NOT_ASSIGNED and removes the trunk, all or nothing: if one number fails, nothing changes. Unmapping first shows you which number failed and why, so the sample unmaps, then deletes only once every number has unmapped. Running it again after a partial failure? Drop the ids that already unmapped: they now report ok: false, and if none unmap the request fails with 400.

from unpod import Client

TRUNK_ID = 21        # your trunk id
NUMBER_IDS = [501]   # every number mapped to the trunk

with Client() as client:
    trunks = client.telephony.trunks
    result = trunks.detach_numbers(TRUNK_ID, NUMBER_IDS)
    if all(r.ok for r in result.numbers):
        trunks.delete(TRUNK_ID)
    else:
        print([(r.number_id, r.error) for r in result.numbers if not r.ok])

TRUNK_ID=21  # your trunk id

# 1. unmap every number on the trunk
curl -s -X POST \
  "https://unpod.ai/api/v2/platform/telephony/trunks/$TRUNK_ID/detach-numbers/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"number_ids": [501]}'

# 2. delete the trunk
curl -s -X DELETE "https://unpod.ai/api/v2/platform/telephony/trunks/$TRUNK_ID/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE"

Delete returns 204, or 404 for a trunk that isn’t your org’s. If a number can’t be detached it returns 400 (or 206) with the reason in message and the trunk stays. trunks.delete() raises on the 400 but not on a 206, so check with trunks.get(TRUNK_ID): it raises httpx.HTTPStatusError with 404 once the trunk is gone. See Delete Trunk.

Getting Started

Telephony APIs

SIP Trunking

Integrations

SIP trunks

List trunks

Get a trunk

Create a trunk

Map numbers to a trunk

Unmap numbers

Inbound config for a whole trunk

Delete a trunk

​SIP trunks

​List trunks

​Get a trunk

​Create a trunk

​Map numbers to a trunk

​Unmap numbers

​Inbound config for a whole trunk

​Delete a trunk

SIP trunks

List trunks

Get a trunk

Create a trunk

Map numbers to a trunk

Unmap numbers

Inbound config for a whole trunk

Delete a trunk