Skip to main content
POST
Create a trunk
Use this endpoint to create a new SIP trunk for handling voice traffic. Each trunk can be configured with rate limits, authentication methods (credentials and IP ACLs), and origination URIs for outbound routing. The request takes three fields: a name, a direction, and a concurrent-call limit. Vobiz returns the new Trunk object with its trunk_id and an auto-generated SIP domain. Authentication and routing are added afterwards with their own endpoints.

When to use it

  • Connect a PBX, SBC, or carrier to Vobiz over SIP for inbound or outbound calling.
  • Give an AI voice agent its own trunk so its call limits are separate from your other traffic.
  • Separate environments or customers onto their own trunks, each with its own concurrent_calls_limit.
Authentication required:
  • X-Auth-ID - Your account Auth ID
  • X-Auth-Token - Your account Auth Token
  • Content-Type: application/json
Auto-Generated Domain: Upon creation, Vobiz automatically generates a unique SIP domain for your trunk in the format: trunk_id.sip.vobiz.ai. This domain is used for routing inbound calls to your trunk.

Request Parameters

Only three fields are required to create a trunk. The rest of the trunk’s configuration - transport, TLS/SRTP, recording, attached credentials, IP ACLs, and origination URIs - is applied afterwards through the dedicated endpoints or the Console.

Request headers

Trunk direction

trunk_type is sent in uppercase. The trunk object reports the direction in lowercase as trunk_direction, and carries different routing fields for each direction.
Defaults applied at creation. New trunks come back with cps_limit: 2, secure: false, transport: udp, and trunk_status: active. The trunk_domain is auto-generated as {trunk_id}.sip.vobiz.ai. Tune limits later with Update a Trunk, and attach auth and routing with Credentials, IP ACLs, and Origination URIs.

Defaults applied at creation

cps_limit vs concurrent_calls_limit. cps_limit caps how many new calls can be started per second (flood protection); concurrent_calls_limit caps how many calls can be live at once (capacity and cost control). They are independent.

Examples

Response

Returns the complete trunk object, including the auto-generated trunk_id UUID and timestamps.
Response - 201 Created

Response fields

See The Trunk Object for the full reference.

Next steps

A new trunk has a name, a direction, and a call limit. To make it usable:
  1. Save the trunk_id. Every other trunk endpoint needs it.
  2. Add credentials or IP ACLs for authentication.
  3. Configure origination URIs for outbound call routing.
  4. Adjust limits if needed with Update a Trunk.
  5. Test the trunk with a sample call before production use.

Choose an authentication method

A new trunk has no authentication attached. Add one or both of these methods after you create it. See SIP Trunking for details. You can combine both methods on the same trunk.

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID

X-Auth-Token
string
header
required

Your Vobiz account Auth Token

Path Parameters

auth_id
string
required

Your account Auth ID

Example:

"MA_XXXXXX"

Body

application/json
name
string
required

Trunk name.

Maximum string length: 100
trunk_direction
enum<string>

Direction of the trunk - inbound or outbound only (a trunk is one direction, not both).

Available options:
inbound,
outbound
trunk_status
enum<string>

Trunk status to set - enabled or disabled. Responses report enabled as active and disabled as suspended.

Available options:
enabled,
disabled
secure
boolean
trunk_domain
string

SIP domain. Auto-generated as {first8ofUUID}.sip.vobiz.ai if omitted.

Maximum string length: 255
transport
enum<string>
Available options:
udp,
tcp,
tls
inbound_destination
string
Maximum string length: 255
description
string
Maximum string length: 500
concurrent_calls_limit
integer

Stored on the trunk. The enforced concurrency limit is account-level (account base + channel subscriptions), not this field.

Required range: 0 <= x <= 1000
cps_limit
integer

Stored on the trunk. The enforced CPS is account-level, not this field.

Required range: 0 <= x <= 100
credential_uuid
string

Attach an existing SIP credential (username / password / realm) by UUID.

ipacl_uuid
string

Attach an existing IP access-control list (IP-based auth) by UUID.

primary_uri_uuid
string

Primary origination URI UUID.

fallback_uri_uuid
string

Fallback origination URI UUID.

recording
boolean
default:false

Enable call recording.

enable_transcription
boolean
default:false

Auto-transcribe recordings when recording=true.

pii_redaction
boolean
default:false

Redact PII from transcriptions.

pii_entity_types
string

Comma-separated list of entity types to redact.

webhook_url
string

Customer webhook for call-admission events (CallInitiated / Hangup). Must be a valid public http/https URL. SSRF-validated - localhost, private (RFC1918), and cloud-metadata (169.254.169.254) URLs are rejected with invalid webhook_url. See Trunk Webhooks.

Maximum string length: 500
Example:

"https://example.com/vobiz/webhook"

webhook_method
enum<string>
default:POST

HTTP method for the webhook callback.

Available options:
POST,
GET
recording_webhook_enabled
boolean
default:false

Fire a recording.completed webhook to webhook_url after a recording is saved.

username
string
deprecated

Deprecated - use credential_uuid.

Maximum string length: 100
password
string
deprecated

Deprecated - use credential_uuid.

Maximum string length: 100
ip_whitelist
string[]
deprecated

Deprecated - use ipacl_uuid.

Response

Success

trunk_id
string
required
account_id
string
required
name
string
required
trunk_domain
string
required
trunk_status
enum<string>
required

Trunk state as reported in responses - active or suspended. Requests set it with enabled (reported as active) or disabled (reported as suspended).

Available options:
active,
suspended
secure
boolean
required
trunk_direction
string
required
concurrent_calls_limit
integer
required
cps_limit
integer
required
description
string
required
transport
string
required
recording
boolean
required
enable_transcription
boolean
required
pii_redaction
boolean
required
webhook_method
string
required
recording_webhook_enabled
boolean
required
created_at
string
required
updated_at
string
required