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

# SIP Trunks API

> Create, update, prioritize, enable, disable, and sync BYO SIP trunks.

The SIP Trunks API lets organization admins manage BYO SIP trunk gateways for outbound and inbound telephony through Burki's SIP bridge.

All SIP trunk management endpoints require an authenticated organization admin.

```text theme={null}
Base path: /api/v1/sip-trunks
```

<Warning>
  SIP trunk records include carrier credentials. Treat responses and request bodies as sensitive and avoid logging full payloads.
</Warning>

## SIP Trunk Object

```json theme={null}
{
  "id": "7f502da1-0f06-4e52-9262-4e625c53791a",
  "name": "Primary Carrier",
  "gateway": "sip.example-carrier.com",
  "username": "sip-user",
  "password": "sip-password",
  "priority": 1,
  "enabled": true,
  "register": true,
  "provider": "example-carrier"
}
```

| Field      | Type    | Description                                       |
| ---------- | ------- | ------------------------------------------------- |
| `id`       | string  | Server-generated trunk UUID                       |
| `name`     | string  | Unique trunk name within the organization         |
| `gateway`  | string  | SIP gateway hostname or IP                        |
| `username` | string  | SIP auth username                                 |
| `password` | string  | SIP auth password                                 |
| `priority` | integer | Lower values are preferred first                  |
| `enabled`  | boolean | Whether the trunk is eligible for routing         |
| `register` | boolean | Whether FreeSWITCH should register to the gateway |
| `provider` | string  | Optional provider label                           |

## PBX Allowlist and Registration

For the current hosted SIP bridge, customer PBX/carrier firewalls should allow:

```text theme={null}
Burki SIP bridge IP: 52.21.157.171
SIP signaling: UDP/TCP 5060
SIP TLS: TCP 5061, if enabled
RTP media: UDP 10000-20000
```

Use `gateway` for the customer's PBX/carrier host and port. If Burki should register to the PBX, set `register: true` and provide the PBX username/password. If the PBX uses IP authentication instead, set `register: false` and allowlist `52.21.157.171` as the trusted SIP peer.

```json Registration example theme={null}
{
  "name": "FreePBX primary",
  "gateway": "138.197.131.209:6061",
  "username": "9228",
  "password": "sip-password",
  "priority": 1,
  "enabled": true,
  "register": true,
  "provider": "freepbx"
}
```

For inbound calls, configure the PBX/carrier to send INVITEs to `52.21.157.171:5060` and allow RTP from `52.21.157.171` on UDP `10000-20000`.

For outbound calls, the PBX/carrier must accept INVITEs and RTP from `52.21.157.171`. If multiple DIDs share one PBX extension, the PBX must also include the original called DID in `Diversion`, `History-Info`, `X-Original-Called`, `P-Called-Party-ID`, the Request-URI, or the `To` user so Burki can route to the correct assistant.

## List Trunks

```http theme={null}
GET /api/v1/sip-trunks
Authorization: Bearer YOUR_TOKEN
```

Returns trunks sorted by `priority`.

```json Response theme={null}
[
  {
    "id": "7f502da1-0f06-4e52-9262-4e625c53791a",
    "name": "Primary Carrier",
    "gateway": "sip.example-carrier.com",
    "username": "sip-user",
    "password": "sip-password",
    "priority": 1,
    "enabled": true,
    "register": true,
    "provider": "example-carrier"
  }
]
```

## Create Trunk

```http theme={null}
POST /api/v1/sip-trunks
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
```

```json Request theme={null}
{
  "name": "Primary Carrier",
  "gateway": "sip.example-carrier.com",
  "username": "sip-user",
  "password": "sip-password",
  "priority": 1,
  "enabled": true,
  "register": true,
  "provider": "example-carrier"
}
```

Returns `201 Created` with the created SIP trunk object.

Duplicate names return `400 Bad Request`.

## Get Trunk

```http theme={null}
GET /api/v1/sip-trunks/{trunk_id}
Authorization: Bearer YOUR_TOKEN
```

Returns one SIP trunk object or `404 Not Found`.

## Update Trunk

```http theme={null}
PUT /api/v1/sip-trunks/{trunk_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
```

All fields are optional. Empty fields are ignored only if omitted; send the exact value you want persisted.

```json Request theme={null}
{
  "name": "Primary Carrier",
  "gateway": "sip2.example-carrier.com",
  "priority": 2,
  "enabled": true
}
```

Returns the updated trunk.

## Delete Trunk

```http theme={null}
DELETE /api/v1/sip-trunks/{trunk_id}
Authorization: Bearer YOUR_TOKEN
```

Returns `204 No Content` on success.

## Enable or Disable Trunk

```http theme={null}
POST /api/v1/sip-trunks/{trunk_id}/enable
Authorization: Bearer YOUR_TOKEN
```

```http theme={null}
POST /api/v1/sip-trunks/{trunk_id}/disable
Authorization: Bearer YOUR_TOKEN
```

Returns the updated trunk object.

## Sync to SIP Bridge

```http theme={null}
POST /api/v1/sip-trunks/sync
Authorization: Bearer YOUR_TOKEN
```

Pushes enabled trunk configuration to the SIP bridge. The API returns success if Burki updates its org config and starts bridge sync; bridge sync failures are logged server-side and should be checked in operations logs.

```json Response theme={null}
{
  "success": true,
  "message": "Synced 2 enabled trunk(s) to bridge",
  "total_trunks": 3,
  "enabled_trunks": 2
}
```

## Assign a Phone Number to a SIP Trunk

Phone-number routing uses the organization phone-number update endpoint:

```http theme={null}
PATCH /api/v1/assistants/organization/phone-numbers/{phone_number_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
```

```json Request theme={null}
{
  "sip_trunk_id": "7f502da1-0f06-4e52-9262-4e625c53791a"
}
```

Send an empty string to clear the SIP trunk assignment:

```json theme={null}
{
  "sip_trunk_id": ""
}
```

## Error Responses

| Status | Cause                                           |
| ------ | ----------------------------------------------- |
| `400`  | Duplicate trunk name or invalid update          |
| `403`  | Authenticated user is not an organization admin |
| `404`  | Organization or trunk not found                 |
| `500`  | Unexpected server error                         |