Create Inbound Trunk#

You can create several type of inbound trunks: SIP, PSTN.

Request#

HTTP Method: POST

URI Path: /v3/voice_in_trunks

Body Parameters#

Name

Type

Nullable

Is Required?

Description

type

string

No

Yes

Trunks

attributes

object

No

Yes

Trunk configuration complex object.

Data Attributes#

Name

Type

Nullable

Is Required?

Description

priority

integer

No

No

The priority of this target host. DIDWW will attempt to contact the target trunk with the lowest-numbered priority; target trunk with the same priority will be tried in an order defined by the weight field. The range is 0-65535. See RFC 2782 for more details.

weight

integer

No

No

A trunk selection mechanism. The weight field specifies a relative weight for entries with the same priority. Larger weights will be given a proportionately higher probability of being selected. The range of this number is 0-65535. In the presence of records containing weights greater than 0, records with weight 0 will have a very small chance of being selected. See RFC 2782 for more details.

capacity_limit

integer

Yes

No

Maximum number of simultaneous calls for the trunk.

ringing_timeout

integer

Yes

No

Ring time in seconds. Supported values are integers from 1 to 32. Null uses the platform default. If the call is not connected within this time, the transaction is ended with the disconnect code Ringing timeout.

name

string

No

Yes

Friendly name of the trunk. Unique among the trunks and trunk groups of the account — they share one name space.

external_reference_id

string

Yes

No

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

cli_format

string

Yes

No

raw - Do not alter CLI. e164 - Attempt to convert CLI to E.164 format (default). local - Attempt to convert CLI to Localized format. CLI format conversion may not work correctly for phone calls originating from outside the country of that specific DID.

cli_prefix

string

Yes

No

You may prefix the CLI with an optional + sign followed by up to 6 characters, including digits and #.

description

string

Yes

No

Optional description of the trunk.

pop

string

Yes

No

Point of Presence the trunk is pinned to. Possible values: nyc, fra, lac, mia, sg, hk, ams. null lets DIDWW choose. Any other value returns 422 Unprocessable Entity.

configuration

One of sip_configurations, pstn_configurations

No

Yes

Trunk configuration complex object.

Object Relationships#

Value

Description

voice_in_trunk_group

Trunk Group Object

Attributes Configuration#

Name

Type

Nullable

Is Required?

Description

type

sip_configurations

No

Yes

SIP configuration complex object.

attributes

sip_configuration_attributes

No

Yes

SIP configuration attributes object.

Configuration Attributes#

Name

Type

Nullable

Is Required?

Description

username

string

Yes

No

User part of R-URI in INVITE request. You also may use “{DID}” pattern which will be replaced by called DID number in E164 format. For example, you can set Username to “+{DID}”; if you wish to have it in +E164 format

host

string

Yes

No

Host part of R-URI in INVITE request. Required while enabled_sip_registration is false, and rejected while it is true.

port

integer

Yes

No

Port part of R-URI in INVITE request (is not mandatory). If port is null, SRV record will be resolved (or A record if SRV is unavailable). Must be empty while enabled_sip_registration is true.

codecs

Array of strings

No

No

Codecs offered on calls to 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, speex, gsm, g726_32, g721, g726_24, g726_40, g726_16, l16, amr, amr_wb. Defaults to pcmu, pcma, g729, g723, telephone_event. See Codecs.

rx_dtmf_format_id

integer

No

No

The method id for receiving DTMF signals from customers equipment. Possible values: 1 - RFC 2833; 2 - SIP INFO application/dtmf-relay or application/dtmf; 3 - RFC 2833 or SIP INFO.

tx_dtmf_format_id

integer

No

No

The method of sending DTMF signals to the customer’s equipment. Possible values: 0 - Disable sending; 1 - RFC 2833; 2 - SIP INFO application/dtmf-relay; 4 - SIP INFO application/dtmf.

resolve_ruri

boolean

No

No

Replace host part of the R-URI by resolved IP address.

auth_enabled

boolean

No

No

