Create Outbound Trunk#

Creates an outbound trunk.

In version 2026-11-19, customers with the Outbound API enabled can create outbound trunks even if the Outbound feature is not enabled on the account. Without the Outbound API, the request returns 403 Forbidden.

Request#

HTTP Method: POST

URI Path: /v3/voice_out_trunks

Body Parameters#

Name

Type

Nullable

Is Required?

Description

type

string

No

Yes

Must be voice_out_trunks.

attributes

object

No

Yes

Outbound trunk attributes object.

Data Attributes#

Name

Type

Nullable

Is Required?

Description

name

string

No

Yes

The outbound trunk name.

external_reference_id

string

Yes

No

Optional identifier for the outbound trunk in the customer’s external system. Maximum length is 100 characters.

allowed_rtp_ips

Array of strings

Yes

No

Allowed RTP IP addresses for media traffic. Null means no restriction. An empty list is rejected. 0.0.0.0/0 and ::/0 are rejected.

authentication_method

object

No

Yes

Authentication method object. Supported POST types: credentials_and_ip - use SIP credentials together with allowed IP addresses. twilio - use a Twilio Account SID for authentication. ip_only is not supported in POST requests.

on_cli_mismatch_action

string

No

Yes

Possible values: send_original_cli - pass the original From header value from your system to the destination without modification. reject_call - reject the call if the From header value does not match any DID allowed on the trunk. replace_cli - replace the CLI with one of the DIDs allowed on the trunk. randomize_cli - replace the CLI with a random DID allowed on the trunk. An action the account does not have the feature for is rejected.

capacity_limit

integer

Yes

No

The capacity limit of the outbound trunk. Allowed values from 1 to 32767.

allow_any_did_as_cli

boolean

No

No

When set to true, all eligible DIDs can be used as CLI and the dids relationship must not contain explicit DIDs.

status

string

No

No

Possible values: active - the trunk can be used for outbound traffic. blocked - outbound traffic on the trunk is blocked. If omitted, the default value is active.

threshold_amount

string

No

No

The outbound trunk 24-hour threshold limit. The accepted range depends on the account.

default_dst_action

string

No

No

Possible values: allow_all - allow calls to all destinations except the prefixes listed in dst_prefixes. reject_all - reject calls to all destinations except the prefixes listed in dst_prefixes.

dst_prefixes

Array of strings

No

No

The destination prefixes allowed or rejected based on default_dst_action. Each prefix is digits only, without a leading + or separators; any other value returns 422 Unprocessable Entity. Repeated prefixes are stored once.

emergency_enable_all

boolean

No

No

Allows all eligible DIDs to be used for emergency calling on the trunk. Default value is false.

media_encryption_mode

string

No

No

Media encryption mode. Possible values: disabled - media encryption is turned off. srtp_sdes - use SRTP encryption with SDES key exchange. srtp_dtls - use SRTP encryption with DTLS key exchange. zrtp - use SRTP encryption with ZRTP key exchange.

ice_mode

string

No

No

ICE (Interactive Connectivity Establishment) for calls from the trunk: not used, accepted when the trunk offers it, or initiated by DIDWW. Possible values: disabled, accept, initiate. Defaults to accept.

rtcp_mux_mode

string

No

No

RTP and RTCP multiplexed on one port: not used, accepted when the trunk offers it, or initiated by DIDWW. Possible values: disabled, accept, initiate. Defaults to accept.

rtcp_feedback_mode

string

No

No

RTCP feedback (AVPF): not used, accepted when the trunk offers it, or initiated by DIDWW. Possible values: disabled, accept, initiate. Defaults to accept. With disabled, a call whose SDP offer uses a feedback profile (RTP/AVPF or UDP/TLS/RTP/SAVPF) is rejected with SIP 500 No suitable media. WebRTC clients always offer such a profile, so use accept or initiate for them.

codecs

Array of strings

No

No

Codecs offered on calls from the trunk, in priority order: the first has the highest priority. Send at least one value, without repeats. Possible values: telephone_event, g723, g729, pcmu, pcma, gsm, g722, opus, amr, amr_wb. Defaults to pcma, pcmu, telephone_event.

callback_url

string

Yes

No

Can be null or a valid HTTP(S) URL.

force_symmetric_rtp

boolean

No

No

Enables symmetric RTP / COMEDIA mode.

rtp_ping

boolean

No

No

Enables RTP ping after the call is connected.

rtp_timeout

integer

No

No

Disconnects the call if RTP packets do not arrive within the specified time. Supported values are from 30 to 600 seconds.

See Outbound Trunk callback details for information about callback_url and the JSON callback payload.

Request Body Object Relationships#

Title

Type

Description

default_did

DID Object

The DID used as the caller ID. Required while on_cli_mismatch_action is replace_cli, and rejected otherwise. Only accepted on accounts with the replace_cli feature.

dids

DIDs

The DID numbers explicitly allowed as CLI when allow_any_did_as_cli is false. DIDs must support voice_out feature to be selected. A DID that is awaiting registration (awaiting_registration is true) cannot be used as an allowed CLI: the request returns 422 Unprocessable Entity with one error per such DID.

emergency_dids

DIDs

The DID numbers explicitly enabled for emergency calling when emergency_enable_all is false. DIDs must support voice_out and emergency features and have emergency_enabled = true to be selected.

Authentication Method#

The outbound trunk authentication is configured through the authentication_method attribute.

