voice-trunks

Create a SIP trunk

Provisions a new SIP trunk for the workspace. Bird assigns a unique domain for the trunk; use this domain as the SIP registrar or proxy address in your PBX or SIP client. Pass digest_algorithms when the PBX needs a specific Digest hash, such as MD5-only equipment. Otherwise the trunk offers Bird's default of SHA-256 then MD5.

post/v1/voice/trunks

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/voice/trunks
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

namestring required

A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain.

outbound_enabledboolean

Whether the new trunk may place calls. Omit it to create a trunk that does neither direction yet, and enable the ones you want once you know what the trunk is for. The settings below configure outbound, so send this as true alongside them.

inbound_enabledboolean

Whether the new trunk may receive calls. Omit it to create a trunk that does neither direction yet. A trunk receives no calls until it also has at least one gateway and at least one number, both added after create.

media_bypassboolean

Whether we take ourselves out of the audio path for calls we forward to this trunk. Omit it to create the trunk with this off, which is what suits equipment behind NAT and any account that wants call recording. It is an inbound setting, so true is accepted only alongside inbound_enabled: true; false is always accepted. It can be changed later.

digest_algorithmsVoiceSIPDigestAlgorithm[]

The Digest hash algorithms to offer, in the order they should be offered. Omit this to use the default of ["SHA-256", "MD5"], which suits most equipment. Send ["MD5"] for a PBX that only implements MD5 and rejects or ignores a challenge offering SHA-256 first. This can be changed later without re-issuing credentials.

session_credentials_enabledboolean

Whether a session credential may be used to connect to this trunk from a web browser, the CLI or MCP. Omit it to create the trunk with this off, which is what a trunk reached only by a PBX wants. It can be changed later.

Example request

{
  "name": "Production PBX trunk",
  "outbound_enabled": true,
  "inbound_enabled": true,
  "media_bypass": true,
  "digest_algorithms": [
    "MD5"
  ],
  "session_credentials_enabled": true
}

Response

SIP trunk created.

idstring required
workspace_idstring required
namestring required

A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain.

domainstring 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_enabledboolean 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_enabledboolean 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_bypassboolean 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.

allowed_api_key_idsAPIKeyID[] 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_idsAPIKeyID[] 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_algorithmsVoiceSIPDigestAlgorithm[] 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_enabledboolean 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_atstring date-time required
updated_atstring date-time required

Example response

{
  "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"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.