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

# SIP trunk API examples and field reference

> Complete Create SIP Trunk API requests for Twilio and Plivo Elastic SIP trunks, including TLS with SDES media encryption, plus every trunk field with types and defaults.

Use these requests with the [Create SIP Trunk](/docs/api-reference/sip-trunks/create) API after completing the provider-side [prerequisites](/docs/sip-trunking/byot-setup#prerequisites).

## Full API examples

Complete [Create SIP Trunk](/docs/api-reference/sip-trunks/create) requests for the most common setups.

### Example -- Twilio Elastic SIP trunk (userpass)

<CodeGroup>
  ```bash request theme={"system"}
  curl -X POST https://api.bolna.ai/sip-trunks/trunks \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Twilio Production",
      "provider": "twilio",
      "description": "Main Twilio Elastic SIP trunk",
      "auth_type": "userpass",
      "auth_username": "<your-sip-username>",
      "auth_password": "<your-sip-password>",
      "gateways": [
        {
          "gateway_address": "your-trunk.pstn.twilio.com",
          "port": 5060,
          "priority": 1
        }
      ],
      "transport": "transport-udp",
      "allow": "ulaw,alaw",
      "disallow": "all",
      "inbound_enabled": true,
      "outbound_leading_plus_enabled": true
    }'
  ```

  ```json response theme={"system"}
  {
    "id": "01HQXYZ123ABC456DEF",
    "name": "Twilio Production",
    "provider": "twilio",
    "description": "Main Twilio Elastic SIP trunk",
    "auth_type": "userpass",
    "auth_username": "<your-sip-username>",
    "gateways": [
      {
        "id": "01HQXYZ111AAA111BBB",
        "gateway_address": "your-trunk.pstn.twilio.com",
        "port": 5060,
        "priority": 1,
        "created_at": "2026-05-09T10:00:00Z"
      }
    ],
    "ip_identifiers": [],
    "phone_numbers": [],
    "allow": "ulaw,alaw",
    "disallow": "all",
    "transport": "transport-udp",
    "direct_media": false,
    "rtp_symmetric": true,
    "force_rport": true,
    "media_encryption": "no",
    "media_encryption_optimistic": false,
    "qualify_frequency": 60,
    "inbound_enabled": true,
    "outbound_leading_plus_enabled": true,
    "is_active": true,
    "created_at": "2026-05-09T10:00:00Z",
    "updated_at": "2026-05-09T10:00:00Z"
  }
  ```
</CodeGroup>

### Example -- Plivo Elastic SIP trunk (ip-based)

<CodeGroup>
  ```bash request theme={"system"}
  curl -X POST https://api.bolna.ai/sip-trunks/trunks \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Plivo Elastic Trunk",
      "provider": "plivo",
      "auth_type": "ip-based",
      "gateways": [
        {
          "gateway_address": "21467306465797919.zt.plivo.com",
          "port": 5060,
          "priority": 1
        }
      ],
      "ip_identifiers": [
        { "ip_address": "15.207.90.192/31" },
        { "ip_address": "204.89.151.128/27" },
        { "ip_address": "13.52.9.0/25" }
      ],
      "transport": "transport-udp",
      "inbound_enabled": true
    }'
  ```

  ```json response theme={"system"}
  {
    "id": "01HQXYZ789GHI012JKL",
    "name": "Plivo Elastic Trunk",
    "provider": "plivo",
    "auth_type": "ip-based",
    "gateways": [
      {
        "id": "01HQXYZ222BBB222CCC",
        "gateway_address": "21467306465797919.zt.plivo.com",
        "port": 5060,
        "priority": 1,
        "created_at": "2026-05-09T10:00:00Z"
      }
    ],
    "ip_identifiers": [
      { "ip_address": "15.207.90.192/31" },
      { "ip_address": "204.89.151.128/27" },
      { "ip_address": "13.52.9.0/25" }
    ],
    "phone_numbers": [],
    "transport": "transport-udp",
    "media_encryption": "no",
    "media_encryption_optimistic": false,
    "is_active": true,
    "inbound_enabled": true,
    "created_at": "2026-05-09T10:00:00Z",
    "updated_at": "2026-05-09T10:00:00Z"
  }
  ```
</CodeGroup>

### Example -- Twilio Elastic SIP trunk, TLS + SDES (encrypted)

<CodeGroup>
  ```bash request theme={"system"}
  curl -X POST https://api.bolna.ai/sip-trunks/trunks \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Twilio Production (encrypted)",
      "provider": "twilio",
      "auth_type": "userpass",
      "auth_username": "<your-sip-username>",
      "auth_password": "<your-sip-password>",
      "gateways": [
        {
          "gateway_address": "your-trunk.pstn.twilio.com",
          "port": 5061,
          "priority": 1
        }
      ],
      "transport": "transport-tls",
      "media_encryption": "sdes",
      "media_encryption_optimistic": false,
      "allow": "ulaw,alaw",
      "disallow": "all",
      "inbound_enabled": true
    }'
  ```

  ```json response theme={"system"}
  {
    "id": "01HQXYZ555TLS888SDES",
    "name": "Twilio Production (encrypted)",
    "provider": "twilio",
    "auth_type": "userpass",
    "gateways": [
      {
        "id": "01HQXYZ333CCC333DDD",
        "gateway_address": "your-trunk.pstn.twilio.com",
        "port": 5061,
        "priority": 1,
        "created_at": "2026-05-09T10:00:00Z"
      }
    ],
    "transport": "transport-tls",
    "media_encryption": "sdes",
    "media_encryption_optimistic": false,
    "inbound_enabled": true,
    "is_active": true,
    "created_at": "2026-05-09T10:00:00Z",
    "updated_at": "2026-05-09T10:00:00Z"
  }
  ```
</CodeGroup>

***

## Create trunk field reference

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | string | **Yes** | -- | Human-readable label. Must be unique per account. |
| `provider` | string | **Yes** | -- | SIP provider name (e.g. `"twilio"`, `"plivo"`, `"telnyx"`, `"vonage"`, `"custom"`). |
| `description` | string | No | `null` | Optional description for internal reference. |
| `auth_type` | string | **Yes** | -- | `"userpass"` or `"ip-based"`. |
| `auth_username` | string | Conditional | `null` | Required when `auth_type` is `"userpass"`. |
| `auth_password` | string | Conditional | `null` | Required when `auth_type` is `"userpass"`. |
| `gateways` | array | **Yes** | -- | At least one gateway. Each has `gateway_address` (required), `port` (default `5060`, use `5061` for TLS), `priority` (default `1`). |
| `ip_identifiers` | array | Conditional | `[]` | Required when `auth_type` is `"ip-based"`. List of `{ "ip_address": "..." }` objects. |
| `allow` | string | No | `"ulaw,alaw"` | Comma-separated codecs to allow. Always include `ulaw`. |
| `disallow` | string | No | `"all"` | Comma-separated codecs to disallow. |
| `inbound_enabled` | boolean | No | `false` | Set `true` to receive inbound calls. |
| `outbound_leading_plus_enabled` | boolean | No | `true` | Prepend `+` to outbound dialed numbers. |
| `transport` | enum | No | `"transport-udp"` | One of `"transport-udp"`, `"transport-tcp"`, `"transport-tls"`. |
| `media_encryption` | enum | No | `"no"` | One of `"no"`, `"sdes"`. `"sdes"` requires `transport="transport-tls"`. |
| `media_encryption_optimistic` | boolean | No | `false` | When `media_encryption="sdes"`, fall back to clear RTP if the carrier does not offer crypto in its SDP. |
| `direct_media` | boolean | No | `false` | RTP routed directly between caller and callee. Keep `false`. |
| `rtp_symmetric` | boolean | No | `true` | Symmetric RTP. Required for NAT. |
| `force_rport` | boolean | No | `true` | Force responses to source port. Required for NAT. |
| `qualify_frequency` | integer | No | `60` | SIP OPTIONS ping interval in seconds. `0` to disable. |
| `phone_numbers` | array | No | `[]` | Optional phone numbers to add at creation time. |

## Next steps

<CardGroup cols={2}>
  <Card title="Set up and register your trunk" href="/docs/sip-trunking/byot-setup" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.