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.
Refer to the Mediator products page for quick start guides and video tutorials. These hold walk-through instructions on configuring Mediator endpoints, creating bindings, performing dialouts, and looking up DIDs.
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, filtering, and callbacks.
Using Postman
This documentation contains cURL commands that you will run in your terminal. Rather than use these commands, you can explore the API using Postman, a stand-alone client with a user-friendly interface. Postman is widely used for API development and allows you to test requests.
You will need to download the Postman client to your computer. To do so, visit the Postman website and click Download. Click Run in Postman to import this collection to the Postman app.
For more information, see our Getting Started with Postman Quick Start Guide.
Main Conventions
The following conventions are used in the sections, which contain the tables with objects attributes, their types, and descriptions:
create | The attribute can be set when the user creates the object using the POST method. |
update | The attribute can be modified when the user updates the object using either PATCH or PUT methods. |
read only | The attribute is set by the system and the user can neither set nor modify it. |
Credentials
The following curl command will return a list of all of the endpoints of the CarrierX account associated with the login credentials. Use your Core API token in the query below. The endpoint
login
andpassword
values are listed in the returned JSON object.
curl -X GET \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
The credentials of a specific endpoint are found in the properties attribute of the nested object. Locate the
login
andpassword
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": "844346ef-93e9-4fa8-a4ab-e3015af94573",
"name": "flex",
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {
"account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
"api_url": "https://api.carrierx.com/flexml/v1",
"container_sid": "null",
"login": "sample_login",
"password": "sample_password"
},
"transformations": [],
"type": "flexml",
"voip_token": null
}
],
"limit": 1000,
"offset": 0,
"pagination": {},
"total": 2
}
API requests require authentication. To obtain a CarrierX account and gain credentials, please submit a request through our Contact Us page. The Core API uses a bearer token, and the endpoint APIs (Conference, FlexML, and Mediator) use a login and password.
Prior to making requests, a Mediator Application Endpoint needs to be created. See the Mediator Endpoint quick start guide for step-by-step instructions on creating a Mediator endpoint.
Each of the application endpoints has different login
and password
values. Entering the Core API token credentials instead of the endpoint-specific credentials when working with the Conference, FlexML, or Mediator APIs will return the unauthorized
error.
Requests
Sample request to create Conference endpoint.
curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_conf", "type":"conference"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
The requests in CarrierX API are made using the standard REST notation, typical for web services. This includes the URL, to which the request will be sent, the request method, the request related headers, and, optionally, a payload.
Request URL
The usual path to the API objects include the base URL to the API used with the object (Core API base URL for the objects used throughout the CarrierX products, or specific API base URLs used for FlexML, Mediator, or Conference), and the path to the object collections and the object items.
If the action targets the specific object, the path to it will include the object secure ID (SID), which allows to distinguish the targeted object from the other ones in the same collection.
The system only accepts HTTPS requests, and not HTTP requests.
Request Methods
CarrierX API uses five main verbs (methods) of REST over HTTP for the requests: POST
, GET
, PUT
, PATCH
, and DELETE
. These methods are used to create the objects, get the information about the objects, modify the objects, and delete them.
CarrierX partners need to have special permissions (or scopes) to use API methods on various objects. Refer to the available_scopes table for the complete list of the scopes that define the partner’s permissions on objects and collections.
POST
The POST
method is used to create new objects. When you create a new object, you usually need to specify at least some of the attributes for the object to be created in the request payload.
The successful POST
request will return a 200
response with the serialized JSON copy of the created object.
GET
The GET
method is used to view the information about the existing objects and their collections.
Generic GET
requests return the list of all the objects (or collections) available for the request sent. Most of such GET
requests can be used together with Pagination, Result Filtering, and Field Filtering.
GET
requests aimed at a specific object require to use the object secure ID to be included as a part of the request path, and return the information about the specified object only. Most of such GET
requests can be used together with Field Filtering.
The successful GET
request will return a 200
response with the serialized JSON copy of the requested objects (or specific object).
PATCH/PUT
The PATCH
/PUT
methods are both used to modify the existing objects and their attributes. The difference between them is explained below.
Sample
PATCH
request to modify or add a newname
record of the nestedattributes
object.
curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name":"New Partner Name"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
The successful request returns the serialized JSON copy of the created object together with the nested object.
{
"attributes": {
"name": "New Partner Name"
},
...,
"partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}
Sample
PATCH
request to add a newname2
record of the nestedattributes
object of the same Partner object.
curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name2":"New Partner Name 2"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
The successful request returns the serialized JSON copy of the created object together with the modified nested object.
{
"attributes": {
"name": "New Partner Name"
"name2": "New Partner Name 2"
},
...,
"partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}
Sample
PATCH
request to modify the entire nestedattributes
object of the same Partner object.
curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b?nested_objects=replace' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name3":"New Partner Name 3"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
The successful request returns the serialized JSON copy of the created object together with the nested object.
{
"attributes": {
"name3": "New Partner Name 3"
},
...,
"partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}
PATCH
is used to modify only some of the object attributes and does not require to send the entire object in the request payload. Only the attributes and their values that need to be modified can be sent in the request body.
Objects can have a complex structure and can contain other objects as part of them, i.e., nested inside them. When you use PATCH
and want to modify the nested objects, PATCH
follows the below rules to define what must be updated and how:
-
If the existing nested object contains the same record (by key), the existing record will be replaced with the new value, provided in the
PATCH
request. The other nested object records will remain unmodified. -
If the existing nested object does not contain the same record, a new record will be added to the object. The other nested object records will remain unmodified.
-
If the existing nested object contains the same record and the value of the incoming record is
null
, then the existing record will be removed. The other nested object records will remain unmodified. -
If the
PATCH
request containsnested_objects=replace
as a query attribute, the whole nested object will be replaced with a new one (i.e., all the old records and their values will be removed and only the new ones will be added).
PUT
is used to modify the complete object and require to send the entire object (together with the nested objects, if there are any) in the request payload.
Both PATCH
and PUT
requests are aimed at a specific object and require the object secure ID as a part of the request path.
The successful PATCH
/PUT
request will return a 200
response with the serialized JSON copy of the modified object.
DELETE
The DELETE
method is used to delete the object targeted by its secure ID.
The successful DELETE
request will return a 204
response code with an empty body.
Additional Request Parameters
All CarrierX API requests require authentication. Refer to the section above for more information about obtaining login credentials. 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.
Responses
All responses are returned in the JSON format with a status code. For common errors returned, refer to the HTTP Errors section.
Pagination
This request returns Call objects starting with the second record available, and returns a maximum of 4 records.
curl -X GET \
'https://api.carrierx.com/conference/v1/calls?offset=2&limit=4' \
-u '[your_user_name]:[your_password]'
To view records not included in the response, make a request to the URL value of the previous key.
{
"count": 0,
"has_more": false,
"items": [],
"limit": 4,
"offset": 2,
"pagination": {
"previous": "https://api.carrierx.com/conference/v1/calls?limit=4&offset=0"
},
"total": 0
}
The three optional parameters for pagination are: offset
, limit
, and order
. GET
requests use these three parameters to dictate 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
. Two values are accepted for this parameter: asc
and desc
. asc
is short for ascending and is the default order. Enter the field name to be ordered followed by either asc
or desc
. For example, name desc
will return names sorted in reverse-alphabetical order. Since the default is asc
, entering just name 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 this field.
Pagination Quick Reference
Parameter | Data Type | Description |
---|---|---|
limit | 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 | 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 | string | The name of the field to be ordered followed by the order of the response data, either asc or desc . The field to be ordered is listed first, followed by the order value. For example: binding_sid desc . asc is the default order. This parameter and values are added to the query URL. |
Result Filtering
This
GET
request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing results to theconference
endpoint type.
curl -X GET \
"https://api.carrierx.com/core/v2/endpoints?filter=type+eq+'conference'" \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
The following response includes all of the endpoints that fit the filter criteria.
{
"count": 1,
"has_more": false,
"items": [
{
"addresses": [],
"attributes": {},
"capacity": 0,
"endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
"name": "my_example_conference",
"partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
"properties": {
"account_sid": "bdrU77AFb-Y1sDwqqxkeb.M3LP7hSKYg",
"api_url": "https://api.carrierx.com/conference/v1",
"container_sid": "null",
"login": "username",
"password": "password"
},
"transformations": [],
"type": "conference",
"voip_token": null
}
],
"limit": 1000,
"offset": 0,
"pagination": {},
"total": 1
}
The filter
parameter is used to restrict or customize the JSON response. Operators can be combined for more specific searches, and are added to the query URL.
Result Filtering Quick Reference
Operator | Definition | Example |
---|---|---|
eq | equal to. This search looks for the exact value entered. In the example, results will have the exact "my_mediator" value for the name field. |
name eq "my_mediator" |
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 |
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 |
ilike | same functionality as like but case insensitive. |
name ilike "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") |
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%" |
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 |
ne | not equal to. This search returns records that do not include the "my_mediator" value for the name field. |
name ne "my_mediator" |
notin | not in. The current value of the specified field must not be in the specified list. The following example will return records that do not have a status value of "active" . |
status notin ("active") |
Field Filtering
In the following, we request Endpoint objects without the
properties
field.
curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings?exclude_fields=properties' \
-u '[your_user_name]:[your_password]'
The following response excludes the
properties
field from returned Endpoint objects.
{
"count": 1,
"has_more": false,
"items": [
{
"addresses": [],
"attributes": {},
"capacity": 0,
"endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
"name": "my_example_conference",
"partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
"transformations": [],
"type": "conference",
"voip_token": null
}
],
"limit": 1000,
"offset": 0,
"pagination": {},
"total": 1
}
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 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.
Field Filtering Quick Reference
Parameter | Data Type | Description |
---|---|---|
exclude_fields | string | The comma separated list of fields to be excluded from the response. The fields depend on the object. See the Object section for that object to see which fields return. |
include_fields | string | The comma separated list of fields to be included in the response. The fields depend on the object. See the Object section for that object to see which fields return. |
HTTP Errors
The Mediator API uses the following HTTP error codes:
Error Code | Message | Description |
---|---|---|
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. |
400 | No JSON object could be decoded | Generally an indicator that there is a syntax error. |
401 | Bad credentials | The request requires correct user authentication. |
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. |
404 | Cannot find item by SID | The SID number does not exist. Verify that the SID has been entered correctly. Note that calls can expire. |
404 | Not Found | The requested resource was not found on the server. |
409 | Cannot find redirect_did |
The redirect_did could not be found. Verify that there are available DIDs that can be assigned as redirect_did automatically or assign it manually using the Mediator API Create Binding method. |
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. |
API Reference
The Mediator API has the following sections: Bindings, Dialouts, and DIDs.
- Use the Accounts object to retrieve information about the available Mediator endpoint accounts.
- Use the Binding object to create call forwarding to specific phone numbers.
- Create and modify Dialout objects, which make calls to phone numbers.
- The DID object holds modifiable data about phone numbers rented through CarrierX.
Accounts
The Account object holds the data associated with the Mediator API. It is used to view information about the partner that is related to the Mediator endpoint.
Account Object
This section describes the elements of the Account object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Account object
{
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"date_created": "2018-10-09T22:47:56.609Z",
"login": "mediator_login",
"name": "CarrierX",
}
Attribute | Data Type | Description |
---|---|---|
account_sid read only | string | The account secure ID. |
date_created read only | string | The date and time when the account was created. |
login read only | string | The login that is used as a part of the Mediator API credentials. |
name read only | string | The account name. |
password read only | string | The password that is used as a part of the Mediator API credentials. The field is hidden and not returned in the response. |
Get Accounts
The following
GET
request returns accounts matching the criteria in the request URL.
curl -X GET \
'https://api.carrierx.com/mediator/v1/accounts' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a list of Account objects.
{
"body": {
"count": 1,
"has_more": false,
"items": [
{
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"date_created": "2018-10-09T22:47:56.609Z",
"login": "mediator_login",
"name": "CarrierX"
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": 1
},
"status": 200
}
This request returns a list of accounts.
GET | /accounts |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Get Account by SID
The following
GET
request returns an account, targeted by secure ID.
curl -X GET \
'https://api.carrierx.com/mediator/v1/accounts/13e156f7-0d21-4ba6-9e32-c56dc2c6098f' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a serialized copy of the Account object.
{
"body": {
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"date_created": "2018-10-09T22:47:56.609Z",
"login": "mediator_login",
"name": "CarrierX"
},
"status": 200
}
This request returns data for an account, targeted by secure ID.
GET | /accounts/{account_sid} |
This request is enabled for Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
account_sid required |
string | The account secure ID. |
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 be created by setting
wait_origination_did_ttl
to-1
and not setting a value fororigination_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
origination_did
as 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 fororigination_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
This section describes the elements of the Binding object. These fields and values make up the JSON object that gets returned with successful requests.
In this section, there is also information about the optional fields that can be added to further customize bindings.
Sample Binding object:
{
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"attributes": {
"ringback":"moh"
},
"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",
"redirect_did_info": {
"country_code": "USA",
"e164_format": "+15162065346",
"in_country_format": "(516) 206-5346",
"international_format": "+1 516-206-5346",
"phonenumber": "15162065346"
},
"wait_origination_did_ttl": -1
}
Attribute | Data Type | Description |
---|---|---|
account_sid read only | string | The account secure ID. |
attributes create update | object | The optional fields and values added to a binding. Refer to the table below for information on the built-in attributes. |
binding_sid read only | string | The binding secure ID. This ID can be used to reference and target a specific Binding object. |
date_created read only | string | The date that the binding was created. |
destination_did create update | 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 create update | 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 0.5 seconds. |
maximum_ttl create update | integer | The number of seconds that the binding will remain active. 3600 is the default value. The -1 value creates an indefinite binding. |
name create update | 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 create update | 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 create update | string | The DID in this field will be used to forward the call to the destination_did . DIDs are rented through CarrierX. |
redirect_did_info read only | object | Additional information about the redirect DID. Refer to the table below fore more information. |
wait_origination_did_ttl create update | 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. The default value is 300 . |
Attribute Object
Below are the additional fields that can be added to further customize bindings. All of these attributes are optional. Custom fields and values can also be added in the same fashion as the other binding attributes are. Add these attributes
as a nested object.
Attribute | Data Type | Description |
---|---|---|
announce create update | string | The audio file that plays to the caller before they are connected to the second party. File types accepted are .wav and .mp3 . |
cnam create update | string | The CNAM for outbound calls. Note that this may not be preserved for calls terminated through the PSTN. |
fix_anonymous_cid create update | 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 true value means that blocked phone numbers will be displayed as the redirect_did phone number. |
hide_origination_did create update | 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. The true value means that the redirect_did will be displayed instead of the origination_did as the caller. The default value is false . To be able to change the value of this field from false to true , please email support@carrierx.com. |
ringback create update | string | This field is used to customize what the caller hears while waiting for the destination_did to answer. The false value will disable ringing for the caller, so the caller will hear silence until the destination_did answers. By passing the moh value, 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_* create update | 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- . |
Redirect DID Info Response Object
Attribute | Data Type | Description |
---|---|---|
country_code read only | string | The ISO 3166-1 alpha-3 code of the redirect DID, given automatically. |
e164_format read only | string | The redirect DID number in E.164 format. |
in_country_format read only | string | The redirect DID number in national format. |
international_format read only | string | The redirect DID number in international format. |
phonenumber read only | string | The redirect DID phone number in E.164 format without the + prefix.. |
Create Binding
The following
POST
request creates a binding.
curl -X POST \
'https://api.carrierx.com/mediator/v1/bindings' \
-H 'Content-Type: application/json' \
--data-binary '{"destination_did":"15162065338", "attributes": {"ringback":"moh"}}' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a serialized copy of the Binding object.
{
"body": {
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"attributes": {
"ringback":"moh"
},
"binding_sid": "05561bef-ce48-4823-a847-bf10f7837a42",
"date_created": "2018-10-09T22:47:56.609Z",
"destination_did": "15162065338",
"dtmf": null,
"maximum_ttl": -1,
"name": "N/A",
"origination_did": null,
"redirect_did": "15162065346",
"redirect_did_info": {
"country_code": "USA",
"e164_format": "+15162065346",
"in_country_format": "(516) 206-5346",
"international_format": "+1 516-206-5346",
"phonenumber": "15162065346"
},
"wait_origination_did_ttl": 300
},
"status": 200
}
This request creates a Binding object.
POST | /bindings |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
fallback_country | string | The fallback country to pick a redirect phone number. If several numbers from various regions are assigned to the Mediator endpoint, the redirect number will be selected from the country specified in this field. If no phone number from the specified country is assigned to the Mediator endpoint, the 409 error will be returned. |
reuse | boolean | Whether an existing binding with the same parameters should be used instead of creating a new one. |
Body Arguments
JSON representation of the fields and values of the Binding object to be created.
A required field to establish a binding is destination_did
.
Refer to this table to view all fields that appear in the Binding object.
Binding Variants
When creating a binding without a redirect_did
specified, an available DID on the account will be assigned as the redirect_did
. If no DID can be assigned for the redirect_did
, the 409 error will be returned.
The request will also fail if there is no available DID for the given origination_did
.
Each binding has a maximum_ttl
and wait_origination_did_ttl
attribute. 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 and be deleted. 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
.
Get Bindings
The following
GET
request returns bindings matching the criteria in the request URL.
curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings?filter=name+eq+"N/A"' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a list of Binding objects.
{
"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",
"redirect_did_info": {
"country_code": "USA",
"e164_format": "+15162065339",
"in_country_format": "(516) 206-5339",
"international_format": "+1 516-206-5339",
"phonenumber": "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",
"redirect_did_info": {
"country_code": "USA",
"e164_format": "+15162065337",
"in_country_format": "(516) 206-5337",
"international_format": "+1 516-206-5337",
"phonenumber": "15162065337"
},
"wait_origination_did_ttl": -1
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": 2
},
"status": 200
}
This request returns a list of Binding objects matching the specified criteria.
GET | /bindings |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Get Binding by SID
The following
GET
request returns a binding, targeted by secure ID.
curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings/bedd33b1-2961-458e-b35a-bf80260cdba4' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a serialized copy of the Binding object.
{
"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",
"redirect_did_info": {
"country_code": "USA",
"e164_format": "+15162065337",
"in_country_format": "(516) 206-5337",
"international_format": "+1 516-206-5337",
"phonenumber": "15162065337"
},
"wait_origination_did_ttl": -1
},
"status": 200
}
This request will return a binding, targeted by secure ID.
GET | /bindings/{binding_sid} |
This request is enabled for Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
binding_sid required |
string | The binding secure ID. |
Update Binding
The following
PATCH
request updates the Binding object, targeted by secure ID, with the values in the request body.
curl -X PATCH \
'https://api.carrierx.com/mediator/v1/bindings/bedd33b1-2961-458e-b35a-bf80260cdba4' \
-H 'Content-Type: application/json' \
--data-binary '{"maximum_ttl":-1}' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a serialized copy of the updated Binding object.
{
"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",
"redirect_did_info": {
"country_code": "USA",
"e164_format": "+15162065337",
"in_country_format": "(516) 206-5337",
"international_format": "+1 516-206-5337",
"phonenumber": "15162065337"
},
"wait_origination_did_ttl": -1
},
"status": 200
}
This request updates a binding, targeted by secure ID.
PATCH | /bindings/{binding_sid} |
PUT | /bindings/{binding_sid} |
A Binding object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The binding secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire Binding object. The binding secure ID is passed in the query URL, and the entire Binding object is passed in the request body.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
binding_sid required |
string | The binding secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
attributes
destination_did
dtmf
maximum_ttl
name
origination_did
redirect_did
wait_origination_did_ttl
Refer to this table to view all fields that appear in the Binding object.
Delete Binding
The following
DELETE
request deletes a binding, targeted by secure ID.
curl -X DELETE \
'https://api.carrierx.com/mediator/v1/bindings/217b55b3-b872-4406-b6b9-716a4a762e40' \
-u '[your_user_name]:[your_password]'
A successful request will return a
204
response code with an empty body.
This request deletes a binding, targeted by secure ID.
DELETE | /bindings/{binding_sid} |
Path Arguments
Parameter | Data Type | Description |
---|---|---|
binding_sid required |
string | The binding secure ID. |
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
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.
Sample Dialout object:
{
"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"
}
Attribute | Data Type | Description |
---|---|---|
account_sid read only | string | The secure ID of the account to which the dialout belongs. |
attributes create update | object | The optional fields and values added to a dialout. Refer to the table below for information on the built-in attributes. Note that custom fields can be added in the same manner as the built-in attributes. |
date_created read only | string | The date and time when the dialout was created. |
delay create update | integer | The delay before both parties are contacted, in seconds. 0 is the default value. |
dialout_sid read only | string | The dialout secure ID. |
redirect_did create update | string | The DID that dials out the stage_one_destination_did and stage_two_destination_did . |
stage_one_destination_did create update | string | The first DID to dial out to. |
stage_two_destination_did create update | string | The second DID to dial out to. |
Attribute Object
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 |
---|---|---|
announce create update | string | 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 create update | string | The CNAM for outbound calls. Note that this may not be preserved for calls terminated through the PSTN. |
fix_anonymous_cid create update | 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 true value means that blocked phone numbers will be displayed as the redirect_did phone number. |
hide_origination_did create update | 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. The true value means that the redirect_did will be displayed instead of the stage_one_destination_did or stage_two_destination_did as the caller. The default value is true . To be able to change the value of this field from true to false , please email support@carrierx.com. |
ringback create update | string | This field is used to customize what stage_one_destination_did will hear while stage_two_destination_did is being dialed. The false value 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 moh value, 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 . |
sip_header_* create update | 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- . |
use_call_confirmation create update | string | When 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
The following
POST
request creates a dialout.
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]'
A successful request will return a
200
response code with a serialized copy of the Dialout object.
{
"body": {
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"attributes": {
"hide_origination_did": "true",
"ringback": "false"
},
"date_created": "2018-10-09T20:40:57.675Z",
"delay": 0,
"dialout_sid": "15e93c0c-a0eb-4c5d-9b92-f8fd60b2def6",
"redirect_did": "15162065340",
"stage_one_destination_did": "15162065339",
"stage_two_destination_did": "15162065338"
},
"status": 200
}
This request creates a dialout.
POST | /dialouts |
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 for a list of the built-in attributes available. Custom attributes can also be included in the same way as the built-in attributes.
Body Arguments
JSON representation of the fields and values of the Dialout object to be created.
Required fields to create a dialout are:
stage_one_destination_did
stage_two_destination_did
Refer to this table to view all fields that appear in the Dialout object.
Get Dialouts
The following
GET
request returns dialouts scheduled for a future time.
curl -X GET \
'https://api.carrierx.com/mediator/v1/dialouts' \
-u '[your_username]:[your_password]'
A successful request will return a
200
response code with a list of Dialout objects.
{
"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
}
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
.
GET | /dialouts |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Get Dialout by SID
The following
GET
request returns dialouts, targeted by secure ID.
curl -X GET \
'https://api.carrierx.com/mediator/v1/dialouts/8b2423ab-5a8b-438d-8c15-b9eee5879a5d' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a serialized copy of the Dialout object.
{
"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
}
This request returns a dialout, targeted by secure ID.
GET | dialouts/{dialout_sid} |
This request is enabled for Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
dialout_sid required |
string | The dialout secure ID. |
Update Dialout
The following
PATCH
request updates the Dialout object, targeted by secure ID, with the values in the request body.
curl -X PATCH \
'https://api.carrierx.com/mediator/v1/dialouts/8b2423ab-5a8b-438d-8c15-b9eee5879a5d' \
-H 'Content-Type: application/json' \
--data-binary '{"delay": "1800"}' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a serialized copy of the updated Dialout object.
{
"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
}
This request updates a dialout, targeted by secure ID.
PATCH | /dialouts/{dialout_sid} |
PUT | /dialouts/{dialout_sid} |
A Dialout object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The dialout secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire Dialout object. The dialout secure ID is passed in the query URL, and the entire Dialout object is passed in the request body.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
dialout_sid required |
string | The dialout secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
attributes
delay
redirect_did
stage_one_destination_did
stage_two_destination_did
Refer to this table to view all fields that appear in the Dialout object.
Delete Dialout
The following
DELETE
request deletes a dialout, targeted by secure ID.
curl -X DELETE \
'https://api.carrierx.com/mediator/v1/dialouts/8b2423ab-5a8b-438d-8c15-b9eee5879a5d' \
-u '[your_user_name]:[your_password]'
A successful request will return a
204
response code with an empty body.
This request deletes a dialout, targeted by secure ID.
DELETE | /dialouts/{dialout_sid} |
Path Arguments
Parameter | Data Type | Description |
---|---|---|
dialout_sid required |
string | The dialout secure ID. |
DIDs
DIDs are phone numbers rented through CarrierX. They serve as redirect_did
values.
DID Object
This section describes the elements of the DID object. These fields and values make up the JSON object that gets returned with successful requests.
Sample DID object:
{
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"country_code": "USA",
"did_sid": "5dbed1ba-b7e7-4337-9d9c-36ef03ac2805",
"in_country_format": "(516) 206-5337",
"international_format": "+1 516-206-5337",
"phonenumber": "15162065337"
}
Attribute | Data Type | Description |
---|---|---|
account_sid read only | string | The secure ID of the account to which the DID belongs. |
country_code read only | string | The ISO 3166-1 alpha-3 code of the DID. |
did_sid read only | string | The secure ID of the DID. |
in_country_format read only | string | The DID in national format. |
international_format read only | string | The DID in international format. |
phonenumber read only | string | The phone number for the DID in E.164 format without the + prefix. |
Get DIDs
The following
GET
request returns DIDs.
curl -X GET \
'https://api.carrierx.com/mediator/v1/dids' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a list of DID objects.
{
"body": {
"count": 1,
"has_more": false,
"items": [
{
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"country_code": "USA",
"did_sid": "5dbed1ba-b7e7-4337-9d9c-36ef03ac2805",
"in_country_format": "(516) 206-5337",
"international_format": "+1 516-206-5337",
"phonenumber": "15162065337"
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": 1
},
"status": 200
}
This request returns a list of DIDs.
GET | /dids |
CarrierX will automatically populate this collection with DIDs routed to the specific endpoint.
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Get DID by SID
The following
GET
request returns a DID, targeted by secure ID.
curl -X GET \
'https://api.carrierx.com/mediator/v1/dids/5dbed1ba-b7e7-4337-9d9c-36ef03ac2805' \
-u '[your_user_name]:[your_password]'
A successful request will return a
200
response code with a serialized copy of the DID object.
{
"body": {
"account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
"country_code": "USA",
"did_sid": "5dbed1ba-b7e7-4337-9d9c-36ef03ac2805",
"in_country_format": "(516) 206-5337",
"international_format": "+1 516-206-5337",
"phonenumber": "15162065337"
},
"status": 200
}
This request returns data for a DID, targeted by secure ID.
GET | /dids/{did_sid} |
This request is enabled for Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required |
string | The DID secure ID. |