Mediator API Reference Guide




Introduction

The hosted Mediator Application Endpoint acts as an intermediary between phone numbers. The service has two primary abilities, bindings and dialouts. With bindings, incoming calls are routed through CarrierX to a destination phone number. In dialouts, The CarrierX system makes outgoing calls to two different parties, who are then brought into a call together.




Using the REST API

This section describes how to obtain credentials to use the API, what types of requests the system recognizes, and the format of the responses. It also holds reference information about pagination and filtering.




Credentials

This section outlines the two sets of credentials: Core API and endpoint-specific. The Core API credentials are used to obtain Mediator endpoint credentials. To get a free CarrierX account and gain Core API credentials, provide an email address on the homepage . The credentials used to log in to the CarrierX website are the same credentials used to access the Core API.

Prior to creating bindings and dialouts , a Mediator Application Endpoint needs to be created. See the Configuring Application Endpoints Quick Start Guide for step-by-step instructions on creating an endpoint.

In the JSON response for a newly created Mediator Application Endpoint, there will be login and password values. These are the credentials to use when working with that particular endpoint. Each endpoint has its own credentials. Entering the Core API credentials instead of the endpoint-specific credentials when working with the mediator API will return the error unauthorized .


Sample Curl Command

This curl command will return a list of all the endpoints of the CarrierX account associated with the login credentials. Use the Core API and CarrierX website login credentials in the query below. The mediator endpoint login and password values will be listed in the returned JSON object. 

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

The credentials of a specific endpoint are found in the properties attribute of the nested mediator object. Locate the login and password values. 

{
  "count": 2,
  "has_more": false,
  "items": [
      {
          "addresses": [
              {
                  "direction": "any",
                  "ip": "10.1.10.69",
                  "port": 5060,
                  "transport": "udp"
              }
          ],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
          "name": "System Gateway",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {},
          "transformations": [],
          "type": "system_gateway",
          "voip_token": null
      },
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "632ec9ba-5bef-4ed3-a36d-56feec8ffd41",
          "name": "current_mediator",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
              "api_url": "https://api.carrierx.com/mediator/v1",
              "login": "sample_mediator_091",
              "password": "LkRO3VOBz0pK"
          },
          "transformations": [],
          "type": "mediator",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 2
}



Requests

API requests require authentication. Refer to the section above for more information about obtaining login information. Endpoint credentials are passed using HTTP basic authentication. Pagination and filtering parameters are passed as part of the query URL. Object fields and values are added to the request body.

The mediator API has the following base URL:

https://api.carrierx.com/mediator/v1

Note that the system only accepts HTTPS requests, and not HTTP requests.




Responses

All responses are returned in the JSON format with a status code. For common errors that get returned, refer to the HTTP Status Codes section.

For a comprehensive list of returned fields for bindings and dialouts, refer to the Binding Object Reference and Dialout Object Reference .




Pagination

The four optional parameters for pagination are: offset , limit , order , and filter . These parameters are added to the query URL of GET requests. They inform how many items should be skipped in the response, the amount of records to return, and in what order the results should appear.

offset determines the amount of items that are skipped in the response. If there are five records and the offset value is 2 , the response will not include the first two records. Instead, it will return records for items three through five. The default value for offset is 0 , meaning that the first existing item will appear first.

The parameter limit determines how many items are returned in the response. The default limit is 10 , meaning that a maximum of ten items will be returned. If the number of items that exist exceeds the limit value, the has_more value in the response will be set to true . Responses also have a total field, which is the total amount of results that match the search criteria. Note that the field total will be null on objects that are uncountable, such as SMS messages.

The last parameter of pagination is order . Enter the field name to be ordered followed by the order value, either asc or desc . For example, name desc will return records sorted by name in reverse-alphabetical order. Since the default is asc , entering name by itself will sort the results by name in alphabetical order.

The JSON response for a successful query using the pagination parameters offset , limit , and order will include a pagination parameter. The value of pagination will be empty if there are no more records existing outside of the queried parameters. If there are existing records outside of the query, the pagination value will include next or previous URLs. These URLs can be used to obtain the remainder of the records available without modifying the original query. Simply construct another GET request with the URL provided in the pagination field.

Parameters and values for pagination are added to the query URL.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings?offset=2&limit=4' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
      "count": 0,
      "has_more": false,
      "items": [],
      "limit": 4,
      "offset": 2,
      "pagination": {
          "previous": "https://api.carrierx.com/mediator/v1/accounts?limit=4&offset=0"
      },
      "total": 1
  },
  "status": 200
}

