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

# SIP Trunking API

> Connect your telephony platform to PolyAI.

The SIP Trunking API lets you connect your own telephony platform to PolyAI. It has two parts:

1. **A management REST API** to create and configure **SIP Trunks** and their **Extensions**, and to **place outbound calls** over a trunk.
2. **A SIP/RTP interface** your telephony system connects to.

<Note>
  A **SIP Trunk** is an account-level virtual connection that carries voice calls between your telephony platform and PolyAI. It authenticates callers, accepts inbound calls, and holds a list of **Extensions** that map a dialed number to a specific PolyAI agent.
</Note>

## Resource model

The API is organized around two nested, account-scoped resources:

```
account
 └── sip-trunk              # virtual connection: CIDRs, transport, inbound auth
      └── extension         # maps a dialed number to a PolyAI agent
```

## Base URL

The API is served from a regional gateway. Use the region your PolyAI account is hosted in:

| Region | Base URL                 |
| ------ | ------------------------ |
| US     | `https://api.us.poly.ai` |
| EU     | `https://api.eu.poly.ai` |
| UK     | `https://api.uk.poly.ai` |

Every resource is scoped to an account, so all management endpoints are prefixed with `/v1/accounts/{account_id}/telephony/…`.

<Warning>
  Do not use `https://api.poly.ai` without a region prefix — it returns an error. Always include the region.
</Warning>

## Authentication

All endpoints authenticate with an API key sent in the `X-API-Key` header — either an Agent Studio personal access token or an account-level API key.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.us.poly.ai/v1/accounts/ACCOUNT_ID/telephony/sip-trunks \
  -H "X-API-Key: YOUR_API_KEY"
```

The key must belong to a user who is an admin on the account named in the request path.

<Note>
  Create a key from the **API Keys** tab in Agent Studio — see [API keys](/secrets/api-keys).
</Note>

## Quick start

Create a trunk, map a number to an agent, then point your telephony platform at PolyAI.

### 1. Create a SIP Trunk

Create an encrypted trunk that authenticates inbound calls with a SIP token:

<CodeGroup>
  ```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.us.poly.ai/v1/accounts/ACCOUNT_ID/telephony/sip-trunks \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Example SIP Trunk",
      "encrypted": true,
      "sip_cidr": ["203.0.113.0/24"],
      "rtp_cidr": ["203.0.113.0/24"],
      "inbound": { "sip_token_auth": { "token": "a-long-random-shared-secret" } }
    }'
  ```

  ```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "tr-0123456789abcdefghijklmn",
    "account_id": "acct-123",
    "name": "Example SIP Trunk",
    "sip_cidr": ["203.0.113.0/24"],
    "rtp_cidr": ["203.0.113.0/24"],
    "encrypted": true,
    "inbound": {
      "hostname": "tr-0123456789abcdefghijklmn.sbc.sip.us.poly.ai",
      "sip_auth": { "enabled": false },
      "sip_token_auth": { "enabled": true }
    },
    "created_at": "2026-07-28T12:00:00Z",
    "updated_at": "2026-07-28T12:00:00Z"
  }
  ```
</CodeGroup>

The response includes the trunk `id` and its `inbound.hostname` — the host your telephony platform connects to.

### 2. Create an extension

Map a dialed number on the trunk to a PolyAI agent. The **extension** is the number or extension sent in the Request URI of the SIP `INVITE` to PolyAI:

<CodeGroup>
  ```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.us.poly.ai/v1/accounts/ACCOUNT_ID/telephony/sip-trunks/TRUNK_ID/extensions \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "extension": "1000",
      "agent": { "agent_id": "my-agent", "client_env": "live" }
    }'
  ```

  ```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "extension": "1000",
    "agent": { "agent_id": "my-agent", "client_env": "live", "variant_id": "" },
    "created_at": "2026-07-28T12:00:00Z",
    "updated_at": "2026-07-28T12:00:00Z"
  }
  ```
</CodeGroup>

Calls dialed to `1000` on this trunk now route to the `my-agent` agent.

### 3. Connect your telephony platform

Update your SIP server to route calls to your trunk's `inbound.hostname` and to the correct port — for TLS that's port 5061, e.g. `tr-0123456789abcdefghijklmn.sbc.sip.us.poly.ai:5061`.

If using SIP token-based auth, you'll also need to send a `X-PolyAI-SIP-Trunk-Token` SIP header on your first SIP `INVITE`.

```text highlight={3} theme={"theme":{"light":"github-light","dark":"github-dark"}}
INVITE sip:1000@tr-0123456789abcdefghijklmn.sbc.sip.us.poly.ai SIP/2.0
…
X-PolyAI-SIP-Trunk-Token: a-long-random-shared-secret
…
```

See [Connecting to PolyAI Telephony](/api-reference/sip-trunking/connecting) for transport, DNS, and authentication details.

## Placing outbound calls

A trunk can also place **outbound** calls: PolyAI dials a number and connects the answered call to one of your agents. First configure the trunk's outbound settings — a `default_caller_id` and the `sip_addresses` your calls route to — with [Update a SIP Trunk](/api-reference/sip-trunking/endpoint/update-a-sip-trunk). Then call the outbound-call endpoint:

<CodeGroup>
  ```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.us.poly.ai/v1/telephony/sip-trunks/TRUNK_ID/outbound-call \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "agent": { "agent_id": "my-agent", "client_env": "live" },
      "to_number": "+447700900123"
    }'
  ```

  ```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "call_sid": "OUT-3f2a7c9e-1b4d-4e6a-9c8b-2d5f7a1e0c34"
  }
  ```
</CodeGroup>

Use the returned `call_sid` to poll the call with [Get outbound call status](/api-reference/sip-trunking/endpoint/get-outbound-call-status) until it reaches `success` or `failure`.

## Error responses

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| 400    | Validation error — check the request body       |
| 401    | Missing or invalid API key                      |
| 403    | Key is not an admin on the account              |
| 404    | Resource not found                              |
| 409    | Conflict with the current state of the resource |

### Example error response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "error": "short_error_code",
  "message": "Human-readable explanation."
}
```

## Related

<CardGroup cols={2}>
  <Card title="Connecting to PolyAI Telephony" icon="phone-arrow-down-left" href="/api-reference/sip-trunking/connecting">
    Route inbound phone calls into PolyAI over SIP/RTP.
  </Card>

  <Card title="Place an outbound call" icon="phone-arrow-up-right" href="/api-reference/sip-trunking/endpoint/place-an-outbound-call">
    Dial a number and connect the call to one of your agents over a trunk.
  </Card>

  <Card title="Outbound calls over PolyAI telephony" icon="phone" href="/api-reference/agents/endpoint/outbound-calls/trigger-outbound-call">
    Place outbound calls over PolyAI-managed telephony with the Agents API.
  </Card>

  <Card title="Agents API" icon="robot" href="/api-reference/agents/introduction">
    Build and deploy the agents your extensions route calls to.
  </Card>
</CardGroup>