Mediator Reference Guide


Getting Started

The CarrierX service offers a hosted Application Endpoint known as Mediator that enables you to control the flow, connectivity and binding durations of your application's voice calls. This endpoint type can be used to create time-limited connections that allow you to log call behavior, such as logging calls to a phone number used in an advertisement that runs for 1 week.

You will need to provision the Application Endpoint type Mediator in your account prior to accessing its API Reference Guide. For immediate help provisioning Mediator, refer to:

Upon successful provisioning of your Application Endpoint Mediator, you will be provided a username and password to access the service. The Mediator API can be accessed from the following base URL:


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

All data is sent and received in the JSON format and all of your API requests will require authentication. If you have not yet obtained your CarrierX account, please provide your email address on the homepage to create your free account.

If you prefer, you can contact our customer service team by phone to help you get started: (844) 844-1322.


Accounts

Once you have obtained your log in credentials, you will be able to access our web-based API Explorer and grab Curl examples to short-cut your coding. Additionally, your credentials will allow you to immediately access our platform programmatically should you prefer.

We look forward to supporting your understanding of our Mediator API

Get Accounts Matching the Specified Criteria

This call will show data for the currently logged in Account.

METHOD URL
GET /accounts

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password]  "https://api.carrierx.com/mediator/v1/accounts?offset=0&limit=10&order=name"

Request Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name like "Account%"
order string Specifies order of items in the response: asc, desc

Example:
account_sid desc

include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
        "account_sid": "53a1ffa0-9312-43f5-959a-ba383b5162d0",
        "login": "march_02_mediator_292",
        "name": "N/A",
        "date_created": "2017-03-02T08:51:03.000Z",
        "callback_url": null
  }

Response Parameters

Attribute Data Type Description
account_sid opt string Account secure ID
name opt string Account name
login string Login to the web or WS API
password string Password to the web or WS API. The field is hidden
date_created opt string Date and time when the account was created
callback_url opt string Callback for this account for different events

Get Account by SID

The call will return information for a particular Account whose secure ID is specified to retrieve the data.

METHOD URL
GET /accounts/{account_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/mediator/v1/accounts/c79722ff-2472-47a0-abbc-11ba04ca7a15"

Request Parameters

Parameter Data Type Description
account_sid req string Partner secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "status": 200,
  "body": {
      "login": "mediator_test_login",
      "name": "Account",
      "date_created": "2016-03-21T12:58:30.000Z",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "callback_url": null
  }
}

Response Parameters

Attribute Data Type Description
account_sid opt string Account secure ID
name opt string Account name
login string Login to the web or WS API
password string Password to the web or WS API. The field is hidden
date_created opt string Date and time when the account was created
callback_url opt string Callback for this account for different events



OAuth

You can use either your master account credentials to access API, or any of your partner’s (i. e. sub accounts). Each partner has access to his and only his resources. To be able to access resources of another partner, use his partner_sid and access_token.

Revoke Current OAuth Token

This call will terminate your session.

METHOD URL
POST /oauth/logout

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/mediator/v1/oauth/logout”



Revoke OAuth Token

This will terminate session of the partner whose token is specified.

METHOD URL
POST /oauth/revoke/{token}

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/mediator/v1/oauth/revoke/8bfd6c6d-6291-488a-bed1-8784c195ce87"

Parameters

Parameter Data Type Description
token req string Access token


Get OAuth Bearer Token

This call generates the token for a partner upon request.

METHOD URL
POST /oauth/token

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password]  "https://api.carrierx.com/mediator/v1/oauth/token?grant_type=password&client_id=fcc4&client_secret=50339091-14fe-442c-bbcb-83b674dbf90c&username=fcc_test&password=fcc_test_pwd&scope=trust

Parameters

Parameter Data Type Description
grant_type req string Grant type for this token
client_id req string Client ID, unique string representing the registration information provided to the client upon request (see also rfc6749)
client_secret req string Client secret, unique string representing the registration information provided to the client upon request (see also rfc6749)
username req string Login of the partner
password req string Password of the partner
scope req string Scope of the access request available for the client

Sample Response

 {
"access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
"token_type": "bearer",
"refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
"expires_in": 599,
"scope": "trust"
}

Attributes

