Conference v2 API Reference

The CarrierX service offers a hosted Conference Application Endpoint that enables two or more parties to speak to one another. Parties call into a meeting room, which stores the meeting configurations, call flow attributes, and meeting key information. Call flows determine how the call is handled.

You can use the Conference API to host audio conferencing for up to 1,000 attendees.

Conference Overview

Each Conference endpoint has an Account object associated with it. The Account object holds the credentials, necessary to access the conference API. It also has an association with a Call Flow object which will be used if you do not change this setting at the lower levels (DID group or DID). Refer to the Call Flows section for more information about the call flow routing.

The following different call flows are available with CarrierX conferences:

Conferences with the direct call flows do not require to create meeting rooms and set access keys for each participant. Anyone who calls the phone number associated with such a conference will be routed into one and the same meeting room without any additional prompts. Depending on the call flow associated with this conference (direct_host or direct_participant), everyone in this conference will either be a host or a participant.

For the secured Conference endpoint to work, it must have at least one Meeting Room object associated with it. The meeting room has a list of meeting keys—key-value pairs, where the key is an access code and the value is the matching access level: host, participant, or listener.

Each access level has settings which determine how the party is treated during a meeting. For example, settings on the Meeting Room object can determine that all listeners will be muted upon entering the meeting. You can configure these settings using the attributes property at different levels.

The base call flow attributes are set at the Call Flow level and are available for reading only. You can override these base settings in other conference objects. Refer to the Call Flow Attributes section for the list of the attributes which you can configure.

Conference Flow

A conference flow looks like this:

Conference Flow

  1. End-users dial a phone number associated with a conference.

  2. Depending on the conference type and the call flow attributes set, the conference either invites the calling party to enter an access codes, or skips this step.

  3. If the conference call flow requires entering an access code (open or secured), the calling parties do it. If not (direct_host or direct_participant), the conference allows the calling parties to enter the meeting.

  4. For each conference user, the system creates a temporary Call object which contains the entered access code (if the conference requires it), as well as the source and the destination phone numbers. System also associates the created Call object with the account the dialed number belongs to.

  5. The call flow attributes determine how the system treats each of the calling parties.

  6. The system compares the entered access code to the ones stored in the Meeting Room objects to determine which meeting room to connect the caller to and what access level to grant.

  7. If the code matches one of the stored ones, a temporary Meeting object, associated with the meeting room and the partner account, is created and the caller is routed to this meeting.

Call and Meeting objects are real-time elements that only exist as long as a meeting is happening and as long as there are callers in the meeting.

Once a meeting is finished, the Meeting object is deleted, along with all of the Call objects associated with the meeting.

Conference

Conference Flow with Prefix

Although DIDs and DID groups are exposed through the Conference API, they belong to the partner account rather than to the Conference endpoint itself. That is why it is possible to use a Conference endpoint without a DID at all.

In this case you will need to assign a prefix to the trunk group associated with the Conference endpoint. The setup will look like this:

Conference Prefix Routing

The callers will have to use some SIP service to call into the conference instead of a PSTN phone. The partner will need to link the prefix to the trunk group so that when the caller dials a phone number with a certain prefix via the third-party endpoint the system routes them into the Conference endpoint even if the partner does not have any DIDs rented from CarrierX and associated with their account.

The only call flow which will be used in this case is the one associated with the partner account.

The conference flow will look like this:

Conference with Prefix

Conference vs. Conference Playback Endpoint

A Conference endpoint enables two or more parties to have a conversation in a meeting.

A Conference Playback endpoint is used to listen to saved recordings made during meetings. In order for recordings to be saved, a Conference endpoint must be created and connected to a Conference Playback endpoint. Create a Conference Playback endpoint in the same way as a Conference endpoint, by using the Core API.

Using the REST API

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

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 Conference application endpoint. Refer to the Conference Endpoint quick start guide for step-by-step instructions on creating a Conference 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 Conference 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/v2",
                "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
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 Conference API has the following sections: Accounts, Calls, Call Flows, DIDs, DID Groups, Meetings, and Meeting Rooms.

Accounts

The Account object holds the data associated with the Conference API. It is used to view information about the partner that is related to the Conference endpoint.

Account Object

In CarrierX API, the Account object describes the Conference endpoint account properties.

The system returns an Account JSON object with the fields listed in the table below in response to one of the following successful requests:

Sample Account object