Enable authorization for the SIP server.

auth_user

string

Yes

No

Authorization user for the SIP server. Required while auth_enabled is true, and rejected while it is false.

auth_password

string

Yes

No

Authorization password for the SIP server. Required while auth_enabled is true, and rejected while it is false.

auth_from_user

string

Yes

No

Specify user in a from field instead of CallerID (overrides CallerID). Some equipment require from; to be equivalent to Auth user.

auth_from_domain

string

Yes

No

Sets default from domain in SIP messages. Some equipment may require specific From Domain.

sst_enabled

boolean

No

No

Enable SIP Session timers customization. SIP session timers are used to make sure that a session (dialog) is still alive, even though there may have been a long time since the last in-dialog message. If the other end is not responding, the dialog will be hung up automatically. SIP session timers need to be supported by all end points for it to work. It’s a SIP extension, standardized by the IETF. See RFC 4028 for more details.

sst_min_timer

integer

Yes

No

Minimal SIP Session timer value (Default 600 seconds). See RFC 4028 for more details.

sst_max_timer

integer

Yes

No

Maximal SIP Session timer value (Default 900 seconds). See RFC 4028 for more details.

sst_accept_501

boolean

No

No

Do not drop the call after receiving SIP 501 response for non-critical messages.

sip_timer_b

integer

No

No

INVITE transaction timeout (Default 8000ms). See RFC 3261 Section 17.1.1.2 for more details.

dns_srv_failover_timer

integer

Yes

No

Invite transaction timeout for each of gateways with DNS SRV rerouting (Default 2000ms).

rtp_ping

boolean

Yes

No

Use RTP PING when connecting a call. After establishing the call, DIDWW will send empty RTP packet RTP PING. It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first.

rtp_timeout

integer

No

No

Disconnect the call if the RTP packets do not arrive within the specified time.

force_symmetric_rtp

boolean

Yes

No

Forced to work in Symmetric RTP / COMEDIA mode.

symmetric_rtp_ignore_rtcp

boolean

Yes

No

Avoid switching RTP session based on RTCP packet while working in Symmetric RTP / COMEDIA. Only RTP packets will be considered.

rerouting_disconnect_code_ids

array

Yes

No

Rerouting disconnect codes.

sst_session_expires

integer

Yes

No

Session-Expires header value. Optional, should be in range with sst_min_timer and sst_max_timer. See RFC 4028 for more details.

sst_refresh_method_id

integer

No

No

SIP method which will be used for session update. See RFC 4028 for more details. Possible values: 1 - Invite; 2 - Update; 3 - Update fallback Invite.

transport_protocol_id

integer

No

No

The transport layer that will be responsible for the actual transmission of SIP requests and responses: 1 - UDP; 2 - TCP; 3 - TLS.

max_transfers

integer

No

No

Max count of the REFER requests.

max_30x_redirects

integer

No

No

Max count of 301/302 redirects.

media_encryption_mode

string

No

No

Media encryption mode. See RFC4568 about SRTP SDES, RFC5764 about SRTP DTLS, and RFC6189 about ZRTP for more details. Possible values: disabled - Disabled; srtp_sdes - SRTP SDES; srtp_dtls - SRTP DTLS; zrtp - ZRTP.

ice_mode

string

No

No

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

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 disabled.

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 disabled.

stir_shaken_mode

string

No

No

Stir/Shaken mode. See STIR/SHAKEN for more details. Possible values: disabled - Do not send identity; original - Transit Identity header as is; pai - Add PAI, P-Attestation-Indicator, P-Origination-ID; original_pai - Transit Identity header as is and add PAI, P-Attestation-Indicator, P-Origination-ID; verstat - Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID.

allowed_rtp_ips

Array of strings

Yes

No

The allowed RTP IPs: IPv4 or IPv6, single or subnet. Up to 10 items. Null means no restriction. An empty list is rejected. 0.0.0.0/0 and ::/0 are rejected.

network_protocol_priority

string

No

No