Attribute Data Type Description
access_token string Access token string
token_type string Type of the token
refresh_token string Refresh token
expires_in string Number of seconds during which the token will be valid
scope string Scope of the access request available for the client


Get All Active OAuth Bearer Tokens for the Partner

Shows tokens for the logged in partner that haven’t yet been expired.

METHOD URL
GET /oauth/token

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password]  "https://api.carrierx.com/mediator/v1/oauth/tokens"

Sample Response

 {
   "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
   "token_type": "bearer",
   "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
   "expires_in": 461,
   "scope": "trust"
}

Attributes

Attribute Data Type Description
access_token string Access token string
token_type string Type of the token
refresh_token string Refresh token
expires_in string Number of seconds during which the token will be valid
scope string Scope of the access request available for the client

Get the Currently Logged in Partner

The call will return the currently logged in partner.

METHOD URL
GET /oauth/whoami

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/mediator/v1/oauth/whoami"

Sample Response

 {
  "name": "Account",
   "login": "mediator_test_login",
   "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
   "date_created": "2016-03-21T12:58:30.000Z"
}

Attributes

Attribute Data Type Description
name string Partner secure ID
parent_sid opt string Parent Partner secure ID
name opt string Partner name
login string Login to the web or WS API
password string Password to the web or WS API. The field is hidden




Dialouts

Dialouts API provides possibility to set up a call bridge between two phone numbers. The redirect_did serves as a bridge number that dials out to both participants in turns and, having reached both, brings them into the call.


The dialout objects are not stored. Once the call has been set up, the dialout is removed. The only dialouts that can be searched for and / or modified are those that have been scheduled for some time in the future. To schedule a dialout, you need to set the “delay” parameter to the amount of seconds that should elapse before the call is set up.

Get Dialouts Matching the Specified Criteria

This method will obtain the list of existing dialout objects scheduled for some time in the future, i. e. the “delay” parameter has been set to some value in seconds that should elapse before the dialing out is performed.

METHOD URL
GET /dialouts

Sample URL


curl -X GET --header "Accept: application/json" -u [your_username]:[your_password] "https://api.carrierx.com/mediator/v1/dialouts?offset=0&limit=10"

Request Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name eq 'Test' and redirect_did like '1208%'
order string Specifies order of items in the response: asc, desc

Example:
name desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "dialout_sid": "68dfed12-d91e-4a9e-a5eb-e9385878140d",
  "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
  "date_created": "2016-09-26T13:23:54.000Z",
  "redirect_did": "15162065032",
  "stage_one_destination_did": "17605692222,,,9,,2542",
  "stage_two_destination_did": "1",
  "delay": 744,
  "attributes": {
      "hide_origination_did": "true"
  }
}

Response Parameters

Attribute Data Type Description
dialout_sid opt string Dialout secure ID
account_sid opt string Secure ID of the Account which Dialout belongs to
date_created opt string Date when the dialout was created
redirect_did opt string DID which performs bridging between 'stage_one_destination_did' and 'stage_two_destination_did' in E.164 format
stage_one_destination_did string First call destination DID in E.164 format
stage_two_destination_did opt string Second call destination DID in E.164 format
transport string Protocol which this Address belongs to (udp – default, tcp)
delay integer Delay for the call in seconds
attributes string Additional attributes for the Dialout

Create a New Dialout

This method is used to create a new dialout instance. The common workflow is as follows: the “redirect_did” dials out to the “stage_one_destination_did” number. If successful, the “redirect_did” reaches for the “stage_two_destination_did”, and sets up the bridging between those two numbers.

The dialout object is removed once the call has been set up.

Should the call happen at some time in future, set the “delay” parameter to the amount of seconds upon expiration of which the POST request should be made. If not defined, the “delay” will be set to “0”, meaning dialing will start the same moment the dialout object is created.

"stage_one_destination_did", "stage_two_destination_did", and "redirect_did" parameters should be unique for each existing dialout object, meaning there can’t be two identical dialout objects Thus, if you intend to schedule several dialouts, ensure each one has a unique set of values for those parameters.

You can use the below attributes to customize your dialout object.

