Trunk Object

This section goes over the parts of the Trunk object. Trunks hold settings that will determine how the system will communicate with an endpoint. Trunks belong to trunk groups.

The Trunk object represents a single telephony connection within a trunk group. Each trunk defines the specific parameters and routing details used to send or receive calls through CarrierX.

A trunk can be configured for inbound, outbound, or bidirectional communication and includes detailed settings for protocols, authentication, capacity limits, and connection endpoints.

Trunks inherit certain attributes from their parent trunk group but can also override group-level settings to define unique behaviors such as codec preferences, SIP signaling details, and routing paths.

This object provides the detailed configuration that enables fine-grained control over how calls are routed through the CarrierX network.

tip

Refer to How It Works: Trunk Groups and Trunks to learn more about what trunks are, what they are used for, and how you can work with them.

Trunk Object Attributes

The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute	Data Type	Description
acls createupdate	array of objects	The Access Control Lists associated with the trunk. Refer to the table below for more information.
allow_forward read only	string	Determines how to handle 302 redirects from leg B. Values accepted in this field are: direct to treat as direct_uri if user@host is specified in contact URI, or to treat as reroute if only user is specified. direct_uri to create call leg to the SIP URI specified in the contact header. If only user is specified without host, assume the host is unchanged and send to the same destination IP again. The new URI will be placed in REDIRECT_URI field of CDRs. disabled to reject the call. protected to allow forward only if the destination IP is associated with an endpoint address, which has its direction set to inbound and is related to the partner third_party endpoint. reroute to use only the phone number portion of the contact URI. Resolve the phone number and route it as a new outbound call, applying all CarrierX routing rules. This will create a 2nd CDR. The default value is disabled.
allow_transcoding createupdate	boolean	Whether transcoding is allowed for calls handled by this trunk. The default value is true.
allow_transfer read only	enum	Determines whether the trunk allows call transfer, using SIP REFER. This field supports blind transfer only; attended transfer is not supported. Values accepted in this field are: disabled: Transfers are disabled. direct_uri: Direct transfer to URI. direct: Direct transfer. reroute: Reroute the call. This creates a second CDR. protected: Protected transfer. The default value is disabled.
asn_mode createupdate	string	Controls the exchange of active speaker notification (ASN) data on the trunk. ASN is used between the conference bridge and the recording server; the bridge normally writes ASN data and the recording server reads it. Values accepted in this field are: disable to disable this feature. read to receive ASN data. write to send ASN data. read_write to both send and receive ASN data. The default value is disable.
call_type createupdate	string	The call type. Values accepted in this field are: redirect_302 for 302 redirect. regular for standard call with media. sip_only for SIP only. The default value is regular.
codec createupdate	string	A legacy codec setting. The value set in this field is always prepended to both in_codec and out_codec, regardless of whether those fields are explicitly set. Values accepted in this field are: alaw, amrwb, g722, g723, g729, gsm, opus8, opus12, opus16, opus24, opus48, ulaw. The default value is null which means that the trunk will use one of the supported codecs from leg A.
endpoint_sid createupdate	string	The secure ID of the endpoint associated with this trunk.
in_capacity createupdate	integer	The maximum number of simultaneous calls which the trunk can receive. Use the -1 value to disable receiving calls by the trunk. 0 means unlimited and is the default value.
in_codec createupdate	string	Defines the ordered list of codecs allowed and prioritized for inbound calls and used to construct the codec list for the outgoing leg when the incoming leg (leg A) does not use a wideband codec. The value is a semicolon-separated string of codec names (e.g., ulaw;alaw). Codecs are listed in priority order, where the first codec has the highest priority. This setting determines which codecs can be used and their priority used when generating the codec list for the outgoing leg (leg B). Uses the same set of supported codec values as the codec field. If any value is set in the codec field, it will be prepended to this field's value. The default value is null. When no value is set, the system uses ulaw;alaw.
in_codec_list createupdate	string	Controls how the codec list is constructed for the outgoing leg (leg B) when the incoming leg (leg A) does not use a wideband codec. If a wideband codec is present on leg A, in_codec_wideband_list is used instead. Values accepted in this field are: full: the system uses the full codec list defined in in_codec (preserving the specified priority order) when building the codec list for the outgoing leg (leg B). passthrough: finds the intersection between the codecs offered on leg A and the codecs defined in in_codec. If there is no match and allow_transcoding is enabled, falls back to the full in_codec list. Note: passthrough does not forward codecs as-is; it performs intersection with the configured codec list. This is the default value. none_if_wideband: if leg A's offer contains a wideband codec, the narrowband codec selection (in_codec) is skipped. This ensures that wideband codec selection is preferred and prevents fallback to narrowband codecs (such as ulaw) to avoid transcoding. If leg A has no wideband codecs, passthrough behavior is applied instead.
in_codec_priority createupdate	string	Defines codec negotiation priority. Values accepted in this field are: leg_a_avoid_transcoding: prefer codecs from leg A to avoid transcoding (default value). leg_b_avoid_transcoding: prefer codecs suitable for leg B to avoid transcoding. leg_b_force: force codec selection based on leg B preferences.
in_codec_wideband createupdate	string	Defines the ordered list of codecs allowed and prioritized for inbound calls and used to construct the codec list for the outgoing leg when the incoming leg (leg A) uses a wideband codec. The value is a semicolon-separated string of codec names (e.g., amrwb;g722). Codecs are listed in priority order, where the first codec has the highest priority. This setting determines which codecs can be used and their priority used when generating the codec list for the outgoing leg (leg B) in wideband scenarios. Uses the same set of supported codec values as the codec field. The default value is null. When no value is set, the system uses amrwb;g722.
in_codec_wideband_list createupdate	string	Controls how the codec list is constructed for the outgoing leg (leg B) when the incoming leg (leg A) uses a wideband codec. If leg A does not use a wideband codec, in_codec_list is applied. Values accepted in this field are: passthrough_if_wideband: applied only when leg A's offer contains a wideband codec. Finds the intersection between leg A's offered codecs and in_codec_wideband. If there is no match and allow_transcoding is enabled, falls back to the full in_codec_wideband list. Note: passthrough does not forward codecs as-is; it performs intersection with the configured codec list. full: always use the full codec list defined in in_codec_wideband when constructing the codec list for leg B, regardless of what codecs leg A offered. full_if_wideband: include all codecs defined in in_codec_wideband, but only if leg A's offer contains at least one wideband codec. If leg A has no wideband codecs, in_codec_list is applied instead. This is the default value. When constructing the final codec list for leg B, codecs selected via in_codec_wideband take precedence over those from in_codec. The system merges both results, removes duplicates, and then applies in_codec_priority to determine the final ordering.
in_identity_format createupdate	string	Determines the format in which the data will be sent to leg B in the case the in_identity_mode/ out_identity_mode is set to pass the RPID/PAI headers. This setting is only applicable when there is data to be sent. Values accepted in this field are: pai to send the information in the PAI format. passthrough to send the information in the format determined by leg A. rpid to send the information in the RPID format. The default value is passthrough.
in_identity_mode createupdate	string	Controls when and how the information about Remote Party ID (RPID) and P-Asserted-Identity (PAI) headers is accepted when the trunk is receiving calls. Values accepted in this field are: always never passthrough rewrite_from See the out_identity_mode parameter below for more information on this. The default value is passthrough.
in_rfc_4694_mode read only	string	Controls whether the number portability parameters for the "tel" URI are accepted for the incoming leg. Values accepted in this field are: accept_all for accepting all the RFC-4694 parameters as they are. cic_only for accepting CIC parameter information only. cut_all for cutting all the RFC-4694 parameters information off the incoming leg. rn_npdi for accepting the information for query to NPDB and routing number only. The default value is cut_all.
location_sid createupdate	string	Secure ID of the Routing Location object that identifies the Trunk object as belonging to a specific location.
name createupdate	string	The trunk name.
out_capacity createupdate	integer	The maximum number of simultaneous calls which the trunk can send. Use the -1 value to disable sending calls by the trunk. 0 means unlimited and is the default value.
out_codec createupdate	string	Defines the ordered list of codecs for outbound calls from the trunk. The value is a semicolon-separated string of codec names in priority order. Uses the same set of supported codec values as the codec field. If any value is set in the codec field, it will be prepended to this field's value.
out_identity_mode createupdate	string	Controls whether Remote Party ID (RPID) and P-Asserted-Identity (PAI) headers are passed when the trunk is sending calls. The behavior depends on the in_identity_mode value and RPID/PAI headers presence, and is described in respect to the accepted values below. passthrough and RPID/PAI headers are present: if in_identity_mode = passthrough or in_identity_mode = never, then 'From' remains unchanged, PAI header is set to RPID/PAI, privacy flags are preserved. if in_identity_mode = always, then 'From' remains unchanged, PAI header is not sent. if in_identity_mode = rewrite_from, then 'From' is set to RPID/PAI, PAI header is not sent. never or RPID/PAI headers are missing: if in_identity_mode = passthrough or in_identity_mode = always or in_identity_mode = rewrite_from, then 'From' remains unchanged, PAI header is not sent. if in_identity_mode = never, then 'From' remains unchanged, PAI header is set to the 'From' value. The default value is passthrough.
out_rfc_4694_mode read only	string	Controls whether the number portability parameters for the "tel" URI are passed to the outgoing leg. Values accepted in this field are: accept_all for passing all the RFC-4694 parameters as they are. cic_only for passing CIC parameter information only. cut_all for cutting all the RFC-4694 parameters information off the outgoing leg. rn_npdi for passing the information for query to NPDB and routing number only. The default value is cut_all.
out_sip_ringing_max_ttl createupdate	integer	Time in seconds during which an outbound call will continue ringing trying to reach the other party before the call is dropped off. The default value is 180.
priority createupdate	integer	Allows to change the routing order for trunks inside a trunk group with the routing_type set to failover. Lower values have higher priority. The default value is 0.
relay_sip_headers createupdate	array	The list of the headers from the incoming leg that must be passed to the outgoing leg. This setting applies when the trunk is receiving calls. Regular expressions can be used instead of complete header names (e.g., the X-.* value will relay all the X-headers).
ring_control createupdate	string	Controls how SIP 183 (Session Progress) and SIP 180 (Ringing) responses are relayed during call setup. Some carriers send a SIP 183 with no media followed by a SIP 180, which can cause the caller to hear silence; this setting adjusts relay behavior to avoid that. Values accepted in this field are: passthrough: relay SIP responses as received, with no special handling. This is the default behavior. suppress_sip183_until_rtp: delay SIP 183 (Session Progress) responses until the first RTP packet is received. suppress_sip180_after_rtp: if a SIP 183 with RTP is followed by a SIP 180, suppress the SIP 180.
transformations createupdate	array of objects	The transformations to apply to the trunk. Refer to the transformations section for more information.
trunk_sid read only	string	The trunk secure ID.
weight createupdate	integer	Allows to distribute the calls among the trunks inside a trunk group with the routing_type set to round_robin. Trunks with bigger values will receive more calls compared to trunks with smaller values. The default value is 0. A weight of 0 is treated as 1, so you cannot use this field to stop calls to a trunk.