Network protocol priority for SIP routing. Possible values: force_ipv4 - Use IPv4 exclusively. force_ipv6 - Use IPv6 exclusively. any - Use either IPv4 or IPv6. prefer_ipv4 - Prefer IPv4 but fall back to IPv6. prefer_ipv6 - Prefer IPv6 but fall back to IPv4.

enabled_sip_registration

boolean

No

No

Enables SIP registration for the trunk. Enabling it generates incoming_auth_username and incoming_auth_password.

use_did_in_ruri

boolean

No

No

Uses the called DID in the R-URI. Requires enabled_sip_registration to be true: sending true while it is false returns 422 Unprocessable Entity.

diversion_relay_policy

string

No

No

Controls how Diversion information is relayed. Possible values: none - Do not relay the Diversion header. as_is - Relay the Diversion header as received. sip - Relay the Diversion header as a SIP URI. tel - Relay the Diversion header as a TEL URI.

diversion_inject_mode

string

No

No

Controls how Diversion information is injected. Possible values: none - Do not add a Diversion header. did_number - Add a Diversion header using the DID number in E.164 format.

cnam_lookup

boolean

No

No

Enables inbound CNAM lookup.

Examples#

http

 1POST /v3/voice_in_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_in_trunks",
10    "attributes": {
11      "priority": 1,
12      "weight": 2,
13      "capacity_limit": 10,
14      "ringing_timeout": 30,
15      "name": "Office",
16      "cli_format": "e164",
17      "cli_prefix": "+",
18      "description": "custom description",
19      "configuration": {
20        "type": "sip_configurations",
21        "attributes": {
22          "username": "username",
23          "host": "example.com",
24          "port": 5060,
25          "codecs": [
26            "pcmu",
27            "g723"
28          ],
29          "rx_dtmf_format_id": 1,
30          "tx_dtmf_format_id": 1,
31          "resolve_ruri": true,
32          "auth_enabled": true,
33          "auth_user": "username",
34          "auth_password": "password",
35          "auth_from_user": "Office",
36          "auth_from_domain": "example.com",
37          "sst_enabled": false,
38          "sst_min_timer": 600,
39          "sst_max_timer": 900,
40          "sst_accept_501": true,
41          "sip_timer_b": 8000,
42          "dns_srv_failover_timer": 2000,
43          "rtp_ping": false,
44          "rtp_timeout": 30,
45          "force_symmetric_rtp": false,
46          "symmetric_rtp_ignore_rtcp": false,
47          "rerouting_disconnect_code_ids": [
48            58,
49            59
50          ],
51          "sst_session_expires": null,
52          "sst_refresh_method_id": 1,
53          "transport_protocol_id": 2,
54          "max_transfers": 0,
55          "max_30x_redirects": 0,
56          "media_encryption_mode": "disabled",
57          "ice_mode": "disabled",
58          "rtcp_mux_mode": "disabled",
59          "rtcp_feedback_mode": "disabled",
60          "stir_shaken_mode": "disabled",
61          "allowed_rtp_ips": null,
62          "network_protocol_priority": "prefer_ipv4",
63          "diversion_relay_policy": "sip",
64          "diversion_inject_mode": "did_number",
65          "cnam_lookup": true
66        }
67      }
68    }
69  }
70}

curl