Attribute Data Type Description
sip_header_* string Extra SIP headers that need to be added to SIP invite. The header name must start with X- or WYDE-)
hide_origination_did boolean Whether or not hide the caller’s number, so that the redirect DID will be used as callerID. Possible values are true or false.
fix_anonymous_cid boolean Whether or not replace anonymous / restricted / unavailable callerID with the redirect DID.
announce URL Play the specified file to caller.
cnam string Custom CNAM for calls.
ringback string 180/183 session message management:
Possible values: passthrough - proxing 180/183 from legb; false - disable 180 for caller, send 200 immediately, moh - play misuc on hold. The call will be answered immediately.
use_call_confirmation URL Play the specified message for the call confirmation.



METHOD URL
POST /dialouts

Sample URL


curl -X POST --header "Content-Type: application/json" -u [your_user_name]:[your_password] -d "{"stage_one_destination_did ":"123456789", "stage_two_destination_did ":"321654987", "redirect_did":"15162065032"}" "https://api.carrierx.com/mediator/v1/bindings/dialouts"

Request Parameters

Parameter Data Type Description
body req ... Body of the Endpoint to be created

Sample Response

{
  "status": 200,
  "body": {
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "redirect_did": "15162065032",
      "stage_one_destination_did": "123456789",
      "stage_two_destination_did": "321654987",
      "attributes": {}
  }
}

Response Parameters

Attribute Data Type Description
dialout_sid opt string Dialout secure ID
account_sid opt string Secure ID of the Account which Dialout belongs to
date_created opt string Date when the dialout was created
redirect_did opt string DID which performs bridging between 'stage_one_destination_did' and 'stage_two_destination_did' in E.164 format
stage_one_destination_did string First call destination DID in E.164 format
stage_two_destination_did opt string Second call destination DID in E.164 format
transport string Protocol which this Address belongs to (udp – default, tcp)
delay integer Delay for the call in seconds
attributes string Additional attributes for the Dialout


Remove Dialout

This call will delete the dialout of the specified secure ID.

METHOD URL
DELETE /dialouts/{dialout_sid}

Sample URL


curl -X DELETE --header "Accept: application/json" -u "[YOUR USERNAME]:[YOUR PASSWORD]" "https://api.carrierx.com/mediator/v1/dialouts/16139110-c15b-4125-81b5-637e867a757d"

Request Parameters

Parameter Data Type Description
dialout_sid req string Dialout secure ID.

Get Dialout by SID

This call will return configured dialout parameters in JSON format for the secure ID specified.