Pagination Quick Reference

Parameter Data Type Description
filter optional string Use the filter operators to find records according to specific criteria. Please reference the Relational Operator Quick Reference table above in this section for specific definitions and examples.
limit optional integer The number of items to be shown in the response. The value entered should not exceed 1000 . 10 is the default value. This parameter and value are added to the query URL.
offset optional integer The amount of items skipped in the response. 0 is the default value. This parameter and value are added to the query URL.
order optional string The field to be ordered followed by the order value, either asc or desc . Declare the field to be ordered first, and then the order asc or desc . For example: binding_sid desc . This parameter and values are added to the query URL. asc is the default order.

The parameter filter is used to restrict or customize the JSON response. Operators can be combined for more specific searches, and are added to the query URL.


Relational Operator Quick Reference

Operator Definition Example
eq equal to. This search looks for exactly the value entered. In the example, results will have the exact value "my_mediator" for the name field. name eq "my_mediator"
ne not equal to. This search returns records that do not include the value "my_mediator" for the name field. name ne "my_mediator"
gt greater than. This search returns records where the value is exceeded for the field listed. For example, records are returned where the value of maximum_ttl is greater than 40000 . maximum_ttl gt 40000
ge greater than or equal to. This search returns records where the value is greater than or equal to the field listed. For example, records are returned where the value of wait_origination_did_ttl is greater than or equal to 70000 . wait_origination_did_ttl ge 70000
lt less than. This search returns records where the value is less than the field listed. For example, records are returned where maximum_ttl is less than 10000 . maximum_ttl lt 10000
le less than or equal to. This search returns records where the value is less than or equal to the field listed. For example, records are returned where wait_origination_did_ttl is less than or equal to 90000 . wait_origination_did_ttl le 90000
like contains the value indicated in the string passed. % can be added anywhere as part of the string to indicate that there can exist text before or after the string parts. In the example, the command looks for a name starting with "Account". This form of search is case sensitive. Note that this method of search will also work: name like "A%t" , and this search will yield records with name values beginning with A and ending in t . name like "Account%"
ilike same functionality as like but case insensitive. name like "AccOUnt%"
in the current value of the specified field must be contained within the specified list. The following example will return records that have a status value of either "active" or "suspended" . status in ("active", "suspended")



Field Filtering

There are two parameters associated with field filtering: include_fields , and exclude_fields . By default, the fields included in JSON responses are specific to the request made. These returned fields are explained in the Object Reference section for that object.

Refer to the specific object to determine which fields can be included and excluded from the JSON responses. include_fields and exclude_fields accept comma-separated strings as values.

Parameters and values for field filtering are added to the query URL.


Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings?exclude_fields="name"' \
-u '[your_user_name]:[your_password]'

Field Filtering Quick Reference

Parameter Data Type Description
include_fields optional string The comma separated list of fields to be included in the response. The fields depend on the object. See the Object Reference section for that object to see which fields return.
exclude_fields optional string The comma separated list of fields to be excluded from the response. The fields depend on the object. See the Object Reference section for that object to see which fields return.





Bindings


Bindings enable call forwarding from one phone number to another. Bindings can be set to last for a specific amount of time or indefinitely. There are several types of bindings:

  • Bindings that apply to all incoming callers. This type of binding can created by setting wait_origination_did_ttl to -1 and not setting a value for origination_did .
  • Bindings with one specified incoming phone number. A binding can also be restricted to a specific phone number, which means that the phone number specified will be subjected to the binding. This type of binding can be created by setting the origination_did to a phone number in E.164 format.
  • Bindings with one unspecified incoming phone number. To establish a binding with an incoming phone number that is not explicitly defined at the onset, a period of time can be designated during which the first phone number that calls will be assigned to the binding. Once the binding is associated with the first incoming caller, the binding will apply only to that caller. This type of binding can be created by setting wait_origination_did_ttl to a positive number and not setting a value for origination_did .

Bindings are useful in many scenarios. For example, during a marketing campaign that lasts one week, a binding can be set up to forward calls from a rented phone number given to consumers. After the week is over, the binding will expire. The company behind the marketing campaign will not have to subject themselves to calls continuing coming in regarding that specific campaign.




Binding Object Reference

