> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Tabs>
  <Tab title="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 |

    ```bash cURL theme={null}
    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:**

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="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 |

    ```bash cURL theme={null}
    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:**

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

### 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)      |

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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](/docs/sip-trunking/api/trunks#retrieve-a-trunk):

```bash cURL theme={null}
curl -i --user {auth_id}:{auth_token} \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/21784177241578/
```

**Response:**

```json theme={null}
{
  "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)     |

<Tabs>
  <Tab title="Without Authentication">
    ```bash cURL theme={null}
    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/
    ```
  </Tab>

  <Tab title="With Authentication">
    ```bash cURL theme={null}
    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/
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "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)             |

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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](https://cx.plivo.com/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](/docs/sip-trunking/api/calls).

***

## Additional API Operations

For retrieving, listing, updating, and deleting resources:

| Resource                | Full API Reference                                                        |
| ----------------------- | ------------------------------------------------------------------------- |
| Trunks                  | [SIP Trunking API - Trunks](/docs/sip-trunking/api/trunks)                     |
| Credentials             | [SIP Trunking API - Credentials](/docs/sip-trunking/api/credentials)           |
| Origination URIs        | [SIP Trunking API - Origination URIs](/docs/sip-trunking/api/origination-uris) |
| IP Access Control Lists | [SIP Trunking API - IP ACLs](/docs/sip-trunking/api/ip-access-control-lists)   |

***

## Related

* [SIP Trunking Overview](/docs/voice-agents/sip-trunking/overview) - Architecture and concepts
* [ElevenLabs Integration](/docs/voice-agents/sip-trunking/integration-guides/elevenlabs) - Connect ElevenLabs
* [LiveKit Integration](/docs/voice-agents/sip-trunking/integration-guides/livekit) - Connect LiveKit
* [Retell AI Integration](/docs/voice-agents/sip-trunking/integration-guides/retell) - Connect Retell AI
* [Vapi Integration](/docs/voice-agents/sip-trunking/integration-guides/vapi) - Connect Vapi
* [Hangup Codes](/docs/voice-agents/sip-trunking/troubleshooting/hangup-codes) - Troubleshooting