METHOD URL
GET /dialouts/{dialout_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u " [YOUR USERNAME]:[YOUR PASSWORD]" "https://api.carrierx.com/mediator/v1/dialouts/2f7fdead-152a-4546-b502-d2d0d9e1b48c"

Request Parameters

Parameter Data Type Description
dialout_sid req string Dialout secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

 {
  "status": 200,
  "body": {
      "dialout_sid": "2f7fdead-152a-4546-b502-d2d0d9e1b48c",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "date_created": "2016-09-26T13:56:29.000Z",
      "redirect_did": "15162065032",
      "stage_one_destination_did": "17605692222,,,9,,2542",
      "stage_two_destination_did": "16417153800,,,86232#",
      "delay": 1490,
      "attributes": {
          "hide_origination_did": "false"
      }
  }
}

Response Parameters

Attribute Data Type Description
dialout_sid opt string Dialout secure ID
account_sid opt string Secure ID of the Account which Dialout belongs to
date_created opt string Date when the dialout was created
redirect_did opt string DID which performs bridging between 'stage_one_destination_did' and 'stage_two_destination_did' in E.164 format
stage_one_destination_did string First call destination DID in E.164 format
stage_two_destination_did opt string Second call destination DID in E.164 format
transport string Protocol which this Address belongs to (udp – default, tcp)
delay integer Delay for the call in seconds
attributes string Additional attributes for the Dialout

Patch Dialout

This call will patch the existing dialout instance. For instance, you can use it to change modify the “delay” value, or specify additional attributes to the dialout

METHOD URL
PATCH /dialouts/{dialout_sid}

Sample URL


curl -X PATCH --header "Content-Type: application/json" -u " [YOUR USERNAME]:[YOUR PASSWORD]" -d "{"delay": "1800"}" "https://api.carrierx.com/mediator/v1/dialouts/2f7fdead-152a-4546-b502-d2d0d9e1b48c"

Request Parameters

Parameter Data Type Description
dialout_sid req string Dialout secure ID
body req ... Dialout body

Sample Response

{
  "status": 200,
  "body": {
      "dialout_sid": "2f7fdead-152a-4546-b502-d2d0d9e1b48c",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "date_created": "2016-09-26T13:56:29.000Z",
      "redirect_did": "15162065032",
      "stage_one_destination_did": "17605692222,,,9,,2542",
      "stage_two_destination_did": "16417153800,,,86232#",
      "delay": 1800,
      "attributes": {
          "hide_origination_did": "false"
      }
  }
}

Response Parameters

Attribute Data Type Description
dialout_sid opt string Dialout secure ID
account_sid opt string Secure ID of the Account which Dialout belongs to
date_created opt string Date when the dialout was created
redirect_did opt string DID which performs bridging between 'stage_one_destination_did' and 'stage_two_destination_did' in E.164 format
stage_one_destination_did string First call destination DID in E.164 format
stage_two_destination_did opt string Second call destination DID in E.164 format
transport string Protocol which this Address belongs to (udp – default, tcp)
delay integer Delay for the call in seconds
attributes string Additional attributes for the Dialout

Update an Existing Dialout

This call will update the dialout instance. This call can be used to remove values.

METHOD URL
PUT /dialouts/{dialout_sid}

Sample URL


curl -X PUT --header "Content-Type: application/json" -u " [YOUR USERNAME]:[YOUR PASSWORD]" -d "{ "dialout_sid": "2f7fdead-152a-4546-b502-d2d0d9e1b48c", "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15", "date_created": \"2016-09-26T13:56:29.000Z", "redirect_did": \"15162065032", "stage_one_destination_did": "17605692222,,,9,,2542", "stage_two_destination_did": "16417153800,,,86232#", "delay": 1603, "attributes": { "hide_origination_did": "false"}} "https://api.carrierx.com/mediator/v1/dialouts/2f7fdead-152a-4546-b502-d2d0d9e1b48c"

Request Parameters

Parameter Data Type Description
dialout_sid req string Dialout secure ID
body req ... Dialout body

Sample Response

 {
  "status": 200,
  "body": {
      "dialout_sid": "2f7fdead-152a-4546-b502-d2d0d9e1b48c",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "date_created": "2016-09-26T13:56:29.000Z",
      "redirect_did": "15162065032",
      "stage_one_destination_did": "17605692222,,,9,,2542",
      "stage_two_destination_did": "16417153800,,,86232#",
      "delay": 1603,
      "attributes": {
          "hide_origination_did": "false"
      }
  }
}

Response Parameters

Attribute Data Type Description
dialout_sid opt string Dialout secure ID
account_sid opt string Secure ID of the Account which Dialout belongs to
date_created opt string Date when the dialout was created
redirect_did opt string DID which performs bridging between 'stage_one_destination_did' and 'stage_two_destination_did' in E.164 format
stage_one_destination_did string First call destination DID in E.164 format
stage_two_destination_did opt string Second call destination DID in E.164 format
transport string Protocol which this Address belongs to (udp – default, tcp)
delay integer Delay for the call in seconds
attributes string Additional attributes for the Dialout





DIDs

Get DIDs Matching the Specified Criteria

Shows the list of DID numbers used as redirect DIDs for binding instances. If no filter is specified, the number of displayed items will be limited by the ‘limit’/’offset” values only. If the number of items exceeds the “limit” value, the ‘has_more’: in the response is set to “true”.

METHOD URL
GET /dids

Sample URL


curl -X GET --header "Accept: application/json" -u "[YOUR USERNAME]:[YOUR PASSWORD]" "https://api.carrierx.com/mediator/v1/dids?offset=0&limit=10&filter=phonenumber%20ne%20%22null%22%20and%20country_code%20eq%20%22USA%22"

Request Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.
order string Specifies order of items in the response: asc, desc

Example:
name desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
      "phonenumber": "15162065030",
      "details": [],
      "did_sid": "8aef5616-c28f-4b67-874c-e7082a01656b",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "country_code": "USA",
      "in_country_format": "(516) 206-5030",
      "international_format": "+1 516-206-5030"
  }