This section goes over the parts of the Binding object. This is the JSON response that gets returned when a request is successful. In this section, there is also information about the optional fields that can be added to further customize bindings.

Field Data Type Description
binding_sid string The binding secure ID. This ID can be used to reference and target a specific Binding object.
account_sid string The account secure ID.
attributes nested object The optional fields and values added to a binding. The built-in attributes are listed in the table below.
date_created string The date that the binding was created.
destination_did string This phone number will be reached after the origination_did has called and the redirect_did has forwarded the call . This is the only required field to create a binding. This field accepts phone numbers in E.164 format.
dtmf string If this field is filled, the dtmf sequence will be executed after dialing the destination_did . For example, this field can be set to automatically enter the access code to a Meeting. (i.e., “,,,,1357” , which means wait two seconds, then enter “1” , “3” , “5” , “7” ). Note that each comma inserted into a dtmf string denotes pausing for .5 seconds.
maximum_ttl integer The number of seconds that the binding will remain active. 3600 is the default value. The value -1 creates an indefinite binding.
name string The name of the binding. If a name is not explicitly assigned to the binding, the value will be set to N/A . Note that this is a friendly name used for internal reference.
origination_did string The calling phone number assigned to the Binding object. If the field is left blank, the binding will apply to calls from any incoming phone numbers. Entering a phone number into the field means that the binding instance will only apply to that specific caller. This field accepts phone numbers in E.164 format.
redirect_did string The DID in this field will be forwarded to the destination_did . DIDs are rented through CarrierX.
wait_origination_did_ttl 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 (at either the creation of the object or through PATCH or PUT requests), the first incoming phone number will be bound. Enter -1 to disable this feature, and allow the binding to apply to all incoming calls if no origination_did is set. 300 is the default value.

Below are the additional binding 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 URL The audio file that plays to the caller before they are connected to the second party. File types accepted are wav and mp3.
cnam string The CNAM for outbound calls. Note that this may not be preserved for calls terminated through the PSTN.
fix_anonymous_cid boolean The value of this field will determine whether or not 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. The value true means that blocked phone numbers will be displayed as the redirect_did phone number.
hide_origination_did boolean The value of this field will determine whether or not to hide the caller’s phone number. Instead, the redirect_did phone number will appear on the caller ID. true is the default value. The value true means that the redirect_did will be displayed instead of the origination_did as the caller. To be able to change the value of this field from true to false , please email support@carrierx.com
ringback string This field is used to customize what the caller hears while waiting for the destination_did to answer.

The value false will disable ringing for the caller, so the caller will hear silence until the destination_did answers.

By passing the value moh , the caller will hear hold music.

Assigning passthrough as the ringback value defers what the caller hears to the destination_did 's behavior.
sip_header_* string The values in this field will be sent as extra SIP headers, added to the SIP invite. The header name must start with X- .




Create Binding

This request creates a new Binding object. destination_did is the only field required to establish a binding. When creating a binding without a binding_did designated, an available DID on the account will be assigned as the binding_did . The request will fail if there is no available DID for the given origination_did .

Each binding has a maximum_ttl and wait_origination_did_ttl attribute. The maximum_ttl attribute is an optional field set to 3600 seconds by default, which can be changed to any duration of seconds. The binding will remain active until the value of this field reaches 0 . After the duration of the maximum_ttl has elapsed, the binding will expire and be deleted. To extend the binding indefinitely, assign -1 as the field value for maximum_ttl .

Adding a value to origination_did will create a binding for that phone number only. If the origination_did value is not specified, the binding will apply to any incoming calling phone number. However, if the wait_origination_did_ttl field is set, the first phone number that calls in will be set as the origination_did and the binding will only apply to that phone number. If no call is received within the time period of wait_origination_did_ttl , the binding will expire. To accept calls from any phone number before the maximum_ttl expires without binding the first phone number that calls, disable wait_origination_did_ttl by setting the field value to -1 .

Method URL
POST /bindings

Body Arguments

Data Type Description
object The body of the Binding object to be created. destination_did is the only field required to establish a binding. The fields for the Binding object are listed in the Binding Object Reference section.

Sample Curl Command

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

Sample JSON Response