Wideband Codecs

A wideband codec is any of the following: amrwb, g722, isac16, isac32, silk16, silk24, opus16, opus24, opus48.

In most cases, including at least one narrowband codec (ulaw or alaw) is recommended to prevent negotiation failures.

Example Trunk Object

{
    "acls": [],
    "allow_forward": "disabled",
    "allow_transcoding": true,
    "allow_transfer": "disabled",
    "asn_mode": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": null,
    "in_capacity": 0,
    "in_codec": "ulaw;alaw",
    "in_codec_list": "passthrough",
    "in_codec_priority": "leg_a_avoid_transcoding",
    "in_codec_wideband": "amrwb;g722",
    "in_codec_wideband_list": "full_if_wideband",
    "in_identity_format": "passthrough",
    "in_identity_mode": "passthrough",
    "in_rfc_4694_mode": "cut_all",
    "location_sid": null,
    "name": "trunk01",
    "out_capacity": 0,
    "out_codec": null,
    "out_identity_mode": "passthrough",
    "out_rfc_4694_mode": "cut_all",
    "priority": 0,
    "relay_sip_headers": [],
    "ring_control": "passthrough", 
    "rtp_timeout": 0,
    "transformations": [],
    "trunk_sid": "4c51c85c-5355-4a91-bf1e-f33d731bcfa9",
    "weight": 0
}

