Mediator API Reference

The hosted Mediator Application Endpoint acts as an intermediary between phone numbers. The service has two primary abilities, bindings and dialouts.

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.

Run in Postman

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.

Authentication

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 and password 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 and password values.

{
  "count": 1,
  "has_more": false,
  "items": [
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flexml",
          "out_sip_password": null,
          "out_sip_username": null,
          "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": 1
}

All CarrierX API requests require authentication. The first step to using CarrierX API is obtaining a CarrierX account and gaining credentials. To do so, please submit a request through our Contact Us page.

Currently, CarrierX API requests use two types of authentication:

Prior to making requests, you need to create a Mediator application endpoint. Refer to the Mediator Endpoint quick start guide for step-by-step instructions on creating a Mediator endpoint.

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.

A simplest request will have the following structure:

All the above elements are required for all CarrierX API requests.

Other request may have additional structure elements which include:

Request URL

The usual path to the API objects includes 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

Sample POST request that creates a trunk

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

Sample GET request that returns the currently logged-in partner

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/whoami' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

Sample PATCH request that modifies or adds a new name record of the nested attributes 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'

Response 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 that adds a new name2 record of the nested attributes 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'

Response 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 that modifies the entire nested attributes 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'

Response 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"
}

The PATCH/PUT methods are both used to modify the existing objects and their attributes. The difference between them is explained below.

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:

  1. 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.

  2. 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.

  3. 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.

  4. If the PATCH request contains nested_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

Sample DELETE request that deletes an endpoint

curl -X DELETE \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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.

Rate Limiting

Currently, CarrierX applies no rate limiting to the partners requests to CarrierX API.

Responses

All responses return conventional HTTP status codes. Most of the responses (GET, POST, PATCH/PUT) also return objects in the JSON format.

CarrierX API allows cross-origin (CORS) requests and data transfers.

HTTP Status Codes

Typical 200 status code in the response

HTTP/2 200
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Credentials,Content-Disposition,Access-Control-Allow-Headers
Content-Length: 1333
Content-Type: application/json
Date: Wed, 22 Sep 2021 08:23:06 GMT
Server: nginx
Strict-Transport-Security: max-age=31536000; includeSubDomains
Vary: accept-encoding

The Mediator API uses the following HTTP status codes:

Sample 400 status code when the JSON sent in the request body has errors in its syntax:

{
    "body": {
        "message": "cannot parse json. Check json for validity",
        "errors": null
    },
    "status": 400
}

Sample 401 status code when trying to send a request without authentication:

{
  "message": "authentication required",
  "errors": [
    {
      "field": "cause",
      "message": "authentication required",
      "reference_sid": null
    }
  ]
}

Sample 403 status code when trying to access resources you do not have enough permission for:

{
    "message": "permission denied",
    "errors": [
        {
            "field": "cause",
            "message": "permission denied",
            "reference_sid": null
        }
    ]
}

Sample 404 status code when trying to access a non-existent object (e.g., a token with an incorrect SID):

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find token",
            "reference_sid": null
        }
    ]
}
Error Code Message Description
2xx Success  
200 OK The request has succeeded. The result will be a returned JSON object or a link to download a file.
201 Created The request has succeeded and led to the creation of a resource. This response is normally returned to the requests that upload files.
204 No Content The server has successfully fulfilled the request. There is no additional content to send in the response payload body. This response code is normally returned to the DELETE requests.
4xx Client Errors  
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 Depends on the conflict source. This status code (aka Conflict) means that your request could not be processed because of some conflict that has occurred during such a request. For specific details see the error section of the API method that you are calling. As a rule, you can try to resolve the conflict by resubmitting your request later.
415 Unsupported media type Ensure that the header includes support for the JSON content type.
5xx Server Errors  
500 Internal server error The server encountered an unexpected condition which prevented it from fulfilling the request.

The above status codes are common for all requests.

There are some error codes specific for certain requests only. They are described in the topics dedicated to these requests (e.g., error 422: Container Object Specific Errors).

Response Objects

Typical formatted JSON object in the response