{
  "body": {
    "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
    "attributes": {},
    "binding_sid": "05561bef-ce48-4823-a847-bf10f7837a42",
    "date_created": "2018-10-09T22:47:56.609Z",
    "destination_did": "15162065338",
    "dtmf": null,
    "maximum_ttl": -1,
    "name": "N/A",
    "origination_did": null,
    "redirect_did": "15162065346",
    "wait_origination_did_ttl": -1
  },
  "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Binding object . Below are some of the common errors that arise when creating a new binding. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Empty phonenumber This error means that no destination_did was assigned to the binding. This is the only field required when creating a new binding.
400 No available DID for this configuration This error will appear if there is no unused DID available to be assigned as the redirect_did . To successfully create a new binding, an unused DID will need to be associated with the trunk group.
400 Does not have one of following value: [*] and does not exist for this account Ensure that a redirect_did is assigned to the trunk group to which the binding belongs.

The redirect_did field can be left blank and the system will choose a DID that is associated with the trunk group automatically if one is available. However, if no redirect_did is available for the assignment, the binding creation will fail.
400 Already busy for this origination_did(s) The redirect_did has already been assigned to the origination_did . The redirect_did or origination_did must be changed.




Get Bindings Matching the Specified Criteria

This request returns Binding objects matching the specified criteria. This request is enabled for pagination and field filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /bindings

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings?filter=name+eq+"N/A"' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
    "count": 2,
    "has_more": false,
    "items": [
        {
            "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
            "attributes": {},
            "binding_sid": "05561bef-ce48-4823-a847-bf10f7837a42",
            "date_created": "2018-10-09T22:47:56.000Z",
            "destination_did": "15162065337",
            "dtmf": null,
            "maximum_ttl": -1,
            "name": "N/A",
            "origination_did": null,
            "redirect_did": "15162065339",
            "wait_origination_did_ttl": -1
        },
        {
            "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
            "attributes": {},
            "binding_sid": "bedd33b1-2961-458e-b35a-bf80260cdba4",
            "date_created": "2018-10-05T23:13:03.000Z",
            "destination_did": "15162065338",
            "dtmf": null,
            "maximum_ttl": -1,
            "name": "N/A",
            "origination_did": null,
            "redirect_did": "15162065337",
            "wait_origination_did_ttl": -1
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 2
    },
    "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Binding object . Below are some of the common errors that arise when getting bindings matching the specific criteria. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Validation error Ensure that the limit value does not exceed 1000 . Also verify that there are no misspellings and that query parameter values are correctly ordered. For example, it should be name desc instead of desc name .
400 Invalid field specified Ensure that the include_fields and exclude_field values are spelled correctly and that the fields exist in the Binding object. Review the Binding Object Reference for all of the field names that come with the response.
400 Filter validation error Check for misspellings and wrong order in the filter query.
400 Object validation error Ensure that proper values have been input into the field.



Get Binding by SID

This request will return the Binding object matching the specified secure ID. The binding secure ID is passed in the query URL. This request is enabled for Field Filtering .

Method URL
GET /bindings/{binding_sid}

Path Arguments

Parameter Data Type Description
binding_sid required string The binding secure ID.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings/bedd33b1-2961-458e-b35a-bf80260cdba4' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
      "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
      "attributes": {},
      "binding_sid": "bedd33b1-2961-458e-b35a-bf80260cdba4",
      "date_created": "2018-10-05T23:13:03.000Z",
      "destination_did": "15162065338",
      "dtmf": null,
      "maximum_ttl": -1,
      "name": "N/A",
      "origination_did": null,
      "redirect_did": "15162065337",
      "wait_origination_did_ttl": -1
    },
    "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Binding object . Below are some of the common errors that arise when getting a binding by SID. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Invalid field specified The values entered for include_fields or exclude_fields are not valid. Check for spelling errors and use of commas.
404 Cannot find binding by SID The binding does not exist. Ensure that the binding_sid was entered properly. Note that the binding could have expired. To create a binding with no expiration, set the maximum_ttl to -1 .



Update Binding

A binding can be updated through PATCH and PUT requests. A PATCH request requires the binding secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the binding secure ID passed in the query URL, as well as the entire Binding object passed in the query body.

Method URL
PATCH /push/bindings/{binding_sid}

Path Arguments

Parameter Data Type Description
binding_sid required string The binding secure ID.

Body Arguments

Data Type Description
object The binding attributes to be updated. To view the fields that appear in the Binding object, see the Binding Object Reference . Fields that can be changed are:
  • attributes
  • destination_did
  • dtmf
  • maximum_ttl
  • name
  • origination_did
  • redirect_did
  • wait_origination_did_ttl

Sample Curl Command

curl -X PATCH \
'https://api.carrierx.com/mediator/v1/bindings/217b55b3-b872-4406-b6b9-716a4a762e40' \
-H 'Content-Type: application/json' \
--data-binary '{"maximum_ttl":-1}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
      "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
      "attributes": {},
      "binding_sid": "bedd33b1-2961-458e-b35a-bf80260cdba4",
      "date_created": "2018-10-05T23:13:03.000Z",
      "destination_did": "15162065338",
      "dtmf": null,
      "maximum_ttl": -1,
      "name": "N/A",
      "origination_did": null,
      "redirect_did": "15162065337",
      "wait_origination_did_ttl": -1
  },
  "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Binding object . Below are some of the common errors that arise when patching a binding. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Cannot parse json. Check json for validity There is an error in the JSON format. Ensure that quotation marks, colon placement, and spelling are correct. Verify that the phone numbers entered appear in E.164 format without the + prefix.