{
    "account_sid": "993a6552-b73b-41e5-a501-a788377ca8ed",
    "attributes": {},
    "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
    "date_created": "2021-02-25T20:36:54.000Z",
    "login": "conference_user_123",
    "name": "John Smith"
}
Attribute Data Type Description
account_sid read only string The account secure ID.
attributes update object The call flow attributes which will be overriden at the account level.
call_flow_sid update string The secure ID of the default call flow associated with the account.
date_created read only string The date and time when the account was created.
login read only string The login username used to access the Conference endpoint. Each endpoint has a unique login and password.
name update string The account name. This is a human-readable nickname for the account.
password update string The account password. This field is hidden from the response and never returned as a plain text.

Get Accounts

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

curl -X GET \
'https://api.carrierx.com/conference/v2/accounts' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a list of Account objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "993a6552-b73b-41e5-a501-a788377ca8ed",
            "attributes": {},
            "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
            "date_created": "2021-02-25T20:36:54.000Z",
            "login": "conference_user_123",
            "name": "John Smith"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

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/conference/v2/accounts/993a6552-b73b-41e5-a501-a788377ca8ed' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the Account object

{
    "account_sid": "993a6552-b73b-41e5-a501-a788377ca8ed",
    "attributes": {},
    "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
    "date_created": "2021-02-25T20:36:54.000Z",
    "login": "conference_user_123",
    "name": "John Smith"
}

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.

Update Account

PATCH /accounts/{account_sid}
Updates the Account object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/conference/v2/accounts/993a6552-b73b-41e5-a501-a788377ca8ed' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"John W. Smith"}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the updated Account object

{
    "account_sid": "993a6552-b73b-41e5-a501-a788377ca8ed",
    "attributes": {},
    "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
    "date_created": "2021-02-25T20:36:54.000Z",
    "login": "conference_user_123",
    "name": "John W. Smith"
}

This request updates an account, targeted by secure ID.

PATCH /accounts/{account_sid}
PUT /accounts/{account_sid}

An Account object can be updated using either a PATCH or PUT request.

Path Arguments
Parameter Data Type Description
account_sid required string The account 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 Account object.

Get Current Account

GET /accounts/whoami
Returns the currently logged-in account

curl -X GET \
'https://api.carrierx.com/conference/v2/accounts/whoami' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the Account object

{
    "account_sid": "993a6552-b73b-41e5-a501-a788377ca8ed",
    "attributes": {},
    "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
    "date_created": "2021-02-25T20:36:54.000Z",
    "login": "conference_user_123",
    "name": "John Smith"
}

This request returns data for the currently logged-in account.

GET /accounts/whoami

Calls

Calls are created by the server automatically when a user dials a phone number associated with a meeting room. This object is used to access information about a current call. When the call is over, the Call object is deleted.

Call Object

In CarrierX API, the Call objects describe the calls of all users into the conference.

The system returns a Call JSON object with the fields listed in the table below in response to one of the following successful requests:

Sample Call object

{
    "access_code": "890671",
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "call_sid": "69057c3e-bb90-4ed3-9c53-000000000563",
    "codecs": "PCMU",
    "date_created": "2021-09-03T14:11:55.000Z",
    "date_joined": "2021-09-03T14:11:55.000Z",
    "direction": "In",
    "duration": 28,
    "gain_level": 0,
    "meeting_room_sid": "d54061ef-8a16-459c-b055-6c0c297f46af",
    "meeting_sid": "aaa07454-fa93-3d2d-b7b4-c5da9f2f87fd",
    "muted": false,
    "name": "",
    "number_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
    "number_src": "<sip:+17605692222@55.66.77.88",
    "on_hold": false,
    "role": "host"
}
Attribute Data Type Description
access_code read only string The access code entered by the caller.
account_sid read only string The secure ID of the account associated with the Call object.
call_sid read only string The call secure ID.
codecs read only string The semicolon-separated list of audio codecs used for the call. The codecs depend on the client used to connect to the conference. Most commonly used conference audio codecs are G722, ISAC, NOVOICE, OPUS, PCMU, and the combinations of these codecs with video codecs (e.g., ISAC,VP8, PCMU,VP8, etc.)
date_created read only string The date and time when the calling party placed the call.
date_joined read only string The date and time when the calling party joined the meeting.
direction read only string The direction of the call. Values accepted in this field are: In and Out.
duration read only integer The duration of the call specified in seconds.
gain_level read only integer The gain of the transmission circuit.
meeting_room_sid read only string The secure ID of the meeting room with which this call is associated. This value is filled only after the caller enters the meeting.
meeting_sid read only string The secure ID of the meeting this call is intended for. This value is filled only after the caller enters the meeting.
muted update boolean Whether the call is muted or not.
name update string The user name as it is sent by the client.
number_dst read only string The DID being dialed.
number_src read only string The phone number of the calling party.
on_hold update boolean Whether the call is on hold or not.
role read only string The role of the calling party in the conference. Values accepted in this field are host, participant, and listener.

