Trunks - Plivo

The Trunks API lets you create and manage SIP trunks that route voice traffic between your infrastructure and Plivo’s network.

API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/

The Trunk Object

A trunk represents a SIP connection between your infrastructure and Plivo’s network. Trunks can be inbound (receiving calls from Plivo) or outbound (sending calls to Plivo).

Attributes

trunk_id

string

Unique identifier for the trunk.

trunk_domain

string

Unique address on Plivo to route SIP traffic (e.g., 21784177241578.zt.plivo.com).

name

string

Friendly name for the trunk.

trunk_status

string

Status of the trunk: enabled or disabled.

trunk_direction

string

Direction of the trunk: inbound or outbound.

secure

boolean

Whether SRTP (media) and TLS (signaling) encryption is enabled.

ipacl_uuid

string

IP access control list UUID (for outbound trunks).

credential_uuid

string

Credentials list UUID (for outbound trunks).

primary_uri_uuid

string

Primary origination URI UUID (for inbound trunks).

fallback_uri_uuid

string

Fallback origination URI UUID (for inbound trunks).

Example Object

{
  "name": "trunk_name_1",
  "trunk_id": "21784177241578",
  "trunk_domain": "21784177241578.zt.plivo.com",
  "trunk_status": "enabled",
  "secure": true,
  "trunk_direction": "outbound",
  "ipacl_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
  "credential_uuid": "eb07-796c-4d86-a4fd-44ed11667ddb",
  "primary_uri_uuid": null,
  "fallback_uri_uuid": null
}

List All Trunks

Get all trunks with optional filtering.

HTTP Request

GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/

Query Parameters

Parameter	Type	Required	Default	Description
`trunk_status`	string	No	-	Filter by status: `enabled`, `disabled`
`trunk_direction`	string	No	-	Filter by direction: `inbound`, `outbound`
`secure`	boolean	No	-	Filter by encryption: `true`, `false`
`ipacl_uuid`	string	No	-	Filter by IP ACL
`credential_uuid`	string	No	-	Filter by credentials
`primary_uri_uuid`	string	No	-	Filter by primary URI
`fallback_uri_uuid`	string	No	-	Filter by fallback URI
`limit`	integer	No	20	Results per page (1-20)
`offset`	integer	No	0	Pagination offset

Response

Example

curl -i --user AUTH_ID:AUTH_TOKEN \
    "https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/?trunk_direction=outbound&limit=10"

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

# List all trunks
response = client.zentrunk.trunks.list()
print(response)

# List with filters
response = client.zentrunk.trunks.list(
    trunk_direction='outbound',
    limit=10
)
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

// List all trunks
client.zentrunk.trunks.list()
  .then(response => console.log(response));

// List with filters
client.zentrunk.trunks.list({
  trunkDirection: 'outbound',
  limit: 10
}).then(response => console.log(response));

Retrieve a Trunk

Get details of a specific trunk.

HTTP Request

GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/{trunk_id}/

Response

Returns the trunk object nested under the object key.

api_id

string

Unique identifier for the API request.

object

The trunk object — see The Trunk Object.

{
  "api_id": "9c5d6b6f-bf14-4036-b504-87e78fe94213",
  "object": {
    "trunk_id": "21784177241578",
    "name": "trunk_name_1",
    "trunk_status": "enabled",
    "secure": true,
    "trunk_domain": "21784177241578.zt.plivo.com",
    "trunk_direction": "outbound",
    "ipacl_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
    "credential_uuid": "eb07-796c-4d86-a4fd-44ed11667ddb",
    "primary_uri_uuid": null,
    "fallback_uri_uuid": null
  }
}

Example

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/21784177241578/

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.trunks.get('21784177241578')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.zentrunk.trunks.get('21784177241578')
  .then(response => console.log(response));

Create a Trunk

Create a new SIP trunk for inbound or outbound traffic.

HTTP Request

POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/

Request Parameters

Parameter	Type	Required	Default	Description
`name`	string	No	-	Friendly name for the trunk
`trunk_direction`	string	Yes	-	Direction: `inbound` or `outbound`
`trunk_status`	string	No	`enabled`	Status: `enabled` or `disabled`
`secure`	boolean	No	`false`	Enable SRTP/TLS encryption
`ipacl_uuid`	string	Conditional	-	IP ACL UUID. Required for outbound trunks
`credential_uuid`	string	Conditional	-	Credentials UUID. Required for outbound trunks
`primary_uri_uuid`	string	Conditional	-	Primary origination URI. Required for inbound trunks
`fallback_uri_uuid`	string	No	-	Fallback origination URI for inbound trunks

Response

api_id

string

Unique identifier for the API request.

message

string

Status of the request. Returns Trunk created successfully. on a successful creation.

trunk_id

string

Unique identifier for the trunk.

{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "Trunk created successfully.",
  "trunk_id": "986908123123411213"
}

Error Codes

Code	Description
400	Invalid request parameters
401	Authentication failed
422	Missing required parameters (e.g., ipacl_uuid for outbound trunk)

Outbound Trunk Example

