Trunks

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

string

Unique identifier for the trunk.

string

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

string

Friendly name for the trunk.

string

Status of the trunk: enabled or disabled.

string

Direction of the trunk: inbound or outbound.

boolean

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

string

IP access control list UUID (for outbound trunks).

string

Credentials list UUID (for outbound trunks).

string

Primary origination URI UUID (for inbound trunks).

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

object

Pagination metadata: limit (results per page), offset (items skipped), total_count (total matching trunks), previous and next (relative URLs for adjacent pages).

array

Array of trunk objects — see The Trunk Object.

{
  "meta": {
    "limit": 2,
    "offset": 0,
    "total_count": 10,
    "previous": null,
    "next": "/v1/Account/{auth_id}/Zentrunk/Trunk/?limit=2&offset=2"
  },
  "objects": [
    {
      "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
    },
    {
      "name": "trunk_name_2",
      "trunk_id": "31784177241575",
      "trunk_domain": "31784177241575.zt.plivo.com",
      "trunk_status": "enabled",
      "secure": false,
      "trunk_direction": "inbound",
      "ipacl_uuid": null,
      "credential_uuid": null,
      "primary_uri_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb",
      "fallback_uri_uuid": "796c-4d86-a4fd-44ed11667ddb-eb07"
    }
  ]
}

Example

cURL

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

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.

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

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

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

string

Unique identifier for the API request.

string

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

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

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/

Inbound Trunk Example

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

cURL

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/

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

string

Unique identifier for the API request.

string

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

string

Unique identifier for the trunk.

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

Example

cURL

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}/

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

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

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

Concepts

SIP REFER

Security

API Reference

Troubleshooting

PBX Integration

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

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