404 Cannot find binding by SID The binding does not exist. Ensure that the binding_sid was entered properly. Note that the binding could have expired. To create a binding with no expiration, set the maximum_ttl to -1 .
415 Unsupported media type Ensure that the header includes support for the content type JSON.

The PUT request below can be used to update an entire Binding object. The binding secure ID is passed in the query URL and the body parameter is passed in the request body.

Method URL
PUT /bindings/{binding_sid}

Path Arguments

Parameter Data Type Description
binding_sid required string The binding secure ID.

Body Arguments

Data Type Description
object The body of the Binding object to be updated. The Binding object attributes are listed in the Binding Object Reference section. Fields that can be changed are:
  • attributes
  • destination_did
  • dtmf
  • maximum_ttl
  • name
  • origination_did
  • redirect_did
  • wait_origination_did_ttl

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/mediator/v1/bindings/bedd33b1-2961-458e-b35a-bf80260cdba4' \
-H 'Content-Type: application/json' \
--data-binary '{"binding_sid": "bedd33b1-2961-458e-b35a-bf80260cdba4", "maximum_ttl":-1, "account_sid":"13e156f7-0d21-4ba6-9e32-c56dc2c6098f", "date_created":"2018-10-05T23:13:03.000Z", "destination_did":"15162065338", "redirect_did":"15162065339", "wait_origination_did_ttl":-1}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
      "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
      "attributes": {},
      "binding_sid": "bedd33b1-2961-458e-b35a-bf80260cdba4",
      "date_created": "2018-10-05T23:13:03.000Z",
      "destination_did": "15162065338",
      "dtmf": null,
      "maximum_ttl": -1,
      "name": "N/A",
      "origination_did": null,
      "redirect_did": "15162065339",
      "wait_origination_did_ttl": -1
  },
  "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Binding object . Below are some of the common errors that arise when updating a binding. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Empty value Ensure that empty fields have been filled in. To update individual fields and not the whole instance, use a PATCH request instead.
400 Does not have one of following value: [*] and does not exist for this account Verify that the redirect_did is associated with the trunk group that is being targeted in this request.
404 Cannot find binding by SID The binding does not exist. Ensure that the binding_sid was entered properly. Note that the binding could have expired. To create a binding with no expiration, set the maximum_ttl to -1 .
415 Unsupported media type Ensure that the header includes support for the content type JSON.



Delete Binding

This request will delete the binding with a specified binding secure ID. Requests are made by passing the binding_sid through the query URL.

Method URL
DELETE /push/bindings/{binding_sid}

Path Arguments

Parameter Data Type Description
binding_sid required string The secure ID of the binding to be deleted.

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/mediator/v1/bindings/217b55b3-b872-4406-b6b9-716a4a762e40' \
-u '[your_user_name]:[your_password]'

A successful request returns a 200 response with an empty body. Refer to the HTTP Status Codes section for common errors.




Dialouts

Dialouts place a phone call to two phone numbers, and allow both people to speak to one another. Specifically, the redirect_did dials out to both participants in turns. Upon successfully reaching the parties, it brings them into a call together.

Dialout objects are not stored after the two parties have been connected. Only future dialouts can be searched for and modified. To schedule a future dialout, set the delay parameter to the number of seconds before the call will be set up. For example, if the delay parameter is set to 1000 , the dialout will be initiated 1000 seconds from its creation.




