API ReferenceTelephonySIP trunks

Create SIP Trunk

Beta

Create a SIP trunk. For provider=byoc supply sip_address plus optional digest credentials and IP allowlist. For provider=twilio use ImportPhoneNumber with a twilio spec instead - trunk creation is handled automatically. Returns 422 when the workspace has reached the 20-trunk cap.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Headers

Speechify-VersionstringOptional

Request

This endpoint expects an object.
namestringRequired

Human-readable name for the trunk.

providerenumRequired

Which provider backs the trunk. Informs the provisioning path and portability story.

  • livekit - Provisioned by LiveKit’s native phone-number API.
  • twilio - Backed by a Twilio Elastic SIP Trunk on the customer’s account.
  • telnyx - Backed by a Telnyx FQDN connection on the customer’s account.
  • byoc - Any SIP provider with a customer-managed trunk.
directionenumRequired

Whether the trunk handles inbound calls, outbound calls, or both. A both trunk has distinct provider inbound and outbound trunk IDs.

sip_addressstringOptional

SIP endpoint hostname. Required for provider=byoc.

auth_usernamestringOptional
SIP digest auth username.
auth_passwordstringOptional

SIP digest auth password. Write-only.

allowed_addresseslist of stringsOptional

IP / CIDR allowlist for inbound connections. Empty means any source is accepted.

destination_countrystringOptional

ISO 3166-1 alpha-2 country for the outbound dial plan.

transportenumOptional

SIP transport protocol. auto lets LiveKit negotiate. Use tls for production where available - note that TLS is incompatible with SIP REFER (cold transfer). Trunks that need transfer_to_number should use udp or tcp.

media_encryptionenumOptional

SRTP media encryption policy.

  • disable - Unencrypted media only.
  • allow - Negotiate SRTP; fall back to unencrypted. Recommended default.
  • require - Reject calls that do not support SRTP.
credentialsobjectOptional

Provider-specific credential blob (for future extensibility).

Response headers

X-Request-IDstring
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The created SIP trunk.
idstringformat: "^trunk_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (trunk_<26 char Crockford base32>). URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

namestring

Human-readable name.

providerenum

Which provider backs the trunk. Informs the provisioning path and portability story.

  • livekit - Provisioned by LiveKit’s native phone-number API.
  • twilio - Backed by a Twilio Elastic SIP Trunk on the customer’s account.
  • telnyx - Backed by a Telnyx FQDN connection on the customer’s account.
  • byoc - Any SIP provider with a customer-managed trunk.
directionenum

Whether the trunk handles inbound calls, outbound calls, or both. A both trunk has distinct provider inbound and outbound trunk IDs.

allowed_addresseslist of strings

IP address / CIDR allowlist for inbound SIP connections.

transportenum

SIP transport protocol. auto lets LiveKit negotiate. Use tls for production where available - note that TLS is incompatible with SIP REFER (cold transfer). Trunks that need transfer_to_number should use udp or tcp.

media_encryptionenum

SRTP media encryption policy.

  • disable - Unencrypted media only.
  • allow - Negotiate SRTP; fall back to unencrypted. Recommended default.
  • require - Reject calls that do not support SRTP.
created_atdatetime
updated_atdatetime
outbound_trunk_setboolean

Whether an outbound trunk is provisioned for this trunk (i.e. it can place outbound calls).

sip_addressstring

SIP endpoint hostname (e.g. sip.telnyx.com). Required for provider=byoc.

auth_usernamestring
SIP digest auth username.
auth_password_setboolean
Whether a SIP digest auth password is configured. The value is never returned.
destination_countrystring

ISO 3166-1 alpha-2 country code for the outbound dial plan (e.g. US, DE). Required for international outbound on some carriers.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error