{
    "callback_url": null,
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

Successful requests return objects in the JSON format with application/json set as Content-Type. The object keys and values depend on the request and the object returned, and are described in the corresponding object sections.

Normally, the system returns the object fields unordered and unformatted. To view the object fields ordered alphabetically and “pretty-formatted” in the response to the command-line requests (e.g., cURL), use the jq command-line JSON processor or similar tools.

With jq, the request will look like this:

curl -X GET 'https://api.carrierx.com/core/v2/oauth/whoami' -H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda' | jq -S

Pagination

This request returns Country objects sorting them descending by the common_name attritute, starting with the second record available, and returns a maximum of two records.

curl -X GET \
'https://api.carrierx.com/core/v2/countries?offset=2&limit=2&order=common_name+desc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous or the next key.

{
  "count": 2,
  "has_more": true,
  "items": [
    {
      "capital": "Sana'a",
      "common_name": "Yemen",
      "dialing_prefix": "967",
      "domain": "ye",
      "iso_3166_alpha_2": "YE",
      "iso_3166_alpha_3": "YEM",
      "iso_3166_numeric": 887,
      "mcc": "421",
      "official_name": "Republic of Yemen",
      "region": "Asia",
      "subregion": "Western Asia"
    },
    {
      "capital": "El Aaiún",
      "common_name": "Western Sahara",
      "dialing_prefix": null,
      "domain": "eh",
      "iso_3166_alpha_2": "EH",
      "iso_3166_alpha_3": "ESH",
      "iso_3166_numeric": 732,
      "mcc": null,
      "official_name": "Sahrawi Arab Democratic Republic",
      "region": "Africa",
      "subregion": "Northern Africa"
    }
  ],
  "limit": 2,
  "offset": 2,
  "pagination": {
    "next": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=4",
    "previous": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=0"
  },
  "total": 251
}

You can use the pagination to limit the number of the objects returned in the response and sort them by the object attributes.

The pagination is available for the GET requests which return the lists of the objects without targeting them by secure IDs.

The pagination parameters include:

limit

An integer parameter that determines how many items are returned in the response. The entered value cannot exceed 1000.

The default value is 10, meaning that a maximum of ten items will be returned.

order

A string parameter that allows to sort the returned objects. Three values are accepted for this parameter:

offset

An integer parameter that determines the amount of items that are skipped in the response.

The default value is 0, meaning that the first existing item will appear first.

after/ before

This request returns a maximum of one record of SMS Detail Record objects following the object with the b6d574ea-b11f-41fd-a25f-602e7b28807f secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/message_drs?after=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous key.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_insert": "2020-07-24T10:25:11.000Z",
            "date_sent": "2020-07-24T10:25:11.014Z",
            "date_start": "2020-07-24T10:25:11.014Z",
            "date_stop": "2020-07-24T10:25:12.014Z",
            "delay_sent": 0,
            "direction": "outbound",
            "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
            "mcc": 310,
            "media_urls": [],
            "message": "This is a test message.",
            "message_segments": 1,
            "mnc": 999,
            "number_billing": "15162065870",
            "number_dst": "12078152557",
            "number_external": "12078152557",
            "number_src": "15162065870",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "sms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/sms/message_drs?before=92cd9154-2f53-4e62-8b4e-8ff6e4849d16&limit=1&offset=0"
    },
    "total": null
}

For some objects (e.g., Call Detail Record or SMS Detail Record objects), the system will not return their total number. This can happen as the number dynamically changes in large quantities and can become not relevant by the time of the next request.

In this case, instead of using the standard pagination offset (which is rather difficult to calculate as the system does not return the total number of objects), you can use the after or before query arguments. With these arguments, the system will return the objects which precede or follow the entered object secure ID. This might be useful if you want to receive an exact range of the objects and know the secure IDs of the records which start and end this range.

Parameter Data Type Description
after string The secure ID of the object. The response will include only the results which follow the specified secure ID in the list of the object secure IDs.
before string The secure ID of the object. The response will include only the results which precede the specified secure ID in the list of object secure IDs.

Currently, CarrierX supports the pagination that uses the after and before arguments for the following objects and methods:

Object Method Sorting (‘order’) Values
Call Detail Record Get Call Detail Records method date_stop
SMS Detail Record Get Message Detail Records method date_insert

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

If you omit any of the parameters from the response, their default values will be used (if there are any).

Pagination Response

The JSON response for a successful query using the pagination parameters will include the following attributes:

Attribute Data Type Description
count integer The number of items present in the response.
has_more boolean Whether or not there are more records existing outside of the queried parameters (e.g., if the number of items that exist exceeds the limit value, the has_more value in the response will be set to true).
items array of objects The list of the objects which match the request with the pagination query parameters applied.
limit integer The limit value applied to the request.
offset integer The offset value applied to the request.
pagination object The links that allow getting the objects which precede or follow the objects in the response due to the offset or after/ before arguments used in the request. This attribute will be an empty object 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 the next or previous URLs, or both of them.
total integer The total number of the queried objects that match the search criteria. This value will be set to null with the uncountable objects (call detail records, messages, etc.)

Result Filtering

This GET request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing the results to the conference 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 added to the query URL to restrict or customize the results of a JSON response by certain parameters (e.g., name, capabilities, state, country_code, etc.).

The structure of result filtering is as follows: filter=object_attribute filter_operator value. You can also use the and operator to combine several filters for more specific searches. For example, for a DID object we could apply the following filter: filter=state eq "NY" and phonenumber like "%555%".

Filter values can also be put inside single or double quotes. This is not necessary when the filter value is just a single word like USA. However, if your filter value consists of more than one word, the quotes are required. For example, name eq "filter value name".

Result Filtering Quick Reference

Operator Definition Example Description
bit Bit mask: this operator is used with the capabilities field only. It may have the following core values: 1 = SMS IN (1 represents 1 in a bit mask), 2 = SMS OUT (2 represents 10 in a bit mask), 4 = VOICE (4 represents 100 in a bit mask), 8 = MMS IN (8 represents 1000 in a bit mask), 16 = MMS OUT (16 represents 10000 in a bit mask). You can use this operator to look for all the DIDs that have a particular capability alongside with other possible capabilities those DIDs may have. For example capabilities bit 4 returns all the available DIDs with the following capabilities: 4(100) and up, whatever other capabilities it may have (if any), e.g. 4+1=5(101), 4+2=6(110), 4+1+2=7(111), 4+8=12(1100), 4+1+8=13(1101), etc. capabilities bit 3

capabilities bit 7
The search will return results for DIDs with SMS capabilities = 1+2=3.
The search will return results for DIDs with both SMS and VOICE capabilities = 1+2+4=7.
eq Equal to: this search looks for the exact value entered. name eq "my_mediator" The search results will include the records that have the exact my_mediator value for the name field.
ge Greater than or equal to: this search returns records where the value is greater than or equal to the field listed. wait_origination_did_ttl ge 70000 The search results will include the records that have the wait_origination_did_ttl field value greater than or equal to 70000.
gt Greater than: this search returns records where the value is exceeded for the field listed. maximum_ttl gt 40000 The search results will include the records that have the maximum_ttl field value greater than 40000.
ilike This search returns records containing the value indicated in the string passed. This form of search is case insensitive. name ilike "AccOUnt%" The search results will include the records that have the name field value starting with Account.
in In: this search returns records where the current value of the specified field must be in the specified list. status in ("active", "suspended") The search results will include the records that have the status field value equal to either active or suspended.
le Less than or equal to: this search returns records where the value is less than or equal to the field listed. wait_origination_did_ttl le 90000 The search results will include the records that have the wait_origination_did_ttl field value less than or equal to 90000.
like The same functionality as ilike but case sensitive. name like "Account%" The search results will include the records that have the name field value starting with Account.
lt Less than: this search returns records where the value is less than the field listed. maximum_ttl lt 10000 The search results will include the records that have the maximum_ttl field value less than 10000.
ne Not equal to: this search returns records that do not include the current values for the specified field. name ne "my_mediator" The search results will include the records that do not have the my_mediator value for the name field.
notin Not in: this search returns records where the current value of the specified field must not be in the specified list. status notin ("active", "suspended") The search results will include the records that do not have a status field value of active.

Field Filtering

In the following, we request Endpoint objects without the properties field.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?exclude_fields=properties' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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",
            "out_sip_password": null,
            "out_sip_username": null,
            "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.

API Reference

The Mediator API has the following sections: Bindings, Dialouts, and DIDs.

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_user_123",
    "name": "John Smith",
}
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

GET /accounts
Returns accounts matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/mediator/v1/accounts' \
-u 'mediator_user_123:qwerty123'

Response 200 status 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_user_123",
                "name": "John Smith"
            }
        ],
        "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