Response Parameters

Attribute Data Type Description
phonenumber string Phone number for this DID in E.164 format
did_sid string DID secure ID
account_sid string Secure ID of the Account which DID belongs to
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
in_country_format string DID in national format
international_format string DID in international format

Get DID by SID

This call will allow you to obtain detailed information for the selected DID associated to a specific SID.

METHOD URL
GET /dids/{did_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u "[YOUR USERNAME]:[YOUR PASSWORD]” "https://api.carrierx.com/mediator/v1/8aef5616-c28f-4b67-874c-e7082a01656b"

Request Parameters

Parameter Data Type Description
did_sid req string DID secure ID
include_fields string Comma separated list of fields that should be included in response
exclude_fields string Comma separated list of fields that should be excluded from response.

Sample Response

 {
  "status": 200,
  "body": {
      "phonenumber": "15162065030",
      "details": [],
      "did_sid": "8aef5616-c28f-4b67-874c-e7082a01656b",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "country_code": "USA",
      "in_country_format": "(516) 206-5030",
      "international_format": "+1 516-206-5030"
  }
}

Response Parameters

Attribute Data Type Description
phonenumber string Phone number for this DID in E.164 format
did_sid string DID secure ID
account_sid string Secure ID of the Account which DID belongs to
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
in_country_format string DID in national format
international_format string DID in international format




Bindings


Getting Binding Matching the Specified Criteria

This call will show all currently existing binding instances in the system. Each binding contains a "maximum_ttl" and "wait_origination_did_ttl" attribute. When each is set to a specific temporal value, the binding will only be valid for that specific amount of time, at which point the binding will expire.

If "origination_did" is not specified the binding will match any calling number. Once an initial call is received, the binding will update itself to accept new calls only from the same calling number. If no call has been received within "wait_origination_did_ttl" (default: 5m), the binding will expire at that time. Otherwise, the binding will stay active until the "maximum_ttl" has been reached.

The call locking feature is useful when you want a temporary binding which should be tied to one end-user, but you do not know what their calling number will be. This functionality can be disabled by setting "wait_origination_did_ttl" to "-1", in which case the binding will continue to accept calls from any calling number for as long as it remains active.

Moreover, if "maximum_ttl" is set to a value of "-1", then the life period of the binding instance is unlimited. If "wait_origination_did_ttl" is set to a value of "-1", then the determination of the originating DID number is disabled.

METHOD URL
GET /bindings

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password]  "https://api.carrierx.com/mediator/v1/bindings?offset=0&limit=10"

Request Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name eq 'test' and redirect_did like '1%'
order string Specifies order of items in the response: asc, desc

Example:
status desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
          {
              "binding_sid": "a3577c38-650d-45ec-9a36-28298fcb54f2",
              "account_sid": "27e96a36-a37b-4246-8ae1-7ee2153c64b5",
              "name": "N/A",
              "date_created": "2016-04-20T11:10:01.000Z",
              "origination_did": null,
              "redirect_did": "17208209020",
              "destination_did": "17605697676",
              "dtmf": null,
              "maximum_ttl": -1,
              "wait_origination_did_ttl": -1,
              "attributes": {
                  "announce": "[LINK TO FILE]"
              }
          }
      ]
  }
}

Response Parameters

Attribute Data Type Description
binding_sid string Binding secure ID
name string Binding name
account_sid string Secure ID of the Account which binding belongs to
date_created string Date when the binding was created
origination_did string DID that originates the call in E.164 format. If empty, receive call from any origination DID
redirect_did string DID that redirects the call in E.164 format
destination_did string Call destination DID in E.164 format.
maximum_ttl integer Number of seconds during which the binding will be active, -1 means eternity
wait_origination_did_ttl integer Number of seconds during which the binding will determine origination_did, -1 means determination is disabled. Default value 300 seconds.
attributes string Additional attributes for the binding

Create a New Binding

This call creates a new binding instance. The only mandatory field is "destination_did" which must be defined for such a binding to occur.

Several additional fields are available for configuration and if not explicitly set will have the following default values:
i. redirect_did - if not specified, the value will be set to one of the available DID numbers associated to your account. ii. maximum_ttl - if not specified, the default value will be set to 1 hour (3600 seconds).