Dialout Object Reference

This section describes the elements of the Dialout object. These fields and values make up the JSON object that gets returned with successful requests. In the second table in this section, there is information about the optional fields that can be added to further customize dialouts. These fields can be added when initially creating the dialout, or later using PATCH or PUT requests.

Field Data Type Description
dialout_sid string The dialout secure ID.
account_sid string The secure ID of the account to which the dialout belongs.
attributes nested object The optional fields and values added to a dialout. The attributes are listed in the table below. Note that custom fields can be added in the same manner as the built-in attributes.
date_created string The date that the dialout was created.
delay integer The delay before both parties are contacted, in seconds. 0 is the default value.
redirect_did string The DID that dials out the stage_one_destination_did and stage_two_destination_did values. This field accepts phone numbers in E.164 format.

Below are the additional binding fields that can be added to further customize dialouts. All of these attributes are optional. Custom attributes can be added to the JSON object in the same method as the built-in attributes. Add these attributes as a nested object.

Attribute Data Type Description
sip_header_* string The values in this field will be sent as extra SIP headers, added to the SIP invite. The header name must start with X- .
hide_origination_did boolean The value of this field will determine whether or not to hide the stage_one_destination_did and stage_two_destination_did phone numbers from one another. Instead, the redirect_did phone number will appear on the caller ID. true is the default value. The value true means that the redirect_did will be displayed as the caller on both parties' caller IDs. To be able to change the value of this field from true to false , please email support@carrierx.com
fix_anonymous_cid boolean The value of this field will determine whether or not a blocked or unavailable caller ID will be replaced with the redirect_did . The value true means that blocked phone numbers will be displayed as the redirect_did phone number.
announce URL The audio file that plays to stage_one_destination_did before they are connected to the stage_two_destination_did . File formats accepted are wav and mp3.
cnam string The CNAM for outbound calls. Note that this may not be preserved for calls terminated through the PSTN.
ringback string This field dictates what stage_one_destination_did will hear while stage_two_destination_did is being dialed.

The value false will disable ringing for stage_one_destination_did , so they will hear silence until brought into the call when stage_two_destination_did answers.

By passing the value moh , stage_one_destination_did will hear hold music.

Assigning passthrough as the ringback value defers what stage_one_destination_did hears to the behavior of stage_two_destination_did .
use_call_confirmation URL When the stage_one_destination_did answers, the use_call_confirmation sound file will play. The default value is null . If the URL is set to an invalid value, the default file will play. A URL can be entered to overwrite the default URL.



Create Dialout

This method will establish a dialout. The common workflow is as follows. The redirect_did dials out to the stage_one_destination_did number. When that phone call is answered, the redirect_did dials the stage_two_destination_did . If the second phone call is also answered, the bridge is established between both parties. The Dialout object is deleted once the call has been set up.

The delay parameter can be set to a particular number of seconds. This is the amount of time before the redirect_did will contact the two phone numbers. If not defined, delay will be set to 0 , meaning that dialing will start as soon as the Dialout object is created.

The stage_one_destination_did , stage_two_destination_did , and redirect_did parameters should be unique for each Dialout object. There cannot be two Dialout objects with the same phone numbers existing at the same time. When scheduling several dialouts, ensure each one has unique values for stage_one_destination_did , stage_two_destination_did , and redirect_did.

Additional attributes can be added to a dialout to customize the object. Refer to the Dialout Object Reference for a list of the built-in attributes available. Custom attributes can also be included in the same way as the built-in attributes.

Method URL
POST /dialouts

Body Arguments

Data Type Description
object The body of the Dialout object to be created. Fields required to create a dialout are stage_one_destination_did , stage_two_destination_did , and redirect_did . The fields for the Dialout object are listed in the Dialout Object Reference section.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/mediator/v1/dialouts' \
-H 'Content-Type: application/json' \
--data-binary '{"stage_one_destination_did":"15162065339", "stage_two_destination_did":"15162065338", "redirect_did":"15162065340", "attributes": {"ringback":"false"}}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
      "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
      "attributes": {
          "hide_origination_did": "true"
      },
      "date_created": "2018-10-09T20:40:57.675Z",
      "delay": 0,
      "dialout_sid": "15e93c0c-a0eb-4c5d-9b92-f8fd60b2def6",
      "redirect_did": "15162065337",
      "stage_one_destination_did": "15162065339",
      "stage_two_destination_did": "15162065338"
  },
  "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Dialout Object Reference . Below are some of the common errors that arise when creating a Dialout object. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 No available DID for this configuration The redirect_did and destination DIDs cannot be the same for two scheduled dialouts. The redirect_did will be reserved by the first instance created. After the dialout has connected the two parties, the redirect_did can be reused for other Dialout objects.



