Connect your own carrier over SIP — credentials are shown once

Creates a trunk in pending_verification: you can configure and test it, and our team approves it before it carries calls. Requires completed business verification AND SIP trunking enabled on your organization (403 sip_trunking_not_enabled otherwise — contact support). 🔴 The digest password in connection.password appears in this response only. Send an Idempotency-Key to make a retried create return the same trunk and the same password.

Requires the admin scope. A key with less gets 403 insufficient_scope.

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

callerIdPolicy?string

Which number an outbound INVITE presents as From: the DID the call was placed from, or whatever your trunk defaults to. Open set — handle an unrecognised value rather than throwing. Today: did, trunk_default.

Default"did"

Value in

"did"
"trunk_default"

codecs?array<>

Codec preference order the gateway offers, best first. G.711 A-law and mu-law today.

Items1 <= items <= 2

Default

[  "PCMA",  "PCMU"]

customHeaders?

Extra headers on every outbound INVITE. Names must start with X-. Some carriers route or bill on these.

Default{}

inboundAuth?string

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.

Default"digest"

Value in

"ip_acl"
"digest"
"both"

ipAcl?array<>

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.

Itemsitems <= 32

maxConcurrent?integer

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.

Range1 <= value <= 200

Default10

name*string

Your name for the trunk. Shown wherever it appears; no effect on routing.

Match^[^\p{C}]+$

Length1 <= length <= 80

outboundAuthPassword?string

The password Tone presents when your carrier challenges. Stored encrypted, never returned.

Length1 <= length <= 128

outboundAuthUsername?string

The username Tone presents when your carrier challenges outbound INVITEs or REGISTERs.

Length1 <= length <= 128

outboundHost?string

Where Tone sends outbound INVITEs — your carrier or SBC. A hostname or IPv4 address, no scheme; the port is its own field. Must be publicly reachable.

Match^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$

Length1 <= length <= 253

outboundNumberFormat?string

How the dialled number is formatted toward your carrier: e164 (+91…), national (10 digits), or national0 (0 + 10 digits). Open set — handle an unrecognised value rather than throwing. Today: e164, national, national0.

Default"e164"

Value in

"e164"
"national"
"national0"

outboundPort?integer

Port on outboundHost. 5061 for TLS, 5060 otherwise.

Range1 <= value <= 65535

Default5061

outboundTransport?string

Signalling transport toward your carrier. Leave it on tls unless your carrier cannot terminate it. Open set — handle an unrecognised value rather than throwing. Today: tls, tcp, udp.

Default"tls"

Value in

"tls"
"tcp"
"udp"

Whether Tone should REGISTER to outboundHost. Some carriers require a registration before they route inbound to you.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://example.com/v1/sip-trunks" \  -H "Content-Type: application/json" \  -d '{    "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  }'

{  "data": {    "connection": {      "host": "sip.usetone.ai",      "ips": [        "13.233.10.20"      ],      "password": "Qm9vZ2llV29vZ2llMTIzNDU2",      "port": 5061,      "realm": "sip.usetone.ai",      "transport": "tls",      "username": "t_9f2c4a7b1d3e5f60"    },    "trunk": {      "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"    }  }}

Was this page helpful?

Connect your own carrier over SIP — credentials are shown once

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`