# Change a trunk's configuration

Source: https://docs.usetone.ai/reference/sip-trunks/update

> Send `null` to clear a field; omit the key to leave it alone.

`PATCH /v1/sip-trunks/{id}`
Send `null` to clear a field; omit the key to leave it alone. Changes reach the gateway within seconds. Status is not settable here — approval is ours, and disabling is a support action.

Requires the `write` scope.

## Parameters

| Name | In | | Meaning |
|---|---|---|---|
| `id` | path | required | The SIP trunk's id. |

## Request body

| Field | Type | | Meaning |
|---|---|---|---|
| `callerIdPolicy` | string | optional | Which number outbound INVITEs present as From. Open set — handle an unrecognised value rather than throwing. Today: `did`, `trunk_default`. |
| `codecs` | string[] | optional | Codec preference order the gateway offers, best first. G.711 A-law and mu-law today. |
| `customHeaders` | object | optional | Extra headers on every outbound INVITE. Names must start with X-. Some carriers route or bill on these. |
| `inboundAuth` | string | optional | How the gateway authenticates INVITEs from your PBX. `digest` challenges with the trunk credentials; `ip_acl` admits by source address from ipAcl; `both` requires both. Open set — handle an unrecognised value rather than throwing. Today: `ip_acl`, `digest`, `both`. |
| `ipAcl` | string[] | optional | Public IPv4 addresses or CIDR blocks (/24 or narrower) your SBC sends INVITEs from. Required when inboundAuth is ip_acl or both. Private, loopback and reserved ranges are refused. |
| `maxConcurrent` | integer | optional | Concurrent calls this trunk may carry, inbound and outbound combined. Match your carrier's channel count; beyond it Tone refuses rather than letting the carrier fail the call. |
| `name` | string | optional | Your name for the trunk. |
| `outboundAuthPassword` | string | null | optional | A new password Tone presents to your carrier. Stored encrypted, never returned. Send null to clear it. |
| `outboundAuthUsername` | string | null | optional | Outbound auth username. Send null to clear both it and the password. |
| `outboundHost` | string | null | optional | Where Tone sends outbound INVITEs. A hostname or IPv4 address, no scheme. Send null to clear it — the trunk then cannot place calls or register. |
| `outboundNumberFormat` | string | optional | Dialled-number format toward your carrier. Open set — handle an unrecognised value rather than throwing. Today: `e164`, `national`, `national0`. |
| `outboundPort` | integer | optional | Port on outboundHost. |
| `outboundTransport` | string | optional | Signalling transport toward your carrier. Open set — handle an unrecognised value rather than throwing. Today: `tls`, `tcp`, `udp`. |
| `register` | boolean | optional | Whether Tone should REGISTER to outboundHost. |

### Example request

