API Reference

SIP Trunking API for AI voice agents - Trunks, Credentials, URIs, and IP ACLs

Connect AI voice agent platforms (ElevenLabs, LiveKit, Vapi) to Plivo’s telephony network via SIP trunking.

Summary

Direction	Setup Steps	Use Case
Outbound (AI → Phone)	1. Create Credentials or IP ACL → 2. Create Outbound Trunk	Your AI agent calls phone numbers
Inbound (Phone → AI)	1. Create Origination URI → 2. Create Inbound Trunk → 3. Assign phone number	Callers reach your AI agent

---

Outbound Calls (AI Agent → Phone)

Route calls from your AI agent platform to phone numbers via PSTN.

Step 1: Create Authentication

Choose one authentication method:

Credentials (Username/Password)

Use when your AI platform has dynamic IPs or you need SIP digest authentication.

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

Parameter	Type	Required	Description
name	string	No	Friendly name
username	string	Yes	SIP authentication username
password	string	Yes	SIP authentication password

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "elevenlabs-credentials",
      "username": "elevenlabs_user",
      "password": "securepassword123!"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/

Response:

{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "credential created successfully.",
  "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}

Save the credential_uuid for trunk creation.

IP Access Control List

Use when your AI platform has static IP addresses. Simpler setup, no password management.

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

Parameter	Type	Required	Description
name	string	No	Friendly name
ip_addresses	array	Yes	IP addresses to whitelist

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "livekit-servers",
      "ip_addresses": ["52.1.2.3", "52.1.2.4", "52.1.2.5"]
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/

Response:

{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "IP access control list created successfully.",
  "ipacl_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}

Save the ipacl_uuid for trunk creation.

Step 2: Create Outbound Trunk

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

Parameter	Type	Required	Description
name	string	No	Friendly name
trunk_direction	string	Yes	Must be outbound
trunk_status	string	No	enabled (default) or disabled
secure	boolean	No	Enable SRTP/TLS. Default: false
credential_uuid	string	Conditional	From Step 1 (if using credentials)
ipacl_uuid	string	Conditional	From Step 1 (if using IP ACL)

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "elevenlabs-outbound",
      "trunk_direction": "outbound",
      "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/

Response:

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

The create response returns only the trunk_id. To get the trunk’s SIP domain, retrieve the trunk:

cURL

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

Response:

{
  "api_id": "9c5d6b6f-bf14-4036-b504-87e78fe94213",
  "object": {
    "trunk_id": "21784177241578",
    "name": "elevenlabs-outbound",
    "trunk_status": "enabled",
    "secure": false,
    "trunk_domain": "21784177241578.zt.plivo.com",
    "trunk_direction": "outbound",
    "ipacl_uuid": null,
    "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
    "primary_uri_uuid": null,
    "fallback_uri_uuid": null
  }
}

Step 3: Configure Your AI Platform

Use the trunk_domain from Step 2 (e.g., 21784177241578.zt.plivo.com) as the SIP address in your AI platform’s configuration. Your platform sends SIP INVITE to this domain to place outbound calls.

---

Inbound Calls (Phone → AI Agent)

Route incoming phone calls to your AI agent platform.

Step 1: Create Origination URI

Define where Plivo sends inbound calls (your AI platform’s SIP endpoint).

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

Parameter	Type	Required	Description
name	string	No	Friendly name
uri	string	Yes	Your AI platform’s SIP address
authentication_needed	boolean	No	Require auth. Default: false
username	string	Conditional	Username (if auth enabled)
password	string	Conditional	Password (if auth enabled)

Without Authentication

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "livekit-primary",
      "uri": "sip.livekit.cloud:5060"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/

With Authentication

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "vapi-primary",
      "uri": "sip.vapi.ai:5060",
      "authentication_needed": true,
      "username": "plivo_inbound",
      "password": "securepassword123!"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/

Response:

{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "Origination URI created successfully.",
  "uri_uuid": "90b6eb07-796c-4d86-a4fd-44ed11667ddb"
}

Save the uri_uuid for trunk creation. Optionally create a second URI for failover.

URI Format Examples

Format	Example
FQDN with port	sip.example.com:5060
FQDN	sip.example.com
IP with port	192.168.1.100:5060
IP address	192.168.1.100

Step 2: Create Inbound Trunk

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

Parameter	Type	Required	Description
name	string	No	Friendly name
trunk_direction	string	Yes	Must be inbound
trunk_status	string	No	enabled (default) or disabled
secure	boolean	No	Enable SRTP/TLS. Default: false
primary_uri_uuid	string	Yes	From Step 1
fallback_uri_uuid	string	No	Backup URI (optional)

cURL

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "livekit-inbound",
      "trunk_direction": "inbound",
      "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/

Response:

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

Step 3: Assign Phone Number to Trunk

1. Go to Phone Numbers in the Plivo Console
2. Select your phone number
3. Under Voice Configuration, select SIP Trunk
4. Choose your inbound trunk from the dropdown
5. Save changes

Calls to this number now route to your AI agent.

---

Call Records

To retrieve call detail records (CDRs) and call quality insights for SIP trunk calls, see SIP Trunking API - Calls.

---

Additional API Operations

For retrieving, listing, updating, and deleting resources:

Resource	Full API Reference
Trunks	SIP Trunking API - Trunks
Credentials	SIP Trunking API - Credentials
Origination URIs	SIP Trunking API - Origination URIs
IP Access Control Lists	SIP Trunking API - IP ACLs

---

Related

• SIP Trunking Overview - Architecture and concepts
• ElevenLabs Integration - Connect ElevenLabs
• LiveKit Integration - Connect LiveKit
• Retell AI Integration - Connect Retell AI
• Vapi Integration - Connect Vapi
• Hangup Codes - Troubleshooting