Get Dialouts Matching the Specified Criteria

This request will return a list of Dialout objects scheduled for a future time. In other words, the returned dialouts will have a delay parameter value of more than 0 .

Dialouts are enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /dialouts

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/dialouts' \
-u '[your_username]:[your_password]'

Sample JSON Response

{
  "body": {
      "count": 1,
      "has_more": false,
      "items": [
          {
              "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
              "attributes": {
                  "hide_origination_did": "true"
              },
              "date_created": "2018-10-12T20:23:18.000Z",
              "delay": 89959,
              "dialout_sid": "58f76642-463c-47a6-b040-285bd3dc4e00",
              "redirect_did": "15162065346",
              "stage_one_destination_did": "15162065339",
              "stage_two_destination_did": "15162065338"
          }
      ],
      "limit": 10,
      "offset": 0,
      "pagination": {},
      "total": 1
  },
  "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Dialout Object Reference . Below are some of the common errors that arise when getting dialouts matching the specified criteria. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Object validation error Check that the required fields have been filled and that the values inputted are valid.



Get Dialout by SID

This request will return the Dialout object in JSON format for the secure ID specified. The dialout secure ID is passed in the query URL. This request is enabled for Field Filtering .

Method URL
GET /dialouts/{dialout_sid}

Path Arguments

Parameter Data Type Description
dialout_sid required string The dialout secure ID.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/dialouts/13e156f7-0d21-4ba6-9e32-c56dc2c6098f' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
            "attributes": {
                "hide_origination_did": "true"
            },
            "date_created": "2018-10-09T20:43:22.000Z",
            "delay": 89992,
            "dialout_sid": "8b2423ab-5a8b-438d-8c15-b9eee5879a5d",
            "redirect_did": "15162065337",
            "stage_one_destination_did": "15162065339",
            "stage_two_destination_did": "15162065338"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
  },
  "status": 200
}

A successful request will return a 200 response code with a serialized copy of the Dialout Object Reference . Below are some of the common errors that arise when getting a dialout by SID. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
404 Cannot find dialout by SID Verify that the dialout SID has been entered correctly. Note that dialouts expire after the call has been connected.



Update Dialout

Dialouts can be updated using a PATCH or PUT request. A PATCH request requires passing the dialout secure ID through the query URL, and the parameter to be updated through the request body. A PUT request requires passing the dialout secure ID through the query URL, and passing the entire Dialout object through the request body.

Method URL
PATCH /dialouts/{dialout_sid}

Path Arguments

Parameter Data Type Description
dialout_sid required string The dialout secure ID.

Body Arguments

Data Type Description
object The dialout fields and values to be updated. To view the attributes that appear in the Dialout object, see the Dialout Object Reference . Fields that can be changed are:
  • attributes
  • delay
  • redirect_did

Sample Curl Command

curl -X PATCH \
'https://api.carrierx.com/mediator/v1/dialouts/13e156f7-0d21-4ba6-9e32-c56dc2c6098f' \
--data-binary '{"delay": "1800"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "body": {
        "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
        "attributes": {
            "hide_origination_did": "true"
        },
        "date_created": "2018-10-09T20:43:22.000Z",
        "delay": 1800,
        "dialout_sid": "8b2423ab-5a8b-438d-8c15-b9eee5879a5d",
        "redirect_did": "15162065337",
        "stage_one_destination_did": "15162065339",
        "stage_two_destination_did": "15162065338"
    },
    "status": 200
  }
}

The following PUT request will update the entire Dialout object, and can be used to delete values. The dialout secure ID is passed in the query URL and the entire Dialout object is passed in the request body.


Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/mediator/v1/dialouts/13e156f7-0d21-4ba6-9e32-c56dc2c6098f' \
--data-binary '{"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f", "attributes": {"hide_origination_did": "true"}, "date_created": "2018-10-09T20:43:22.000Z", "delay": 0, "dialout_sid": "8b2423ab-5a8b-438d-8c15-b9eee5879a5d", "redirect_did": "15162065337", "stage_one_destination_did": "15162065339", "stage_two_destination_did": "15162065338"}' \
-u '[your_user_name]:[your_password]'