Get Calls

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

curl -X GET \
'https://api.carrierx.com/conference/v2/calls' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a list of Call objects

{
    "count": 1,
    "has_more": false,
    "items": [
          {
            "access_code": "890671",
            "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
            "call_sid": "69057c3e-bb90-4ed3-9c53-000000000563",
            "codecs": "PCMU",
            "date_created": "2021-09-03T14:11:55.000Z",
            "date_joined": "2021-09-03T14:11:55.000Z",
            "direction": "In",
            "duration": 28,
            "gain_level": 0,
            "meeting_room_sid": "d54061ef-8a16-459c-b055-6c0c297f46af",
            "meeting_sid": "aaa07454-fa93-3d2d-b7b4-c5da9f2f87fd",
            "muted": false,
            "name": "",
            "number_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
            "number_src": "<sip:+17605692222@55.66.77.88",
            "on_hold": false,
            "role": "host"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of calls.

GET /calls

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get Call by SID

GET /calls/{call_sid}
Returns a call, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/conference/v2/calls/69057c3e-bb90-4ed3-9c53-000000000563' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the Call object

{
    "access_code": "890671",
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "call_sid": "69057c3e-bb90-4ed3-9c53-000000000563",
    "codecs": "PCMU",
    "date_created": "2021-09-03T14:11:55.000Z",
    "date_joined": "2021-09-03T14:11:55.000Z",
    "direction": "In",
    "duration": 28,
    "gain_level": 0,
    "meeting_room_sid": "d54061ef-8a16-459c-b055-6c0c297f46af",
    "meeting_sid": "aaa07454-fa93-3d2d-b7b4-c5da9f2f87fd",
    "muted": false,
    "name": "",
    "number_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
    "number_src": "<sip:+17605692222@55.66.77.88",
    "on_hold": false,
    "role": "host"
}

This request returns data for a call, targeted by secure ID.

GET /calls/{call_sid}

This request is enabled for Field Filtering.

Path Arguments
Parameter Data Type Description
call_sid required string The call secure ID.

Update Call

PATCH /calls/{call_sid}
Updates the Call object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/conference/v2/calls/69057c3e-bb90-4ed3-9c53-000000000563' \
-H 'Content-Type: application/json' \
--data-binary '{"muted":"true"}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the updated Call object

{
    "access_code": "890671",
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "call_sid": "69057c3e-bb90-4ed3-9c53-000000000563",
    "codecs": "PCMU",
    "date_created": "2021-09-03T14:11:55.000Z",
    "date_joined": "2021-09-03T14:11:55.000Z",
    "direction": "In",
    "duration": 28,
    "gain_level": 0,
    "meeting_room_sid": "d54061ef-8a16-459c-b055-6c0c297f46af",
    "meeting_sid": "aaa07454-fa93-3d2d-b7b4-c5da9f2f87fd",
    "muted": true,
    "name": "",
    "number_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
    "number_src": "<sip:+17605692222@55.66.77.88",
    "on_hold": false,
    "role": "host"
}

This request updates a call, targeted by secure ID.

PATCH /calls/{call_sid}

A PATCH request can be used to update one or more Call object attribute values. Only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The call secure ID is passed in the query URL, and the values to be modified are passed in the request body.

Path Arguments
Parameter Data Type Description
call_sid required string The call 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 Call object.

Call Flows

Call flows define the way that the system handles the calls.

Normally, you can choose between the following main call flows when creating a meeting room:

The system automatically associates a call flow with the partner account at the creation of a Conference endpoint. The attributes values of the Call Flow object serve as default settings. These settings can be overridden at various levels:

Refer to the Call Flow Attributes section for more information on this.

The typical call flow routing looks like this:

Call Flow Routing

  1. First, the system will check if the call flow is set at the phone number level.

  2. If it is not the case, the next step for the system is to check if the call flow is set at the DID group level.

  3. If it is also not true, finally, the system will look for the call flow settings at the account level.

The account associated with the conference should have a call flow set. If it is not so and the system fails to find the call flow settings at the DID or DID group level, the call will be dropped and the Meeting object will not be created.

Call Flow Object

In CarrierX API, the Call Flow objects describe all the available call flows with their default attributes.

The system returns a Call Flow JSON object with the fields listed in the table below in response to one of the following successful requests:

Sample Call Flow object

{
    "attributes": {
        "call_announceparticipantcount": "hpl",
        "call_instructions_dtmf_binding": "*4",
        "call_moh_dtmf_binding": "0",
        "call_moh_list": "legacy,beep,default,custom",
        "call_mute_dtmf_binding": "*6",
        "call_participantsnumber_dtmf_binding": "*2",
        "conference_drop_dtmf_binding": "92",
        "conference_entryexittones_dtmf_binding": "*8",
        "conference_entrytones": "on",
        "conference_exittones": "on",
        "conference_greeting_enabled": "on",
        "conference_hold_dtmf_binding": "*3",
        "conference_language": "EN",
        "conference_lock_dtmf_binding": "*7",
        "conference_moh": "default",
        "conference_moh_enabled": "on",
        "conference_mute_dtmf_binding": "*5",
        "conference_qa_dtmf_binding": "*1",
        "conference_rollcall": "off",
        "conference_rollcall_onenter": "off",
        "conference_rollcall_onexit": "off",
        "conference_singlemember": "off",
        "conference_start_how": "first",
        "conference_start_wait": "360",
        "conference_stop_how": "moderator",
        "conference_stop_wait": "180",
        "recording_addr": "15162065121@10.1.10.190",
        "recording_dtmf_binding": "*9",
        "recording_metadata": "custom",
        "recording_method": "remote",
        "recording_stop_how": "last"
    },
    "call_flow_sid": "665bd4c6-7f44-4c46-a467-1e4696f52968",
    "name": "secured"
}
Attribute Data Type Description
attributes read only object The call flow base attributes which are set at the call flow level. Refer to this section for more details on various conference call flow attributes.
call_flow_sid read only string The call flow secure ID.
name read only string The call flow name. This is a human-readable nickname for the call flow.

Get Call Flows

GET /call_flows
Returns call flows matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/conference/v2/call_flows' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a list of Call Flow objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "attributes": {
                "call_announceparticipantcount": "hpl",
                "call_instructions_dtmf_binding": "*4",
                "call_moh_dtmf_binding": "0",
                "call_moh_list": "legacy,beep,default,custom",
                "call_mute_dtmf_binding": "*6",
                "call_participantsnumber_dtmf_binding": "*2",
                "conference_drop_dtmf_binding": "92",
                "conference_entryexittones_dtmf_binding": "*8",
                "conference_entrytones": "on",
                "conference_exittones": "on",
                "conference_greeting_enabled": "on",
                "conference_hold_dtmf_binding": "*3",
                "conference_language": "EN",
                "conference_lock_dtmf_binding": "*7",
                "conference_moh": "default",
                "conference_moh_enabled": "on",
                "conference_mute_dtmf_binding": "*5",
                "conference_qa_dtmf_binding": "*1",
                "conference_rollcall": "off",
                "conference_rollcall_onenter": "off",
                "conference_rollcall_onexit": "off",
                "conference_singlemember": "off",
                "conference_start_how": "first",
                "conference_start_wait": "360",
                "conference_stop_how": "moderator",
                "conference_stop_wait": "180",
                "recording_addr": "15162065121@10.1.10.190",
                "recording_dtmf_binding": "*9",
                "recording_metadata": "custom",
                "recording_method": "remote",
                "recording_stop_how": "last"
            },
            "call_flow_sid": "665bd4c6-7f44-4c46-a467-1e4696f52968",
            "name": "secured"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of call flows.

GET /call_flows

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get Call Flow by SID

GET /call_flows/{call_flow_sid}
Returns a call flow, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/conference/v2/call_flows/fb2b69b1-6998-4cdc-b04c-a267c585f767' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the Call Flow object

{
    "attributes": {
        "call_announceparticipantcount": "hpl",
        "call_instructions_dtmf_binding": "*4",
        "call_moh_dtmf_binding": "0",
        "call_moh_list": "legacy,beep,default,custom",
        "call_mute_dtmf_binding": "*6",
        "call_participantsnumber_dtmf_binding": "*2",
        "conference_drop_dtmf_binding": "92",
        "conference_entryexittones_dtmf_binding": "*8",
        "conference_entrytones": "on",
        "conference_exittones": "on",
        "conference_greeting_enabled": "on",
        "conference_hold_dtmf_binding": "*3",
        "conference_language": "EN",
        "conference_lock_dtmf_binding": "*7",
        "conference_moh": "default",
        "conference_moh_enabled": "on",
        "conference_mute_dtmf_binding": "*5",
        "conference_qa_dtmf_binding": "*1",
        "conference_rollcall": "off",
        "conference_rollcall_onenter": "off",
        "conference_rollcall_onexit": "off",
        "conference_singlemember": "off",
        "conference_start_how": "first",
        "conference_start_wait": "360",
        "conference_stop_how": "moderator",
        "conference_stop_wait": "180",
        "recording_addr": "15162065121@10.1.10.190",
        "recording_dtmf_binding": "*9",
        "recording_metadata": "custom",
        "recording_method": "remote",
        "recording_stop_how": "last"
    },
    "call_flow_sid": "665bd4c6-7f44-4c46-a467-1e4696f52968",
    "name": "secured"
}

This request returns data for a call flow, targeted by secure ID.

GET /call_flows/{call_flow_sid}

This request is enabled for Field Filtering.

Path Arguments
Parameter Data Type Description
call_flow_sid required string The call flow secure ID.

DIDs

DIDs are phone numbers rented through CarrierX and associated with a specific conference.

DID Object

In CarrierX API, the DID objects describe all the rented phone numbers associated with the Conference endpoint.

The system returns a DID JSON object with the fields listed in the table below in response to one of the following successful requests:

Sample DID object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
    "country_code": "USA",
    "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
    "did_sid": "022aa786-2c40-484f-9a36-2a51e84579d6",
    "in_country_format": "(516) 206-5919",
    "international_format": "+1 516-206-5919",
    "phonenumber": "15162065919"
}
Attribute Data Type Description
account_sid read only string The secure ID of the account associated with the DID.
attributes update object The call flow attributes which will be overriden at the DID level.
call_flow_sid update string The secure ID of the call flow associated with the DID.
country_code read only string The ISO 3166-1 alpha-3 code of this DID. This field is assigned automatically.
did_group_sid update string The secure ID of the DID group associated with the DID.
did_sid read only string The DID secure ID.
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 E.164 format.

Get DIDs

GET /dids
Returns DIDs matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/conference/v2/dids' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a list of DID objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
            "attributes": {},
            "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
            "country_code": "USA",
            "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
            "did_sid": "022aa786-2c40-484f-9a36-2a51e84579d6",
            "in_country_format": "(516) 206-5919",
            "international_format": "+1 516-206-5919",
            "phonenumber": "15162065919"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of DIDs.

GET /dids

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/conference/v2/dids/022aa786-2c40-484f-9a36-2a51e84579d6' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the DID object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
    "country_code": "USA",
    "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
    "did_sid": "022aa786-2c40-484f-9a36-2a51e84579d6",
    "in_country_format": "(516) 206-5919",
    "international_format": "+1 516-206-5919",
    "phonenumber": "15162065919"
}

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.

