Binding Object

The Binding object defines a forwarding rule that connects incoming calls from one phone number (origination_did) to another (destination_did) through a CarrierX-provided redirect number (redirect_did).

Bindings can be created to apply globally to all incoming calls, or they can be restricted to specific originating numbers. Each binding can have a defined duration, custom audio, caller ID behavior, and SIP headers. The attributes sub-object allows for additional configuration and fine-grained call handling options.

The redirect_did_info sub-object provides structured information about the redirect number, such as country code and formatted display variations.

Binding Object Attributes

These fields and values make up the JSON object that gets returned with successful requests.

This section also includes information about optional fields that can be added to further customize bindings.

Attribute	Data Type	Description
account_sid read only	string	The account secure ID.
attributes createupdate	object	Optional fields and values added to a binding. Refer to the table below for information on the built-in attributes.
binding_sid read only	string	The binding secure ID. This ID can be used to reference and target a specific Binding object.
date_created read only	string	The date when the binding was created.
destination_did createupdate	string	This phone number will be reached after the origination_did calls and the redirect_did forwards the call. This is a required field to create a binding, alongside with redirect_did. This field accepts phone numbers in the E.164 format.
dtmf createupdate	string	If filled, the dtmf sequence will be executed after dialing the destination_did. For example, this field can be set to automatically enter an access code to a meeting, (e.g., ",,,,1357" means wait two seconds, then enter 1, 3, 5, 7). Each comma pauses for 0.5 seconds.
maximum_ttl createupdate	integer	The number of seconds the binding will remain active. The default value is 3600. Use -1 to create an indefinite binding.
name createupdate	string	The name of the binding. If not explicitly assigned, the value will be set to N/A. This is a friendly name used for internal reference.
origination_did createupdate	string	The calling phone number assigned to the Binding object. If left blank, the binding will apply to calls from any incoming phone number. Entering a phone number restricts the binding to that specific caller. Accepts phone numbers in E.164 format.
redirect_did createupdate	string	The DID used to forward the call to the destination_did. DIDs are rented through CarrierX. This is a required field to create a binding, alongside with destination_did.
redirect_did_info read only	object	Additional information about the redirect_did. Refer to the table below fore more details.
wait_origination_did_ttl createupdate	integer	The number of seconds during which an origination_did can be assigned if it has not already been assigned to the Binding object. As long as the origination_did is not yet set (either at the object creation or through PATCH or PUT requests), the first incoming phone number will be bound. Use -1 to disable this feature, and allow the binding to apply to all incoming calls if no origination_did is set. The default value is 300.

Sample Binding Object

{
    "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
    "attributes": {
        "ringback":"moh"
    },
    "binding_sid": "05561bef-ce48-4823-a847-bf10f7837a42",
    "date_created": "2025-04-09T22:47:56.609Z",
    "destination_did": "15162065338",
    "dtmf": null,
    "maximum_ttl": -1,
    "name": "N/A",
    "origination_did": null,
    "redirect_did": "15162065346",
    "redirect_did_info": {
        "country_code": "USA",
        "e164_format": "+15162065346",
        "in_country_format": "(516) 206-5346",
        "international_format": "+1 516-206-5346",
        "phonenumber": "15162065346"
    },
    "wait_origination_did_ttl": -1
}

Attributes Object

The Attributes sub-object contains optional customization fields for the Binding object. These allow you to control audio playback, caller ID display, SIP headers, and other behaviors.

All attributes are optional and can be combined as needed. Custom attributes can be added using the same structure.

Attribute	Data Type	Description
announce createupdate	string	The audio file that plays to the caller before they are connected to the second party. Accepted file types: .wav and .mp3.
cnam createupdate	string	The CNAM for outbound calls. Note that this may not be preserved for calls terminated through the PSTN.
fix_anonymous_cid createupdate	boolean	Determines whether a blocked or unavailable caller ID will be replaced with the redirect_did. This field is similar to hide_origination_did but targets blocked phone numbers only. Set to true to display the redirect_did instead of blocked numbers.
hide_origination_did createupdate	boolean	Determines whether to hide the caller's phone number. Instead, the redirect_did phone number will appear on the caller ID. Set to true to display the redirect_did instead of the origination_did. The default value is false. To change this value, contact support@carrierx.com.
ringback createupdate	string	Customizes what the caller hears while waiting for the destination_did to answer. Set to false to disable ringing (caller hears silence). Use moh for hold music or passthrough to defer to the destination_did's behavior.
sip_header_* createupdate	string	Values sent as extra SIP headers in the SIP invite. Header names must start with X-.

Redirect DID Info Response Object

The Redirect DID Info sub-object provides metadata about the redirect number used for call forwarding. It includes standardized number formats (E.164, national, and international) and the country code derived from the number.

Attribute	Data Type	Description
country_code read only	string	The ISO 3166-1 alpha-3 code of the redirect DID, given automatically.
e164_format read only	string	The redirect DID number in the E.164 format.
in_country_format read only	string	The redirect DID number in a national format.
international_format read only	string	The redirect DID number in an international format.
phonenumber read only	string	The redirect DID phone number in the E.164 format without the + prefix.