Introduction

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.

Refer to the Conference products page for quick start guides and video tutorials. These hold walk-through instructions on configuring Conference endpoints, creating meeting rooms, assigning containers for meeting recordings, and accessing recordings.

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.

For more information, see our Getting Started with Postman Quick Start Guide.

Main Conventions

The following conventions are used in the sections, which contain the tables with objects attributes, their types, and descriptions:

Credentials

The following curl command will return a list of all of the endpoints of the CarrierX account associated with the login credentials. Use your Core API token in the query below. The endpoint login 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": 2,
  "has_more": false,
  "items": [
      {
          "addresses": [
              {
                  "direction": "any",
                  "ip": "10.1.10.69",
                  "port": 5060,
                  "transport": "udp"
              }
          ],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
          "name": "System Gateway",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {},
          "transformations": [],
          "type": "system_gateway",
          "voip_token": null
      },
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flex",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
              "api_url": "https://api.carrierx.com/flexml/v1",
              "container_sid": "null",
              "login": "sample_login",
              "password": "sample_password"
          },
          "transformations": [],
          "type": "flexml",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 2
}

API requests require authentication. To obtain a CarrierX account and gain credentials, please submit a request through our Contact Us page. The Core API uses a bearer token, and the endpoint APIs (Conference, FlexML, and Mediator) use a login and password.

Prior to making requests, a Conference Application Endpoint needs to be created. See the Configure an Application Endpoint quick start guide for step-by-step instructions on creating an endpoint.

Each of the application endpoints has different login and password values. Entering the Core API token credentials instead of the endpoint-specific credentials when working with the Conference, FlexML, or Mediator APIs will return the error unauthorized.

Requests

Sample request to create Conference endpoint.

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_conf", "type":"conference"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The requests in CarrierX API are made using the standard REST notation, typical for web services. This includes the URL, to which the request will be sent, the request method, the request related headers, and, optionally, a payload.

Request URL

The usual path to the API objects include the base URL to the API used with the object (Core API base URL for the objects used throughout the CarrierX products, or specific API base URLs used for FlexML, Mediator, or Conference), and the path to the object collections and the object items.

If the action targets the specific object, the path to it will include the object secure ID (SID), which allows to distinguish the targeted object from the other ones in the same collection.

The system only accepts HTTPS requests, and not HTTP requests.

Request Methods

CarrierX API uses five main verbs (methods) of REST over HTTP for the requests: POST, GET, PUT, PATCH, and DELETE. These methods are used to create the objects, get the information about the objects, modify the objects, and delete them.

CarrierX partners need to have special permissions (or scopes) to use API methods on various objects. Refer to the available_scopes table for the complete list of the scopes that define the partner’s permissions on objects and collections.

POST

The POST method is used to create new objects. When you create a new object, you usually need to specify at least some of the attributes for the object to be created in the request payload.

The successful POST request will return a 200 response with the serialized JSON copy of the created object.

GET

The GET method is used to view the information about the existing objects and their collections.

Generic GET requests return the list of all the objects (or collections) available for the request sent. Most of such GET requests can be used together with Pagination, Result Filtering, and Field Filtering.

GET requests aimed at a specific object require to use the object secure ID to be included as a part of the request path, and return the information about the specified object only. Most of such GET requests can be used together with Field Filtering.

The successful GET request will return a 200 response with the serialized JSON copy of the requested objects (or specific object).

PATCH/PUT

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

Sample PATCH request to modify or add a 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'

The successful request returns the serialized JSON copy of the created object together with the nested object.