Update DID

PATCH /dids/{did_sid}
Updates the DID object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/conference/v2/dids/022aa786-2c40-484f-9a36-2a51e84579d6' \
-H 'Content-Type: application/json' \
--data-binary '{"did_group_sid":"ea1d0f8d-4f2d-4437-a627-694a23a2d568"}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the updated DID object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "call_flow_sid": "fb2b69b1-6998-4cdc-b04c-a267c585f767",
    "country_code": "USA",
    "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
    "did_sid": "022aa786-2c40-484f-9a36-2a51e84579d6",
    "in_country_format": "(516) 206-5919",
    "international_format": "+1 516-206-5919",
    "phonenumber": "15162065919"
}

This request updates a DID, targeted by secure ID.

PATCH /dids/{did_sid}
PUT /dids/{did_sid}

A DID object can be updated using either a PATCH or PUT request.

Path Arguments
Parameter Data Type Description
did_sid required string The DID 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 DID object.

DID Groups

A DID Group is a set of phone numbers rented through CarrierX and associated with a specific conference. You can easily associate the same call flows and attributes with all the DIDs which are grouped into a single DID group.

DID Group Object

In CarrierX API, the DID Group objects describe the groups of rented phone numbers associated with the Conference endpoint.

The system returns a DID Group JSON object with the fields listed in the table below in response to one of the following successful requests:

Sample DID Group object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "call_flow_sid": null,
    "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
    "name": "New DID group",
}
Attribute Data Type Description
account_sid read only string The secure ID of the account associated with the DID group.
attributes create update object The call flow attributes which will be overriden at the DID group level.
call_flow_sid create update string The secure ID of the call flow associated with the DID group.
did_group_sid read only string The DID group secure ID.
name create update string The name of the DID group.

Create DID Group

/did_groups
Creates a DID group

curl -X POST \
'https://api.carrierx.com/conference/v2/did_groups' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the DID Group object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "call_flow_sid": null,
    "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
    "name": "N/A",
}

This request creates a DID group.

/did_groups
Body Arguments

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

No fields are required to create a DID group, an empty object can be passed.

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

Get DID Groups

GET /did_groups
Returns DID groups matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/conference/v2/did_groups' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a list of DID Group objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
            "attributes": {},
            "call_flow_sid": null,
            "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
            "name": "N/A",
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1,
}

This request returns a list of DID groups.

GET /did_groups

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get DID Group by SID

GET /did_groups/{did_group_sid}
Returns a DID group, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/conference/v2/did_groups/ea1d0f8d-4f2d-4437-a627-694a23a2d568' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the DID Group object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "call_flow_sid": null,
    "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
    "name": "N/A",
}