For outbound trunks (calls from your PBX to Plivo), you need either ipacl_uuid or credential_uuid for authentication.

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "outbound-trunk",
      "trunk_direction": "outbound",
      "trunk_status": "enabled",
      "ipacl_uuid": "1c13de4c-423d-11e3-9899-22000abfa5d5"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.trunks.create(
    name='outbound-trunk',
    trunk_direction='outbound',
    trunk_status='enabled',
    ipacl_uuid='1c13de4c-423d-11e3-9899-22000abfa5d5'
)
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.zentrunk.trunks.create({
  name: 'outbound-trunk',
  trunkDirection: 'outbound',
  trunkStatus: 'enabled',
  ipaclUuid: '1c13de4c-423d-11e3-9899-22000abfa5d5'
}).then(response => console.log(response));

Inbound Trunk Example

For inbound trunks (calls from Plivo to your PBX), you need a primary_uri_uuid pointing to your server.

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "inbound-trunk",
      "trunk_direction": "inbound",
      "trunk_status": "enabled",
      "primary_uri_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
      "fallback_uri_uuid": "796c-4d86-a4fd-44ed11667ddb-eb07"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.trunks.create(
    name='inbound-trunk',
    trunk_direction='inbound',
    trunk_status='enabled',
    primary_uri_uuid='90b6eb07-796c-4d86-a4fd-44ed11667ddb',
    fallback_uri_uuid='796c-4d86-a4fd-44ed11667ddb-eb07'
)
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.zentrunk.trunks.create({
  name: 'inbound-trunk',
  trunkDirection: 'inbound',
  trunkStatus: 'enabled',
  primaryUriUuid: '90b6eb07-796c-4d86-a4fd-44ed11667ddb',
  fallbackUriUuid: '796c-4d86-a4fd-44ed11667ddb-eb07'
}).then(response => console.log(response));

Update a Trunk

Modify an existing trunk’s properties.

HTTP Request

POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/{trunk_id}/

Request Parameters

Parameter	Type	Required	Default	Description
`name`	string	No	-	New name for the trunk
`trunk_status`	string	No	-	Status: `enabled` or `disabled`
`trunk_direction`	string	No	-	Direction: `inbound` or `outbound`
`secure`	boolean	No	-	Enable/disable SRTP/TLS encryption
`ipacl_uuid`	string	No	-	New IP ACL UUID
`credential_uuid`	string	No	-	New credentials UUID
`primary_uri_uuid`	string	No	-	New primary origination URI
`fallback_uri_uuid`	string	No	-	New fallback origination URI

Response

api_id

string

Unique identifier for the API request.

message

string

Status of the request. Returns Trunk updated successfully. on a successful update.

trunk_id

string

Unique identifier for the trunk.

{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "Trunk updated successfully.",
  "trunk_id": "986908123123411213"
}

Example

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"name": "updated-trunk-name", "trunk_status": "disabled"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/{trunk_id}/

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.trunks.update(
    '<trunk_id>',
    name='updated-trunk-name',
    trunk_status='disabled'
)
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.zentrunk.trunks.update('<trunk_id>', {
  name: 'updated-trunk-name',
  trunkStatus: 'disabled'
}).then(response => console.log(response));

Delete a Trunk

Permanently delete a trunk.

HTTP Request

DELETE https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/{trunk_id}/

Response

HTTP 204 No Content

Example

curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/{trunk_id}/

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.trunks.delete('<trunk_id>')
print(response)

const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');

client.zentrunk.trunks.delete('<trunk_id>')
  .then(response => console.log(response));

Trunk Types

Trunk Type	Purpose	Can Attach to Phone Numbers?
Inbound	Route calls from Plivo to your PBX/infrastructure	Yes
Outbound	Route calls from your PBX/infrastructure to Plivo	No

Only inbound trunks can be attached to phone numbers. If you create an outbound trunk, it will not appear in the phone number configuration dropdown. To receive calls on a Plivo number via SIP, you must create an inbound trunk.

Outbound Trunks

Route calls from your PBX/infrastructure to Plivo:

Your system sends SIP INVITE to the trunk domain
Authentication via IP ACL or credentials
Calls terminate on PSTN via Plivo

Inbound Trunks

Route calls from Plivo to your PBX/infrastructure:

Calls arrive at Plivo (from PSTN or Plivo numbers)
Plivo forwards to your origination URI
Fallback URI used if primary fails
Can be attached to purchased phone numbers

Credentials - Manage SIP credentials
IP Access Control Lists - Manage IP whitelists
Origination URIs - Manage destination URIs

​API Endpoint

​The Trunk Object

​Attributes

​Example Object

​List All Trunks

​HTTP Request

​Query Parameters

​Response

​Example

​Retrieve a Trunk

​HTTP Request

​Response

​Example

​Create a Trunk

​HTTP Request

​Request Parameters

​Response

​Error Codes

​Outbound Trunk Example

​Inbound Trunk Example

​Update a Trunk

​HTTP Request

​Request Parameters

​Response

​Example

​Delete a Trunk

​HTTP Request

​Response

​Example

​Trunk Types

​Outbound Trunks

​Inbound Trunks

​Related

API Endpoint

The Trunk Object

Attributes

Example Object

List All Trunks

HTTP Request

Query Parameters

Response

Example

Retrieve a Trunk

HTTP Request

Response

Example

Create a Trunk

HTTP Request

Request Parameters

Response

Error Codes

Outbound Trunk Example

Inbound Trunk Example

Update a Trunk

HTTP Request

Request Parameters

Response

Example

Delete a Trunk

HTTP Request

Response

Example

Trunk Types

Outbound Trunks

Inbound Trunks

Related