You may use the following attributes to customize your binding.

Attribute Data Type Description
sip_header_* string Extra SIP headers that need to be added to SIP invite. The header name must start with X- or WYDE-)
hide_origination_did boolean Whether or not hide the caller’s number, so that the redirect DID will be used as callerID. Possible values are true or false.
fix_anonymous_cid boolean Whether or not replace anonymous / restricted / unavailable callerID with the redirect DID.
announce URL Play the specified file to caller.
cnam string Custom CNAM for calls.
ringback string 180/183 session message management:
Possible values: passthrough - proxing 180/183 from legb; false - disable 180 for caller, send 200 immediately, moh - play misuc on hold. The call will be answered immediately.
use_call_confirmation URL Play the specified message for the call confirmation.

Note: Bindings will be automatically removed should one of the following cases occur:

i. Case 1: maximum_ttl - by setting this parameter to a specific value in seconds, the binding will expire once that value is achieved. ii. Case 2: origination_did - if this parameter has no value, and the "wait_origination_did_ttl" timer expires, if set to some value in seconds.

METHOD URL
POST /bindings

Sample URL


curl -X POST --header "Content-Type: application/json" -u [your_user_name]:[your_password] -d "{"destination_did":"5055000550005", "name":"B42016","origination_did":"455122336444"}" "https://api.carrierx.com/mediator/v1/bindings"

Request Parameters

Parameter Data Type Description
body req object Body of the binding object to be created

Sample Response

 {
  "status": 200,
  "body": {
      "binding_sid": "b119aa4f-7146-46e3-af9f-dad0fdea5825",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "name": " B42016",
      "date_created": "2016-06-10T10:10:25.000Z",
      "origination_did": “455122336444”,
      "redirect_did": "15162065032",
      "destination_did": “5055000550005”,
      "dtmf": null,
      "maximum_ttl": 3600,
      "wait_origination_did_ttl": 300,
      "attributes": {
          "hide_origination_did": "false"
          "announce": "[LINK TO FILE]"
      }
  }
}

Response Parameters

Attribute Data Type Description
binding_sid string Binding secure ID
name string Binding name
account_sid string Secure ID of the Account which binding belongs to
date_created string Date when the binding was created
origination_did string DID that originates the call in E.164 format. If empty, receive call from any origination DID
redirect_did string DID that redirects the call in E.164 format
destination_did string Call destination DID in E.164 format.
maximum_ttl integer Number of seconds during which the binding will be active, -1 means eternity
wait_origination_did_ttl integer Number of seconds during which the binding will determine origination_did, -1 means determination is disabled. Default value 300 seconds.
attributes string Additional attributes for the binding

Remove Binding

This call will delete the binding of the specified secure ID.

METHOD URL
DELETE /push/bindings/{binding_sid}

Sample URL


curl -X DELETE --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/mediator/v1/bindings/c4971ae7-2c3a-4c88-8159-53d0c61a4c98"

Request Parameters

Parameter Data Type Description
application_sid string Secure ID of the binding to be removed

Get Binding by SID

This call will return configured binding parameters in JSON format for the secure ID specified.

METHOD URL
GET /bindings/{binding_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password]" "https://api.carrierx.com/mediator/v1/bindings/b119aa4f-7146-46e3-af9f-dad0fdea5825"

Request Parameters

Parameter Data Type Description
binding_sid string Application secure ID
include_fields string Comma separated list of fields that should be included in response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

 {
  "status": 200,
  "body": {
      "binding_sid": "b119aa4f-7146-46e3-af9f-dad0fdea5825",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "name": "N/A",
      "date_created": "2016-06-10T10:10:25.000Z",
      "origination_did": null,
      "redirect_did": "15162065032",
      "destination_did": “5055000550005”,
      "dtmf": null,
      "maximum_ttl": 3600,
      "wait_origination_did_ttl": 300,
      "attributes": {
          "hide_origination_did": "false"
          "announce": "[LINK TO FILE]"
      }
  }
}

Response Parameters