This request returns data for a DID group, targeted by secure ID.

GET /did_groups/{did_group_sid}

This request is enabled for Field Filtering.

Path Arguments
Parameter Data Type Description
did_group_sid required string The DID group secure ID.

Update DID Group

PATCH /did_groups/{did_group_sid}
Updates the DID Group object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/conference/v2/did_groups/ea1d0f8d-4f2d-4437-a627-694a23a2d568' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"New DID group"}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the updated DID Group object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "call_flow_sid": null,
    "did_group_sid": "ea1d0f8d-4f2d-4437-a627-694a23a2d568",
    "name": "New DID group",
}

This request updates a DID group, targeted by secure ID.

PATCH /did_groups/{did_group_sid}
PUT /did_groups/{did_group_sid}

A DID Group object can be updated using either a PATCH or PUT request.

Path Arguments
Parameter Data Type Description
did_group_sid required string The DID group 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 DID Group object.

Delete DID Group

DELETE /did_groups/{did_group_sid}
Deletes a DID Group, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/conference/v2/did_groups/ea1d0f8d-4f2d-4437-a627-694a23a2d568' \
-u 'conference_user_123:qwerty123'

Response 204 response code with an empty body

This request deletes a DID group, targeted by secure ID.

DELETE /did_groups/{did_group_sid}
Path Arguments
Parameter Data Type Description
did_group_sid required string The DID group secure ID.

Meetings

A Meeting object is generated once a meeting begins. The object only exists as long as the meeting is occurring.

Meeting Object

In CarrierX API, the Meeting objects describe the temporary entities which represent the meetings.

The system returns a Meeting JSON object with the fields listed in the table below in response to one of the following successful requests:

Sample Meeting object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attendees": {
        "hosts": 1,
        "listeners": 0,
        "participants": 0
    },
    "date_created": "2021-06-23T17:36:37.000Z",
    "duration": 35,
    "locked": false,
    "meeting_room_sid": "e1b86c9b-d758-4e3a-9bd4-a0016a3b10b1",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000944173",
    "on_hold": "pl",
    "participant_muted": "false",
    "recording": false
}
Attribute Data Type Description
account_sid read only string The secure ID of the account associated with the meeting.
attendees read only object The attendees currently present at the meeting. The returned object contains the list of the meeting attendees (host, participant, and listener) and the quantity of each of the attendees.
date_created read only string The date and time when the meeting was created.
duration read only integer The meeting duration in seconds.
locked read only boolean Whether the meeting allows more participants and listeners to join. Hosts can join the meeting with any value in this field. Values accepted in this field are true or false.
meeting_room_sid read only string The secure ID of the meeting room associated with the meeting.
meeting_sid read only string The meeting secure ID.
on_hold update string The meeting participants for whom the meeting is currently put on hold. Values accepted in this field are h, p, l, and any combinations of these.
participant_muted update string Specifies whether the meeting participants are muted. Values accepted in this field are:
  • false to show that only the users with the listener access role are muted. The users with the participant and host roles can talk.
  • relaxed to show that the users with the participant and listener access roles are muted. The users with the participant roles can unmute themselves.
  • true to show that the users with the participant and listener access roles are muted by the host or the conference attribute settings and cannot unmute themselves.
