Create Binding

This request creates a Binding object.

post

/bindings

Sample

A sample POST request to create a binding:

curl -X POST \
'https://api.carrierx.com/mediator/v1/bindings' \
-H 'Content-Type: application/json' \
--data-binary '{"destination_did":"15162065338", "attributes": {"ringback":"moh"}}' \
-u 'mediator_user_123:qwerty123'

Response

200 status code with a serialized copy of the Binding object:

{
    "body": {
        "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": 300
    },
    "status": 200
}

Query Arguments

Parameter	Data Type	Description
fallback_country	string	The fallback country to pick a redirect phone number. If multiple numbers from various regions are assigned to the Mediator endpoint, the redirect number will be selected from the specified country. If no phone number from the specified country is assigned, a 409 error will be returned.
reuse	boolean	Whether an existing binding with the same parameters should be used instead of creating a new one.

Body Arguments

JSON representation of the fields and values of the Binding object to be created.

The only required field to establish a binding is destination_did.

For a complete list of Binding object attributes, refer to this section.

Binding Variants

When creating a binding without specifying a redirect_did, an available DID on the account will be assigned as the redirect_did. If no DID can be assigned, a 409 error will be returned, indicating that no redirect_did could be found. Verify that there are available DIDs that can be assigned as a redirect_did automatically.

The request will also fail if there is no available DID for the given origination_did.

Each binding has a maximum_ttl and wait_origination_did_ttl attribute:

• maximum_ttl: An optional field set to 3600 seconds by default, which can be changed to any number of seconds. The binding will remain active until this value reaches 0. After the duration of the maximum_ttl elapses, the binding will expire and be deleted. To extend the binding indefinitely, set this field to -1.

• wait_origination_did_ttl: If origination_did is not specified, the first phone number that calls within this time period will be set as the origination_did, and the binding will only apply to that number. If no call is received within this period, the binding will expire and be deleted. To accept calls from any phone number without binding the first caller, disable this feature by setting the field value to -1.