Binding Object

This section describes the elements of the Binding object.

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
}

Attribute Object

Below are the additional fields that can be added to further customize bindings. All of these attributes are optional. Custom fields and values can also be added in the same fashion as the other binding attributes are. Add these attributes as a nested object.

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

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.