```json
{
  "callerIdPolicy": "did",
  "codecs": [
    "PCMA",
    "PCMU"
  ],
  "customHeaders": {
    "X-Account-Code": "acme-sales"
  },
  "inboundAuth": "digest",
  "ipAcl": [
    "49.207.12.0/24",
    "103.21.58.4"
  ],
  "maxConcurrent": 10,
  "name": "Airtel SIP — Mumbai office",
  "outboundAuthPassword": "K7x2QpL9vR4nT1cW",
  "outboundAuthUsername": "acme-out",
  "outboundHost": "sbc.acme-telecom.example",
  "outboundNumberFormat": "e164",
  "outboundPort": 5061,
  "outboundTransport": "tls",
  "register": false
}
```

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `allowOrigination` | boolean | required | Whether this trunk may ORIGINATE: send Tone an INVITE for a number Tone does not host and have Tone dial it out. Granted by Tone support, not settable here. Every originated call runs the full pre-dial compliance gate before anything is dialled. |
| `approvedAt` | string | null | required | When our team approved the trunk. Null while pending. |
| `callerIdPolicy` | string | required | Which number outbound INVITEs present as From. Open set — handle an unrecognised value rather than throwing. Today: `did`, `trunk_default`. |
| `codecs` | string[] | required | Codec preference order, best first. |
| `connection` | object | required | Where your PBX sends INVITEs. The same for every trunk on this deployment. |
| `connection.host` | string | required | What to point your PBX or SBC at. |
| `connection.ips` | string[] | required | The gateway's public addresses, for your firewall allow-list. Signalling and media both originate here. |
| `connection.port` | integer | required | Signalling port. TLS. |
| `connection.transport` | string | required | Signalling transport Tone accepts. |
| `createdAt` | string | required | RFC 3339, UTC. |
| `customHeaders` | object | required | Extra X-* headers on every outbound INVITE. |
| `digestUsername` | string | null | required | The username your PBX authenticates with. 🔴 Its password is returned exactly once, at creation and at rotation, and never again. |
| `disabledReason` | string | null | required | Why the trunk is disabled, when it is. |
| `hasOutboundPassword` | boolean | required | Whether an outbound password is stored. The value itself is never returned. |
| `id` | string | required | The trunk's id. |
| `inboundAuth` | string | required | How the gateway authenticates INVITEs from your PBX. Open set — handle an unrecognised value rather than throwing. Today: `ip_acl`, `digest`, `both`. |
| `ipAcl` | string[] | required | Public CIDRs your SBC sends from, canonicalised. |
| `lastInboundAt` | string | null | required | When a call last arrived over this trunk. RFC 3339, UTC. |
| `lastOutboundAt` | string | null | required | When Tone last placed a call over this trunk. RFC 3339, UTC. |
| `lastProbe` | object | null | required | The most recent POST /v1/sip-trunks/{id}/test result, or null if never tested. |
| `maxConcurrent` | integer | required | Concurrent calls this trunk may carry, both directions combined. |
| `name` | string | required | Your own name for it. |
| `outboundAuthUsername` | string | null | required | Username Tone presents to your carrier. |
| `outboundHost` | string | null | required | Where Tone sends outbound INVITEs. |
| `outboundNumberFormat` | string | required | Dialled-number format toward your carrier. Open set — handle an unrecognised value rather than throwing. Today: `e164`, `national`, `national0`. |
| `outboundPort` | integer | required | Port on outboundHost. |
| `outboundTransport` | string | required | Transport toward your carrier. Open set — handle an unrecognised value rather than throwing. Today: `tls`, `tcp`, `udp`. |
| `realm` | string | required | The digest realm the gateway challenges with. |
| `register` | boolean | required | Whether Tone REGISTERs to your carrier. |
| `status` | string | required | Lifecycle. `pending_verification` until our team approves the carrier relationship; only `active` carries calls; `disabled` is the kill switch and `disabledReason` says why. Open set — handle an unrecognised value rather than throwing. Today: `pending_verification`, `active`, `disabled`. |
| `updatedAt` | string | required | RFC 3339, UTC. |

### Example response

```json
{
  "data": {
    "allowOrigination": false,
    "approvedAt": "2026-09-09T11:00:00Z",
    "callerIdPolicy": "did",
    "codecs": [
      "PCMA",
      "PCMU"
    ],
    "connection": {
      "host": "sip.usetone.ai",
      "ips": [
        "13.233.10.20"
      ],
      "port": 5061,
      "transport": "tls"
    },
    "createdAt": "2026-09-09T10:14:22Z",
    "customHeaders": {},
    "digestUsername": "t_9f2c4a7b1d3e5f60",
    "disabledReason": null,
    "hasOutboundPassword": true,
    "id": "4b7c1a02-9de5-4f31-bb07-2c1a5e9f0d43",
    "inboundAuth": "digest",
    "ipAcl": [
      "49.207.12.0/24"
    ],
    "lastInboundAt": "2026-09-10T08:12:44Z",
    "lastOutboundAt": null,
    "lastProbe": {
      "at": "2026-09-10T08:12:44Z",
      "error": null,
      "latencyMs": 41,
      "method": "options",
      "ok": true,
      "sipStatus": 200
    },
    "maxConcurrent": 10,
    "name": "Airtel SIP — Mumbai office",
    "outboundAuthUsername": "acme-out",
    "outboundHost": "sbc.acme-telecom.example",
    "outboundNumberFormat": "e164",
    "outboundPort": 5061,
    "outboundTransport": "tls",
    "realm": "sip.usetone.ai",
    "register": false,
    "status": "active",
    "updatedAt": "2026-09-10T08:12:44Z"
  }
}
```