Supported authentication method types:

  • credentials_and_ip - uses SIP credentials together with allowed IP addresses.

  • twilio - uses a Twilio Account SID for authentication.

  • ip_only is returned by GET endpoints but is not supported in POST requests.

Authentication Method Attributes by Type#

Name

Type

Nullable

Is Required?

Description

allowed_sip_ips

Array of strings

No

Yes

The allowed originating SIP IPs.

tech_prefix

string

Yes

No

Prefix stripped from the dialled number before routing. The maximum length is 8 characters and only digits and # are supported.

Examples#

http

 1POST /v3/voice_out_trunks HTTP/1.1
 2Host: api.didww.com
 3Content-Type: application/vnd.api+json
 4Accept: application/vnd.api+json
 5Authorization: Bearer [access token]
 6
 7{
 8  "data": {
 9    "type": "voice_out_trunks",
10    "attributes": {
11      "name": "Outbound trunk Name",
12      "callback_url": null,
13      "allowed_rtp_ips": [
14        "203.0.113.0/24"
15      ],
16      "authentication_method": {
17        "type": "credentials_and_ip",
18        "attributes": {
19          "allowed_sip_ips": [
20            "0.0.0.0/0"
21          ],
22          "tech_prefix": null
23        }
24      },
25      "on_cli_mismatch_action": "send_original_cli",
26      "capacity_limit": 100,
27      "allow_any_did_as_cli": true,
28      "status": "active",
29      "threshold_amount": "10000.0",
30      "default_dst_action": "allow_all",
31      "dst_prefixes": [],
32      "emergency_enable_all": false,
33      "media_encryption_mode": "disabled",
34      "ice_mode": "accept",
35      "rtcp_mux_mode": "accept",
36      "rtcp_feedback_mode": "accept",
37      "codecs": [
38        "pcma",
39        "pcmu",
40        "g729",
41        "g723",
42        "gsm",
43        "telephone_event"
44      ],
45      "force_symmetric_rtp": false,
46      "rtp_ping": false,
47      "rtp_timeout": 30
48    }
49  }
50}

curl

1curl -i -X POST https://api.didww.com/v3/voice_out_trunks -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"allow_any_did_as_cli": true, "allowed_rtp_ips": ["203.0.113.0/24"], "authentication_method": {"attributes": {"allowed_sip_ips": ["0.0.0.0/0"], "tech_prefix": null}, "type": "credentials_and_ip"}, "callback_url": null, "capacity_limit": 100, "codecs": ["pcma", "pcmu", "g729", "g723", "gsm", "telephone_event"], "default_dst_action": "allow_all", "dst_prefixes": [], "emergency_enable_all": false, "force_symmetric_rtp": false, "ice_mode": "accept", "media_encryption_mode": "disabled", "name": "Outbound trunk Name", "on_cli_mismatch_action": "send_original_cli", "rtcp_feedback_mode": "accept", "rtcp_mux_mode": "accept", "rtp_ping": false, "rtp_timeout": 30, "status": "active", "threshold_amount": "10000.0"}, "type": "voice_out_trunks"}}'

response

 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": {
 6    "id": "03813615-da15-4e3b-8e0a-3ea64b2585de",
 7    "type": "voice_out_trunks",
 8    "attributes": {
 9      "name": "Outbound trunk Name",
10      "callback_url": null,
11      "allowed_rtp_ips": [
12        "203.0.113.0/24"
13      ],
14      "authentication_method": {
15        "type": "credentials_and_ip",
16        "attributes": {
17          "allowed_sip_ips": [
18            "0.0.0.0/0"
19          ],
20          "tech_prefix": null,
21          "username": "554******",
22          "password": "fqe******"
23        }
24      },
25      "on_cli_mismatch_action": "send_original_cli",
26      "capacity_limit": 100,
27      "allow_any_did_as_cli": true,
28      "status": "active",
29      "threshold_reached": false,
30      "threshold_amount": "10000.0",
31      "default_dst_action": "allow_all",
32      "dst_prefixes": [],
33      "emergency_enable_all": false,
34      "media_encryption_mode": "disabled",
35      "ice_mode": "accept",
36      "rtcp_mux_mode": "accept",
37      "rtcp_feedback_mode": "accept",
38      "codecs": [
39        "pcma",
40        "pcmu",
41        "g729",
42        "g723",
43        "gsm",
44        "telephone_event"
45      ],
46      "force_symmetric_rtp": false,
47      "rtp_ping": false,
48      "rtp_timeout": 30,
49      "created_at": "2025-04-02T10:00:00.000Z",
50      "external_reference_id": null
51    },
52    "relationships": {
53      "dids": {
54        "links": {
55          "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/dids",
56          "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/dids"
57        }
58      },
59      "emergency_dids": {
60        "links": {
61          "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/emergency_dids",
62          "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/emergency_dids"
63        }
64      }
65    },
66    "meta": {
67      "spent_amount": "0.0"
68    }
69  },
70  "meta": {
71    "api_version": "2026-11-19"
72  }
73}

Other Responses#

Code

Success

Description

422

No

Validation Error Object

400

No

Bad Request. Also returned with the title Quota limit reached when the account has reached its limit of outbound trunks.

401

No

Unauthorized

403

No

The Outbound API is not enabled for the account. Also returned when the access token carries the read scope, which does not cover this method (title Insufficient scope, WWW-Authenticate: Bearer error="insufficient_scope"). See Scopes.

429

No

The request budget of the account for the current window is spent (too_many_requests). Retry-After gives the number of seconds to wait.