GET /accounts/{account_sid}
Returns an account, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/mediator/v1/accounts/13e156f7-0d21-4ba6-9e32-c56dc2c6098f' \
-u 'mediator_user_123:qwerty123'

Response 200 status 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_user_123",
        "name": "John Smith"
    },
    "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 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 the 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 the 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 the E.164 format.
in_country_format read only string The redirect DID number in a national format.
international_format read only string The redirect DID number in an international format.
phonenumber read only string The redirect DID phone number in the E.164 format without the + prefix..

Create Binding

/bindings
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 'mediator_user_123:qwerty123'

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

{
    "body": {
        "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
        "attributes": {
            "ringback":"moh"
        },
        "binding_sid": "05561bef-ce48-4823-a847-bf10f7837a42",
        "date_created": "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.

/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 meaning that no redirect_did could be found. Verify that there are available DIDs that can be assigned as a redirect_did automatically.

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

Each binding has a maximum_ttl and wait_origination_did_ttl attribute. 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

GET /bindings
Returns bindings matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings' \
-u 'mediator_user_123:qwerty123'

Response 200 status code with a list of Binding objects

{
    "body": {
        "count": 1,
        "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
            }
        ],
        "limit": 10,
        "offset": 0,
        "pagination": {},
        "total": 1
    },
    "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

GET /bindings/{binding_sid}
Returns a binding, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings/bedd33b1-2961-458e-b35a-bf80260cdba4' \
-u 'mediator_user_123:qwerty123'

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

{
    "body": {
        "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
        "attributes": {},
        "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

PATCH /bindings/{binding_sid}
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 'mediator_user_123:qwerty123'

Response 200 status 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.

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:

Refer to this table to view all fields that appear in the Binding object.

Delete Binding

DELETE /bindings/{binding_sid}
Deletes a binding, targeted by secure ID

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

Response 204 status 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, which Mediator dials out to. If the first DID is reached successfully, the redirect_did tries to reach stage_two_destination_did.
stage_two_destination_did create update string The second DID, which Mediator dials out to upon successfully reaching the stage_one_destination_did. If the second DID is reached successfully, a connection between them is established.
Attributes Object

Below are the additional 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 string The value of this field will determine whether or not to hide one or all of the caller’s phone numbers. There are four possible values for this field:
  • true means that the redirect_did will be displayed to both calling parties instead of the stage_one_destination_did or stage_two_destination_did.
  • false will display both DIDs to each other, the first calling party will see the stage_two_destination_did and, vice-versa, the second calling party will see the stage_one_destination_did.
  • stage_one will hide the second DID for the stage_one_destination_did, so the first party will see the redirect_did as the call originator, but the second party will still see the first party’s DID.
  • stage_two is opposite to stage_one, this value will hide the first DID for the stage_two_destination_did, so the second party will see the redirect_did as the call originator, but the first party will still see the second party’s DID.
The default value is true. To be able to change the value of this field the one you need, please contact us at 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

/dialouts
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 'mediator_user_123:qwerty123'

Response 200 status 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.

/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:

Refer to this table to view all fields that appear in the Dialout object.

Get Dialouts

GET /dialouts
Returns dialouts scheduled for a future time

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

Response 200 status 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

GET /dialouts/{dialout_sid}
Returns a dialout, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/mediator/v1/dialouts/8b2423ab-5a8b-438d-8c15-b9eee5879a5d' \
-u 'mediator_user_123:qwerty123'

Response 200 status 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

PATCH /dialouts/{dialout_sid}
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 'mediator_user_123:qwerty123'

Response 200 status 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.

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:

Refer to this table to view all fields that appear in the Dialout object.

Delete Dialout

DELETE /dialouts/{dialout_sid}
Deletes a dialout, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/mediator/v1/dialouts/8b2423ab-5a8b-438d-8c15-b9eee5879a5d' \
-u 'mediator_user_123:qwerty123'

Response 204 status 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 a national format.
international_format read only string The DID in an international format.
phonenumber read only string The phone number for the DID in the E.164 format without the + prefix.

Get DIDs

GET /dids
Returns the list of DIDs rented through CarrierX

curl -X GET \
'https://api.carrierx.com/mediator/v1/dids' \
-u 'mediator_user_123:qwerty123'

Response 200 status 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

GET /dids/{did_sid}
Returns a DID, targeted by secure ID

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

Response 200 status 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.