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 createupdate	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_transfer createupdate	enum	Determines the transfer mode for the trunk. Values accepted in this field are: disabled — Transfers are disabled. direct_uri — Direct transfer to URI. direct — Direct transfer. reroute — Reroute the call. protected — Protected transfer. The default value is disabled.
asn_mode createupdate	string	Controls access to PASSCALLERCSRC and PASSCALLEECSRC variables for ASN proxy. Values accepted in this field are: disable to disable this feature. read to allow reading of ASN proxy flags. write to allow writing of ASN proxy flags. read_write to allow both reading and writing of ASN proxy flags. 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 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 ulaw;alaw.
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 amrwb;g722.
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 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	Determines how SIP 180 (ringing) is handled relative to SIP 183 responses. Values accepted in this field are: passthrough — pass SIP 180 responses as received. This is the default behavior. suppress_sip183_until_rtp — delay SIP 183 responses until RTP is received.
rtp_timeout createupdate	integer	Time in seconds before an RTP (media) timeout occurs. A value of 0 disables the timeout.
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.

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_transfer": "disabled",
    "asn_mode": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": null,
    "in_capacity": 0,
    "in_codec": "ulaw;alaw",
    "in_codec_wideband": "amrwb;g722",
    "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.