1curl -i -X POST https://api.didww.com/v3/voice_in_trunks -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"capacity_limit": 10, "cli_format": "e164", "cli_prefix": "+", "configuration": {"attributes": {"allowed_rtp_ips": null, "auth_enabled": true, "auth_from_domain": "example.com", "auth_from_user": "Office", "auth_password": "password", "auth_user": "username", "cnam_lookup": true, "codecs": ["pcmu", "g723"], "diversion_inject_mode": "did_number", "diversion_relay_policy": "sip", "dns_srv_failover_timer": 2000, "force_symmetric_rtp": false, "host": "example.com", "ice_mode": "disabled", "max_30x_redirects": 0, "max_transfers": 0, "media_encryption_mode": "disabled", "network_protocol_priority": "prefer_ipv4", "port": 5060, "rerouting_disconnect_code_ids": [58, 59], "resolve_ruri": true, "rtcp_feedback_mode": "disabled", "rtcp_mux_mode": "disabled", "rtp_ping": false, "rtp_timeout": 30, "rx_dtmf_format_id": 1, "sip_timer_b": 8000, "sst_accept_501": true, "sst_enabled": false, "sst_max_timer": 900, "sst_min_timer": 600, "sst_refresh_method_id": 1, "sst_session_expires": null, "stir_shaken_mode": "disabled", "symmetric_rtp_ignore_rtcp": false, "transport_protocol_id": 2, "tx_dtmf_format_id": 1, "username": "username"}, "type": "sip_configurations"}, "description": "custom description", "name": "Office", "priority": 1, "ringing_timeout": 30, "weight": 2}, "type": "voice_in_trunks"}}'

response

 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": {
 6    "id": "f36d1d17-bd16-42b9-af42-0cfe166bf3ec",
 7    "type": "voice_in_trunks",
 8    "attributes": {
 9      "priority": 1,
10      "capacity_limit": 10,
11      "weight": 2,
12      "name": "Office",
13      "cli_format": "e164",
14      "cli_prefix": "+",
15      "description": "custom description",
16      "ringing_timeout": 30,
17      "pop": null,
18      "created_at": "2017-06-25T08:21:41.795Z",
19      "external_reference_id": null,
20      "configuration": {
21        "type": "sip_configurations",
22        "attributes": {
23          "username": "username",
24          "host": "example.com",
25          "port": 5060,
26          "codecs": [
27            "pcmu",
28            "g723"
29          ],
30          "rx_dtmf_format_id": 1,
31          "tx_dtmf_format_id": 1,
32          "resolve_ruri": true,
33          "auth_enabled": true,
34          "auth_user": "username",
35          "auth_password": "password",
36          "auth_from_user": "Office",
37          "auth_from_domain": "example.com",
38          "sst_enabled": false,
39          "sst_min_timer": 600,
40          "sst_max_timer": 900,
41          "sst_accept_501": true,
42          "sip_timer_b": 8000,
43          "dns_srv_failover_timer": 2000,
44          "rtp_ping": false,
45          "rtp_timeout": 30,
46          "force_symmetric_rtp": false,
47          "symmetric_rtp_ignore_rtcp": false,
48          "rerouting_disconnect_code_ids": [
49            58,
50            59
51          ],
52          "sst_session_expires": null,
53          "sst_refresh_method_id": 1,
54          "transport_protocol_id": 2,
55          "max_transfers": 0,
56          "max_30x_redirects": 0,
57          "media_encryption_mode": "disabled",
58          "ice_mode": "disabled",
59          "rtcp_mux_mode": "disabled",
60          "rtcp_feedback_mode": "disabled",
61          "stir_shaken_mode": "disabled",
62          "allowed_rtp_ips": null,
63          "network_protocol_priority": "prefer_ipv4",
64          "enabled_sip_registration": false,
65          "use_did_in_ruri": false,
66          "incoming_auth_username": null,
67          "incoming_auth_password": null,
68          "diversion_relay_policy": "sip",
69          "diversion_inject_mode": "did_number",
70          "cnam_lookup": true
71        }
72      }
73    },
74    "relationships": {
75      "voice_in_trunk_group": {
76        "links": {
77          "self": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/relationships/voice_in_trunk_group",
78          "related": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/voice_in_trunk_group"
79        }
80      }
81    }
82  },
83  "meta": {
84    "api_version": "2026-11-19"
85  }
86}

Other Responses#

Code

Success

Description

422

No

Unprocessable Entity

400

No

Bad Request. The body is malformed: configuration is missing, or it carries a member the API does not accept. Also returned with the title Quota limit reached when the account has reached its limit of inbound trunks.

401

No

Unauthorized

403

No

The access token carries the read scope, which does not cover this method (title Insufficient scope). The response carries 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.