Documentation
Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Update a SIP trunk

PATCH
/v1/voice/trunks/{trunk_id}
const trunk = await bird.voice.trunks.update("spt_01krdgeqcxet5s7t44vh8rt9mg", {
  // Each list replaces the previous one, so send what you want to end up with.
  ip_acls: [{ cidr: "203.0.113.0/24", description: "Amsterdam PBX" }],
});
console.log(trunk.ip_acls);
Response200
{
  "id": "spt_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "name": "Production PBX trunk",
  "domain": "01kxp5bb9qf878642atrf0xy5r.trunk.eu1.sip.bird.com",
  "ip_acls": [
    {
      "id": "sta_01krdgeqcxet5s7t44vh8rt9mg",
      "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg",
      "cidr": "203.0.113.0/24",
      "description": "Office network"
    }
  ],
  "allowed_api_key_ids": [
    "key_01krdgeqcxet5s7t44vh8rt9mg"
  ],
  "ineligible_api_key_ids": [
    "key_01krdgeqcxet5s7t44vh8rt9mg"
  ],
  "digest_algorithms": [
    "SHA-256",
    "MD5"
  ],
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}
Updates a SIP trunk's name, access control (ip_acls, allowed_api_key_ids), and Digest algorithm offer (digest_algorithms). Omitted fields stay unchanged; each list, when present, replaces the previous list wholesale. An empty body or invalid list entry returns a 422 validation_error; a trunk outside the workspace returns a 404 not_found_error.
Parameters
trunk_id
string
Request Payload
name
string
A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain.
outbound_enabled
boolean
Whether this trunk may place calls. Turning it off stops the trunk admitting call attempts at the next call setup and leaves its connection and authentication settings stored, so turning it back on restores a working trunk. Omit the field to leave it unchanged.
inbound_enabled
boolean
Whether this trunk may receive calls. Turning it off resets number routes that use this trunk to reject incoming calls. Turning it back on does not restore those routes. The gateways remain configured. Omit the field to leave it unchanged.
media_bypass
boolean
Whether we take ourselves out of the audio path for calls we forward to this trunk. Turning it on takes effect at the next call setup and leaves calls already up untouched. It is an inbound setting, so the trunk must have inbound_enabled on; one update can do both. While it is on we cannot record those calls, report their audio quality, or end one because its audio stopped, and your equipment must be reachable for audio from the public internet. Turning it off puts us back in the path at the next call setup. Omit the field to leave it unchanged.
ip_acls
array of object
Replaces the trunk's entire IP allow list. When present, the allow list is set to exactly these CIDR blocks: ranges not listed are removed and new ones are added. Send an empty array to clear the list, turning IP filtering off. Omit the field to leave the allow list unchanged.
Show child parameters
ip_acls.cidr
string
required
IPv4 or IPv6 CIDR block to allow. Use /32 for a single IPv4 address or /128 for a single IPv6 address.
ip_acls.description
string
Optional human-readable label for this ACL entry.
allowed_api_key_ids
array of string
Replaces the trunk's entire set of allowed API keys. When present, exactly these keys may authenticate the trunk over SIP Digest. Each key you ADD must belong to this workspace and hold voice at write level; a key that does not is refused and the whole update is rolled back. A key already on the list that has since lost the permission or expired does not block the update, so you can keep editing the trunk while you put its permission back. A non-empty list turns API-key authentication on; send an empty array to turn it off. Omit the field to leave the allowed keys unchanged.
digest_algorithms
array of string
Replaces the Digest hash algorithms this trunk offers, in the order they should be offered. Send ["MD5"] for a PBX that only implements MD5 and rejects or ignores a challenge offering SHA-256 first. Send an empty array to return to the default of ["SHA-256", "MD5"]. The offer is never empty, because a trunk that offered nothing could not be authenticated at all. Narrowing the list also narrows what the trunk accepts: an answer using an algorithm no longer offered is rejected. Takes effect on the next call setup; no credential is re-issued. Omit the field to leave the offer unchanged.
session_credentials_enabled
boolean
Whether a session credential may be used to connect to this trunk from a web browser, the CLI or MCP. Off by default; turning it on does not change what the allow lists admit, and turning it off stops those connections at the next call setup without re-issuing anything. Omit the field to leave it unchanged.
Response Payload
id
string
required
Unique identifier for this SIP trunk.
workspace_id
string
required
name
string
required
A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain.
domain
string
required
Full SIP address for this trunk, generated as {trunk-id}.trunk.{region}.sip.bird.com. This is the trunk's identity, so configure your PBX or SIP client to send calls to this address. It is derived from the trunk id and cannot be chosen or changed.
outbound_enabled
boolean
required
Whether this trunk may place calls: your PBX connects to us to dial out. Off on a new trunk. While it is off the trunk refuses every call attempt no matter what its allow lists say, and the connection and authentication settings below have no effect. Set outbound_enabled through the trunk update operation.
inbound_enabled
boolean
required
Whether this trunk may receive calls: we dial the addresses you declared, for the numbers this trunk answers. Off on a new trunk. Turning it off resets number routes that use this trunk to reject incoming calls. Turning it back on does not restore those routes. Set inbound_enabled through the trunk update operation.
media_bypass
boolean
required
Whether we take ourselves out of the audio path for calls we forward to this trunk: your equipment and the originating carrier exchange audio directly, and only the call signalling passes through us. Off by default. It applies to inbound calls alone (calls this trunk places are always carried through us, whatever this says). While it is on we cannot record those calls, report their audio quality, or end one because its audio stopped. Your equipment must be reachable for audio from the public internet. Set media_bypass through the trunk update operation.
ip_acls
array of object
required
The trunk's IP allow list. IP filtering is active whenever this has at least one entry: calls admitted through the allow lists must come from those CIDR ranges. This restriction does not apply to session credentials when session_credentials_enabled is true. An empty list means no IP restriction. Replace the whole ip_acls list through the trunk update operation.
Show child attributes
ip_acls.id
string
required
Unique identifier for this IP ACL entry.
ip_acls.trunk_id
string
required
ip_acls.cidr
string
required
IPv4 or IPv6 CIDR block that is allowed to send SIP traffic to this trunk.
ip_acls.description
nullable string
Optional human-readable label for this ACL entry.
ip_acls.created_at
string
required
allowed_api_key_ids
array of string
required
The API keys allowed to authenticate this trunk over SIP Digest. A key must hold voice at write level and be neither revoked nor expired to authenticate. ineligible_api_key_ids names the entries that currently cannot. A nonempty list enables API-key authentication, limited to its eligible keys. An empty list means no API-key authentication. A trunk with empty ip_acls and allowed_api_key_ids lists accepts nothing when session_credentials_enabled is false. Replace the whole allowed_api_key_ids list through the trunk update operation.
ineligible_api_key_ids
array of string
required
The entries in allowed_api_key_ids that cannot authenticate this trunk right now because the key lacks voice at write level, has expired, or was revoked. The bindings remain until you remove them from the trunk. Restoring voice at write level makes a key eligible again if it is still unexpired and unrevoked, without changing its secret or trunk binding. Empty when every allowed key can authenticate.
digest_algorithms
array of string
required
The Digest hash algorithms this trunk offers, in the order they are offered. We send one challenge line per algorithm and your PBX answers with the first it supports, so the order decides what most equipment picks. Always populated: a trunk with no explicit setting reports the default, ["SHA-256", "MD5"]. A trunk answering with an algorithm that is not on this list is rejected, so narrowing the list also narrows what the trunk accepts. Replace digest_algorithms through the trunk update operation.
session_credentials_enabled
boolean
required
Whether a session credential may be used to connect to this trunk from a web browser, the CLI or MCP, alongside whatever the allow lists admit. Off by default. It grants nothing on its own: a call still has to present a credential issued to this workspace, and each one expires within minutes. Set session_credentials_enabled through the trunk update operation.
created_at
string
required
updated_at
string
required

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Understand the conceptShould I use a Bird SDK or call the API directly?Follow the learning pathBuild your first integrationImplementation guideSend your first email
Get an implementation brief