recording read only boolean Whether the meeting is currently being recorded or not. Values accepted in this field are true or false.

Get Meetings

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

curl -X GET \
'https://api.carrierx.com/conference/v2/meetings' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a list of Meeting objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
            "attendees": {
                "hosts": 1,
                "listeners": 0,
                "participants": 0
            },
            "date_created": "2021-06-23T17:36:37.000Z",
            "duration": 35,
            "locked": false,
            "meeting_room_sid": "e1b86c9b-d758-4e3a-9bd4-a0016a3b10b1",
            "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000944173",
            "on_hold": "pl",
            "participant_muted": "false",
            "recording": false
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of meetings.

GET /meetings

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get Meeting by SID

GET /meetings/{meeting_sid}
Returns a meeting, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/conference/v2/meetings/69057c3e-bb90-4ed3-9c53-000000944173' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the Meeting object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attendees": {
        "hosts": 1,
        "listeners": 0,
        "participants": 0
    },
    "date_created": "2021-06-23T17:36:37.000Z",
    "duration": 35,
    "locked": false,
    "meeting_room_sid": "e1b86c9b-d758-4e3a-9bd4-a0016a3b10b1",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000944173",
    "on_hold": "pl",
    "participant_muted": "false",
    "recording": false
}

This request returns data for a meeting, targeted by secure ID.

GET /meetings/{meeting_sid}

This request is enabled for Field Filtering.

Path Arguments
Parameter Data Type Description
meeting_sid required string The meeting secure ID.

Update Meeting

PATCH /meetings/{meeting_sid}
Updates the Meeting object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/conference/v2/meetings/69057c3e-bb90-4ed3-9c53-000000944173' \
-H 'Content-Type: application/json' \
--data-binary '{"on_hold":"pl"}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the updated Meeting object

{
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attendees": {
        "hosts": 1,
        "listeners": 0,
        "participants": 0
    },
    "date_created": "2021-06-23T17:36:37.000Z",
    "duration": 35,
    "locked": false,
    "meeting_room_sid": "e1b86c9b-d758-4e3a-9bd4-a0016a3b10b1",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000944173",
    "on_hold": "pl",
    "participant_muted": "false",
    "recording": false
}

This request updates a meeting, targeted by secure ID.

PATCH /meetings/{meeting_sid}

A PATCH request can be used to update one or more Meeting object attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The meeting secure ID is passed in the query URL, and the values to be modified are passed in the request body.

Path Arguments
Parameter Data Type Description
meeting_sid required string The meeting 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 Meeting object.

Delete Meeting

DELETE /meetings/{meeting_sid}
Deletes a meeting, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/conference/v2/meetings/69057c3e-bb90-4ed3-9c53-000000944173' \
-u 'conference_user_123:qwerty123'

Response 204 response code with an empty body

This request deletes a meeting, targeted by secure ID.

DELETE /meetings/{meeting_sid}
Path Arguments
Parameter Data Type Description
meeting_sid required string The meeting secure ID.

Meeting Rooms

Meeting rooms hold meeting configurations, DID group references, and contain role information. Access codes are also set at the Meeting Room object level. These are DTMF sequences entered by callers which determine the role of the caller. The three roles are:

Meeting Room Object

In CarrierX API, the Meeting Room objects describe the meeting configurations.

The system returns a Meeting Room JSON object with the fields listed in the table below in response to one of the following successful requests:

Sample Meeting Room object

{
    "access_codes": [
        {
            "access_code": "890671",
            "role": "host"
        },
        {
            "access_code": "265423",
            "role": "listener"
        },
        {
            "access_code": "143623",
            "role": "participant"
        }
    ],
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "did_group_sid": null,
    "meeting_room_sid": "2652635f-10a6-4b2a-a46b-2eeb75ddeab6",
    "name": "N/A"
}
Attribute Data Type Description
access_codes create update array of objects An array of Meeting Key objects containing the information about the access codes and their matching roles. Please note that access codes must be unique across all the meeting rooms within a single conference endpoint.
account_sid read only string The secure ID of the account associated with the meeting room.
attributes create update object The call flow attributes which will be overriden at the meeting room level.
did_group_sid create update string The secure ID of the DID group associated with the meeting room.
meeting_room_sid read only string The secure ID of the meeting room.
name create update string The meeting room name. This is a human-readable nickname for the meeting room.
Meeting Key Object