Attribute Data Type Description
binding_sid string Binding secure ID
name string Binding name
account_sid string Secure ID of the Account which binding belongs to
date_created string Date when the binding was created
origination_did string DID that originates the call in E.164 format. If empty, receive call from any origination DID
redirect_did string DID that redirects the call in E.164 format
destination_did string Call destination DID in E.164 format.
maximum_ttl integer Number of seconds during which the binding will be active, -1 means eternity
wait_origination_did_ttl integer Number of seconds during which the binding will determine origination_did, -1 means determination is disabled. Default value 300 seconds.
attributes string Additional attributes for the binding

Patch Binding

This call will patch the existing binding instance.

METHOD URL
PATCH /push/bindings/{binding_sid}

Sample URL


curl -X PATCH --header "Content-Type: application/json" -u [your_user_name]:[your_password] -d "{"attributes":{"maximum_ttl":"5000"}}" "https://api.carrierx.com/mediator/v1/bindings/172f90d3-38c4-42fe-85d7-94f2a3bef7b4"

Request Parameters

Parameter Data Type Description
application_sid req string Application secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "status": 200,
  "body": {
      "binding_sid": "172f90d3-38c4-42fe-85d7-94f2a3bef7b4",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "name": "B42016",
      "date_created": "2016-04-11T15:13:00.783Z",
      "origination_did": "455122336444",
      "redirect_did": "15162065030",
      "destination_did": "5055000550005",
      "dtmf": null,
      "maximum_ttl": 5000,
      "wait_origination_did_ttl": 300,
      "attributes": {
                  "announce": "[LINK TO FILE]"
                  "mcc": "123",
                  "mnc": "456"}
  }
}

Response Parameters

Attribute Data Type Description
binding_sid string Binding secure ID
name string Binding name
account_sid string Secure ID of the Account which binding belongs to
date_created string Date when the binding was created
origination_did string DID that originates the call in E.164 format. If empty, receive call from any origination DID
redirect_did string DID that redirects the call in E.164 format
destination_did string Call destination DID in E.164 format.
maximum_ttl integer Number of seconds during which the binding will be active, -1 means eternity
wait_origination_did_ttl integer Number of seconds during which the binding will determine origination_did, -1 means determination is disabled. Default value 300 seconds.
attributes string Additional attributes for the binding

Update Binding

This call will update the binding instance. This call can be used to remove values.

METHOD URL
PUT /bindings/{binding_sid}

Sample URL


curl -X PUT --header "Content-Type: application/json" -u [your_user_name]:[your_password] -d "{"binding_sid": "172f90d3-38c4-42fe-85d7-94f2a3bef7b4", "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15", "name": "B42016", "origination_did": "", "redirect_did": "15162065030", "destination_did": "5055000550005",  "maximum_ttl": 3600, "wait_origination_did_ttl": 300, "attributes": {} } " "https://api.carrierx.com/mediator/v1/bindings/f4bb0ed5-ad2d-4db6-8ffa-0788357e5b79"

Request Parameters

Parameter Data Type Description
binding_sid integer Binding secure ID
body object Body of the binding object to be updated


Sample Response

 {
  "status": 200,
  "body": {
      "binding_sid": "f4bb0ed5-ad2d-4db6-8ffa-0788357e5b79",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "name": "B42016",
      "date_created": "2016-04-08T10:40:17.000Z",
      "origination_did": null,
      "redirect_did": "15162065030",
      "destination_did": "5055000550005",
      "dtmf": null,
      "maximum_ttl": 3600,
      "wait_origination_did_ttl": 300,
      "attributes": {
                  "announce": "[LINK TO FILE]"
                  "mcc": "123",
                  "mnc": "456"}
  }
}

Response Parameters

Attribute Data Type Description
binding_sid string Binding secure ID
name string Binding name
account_sid string Secure ID of the Account which binding belongs to
date_created string Date when the binding was created
origination_did string DID that originates the call in E.164 format. If empty, receive call from any origination DID
redirect_did string DID that redirects the call in E.164 format
destination_did string Call destination DID in E.164 format.
maximum_ttl integer Number of seconds during which the binding will be active, -1 means eternity
wait_origination_did_ttl integer Number of seconds during which the binding will determine origination_did, -1 means determination is disabled. Default value 300 seconds.
attributes string Additional attributes for the binding




Countries