{
    "attributes": {
        "name": "New Partner Name"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

Sample PATCH request to add a 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'

The successful request returns the serialized JSON copy of the created object together with the modified nested object.

{
    "attributes": {
        "name": "New Partner Name"
        "name2": "New Partner Name 2"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

Sample PATCH request to modify the entire 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'

The successful request returns the serialized JSON copy of the created object together with the nested object.

{
    "attributes": {
        "name3": "New Partner Name 3"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

PATCH is used to modify only some of the object attributes and does not require to send the entire object in the request payload. Only the attributes and their values that need to be modified can be sent in the request body.

Objects can have a complex structure and can contain other objects as part of them, i.e., nested inside them. When you use PATCH and want to modify the nested objects, PATCH follows the below rules to define what must be updated and how:

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

The DELETE method is used to delete the object targeted by its secure ID.

The successful DELETE request will return a 204 response code with an empty body.

Additional Request Parameters

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

Responses

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

For a comprehensive list of returned attributes refer to the Call Object, DID Object, DID Group Object, Meeting Object, and Meeting Room Object.

Pagination

This request returns Call objects starting with the second record available, and returns a maximum of 4 records.

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

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

{
  "count": 0,
  "has_more": false,
  "items": [],
  "limit": 4,
  "offset": 2,
  "pagination": {
      "previous": "https://api.carrierx.com/conference/v1/calls?limit=4&offset=0"
  },
  "total": 0
}

The three optional parameters for pagination are: offset, limit, and order. GET requests use these three parameters to dictate how many items should be skipped in the response, the amount of records to return, and in what order the results should appear.

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

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

The last parameter of pagination is order. Two values are accepted for this parameter: asc and desc. asc is short for ascending and is the default order. Enter the field name to be ordered followed by either asc or desc. For example, name desc will return names sorted in reverse-alphabetical order. Since the default is asc, entering just name will sort the results by name in alphabetical order.

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

Pagination Quick Reference

Result Filtering

This GET request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing 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 used to restrict or customize the JSON response. Operators can be combined for more specific searches, and are added to the query URL.

Result Filtering Quick Reference

Field Filtering

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

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

The following response excludes the properties field from returned Endpoint objects.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
            "name": "my_example_conference",
            "partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
            "transformations": [],
            "type": "conference",
            "voip_token": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

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

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

Field Filtering Quick Reference

HTTP Errors

The Conference API uses the following HTTP error codes:

Conference Overview

The Conference API is used to host audio conferencing for up to 1,000 attendees. Meeting rooms are configurable objects that hold the settings for meetings. End-users dial a phone number and enter an access code, which the system uses to determine which meeting room they will be connected to.

Access codes correspond with the three access levels: host, participant, and 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.

A Meeting Room object holds other configurations called Meeting Attributes, which dictate how the call is handled. A Meeting object is created in real time once a meeting starts. The start of a meeting is determined by meeting room settings. For example, a meeting can begin once a host calls in, or a meeting can start once any party calls in.

A Call object is also created in real time when a call begins. Meeting and Call 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 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. Learn how to connect the endpoints by referring to the Conference Playback Quick Start.

API Reference

The Conference API has the following sections: Calls, DIDs, DID Groups, Meetings, and Meeting Rooms.

Use the Call object to retrieve, update, and delete future calls. Target the DID object to get list of DIDs, and the DID Group object to return DID groups. Through the Conference API, Meeting objects can be returned, updated, and deleted. Finally, Meeting Room objects can be created, returned, updated, and deleted.

Call Flows

Call flows define the way that calls are handled. There are two call flows that can be chosen from when creating a meeting room. The call flows are CONF and SPECTEL. The CONF call flow enables callers to enter a conference room with an access code associated with the meeting room. Alternatively, the CONF call flow also enables creating a meeting on the fly by entering a random access code.

The SPECTEL call flow only accepts access codes associated with the meeting room.

Call flows are set at the creation of a Meeting Room object. The attributeTemplates values of the Call Flow object serve as default settings. These settings can be overridden in various places once the Meeting Room object has been created.

Call Flow Object

This section outlines the Call Flow object. The attributes listed in the table below will be returned in a JSON object when a successful request has been made.

Sample Call Flow object:

{
    "id": 3,
    "name": "CONF",
    "path": "/usr/local/DNCA/callflows/CONF"
}

Attribute Object

This object is used in attributeTemplates.

Get Call Flows

The following GET request returns call flows matching the criteria in the request URL.

curl -X GET \
'https://api.carrierx.com/conference/v1/callFlows?exclude_fields=attributeTemplates' \
-u '[your_use_name]:[your_password]'

A successful request will return a 200 response code with a list of Call Flow objects.

{
    "callFlows": [
        {
            "id": 1,
            "name": "SPECTEL",
            "path": "/usr/local/DNCA/callflows/SPECTEL"
        },
        {
            "id": 3,
            "name": "CONF",
            "path": "/usr/local/DNCA/callflows/CONF"
        }
    ],
    "last": 0,
    "offset": 0,
    "total": 2
}

This request returns a list of call flows that match the optional filters provided.

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

Get Call Flow by ID

The following GET request returns a list of call flows by ID associated with the Conference endpoint.

curl -X GET \
'https://api.carrierx.com/conference/v1/callFlows/1?exclude_fields=attributeTemplates' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the Call Flow object.

{
    "id": 1,
    "name": "SPECTEL",
    "path": "/usr/local/DNCA/callflows/SPECTEL"
}

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

This request is enabled for Field Filtering.

Path Arguments

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.

Note that a meeting room can have multiple calls. Each participant calling into a meeting room will be represented with a Call object.

Call Object

This section outlines the Call object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample Call object:

{
    "accessCode": "111",
    "addressFrom": "\"+15162065319\" ",
    "bridgeName": "MIA-QA-FCC4D",
    "callee": "15162065318",
    "caller": "+15162065319",
    "codec": "PCMU",
    "connectionStatus": 0,
    "created": 1544643810000,
    "customName": "",
    "duration": 171,
    "gainLevel": 0,
    "holdMode": 0,
    "id": 6889184,
    "joined": 1544643810000,
    "meetingNumber": 106131,
    "muteMode": 0,
    "nodeName": "10.2.114.15",
    "presenterMedia": 0,
    "qaMode": 0,
    "role": 1,
    "state": 2
}

Get Calls

The following GET request returns calls scheduled to happen in the future.

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

A successful request will return a 200 response code with a list of Call objects scheduled for a future time.

{
    "calls": [
        {
            "accessCode": "111",
            "addressFrom": "\"+15162065319\" ",
            "bridgeName": "MIA-QA-FCC4D",
            "callee": "15162065318",
            "caller": "+15162065319",
            "codec": "PCMU",
            "connectionStatus": 0,
            "created": 1544643810000,
            "customName": "",
            "duration": 171,
            "gainLevel": 0,
            "holdMode": 0,
            "id": 6889184,
            "joined": 1544643810000,
            "meetingNumber": 106131,
            "muteMode": 0,
            "nodeName": "10.2.114.15",
            "presenterMedia": 0,
            "qaMode": 0,
            "role": 1,
            "state": 2
        }
    ],
    "last": 0,
    "offset": 0,
    "total": 1
}

This request returns a list of calls.

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

Get Call by ID

The following GET request returns a call, targeted by ID.

curl -X GET \
'https://api.carrierx.com/conference/v1/calls/6889184' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the Call object.

{
    "accessCode": "111",
    "addressFrom": "\"+15162065319\" ",
    "bridgeName": "MIA-QA-FCC4D",
    "callee": "15162065318",
    "caller": "+15162065319",
    "codec": "PCMU",
    "connectionStatus": 0,
    "created": 1544643810000,
    "customName": "",
    "duration": 238,
    "gainLevel": 0,
    "holdMode": 0,
    "id": 6889184,
    "joined": 1544643810000,
    "meetingNumber": 106131,
    "muteMode": 0,
    "nodeName": "10.2.114.15",
    "presenterMedia": 0,
    "qaMode": 0,
    "role": 1,
    "state": 2
}

This request returns details for a call, targeted by ID.

Path Arguments

Update Call

The following PATCH request updates a call.

curl -X PATCH \
'https://api.carrierx.com/conference/v1/calls/6889184' \
-H 'Content-Type: application/json' \
--data-binary '{"customName": "name"}' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the updated Call object.

{
    "calls": [
        {
            "accessCode": "111",
            "addressFrom": "\"+15162065319\" ",
            "bridgeName": "MIA-QA-FCC4D",
            "callee": "15162065318",
            "caller": "+15162065319",
            "codec": "PCMU",
            "connectionStatus": 0,
            "created": 1544643810000,
            "customName": "",
            "duration": 171,
            "gainLevel": 0,
            "holdMode": 0,
            "id": 6889184,
            "joined": 1544643810000,
            "meetingNumber": 106131,
            "muteMode": 0,
            "nodeName": "10.2.114.15",
            "presenterMedia": 0,
            "qaMode": 0,
            "role": 1,
            "state": 2
        }
    ],
    "last": 0,
    "offset": 0,
    "total": 1
}

This request changes the call state.

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

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

• A PUT request can be used to update an entire Call object. The call ID is passed in the query URL, and the entire Call object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• accessCode
• addressFrom
• addressTo
• callee
• caller
• codec
• connectionStatus
• customName
• gainLevel
• holdMode
• muteMode
• nodeName
• operatorMode
• presenterMedia
• role
• state

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

Delete Call

The following DELETE request hangs up the call, targeted by ID.

curl -X DELETE \
'https://api.carrierx.com/conference/v1/calls/174' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body.

This request hangs up the call, targeted by ID.

Path Arguments

DIDs

DIDs are phone numbers rented through CarrierX.

DID Object

This section outlines the DID object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample DID object:

{
    "attributes": [],
    "countryCode": "US",
    "didGroupId": 219,
    "id": 220,
    "phoneNumber": "15162065319",
    "state": -1
}

Attribute Object

Get DIDs

The following GET request returns DIDs associated with the endpoint.

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

A successful request will return a 200 response code with a list of DID objects associated with the Conference endpoint.

{
    "dids": [
        {
            "attributes": [],
            "countryCode": "US",
            "didGroupId": 219,
            "id": 220,
            "phoneNumber": "15162065319",
            "state": -1
        },
        {
            "attributes": [],
            "countryCode": "US",
            "didGroupId": 219,
            "id": 221,
            "phoneNumber": "15162065318",
            "state": -1
        }
    ],
    "last": 1,
    "offset": 0,
    "total": 2
}

This request will return a list of DIDs associated with the specific endpoint.

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

Get DID by ID

The following GET request returns a DID, targeted by ID.

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

A successful request will return a 200 response code with a serialized copy of the DID object.

{
    "attributes": [],
    "countryCode": "US",
    "didGroupId": 219,
    "id": 220,
    "phoneNumber": "15162065319",
    "state": -1
}

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

This request is enabled for Field Filtering.

Path Arguments

DID Groups

A DID Group is a set of phone numbers rented through CarrierX and associated with a specific conference. The system will automatically assign phone numbers into a DID group when they are routed to a Conference endpoint.

DID Group Object

This section outlines the DID Group object. The attributes listed in the table below will be returned in a JSON object when a successful request has been made.

Sample DID Group object:

{
    "attributes": [],
    "callFlowId": 3,
    "description": "",
    "dids": [
        {
            "attributes": [],
            "countryCode": "US",
            "didGroupId": 219,
            "id": 221,
            "phoneNumber": "15162065319",
            "state": -1
        }
    ],
    "id": 219,
    "name": "sample_conference_008_didGroup",
    "state": -1,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

DID Object

Get DID Groups

The following GET request returns DID groups associated with the endpoint.

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

A successful request will return a 200 response code with a list of DID Group objects associated with the Conference endpoint.

{
    "didGroups": [
        {
            "attributes": [],
            "callFlowId": 3,
            "description": "",
            "dids": [
                {
                    "attributes": [],
                    "countryCode": "US",
                    "didGroupId": 219,
                    "id": 221,
                    "phoneNumber": "15162065319",
                    "state": -1
                },
                {
                    "attributes": [],
                    "countryCode": "US",
                    "didGroupId": 219,
                    "id": 220,
                    "phoneNumber": "15162065318",
                    "state": -1
                }
            ],
            "id": 219,
            "name": "sample_conference_008_didGroup",
            "state": -1,
            "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
        }
    ],
    "last": 0,
    "offset": 0,
    "total": 1
}

This request returns a list of DIDs associated with the specific conference.

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

Get DID Group by ID

The following GET request returns DID groups, targeted by ID.

curl -X GET \
'https://api.carrierx.com/conference/v1/didGroups/219' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the DID Group object.

{
    "attributes": [],
    "callFlowId": 3,
    "description": "",
    "dids": [
        {
            "attributes": [],
            "countryCode": "US",
            "didGroupId": 219,
            "id": 221,
            "phoneNumber": "15162065319",
            "state": -1
        },
        {
            "attributes": [],
            "countryCode": "US",
            "didGroupId": 219,
            "id": 220,
            "phoneNumber": "15162065318",
            "state": -1
        }
    ],
    "id": 219,
    "name": "sample_conference_008_didGroup",
    "state": -1,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

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

This request is enabled for Field Filtering.

Path Arguments

Meetings

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

Meeting Object

This section outlines the Meeting object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample Meeting object:

{
    "attributes": [],
    "created": 1544729701000,
    "duration": 48,
    "holdMode": 0,
    "id": 196938,
    "isRecording": false,
    "isSecured": false,
    "meetingNumber": 106131,
    "muteMode": 32,
    "participantCount": 1,
    "qaMode": 0,
    "state": 2,
    "subscriberName": "John Smith",
    "type": 1
}

Attribute Object

Refer to the Meeting Attributes section for a comprehensive list of the attributes. This section describes the structure of the attribute objects.

Get Meetings

The following GET request returns meetings matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of meetings associated with the Conference endpoint.

{
    "last": 0,
    "meetings": [
        {
            "attributes": [],
            "created": 1544729701000,
            "duration": 48,
            "holdMode": 0,
            "id": 196938,
            "isRecording": false,
            "isSecured": false,
            "meetingNumber": 106131,
            "muteMode": 32,
            "participantCount": 1,
            "qaMode": 0,
            "state": 2,
            "subscriberName": "John Smith",
            "type": 1
        }
    ],
    "offset": 0,
    "total": 1
}

This request returns a list of active meetings.

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

Get Meeting by meetingNumber

The following GET request returns a meeting, targeted by meetingNumber.

curl -X GET \
'https://api.carrierx.com/conference/v1/meetings/106131' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a meeting matching the meetingNumber.

{
    "attributes": [],
    "created": 1544742875000,
    "duration": 504,
    "holdMode": 0,
    "id": 196939,
    "isRecording": false,
    "isSecured": false,
    "meetingNumber": 106131,
    "muteMode": 32,
    "participantCount": 1,
    "qaMode": 0,
    "state": 2,
    "subscriberName": "John Smith",
    "type": 1
}

This request returns a Meeting object, targeted by the meetingNumber.

This request is enabled for Field Filtering.

Path Arguments

Get Meeting Attributes

The following GET request returns meeting attributes for a specific meeting, targeted by meetingNumber.

curl -X GET \
'https://api.carrierx.com/conference/v1/meetings/111/attributes?limit=5' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the Meeting object.

[
    {
        "name": "conference_exittones",
        "value": "on"
    },
    {
        "name": "conference_qa_policy",
        "value": "p"
    },
    {
        "name": "conf_participants_count",
        "value": "0"
    },
    {
        "name": "conf_hosts_count",
        "value": "1"
    },
    {
        "name": "conf_listeners_count",
        "value": "0"
    },
    {
        "name": "participant_list",
        "value": "5626245432:15162065310:'2756'"
    }
]

This request returns a list of call flow attributes associated with the specified meeting.

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

Path Arguments

Update Meeting

The following PUT request updates the Meeting object, targeted by meetingNumber, with the values in the request body.

curl -X PUT \
'https://api.carrierx.com/conference/v1/meetings/106131' \
-H 'Content-Type: application/json' \
--data-binary '{"pollingMode": {"status": 2}}' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the Meeting object.

{
    "attributes": [],
    "created": 1544742875000,
    "duration": 23,
    "holdMode": 0,
    "id": 196939,
    "isRecording": false,
    "isSecured": false,
    "meetingNumber": 106131,
    "muteMode": 32,
    "participantCount": 1,
    "qaMode": 0,
    "state": 2,
    "subscriberName": "John Smith",
    "type": 1
}

This request is used to change the state of a meeting.

A PUT request is used to update an entire Meeting object. The meetingNumber is passed in the query URL, and the entire Meeting object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• attributes
• holdMode
• isRecording
• isSecured
• muteMode

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

Delete Meeting

The following DELETE request deletes a meeting, targeted by meetingNumber.

curl -X DELETE \
'https://api.carrierx.com/conference/v1/meetings/106131' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body.

This request drops all calls from a meeting and deletes the meeting instance.

Path Arguments

Meeting Rooms

Meeting rooms hold meeting configurations, overridden call flow values, and contain role information. Access codes are also set at the Meeting Room object level. These are DTMF sequences entered by callers, and determine the role of the caller. The three roles are: host, participant, and listener. For example, a caller may enter an access code for a host role and gain the ability to mute participants and listeners.

Meeting Room Object

This section outlines the Meeting Room object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample Meeting Room object:

{
    "attributes": [],
    "created": 1544482680000,
    "didGroupReferences": [
        {
            "didGroupId": 219,
            "state": 0
        }
    ],
    "keychain": [],
    "meetingNumber": 273751,
    "primaryDidGroupId": 219,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

DID Group Reference Object

The didGroupReferences array contains the didGroupId and state. The didGroupId references the DID group containing the phone numbers that can be dialed to access a Meeting Room.

Meeting Key Object

The keychain array holds the meeting access codes. The three access levels are host, participant, and listener. Note that there can be multiple access codes for each access level.

Create Meeting Room

The following POST request creates a meeting room.

curl -X POST \
'https://api.carrierx.com/conference/v1/meetingRooms' \
-H 'Content-Type: application/json' \
--data-binary '{"primaryDidGroupId": 219, "callFlowId": 3}' \
-u '[your_user_name]:[your_password]'

A successful response will return a 200 status code and a serialized copy of the new Meeting Room object.

{
    "attributes": [],
    "created": 1544482680000,
    "didGroupReferences": [
        {
            "didGroupId": 219,
            "state": 0
        }
    ],
    "keychain": [],
    "meetingNumber": 273751,
    "primaryDidGroupId": 219,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

This request creates a meeting room using the data passed in the query body.

To create a meeting room, primaryDidGroupId and callFlowId are required. This information can be found by sending a GET request to the didGroups URL. Refer to the Get DID Groups section for more information. The response will contain an id, which will be passed in the body parameter as primaryDidGroupId. The returned callFlowId will also need to be passed in the body when creating a meeting room.

Body Arguments

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

Required fields to create a Meeting Room object are:

• callFlowId
• primaryDidGroupId

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

Get Meeting Rooms

The following GET request returns meeting rooms matching the criteria in the request URL.

curl -X GET \
'https://api.carrierx.com/conference/v1/meetingRooms?exclude_fields=attributes' \
-u '[your_user_name]:[your_password]'

A successful response will return a 200 status code and a list of meeting rooms.

{
    "last": 0,
    "meetingRooms": [
        {
            "created": 1544482680000,
            "didGroupReferences": [
                {
                    "didGroupId": 219,
                    "state": 0
                }
            ],
            "keychain": [],
            "meetingNumber": 273751,
            "primaryDidGroupId": 219,
            "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
        }
    ],
    "offset": 0,
    "total": 1
}

This request returns a list of meeting rooms.

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

Get Meeting Room by meetingNumber

The following GET request returns a meeting room, targeted by meetingNumber.

curl -X GET \
'https://api.carrierx.com/conference/v1/meetingRooms/273751?exclude_fields=attributes' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the Meeting Room object.

{
    "attributes": [],
    "created": 1544482680000,
    "didGroupReferences": [
        {
            "didGroupId": 219,
            "state": 0
        }
    ],
    "keychain": [],
    "meetingNumber": 273751,
    "primaryDidGroupId": 219,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

This request returns information about a meeting room.

This request is enabled for Field Filtering.

Path Arguments

Update Meeting Room

The following PATCH request updates the Meeting Room object, targeted by meetingNumber, with the values in the request body.

curl -X PATCH \
'https://api.carrierx.com/conference/v1/meetingRooms/273751' \
-H 'Content-Type: application/json' \
--data-binary '{"description":"Another description"}' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the updated Meeting Room object.

{
    "attributes": [],
    "created": 1544482680000,
    "description": "Another description",
    "didGroupReferences": [
        {
            "didGroupId": 219,
            "state": 0
        }
    ],
    "keychain": [],
    "meetingNumber": 273751,
    "primaryDidGroupId": 219,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

This request updates an existing meeting room, targeted by meetingNumber.

A PUT request is used to update an entire Meeting Room object. The meeting room meetingNumber is passed in the query URL, and the entire Meeting Room object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• attributes
• didGroupReferences
• keychain
• meetingNumber
• primaryDidGroupId

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

Delete Meeting Room

The following DELETE request deletes a meeting room, targeted by MeetingNumber.

curl -X DELETE \
'https://api.carrierx.com/conference/v1/meetingRooms/452650' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body.

This request deletes a meeting room, targeted by meetingNumber.

Path Arguments

Meeting Attributes

The following PATCH request is an example of how to update a meeting attribute for a meeting room. Note that you can also add attributes on the DID Group object and DID object.

curl -X PATCH \
'https://api.carrierx.com/conference/v1/meetingRooms/452650' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":[{"name":"call_maxduration","value":120}]}' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the updated Meeting Room object.

{
    "attributes": [
        {
            "description": "Maximal calls duration (s)",
            "group": 0,
            "name": "call_maxduration",
            "value": "120"
        }
    ],
    "created": 1568822760000,
    "description": "another_meeting_room",
    "didGroupReferences": [
        {
            "didGroupId": 2325,
            "state": 0
        }
    ],
    "keychain": [
        {
            "accessCode": "666",
            "id": 5302,
            "role": 3
        },
        {
            "accessCode": "444",
            "id": 5300,
            "role": 1
        },
        {
            "accessCode": "555",
            "id": 5301,
            "role": 2
        }
    ],
    "meetingNumber": 508005,
    "primaryDidGroupId": 4425,
    "subscriberSid": "cxDD96hPO-bGt6TvLlluid23UQs01Djz"
}

The following are meeting attributes that can be applied on the Meeting Room, DID Group, or DID object levels. For each of these levels, the meeting attributes will be passed as a value of attributes as an array of objects.

This will look like the following format: "attributes":[{"name":"call_maxduration","value":120}].

Some fields accept a string containing the first letter of the access level name. The three access levels are host, participant, or listener. To enable a feature for all three access levels, enter the string hpl. Alternatively, to enable the feature for one access level, enter the first letter of the word. For example, participant is p.

Attributes List

conference_language