Attribute Data Type Description
access_code create update string The access code which the calling party must enter to gain the abilities of the corresponding role.
role create update string The roles that the calling party will have in the conference. Values accepted in this field are:
  • host for the users that have the moderator access role.
  • listener for the users that have a limited listener access role, cannot take a full-fledged part in the meeting, but can only listen to what others say.
  • participant for the users that have a normal user access role.

Create Meeting Room

/meeting_rooms
Creates a meeting room

curl -X POST \
'https://api.carrierx.com/conference/v2/meeting_rooms' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"My meeting room","access_codes":[{"access_code":"890671","role":"host"},{"access_code":"265423","role":"listener"},{"access_code":"143623","role":"participant"}]}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the Meeting Room object

{
    "access_codes": [
        {
            "access_code": "890671",
            "role": "host"
        },
        {
            "access_code": "265423",
            "role": "listener"
        },
        {
            "access_code": "143623",
            "role": "participant"
        }
    ],
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "did_group_sid": null,
    "meeting_room_sid": "2652635f-10a6-4b2a-a46b-2eeb75ddeab6",
    "name": "My meeting room"
}

This request creates a meeting room.

/meeting_rooms
Body Arguments

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

No fields are required to create a meeting room, an empty object can be passed.

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

Get Meeting Rooms

GET /meeting_rooms
Returns meeting rooms matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/conference/v2/meeting_rooms' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a list of Meeting Room objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "access_codes": [
                {
                    "access_code": "890671",
                    "role": "host"
                },
                {
                    "access_code": "265423",
                    "role": "listener"
                },
                {
                    "access_code": "143623",
                    "role": "participant"
                }
            ],
            "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
            "attributes": {},
            "did_group_sid": null,
            "meeting_room_sid": "2652635f-10a6-4b2a-a46b-2eeb75ddeab6",
            "name": "N/A"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of meeting rooms.

GET /meeting_rooms

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get Meeting Room by SID

GET /meeting_rooms/{meeting_room_sid}
Returns a meeting room, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/conference/v2/meeting_rooms/2652635f-10a6-4b2a-a46b-2eeb75ddeab6' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the Meeting Room object

{
    "access_codes": [
        {
            "access_code": "890671",
            "role": "host"
        },
        {
            "access_code": "265423",
            "role": "listener"
        },
        {
            "access_code": "143623",
            "role": "participant"
        }
    ],
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "did_group_sid": null,
    "meeting_room_sid": "2652635f-10a6-4b2a-a46b-2eeb75ddeab6",
    "name": "N/A"
}

This request returns data for a meeting room, targeted by secure ID.

GET /meeting_rooms/{meeting_room_sid}

This request is enabled for Field Filtering.

Path Arguments
Parameter Data Type Description
meeting_room_sid required string The meeting room secure ID.

Update Meeting Room

PATCH /meeting_rooms/{meeting_room_sid}
Updates the Meeting Room object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/conference/v2/meeting_rooms/2652635f-10a6-4b2a-a46b-2eeb75ddeab6' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"Updated meeting room"}' \
-u 'conference_user_123:qwerty123'

Response 200 response code with a serialized copy of the updated Meeting Room object

{
    "access_codes": [
        {
            "access_code": "890671",
            "role": "host"
        },
        {
            "access_code": "265423",
            "role": "listener"
        },
        {
            "access_code": "143623",
            "role": "participant"
        }
    ],
    "account_sid": "a1f38bf7-5879-49c1-be72-50ffa7f249a6",
    "attributes": {},
    "did_group_sid": null,
    "meeting_room_sid": "2652635f-10a6-4b2a-a46b-2eeb75ddeab6",
    "name": "Updated meeting room"
}

This request updates a meeting room, targeted by secure ID.

PATCH /meeting_rooms/{meeting_room_sid}
PUT /meeting_rooms/{meeting_room_sid}

A Meeting Room object can be updated using either a PATCH or PUT request.

Path Arguments
Parameter Data Type Description
meeting_room_sid required string The meeting room 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 Meeting Room object.

Delete Meeting Room

DELETE /meeting_rooms/{meeting_room_sid}
Deletes a meeting room, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/conference/v2/meeting_rooms/2652635f-10a6-4b2a-a46b-2eeb75ddeab6' \
-u 'conference_user_123:qwerty123'

Response 204 response code with an empty body

This request deletes a meeting room, targeted by secure ID.

DELETE /meeting_rooms/{meeting_room_sid}
Path Arguments
Parameter Data Type Description
meeting_room_sid required string The meeting room secure ID.