The countries resource instance allows to retrieve extensive information for each country, like the country code in universally accepted formats, mobile country code, dialing prefix, etc. It helps to define which country the specified IP address belongs to.

Get Countries Matching the Specified Criteria

Shows the list of countries. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true,

METHOD URL
GET /countries

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/mediator/v1/countries?filter=capital%20ne%20Kabul%20and%20dialing_prefix%20gt%201&order=common_name%20asc"

Request Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
common_name eq Italy
name like Italy and country_code ne USA
order string Specifies order of items in the response: asc, desc

Example:
common_name desc
country_code asc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
"common_name": "Andorra",
"official_name": "Principality of Andorra",
"iso_3166_alpha_2": "AD",
"iso_3166_alpha_3": "AND",
"iso_3166_numeric": 20,
"domain": "ad",
"dialing_prefix": "376",
"region": "Europe",
"subregion": "Southern Europe",
"capital": "Andorra la Vella",
"mcc": "213"
}

Response Parameters

Attribute Data Type Description
common_name string Common name of the country
official_name string Official name of the country
iso_3166_alpha_2 string ISO 3166-1 alpha-2 code of this country
iso_3166_alpha_3 string ISO 3166-1 alpha-3 code of this country
iso_3166_numeric string ISO 3166-1 numeric code of this country
domain string The Internet domain of this country
dialing_prefix string Telephone code of this country
region string Region of this сountry
subregion string Sub region of this сountry
capital string The capital of this сountry
mcc integer Mobile country code

Get Country by ISO 3166-1 alpha-3 code

Shows the country which ISO 3166-1 alpha-3 code is specified.

METHOD URL
GET /countries/{country_code}

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/mediator/v1/countries/ITA?exclude_fields=common_name"

Request Parameters

Parameter Data Type Description
country_code req string ISO 3166-1 alpha-3 code of this Country
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response.

Sample Response

 {
"official_name": "Italian Republic",
"iso_3166_alpha_2": "IT",
"iso_3166_alpha_3": "ITA",
"iso_3166_numeric": 380,
"domain": "it",
"dialing_prefix": "39",
"region": "Europe",
"subregion": "Southern Europe",
"capital": "Rome",
"mcc": "222"
}

Response Parameters

Attribute Data Type Description
common_name string Common name of the country
official_name string Official name of the country
iso_3166_alpha_2 string ISO 3166-1 alpha-2 code of this country
iso_3166_alpha_3 string ISO 3166-1 alpha-3 code of this country
iso_3166_numeric string ISO 3166-1 numeric code of this country
domain string The Internet domain of this country
dialing_prefix string Telephone code of this country
region string Region of this country
subregion string Sub region of this country
capital string The capital of this country
mcc integer Mobile country code




CallBacks

The CarrierX API enables CallBacks to be sent to your hosted endpoint.

Assigning a CallBack URL through the partners API will allow you to receive Global feedback on all SMS activity associated to the Partner account. For example, if your partner account has three SMS enabled DIDs assigned to it, then the callback URL will receive JSON responses from all three DIDs. Conversely, if you set a CallBack using the /dids API, you will only receive a JSON response related to that specific DID. Please note that once you have set a CallBack value at the level of the DID, you will override whatever CallBack you have set at the level of the partner for that DID.


Sample JSON Response

 {
  "price": "1",
  "message_segments": 1,
  "mnc": null,
  "mcc": null,
  "status": "received",
  "message_sid": "e405fa47-48f5-4dc5-bbba-77231587188e",
  "partner_sid": "QLJ79xlC2vP-UEx3hS0R4rldas8.G1UB",
  "message": “This is a test inbound message delivered by CarrierX",
  "direction": "inbound",
  "date_created": "2016-04-21T17:42:55.000Z",
  "date_status_changed": "2016-04-21T17:42:55.000Z",
  "from_did": “18448441322",
  "to_did": “15624371411"
}
Attribute Data Type Description
price string The associated price
message_segments integer Number of segments in the message
mnc string Mobile network code
status string Status of the message
  • created
  • queued
  • sending
  • sent
  • receiving





System Codes

This section lists the HTTP status codes the API returns to each request.


Success Response

Response Code Text 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 Text Description
401 Unauthorized The request requires 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.
400 Bad request The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
404 Not Found The requested resource was not found on the server.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.