Path Arguments

Parameter Data Type Description
dialout_sid required string The dialout secure ID.

Body Arguments

Data Type Description
object The entire Dialout object including the values to be updated. To view the attributes that appear in the Dialout object, see the Dialout Object Reference . Fields that can be changed are:
  • attributes
  • delay
  • redirect_did

Sample JSON Response

{
    "body": {
        "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
        "attributes": {
            "hide_origination_did": "true"
        },
        "date_created": "2018-10-09T20:43:22.000Z",
        "delay": 0,
        "dialout_sid": "8b2423ab-5a8b-438d-8c15-b9eee5879a5d",
        "redirect_did": "15162065337",
        "stage_one_destination_did": "15162065339",
        "stage_two_destination_did": "15162065338"
    },
    "status": 200
  }
}



Delete Dialout

This call will delete the dialout associated with the specified secure ID. The dialout secure ID is passed in the query URL.

Method URL
DELETE /dialouts/{dialout_sid}

Path Arguments

Parameter Data Type Description
dialout_sid required string The dialout secure ID.

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/mediator/v1/dialouts/13e156f7-0d21-4ba6-9e32-c56dc2c6098f' \
-u '[your_user_name]:[your_password]'

A successful request returns a 200 response with an empty body. Refer to the HTTP Status Codes section for common errors.





DIDs

DIDs are phone numbers rented through CarrierX. They serve as redirect_did values.




DID Object Reference

This section describes the elements of the DID object. These fields and values make up the JSON object that gets returned with successful requests.

Attribute Data Type Description
account_sid string The secure ID of the account to which the DID belongs.
destination_did string The ISO 3166-1 alpha-3 code of the DID. This field is not used for mediator endpoints.
did_sid string The secure ID of the DID.
in_country_format string The DID in national format. This field is not used for mediator endpoints.
attributes string The DID in international format. This field is not used for mediator endpoints.
phonenumber string The phone number for the DID in E.164 format without the + prefix.



Get DIDs Matching the Specified Criteria

This request returns a list of DIDs associated with a Mediator endpoint. CarrierX will automatically populate this collection with DIDs routed to the specific endpoint. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /bindings/{binding_sid}

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/dids' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
      "count": 1,
      "has_more": false,
      "items": [
          {
              "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
              "country_code": null,
              "did_sid": "5dbed1ba-b7e7-4337-9d9c-36ef03ac2805",
              "in_country_format": null,
              "international_format": null,
              "phonenumber": "15162065337"
          }
      ],
      "limit": 10,
      "offset": 0,
      "pagination": {},
      "total": 1
  },
  "status": 200
}




Get DID by SID

This request will return detailed information for a selected DID associated with a specific secure ID. The DID secure ID is passed in the query URL. This request is enabled for Field Filtering .

Method URL
GET /dids/{did_sid}

Path Arguments

Parameter Data Type Description
did_sid required string The secure ID of the DID.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/mediator/v1/dids/5dbed1ba-b7e7-4337-9d9c-36ef03ac2805' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "body": {
      "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
      "country_code": null,
      "did_sid": "5dbed1ba-b7e7-4337-9d9c-36ef03ac2805",
      "in_country_format": null,
      "international_format": null,
      "phonenumber": "15162065337"
  },
  "status": 200
}





HTTP Status Codes

This section lists the HTTP status codes that the API returns with each request. Note that additional error codes and messages are listed after Sample JSON Responses in the sections to which they are pertinent.


Success Response

Response Code Message Description
200 OK                               The request has succeeded. The information returned with the response depends on the method used in the request.

Error Response

Response Code Message Description
400 Bad request The request could not be understood by the server due to incorrect syntax, improper formatting of a request, or invalid/unauthorized request. The client should not repeat the request without modifications.
400 No JSON object could be decoded Generally an indicator that there is a syntax error.
401 Unauthorized The request requires user authentication.
401 Bad credentials The request requires correct user authentication.
403 Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
404 Not Found The requested resource was not found on the server.
404 Cannot find (binding, item, dialout) by SID The SID number does not exist. Verify that the SID has been entered correctly. Note that bindings and dialouts can expire.
415 Unsupported media type Ensure that the header includes support for the content type JSON.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.