note

Please note, that identity information (the in_identity_mode and out_identity_mode parameters) is supported using either RPID or PAI headers. However, when placing the outbound call leg, the PAI format will always be used for sending.

ACL Object

The ACL (Access Control List) object defines the access rules applied to an individual trunk. It includes the same fields as the trunk group ACL — access_control_rules, direction, and the action fields — but applies them specifically to a single trunk connection.

A trunk-level ACL can override the trunk group's ACL to provide more granular control. As with trunk groups, the SMS-related fields are always null because trunks handle only voice traffic. The voice_action_true and voice_action_false fields define the result of rule matches for voice calls.

Refer to the ACL Object for the full attribute set and behavior.

Attribute	Data Type	Description
access_control_rules createupdate	array	The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules.
direction createupdate	string	The direction for the access control list. Values accepted in this field are: any to apply the rules from the list to both sent and received calls and messages. inbound to apply the rules from the list to received calls and messages. outbound to apply the rules from the list to sent calls and messages. undirected to apply the rules from the list to actions with no direction specified.
sms_action_false read only	string	For the Trunk Object this field is always null and read-only because Trunks are used for voice only.
sms_action_true read only	string	For the Trunk Object this field is always null and read-only because Trunks are used for voice only.
voice_action_false createupdate	string	The action to be executed for calls if no access control rules are applied. Values accepted in this field are: accept to accept the calls. reject403 to reject the call with the 403 status code. reject503 to reject the call with the 503 status code.
voice_action_true createupdate	string	The action to be executed for calls if any access control rules are applied. Values accepted in this field are: accept to accept the calls. reject403 to reject the call with the 403 status code. reject503 to reject the call with the 503 status code.