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

# SIP Trunking (Beta)

> Connect a SIP trunk to use your own carrier with Cartesia agents.

## How SIP trunking works

SIP trunking lets you connect your existing telephony infrastructure directly to Cartesia Agents.

**Inbound calls** — Traffic from your trunk is sent to Cartesia's SIP endpoint. Inbound calls to your numbers are routed to the agent assigned to that number.

**Outbound calls** — Cartesia places calls through your trunk's SIP hostname, so outgoing calls use your carrier and caller ID.

**Authentication** — Restrict who can send traffic with digest authentication (username and password) and/or by allowing only specific source IPs.

**Signaling and media** — Call setup (signaling) uses TCP or TLS; use TLS when you want encrypted signaling. Once a call is up, RTP audio can be encrypted according to your `media_encryption` setting (`disabled`, `allowed`, or `required`).

## Configure your PSTN provider

In your PSTN provider's SIP trunk settings, point the trunk to Cartesia's SIP endpoint. Choose the transport your carrier supports:

* **TCP:** `sip:sip.cartesia.ai;transport=tcp`
* **TLS:** `sip:sip.cartesia.ai;transport=tls` (encrypted signaling)

## Link the trunk to Cartesia

Once the trunk is configured on your carrier's side, register it with Cartesia. Some fields are omitted below — see [Create Provider](/api-reference/agents/providers/create) for the full list.

```bash theme={null}
curl -X POST "https://api.cartesia.ai/agents/phone-numbers/providers" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sip_trunk",
    "label": "Primary carrier trunk",
    "inbound": {
      "media_encryption": "allowed"
    },
    "outbound": {
      "address": "abcd1234.pstn.twilio.com",
      "transport": "tls",
      "destination_country": "US",
      "media_encryption": "required",
      "credentials": {
        "username": "cartesia-outbound",
        "password": "your-sip-password"
      }
    }
  }'
```

The response returns the provider `id` and read-only trunk details. Passwords are never returned; Cartesia exposes the configured username as `auth_username`.

```json theme={null}
{
  "type": "sip_trunk",
  "id": "ata_P4MgdLf1cpaucZJ7xWehCC",
  "label": "Primary carrier trunk",
  "inbound": {
    "allowed_addresses": [],
    "allowed_numbers": [],
    "auth_username": "",
    "media_encryption": "allowed"
  },
  "outbound": {
    "address": "abcd1234.pstn.twilio.com",
    "destination_country": "US",
    "transport": "tls",
    "media_encryption": "required",
    "auth_username": "example_username"
  }
}
```

## Import a number

Import a carrier number using the provider `id` from the previous step. See [Import Phone Number](/api-reference/agents/phone-numbers/import) for all fields.

```bash theme={null}
curl -X POST "https://api.cartesia.ai/agents/phone-numbers" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Support line",
    "number": "+14155551234",
    "provider": { "id": "ata_P4MgdLf1cpaucZJ7xWehCC" }
  }'
```

Expected Response:

```json theme={null}
{
  "id": "ap_M3gdLf1cpaucZJ7xWehCCa",
  "label": "Support line",
  "number": "+14155551234",
  "agent": null,
  "provider": {
    "type": "sip_trunk",
    "id": "ata_P4MgdLf1cpaucZJ7xWehCC",
    "label": "Primary carrier trunk"
  }
}
```

## Assign to an agent

Assign the imported number to an agent so inbound calls are routed to it.

<Note>
  You can alternatively pass `agent_id` on [import](/api-reference/agents/phone-numbers/import) to assign an agent in the same request.
</Note>

```bash theme={null}
curl -X PATCH "https://api.cartesia.ai/agents/phone-numbers/ap_M3gdLf1cpaucZJ7xWehCCa" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC"
  }'
```

Expected Response:

```bash theme={null}
{
  "id": "ap_M3gdLf1cpaucZJ7xWehCCa",
  "label": "Support line",
  "number": "+14155551234",
  "agent": {
    "id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
    "name": "example-agent"
  },
  "provider": {
    "type": "sip_trunk",
    "id": "ata_P4MgdLf1cpaucZJ7xWehCC",
    "label": "Primary carrier trunk"
  }
}
```

To unassign, set `agent_id` to `null`.

## Place outbound calls

Use the imported phone number to route outbound calls through. The carrier ultimately decides the caller ID. See [Create Outbound Call](/api-reference/agents/calls/create-outbound-call) for all fields.

```bash theme={null}
curl -X POST "https://api.cartesia.ai/agents/calls" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number_id": "ap_M3gdLf1cpaucZJ7xWehCCa",
    "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
    "outbound_calls": [
      {
        "to_number": "+14155559876",
        "metadata": {
          "customer_id": "cust_Na9d9f9xK4mN2pQ7vR8wL"
        }
      }
    ]
  }'
```

Expected Response:

```bash theme={null}
{"calls":[{"number":"+14155559876","agent_call_id":"ac_gqkgRWUz2u64qFUjA1mZyr"}]}
```

The response includes a call ID per destination. Use [Get Call](/api-reference/agents/calls/get-call) to monitor call status.