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.

Run in Postman

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

Main Conventions

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

create The attribute can be set when the user creates the object using the POST method.
update The attribute can be modified when the user updates the object using either PATCH or PUT methods.
read only The attribute is set by the system and the user can neither set nor modify it.
admin The attribute can be set or modified using the administrator API only. In case the attribute is read only, it is visible to the partners with access to the administrator API, and hidden from other partners.
preview The attribute is part of the feature that is still in development and is not recommended to use in production.

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

Parameter Data Type Description
limit integer The number of items to be shown in the response. The value entered should not exceed 1000. 10 is the default value. This parameter and value are added to the query URL.
offset integer The amount of items skipped in the response. 0 is the default value. This parameter and value are added to the query URL.
order string The name of the field to be ordered followed by the order of the response data, either asc or desc. The field to be ordered is listed first, followed by the order value. For example: binding_sid desc. asc is the default order. This parameter and values are added to the query URL.

Result Filtering

This GET request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing results to 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

Operator Definition Example
eq equal to. This search looks for the exact value entered. In the example, results will have the exact "my_mediator" value for the name field. name eq "my_mediator"
ge greater than or equal to. This search returns records where the value is greater than or equal to the field listed. For example, records are returned where the value of wait_origination_did_ttl is greater than or equal to 70000. wait_origination_did_ttl ge 70000
gt greater than. This search returns records where the value is exceeded for the field listed. For example, records are returned where the value of maximum_ttl is greater than 40000. maximum_ttl gt 40000
ilike same functionality as like but case insensitive. name like "AccOUnt%"
in the current value of the specified field must be contained within the specified list. The following example will return records that have a status value of either "active" or "suspended". status in ("active", "suspended")
le less than or equal to. This search returns records where the value is less than or equal to the field listed. For example, records are returned where wait_origination_did_ttl is less than or equal to 90000. wait_origination_did_ttl le 90000
like contains the value indicated in the string passed. % can be added anywhere as part of the string to indicate that there can exist text before or after the string parts. In the example, the command looks for a name starting with “Account”. This form of search is case sensitive. Note that this method of search will also work: name like "A%t", and this search will yield records with name values beginning with A and ending in t. name like "Account%"
lt less than. This search returns records where the value is less than the field listed. For example, records are returned where maximum_ttl is less than 10000. maximum_ttl lt 10000
ne not equal to. This search returns records that do not include the "my_mediator" value for the name field. name ne "my_mediator"
notin not in. The current value of the specified field must not be in the specified list. The following example will return records that do not have a status value of "active". status notin ("active")

Field Filtering

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

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

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

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

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

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

Field Filtering Quick Reference

Parameter Data Type Description
exclude_fields string The comma separated list of fields to be excluded from the response. The fields depend on the object. See the Object section for that object to see which fields return.
include_fields string The comma separated list of fields to be included in the response. The fields depend on the object. See the Object section for that object to see which fields return.

HTTP Errors

The Conference API uses the following HTTP error codes:

Error Code Message Description
400 Bad Request The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
400 No JSON object could be decoded Generally an indicator that there is a syntax error.
401 Bad credentials The request requires correct user authentication.
401 Unauthorized The request requires user authentication.
403 Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
404 Cannot find item by SID The SID number does not exist. Verify that the SID has been entered correctly. Note that calls can expire.
404 Not Found The requested resource was not found on the server.
409 Cannot find redirect_did The redirect_did could not be found. Verify that there are available DIDs that can be assigned as redirect_did automatically or assign it manually using the Mediator API Create Binding method.
415 Unsupported media type Ensure that the header includes support for the content type JSON.
500 Internal server error The server encountered an unexpected condition which prevented it from fulfilling the request.

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.

You can choose between two call flows when creating a meeting room: CONF and SPECTEL.

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:

{
    "attributeTemplates": [
        {
            "description": "Announce participant count on enter",
            "enumValues": "",
            "group": 5,
            "name": "call_announceparticipantcount",
            "type": 4,
            "value": "hpl"
        }
    ],
    "id": 3,
    "name": "CONF",
    "path": "/usr/local/DNCA/callflows/CONF"
}
Attribute Data Type Description
attributeTemplates read only array The attributes belonging to the call flow. Refer to the table below for a comprehensive list of the format of attributes. For a list of the attributes themselves, refer to the Meeting Attributes section.
id read only integer The call flow ID. Note that this ID may differ for each user.
name read only string The call flow name.
path read only string This field is for internal use only.

Attribute Object

This object is used in attributeTemplates.

Attribute Data Type Description
description read only string The description of the attribute.
enumValues read only string If the type value is 5, this attribute will be automatically populated with possible values.
group read only integer Defines the levels at which the call flow attribute value can be overridden. Integer values denote that the call flow attribute can be overridden at the following object levels:
  • 1 (0 bit) for Call Flow and DID Group
  • 2 (1 bit) for DID
  • 4 (2 bit) for Meeting Room
The combinations of the values can also be used:
  • 3 (1 + 2) for Call Flow, DID Group, and DID
  • 5 (1 + 4) for Call Flow, DID Group, and Meeting Room
  • 6 (2 + 4) for DID and Meeting Room
  • 7 (1 + 2 + 4) for Call Flow, DID Group, DID, and Meeting Room
name read only string The attribute name.
type read only integer The attribute type. Values accepted in this field are:
  • 0 for TYPE_STRING
  • 2 for TYPE_INT
  • 3 for TYPE_DTMF
  • 4 for TYPE_ROLE
  • 5 for TYPE_CHOICE
  • 6 for TYPE_DB_REFERENCE
  • 7 for TYPE_UPLOAD
  • * for any
value read only string The attribute value.

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.

GET /callFlows

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.

GET /callFlows/{id}

This request is enabled for Field Filtering.

Path Arguments

Parameter Data Type Description
id required integer The call flow ID.

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

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",
    "addressTo": "\"15162065318\" <sip:15162065318@10.2.114.15>",
    "bridgeName": "MIA-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
}
Attribute Data Type Description
accessCode update string The access code entered by the caller.
addressFrom update string The phone number and SIP data of the calling party.
addressTo update string The phone number and SIP data of the called party.
bridgeName read only string The hosted bridge name.
callee update string The DID being dialed.
caller update string The phone number of the calling party.
codec update string The audio codec of the call.
connectionStatus update integer This field indicates the call direction. Values accepted in this field are as follows:
  • 0 for inbound call
  • 1 for outbound call
created read only string The date and time when the call was created.
customName update string A friendly name for the call.
duration read only integer The duration in seconds of the call.
gainLevel update integer The gain of the transmission circuit.
holdMode update integer Whether meeting participants and listeners are on hold. Values accepted in this field are either 0 or 40. 0 means that no parties are on hold. 40 means that participants and listeners have been placed on hold by the meeting host. When callers are on hold, they will hear music while the hosts have a private discussion.
id read only integer The call ID.
joined read only integer The date and time when the call was joined.
meetingNumber read only integer The meeting number of the meeting associated with the call.
muteMode update integer There are three mute states. The following values reflect which access level parties have been muted:
  • 32 for listeners have been muted
  • 36 for listeners have muted themselves and participants have muted themselves
  • 40 for participants and listeners have been muted
nodeName update string The name of the hosted node, or communication endpoint.
presenterMedia update integer The media for the call. Values accepted in this field are:
  • 1 for audio
  • 2 for screensharing
  • 4 for video
  • 8 for controlling
Note that you can add the integer values together. For example, for audio and video, 1 + 4 = 5.
qaMode read only integer The state of a Q&A meeting. Values accepted in this field are:
  • 0 for meeting has not started yet
  • 1 for active meeting
  • 2 for talking to the next participant in the queue
  • 4 for clearing the queue
role update integer The role associated with the access code. Values accepted in this field are:
  • 1 for host
  • 2 for participant
  • 3 for listener
state update integer The current call state. Values accepted in this field are:
  • 1 for call that is owned by the frontend
  • 2 for call that is owned by the backend
  • 3 for call that is closed
  • 4 for call that is being dialed

Get Calls

The following GET request returns calls which are currently active.

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.

{
    "calls": [
        {
            "accessCode": "111",
            "addressFrom": "+15162065319",
            "addressTo": "\"15162065318\" <sip:15162065318@10.2.114.15>",
            "bridgeName": "MIA-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.

GET /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",
    "addressTo": "\"15162065318\" <sip:15162065318@10.2.114.15>",
    "bridgeName": "MIA-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.

GET /calls/{id}

Path Arguments

Parameter Data Type Description
id required integer The ID of the call.

Update Call

The following PUT request updates a call.

curl -X PUT \
'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",
            "addressTo": "\"15162065318\" <sip:15162065318@10.2.114.15>",
            "bridgeName": "MIA-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.

PUT /calls/{id}

A Call object can be updated using a PUT request. The call 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
id required integer The call 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.

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.

DELETE /calls/{id}

Path Arguments

Parameter Data Type Description
id required integer The ID of the call to be deleted.

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 Data Type Description
attributes read only array Additional attributes that can be set to modify a DID. Refer to the table below for a list of preset attributes.
countryCode read only string The region of the DID. The format for this field is ISO 3166-1 alpha 2.
description read only string The code of the country in ISO 3166-1 alpha-2 format.
didGroupId read only string The ID of the DID group to which the DID belongs.
id read only string The unique ID of a specific DID.
phoneNumber read only string The phone number in E.164 format.

Attribute Object

Attribute Data Type Description
description read only string The attribute description.
enumValues read only string The possible attribute values if the attribute type is 5.
name read only string The attribute name.
type read only integer The attribute type. Values accepted in this field are:
  • 0 for string (this is the default)
  • 2 for integer
  • 3 for DTMF
  • 4 for role
  • 5 for choice
  • 6 for db reference
  • 7 for upload
value read only string The value of the DID attribute. Values accepted in this field are:
  • 0 for string (this is the default)
  • 2 for integer
  • 3 for DTMF
  • 4 for role
  • 5 for choice
  • 6 for db reference
  • 7 for upload

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.

GET /dids

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.

GET /dids/{id}

This request is enabled for Field Filtering.

Path Arguments

Field Data Type Description
id required integer The ID of the specific DID.

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"
}
Attribute Data Type Description
attributes read only array Refer to the Meeting Attributes section for a comprehensive list of attributes.
callFlowId read only string The ID of the call flow.
description read only string The description of the DID group.
dids read only array An array of the DIDs belonging to the DID group. Each object in the array contains attributes, countryCode, didGroupId, id, phoneNumber, and state. Refer to the table below for a description of these attributes.
id read only string The ID of the DID group.
name read only string The name of the DID group.
state read only integer The state of the DID group.
subscriberSid read only string The secure ID of the subscriber associated with the DID group.

DID Object

Attribute Data Type Description
attributes read only array The DID attributes.
countryCode read only integer The country code of the DID.
didGroupId read only integer The DID Group ID.
id read only integer The DID ID.
phoneNumber read only string The phone number.
state read only string The state of the DID.

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.

GET /didGroups

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.

GET /didGroups/{id}

This request is enabled for Field Filtering.

Path Arguments

Parameter Data Type Description
id required integer The ID of the DID group.

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 Data Type Description
attributes update array The meeting attributes. These attributes define the call flow of the meeting. They can be overridden in the DID and Meeting Room objects. Refer to the attributes table below for a description of the object structure. Additionally, refer to the Meeting Attributes section for a comprehensive list of the attributes.
created read only string The date and time when the meeting was created.
duration read only integer The number of seconds that have elapsed since the meeting was created.
holdMode update integer Whether meeting participants and listeners are on hold. Values accepted in this field are either 0 or 40. 0 means that no parties are on hold. 40 means that participants and listeners have been placed on hold by the meeting host. When callers are on hold, they will hear music while the hosts have a private discussion. Note that this value does not change. It is reflective of the initial hold state when the meeting starts.
id read only integer The meeting ID. Note that when using GET, PUT, and DELETE requests, the meetingNumber should be used instead of this value.
isRecording update boolean Determines whether or not recording is currently on.
isSecured update boolean Determines whether or not the meeting is secured.
meetingNumber read only integer The meeting number. Note that this is the value used to target a specific meeting in GET, PUT, and DELETE requests.
muteMode update integer There are three mute states. The following values reflect which access level parties have been muted:
  • 32 for listeners have been muted
  • 36 for listeners have muted themselves and participants have muted themselves
  • 40 for participants and listeners have been muted
Note that this value does not change in the Meeting object. It is reflective of the initial mute state when the meeting is started.
participantCount read only integer The number of participants in the meeting.
qaMode read only integer The state of a Q&A meeting. Values accepted in this field are:
  • 0 for meeting has not started yet
  • 1 for active meeting
  • 2 for talking to the next participant in the queue
  • 4 for clearing the queue
state read only integer The state of the meeting. Values accepted in this field are:
  • 0 for completed meeting, or meeting that has not started yet
  • 1 for on hold meeting
  • 2 for active meeting
subscriberName read only string The name of the first subscriber in the meeting.
type read only integer Defines whether or not the meeting is participating in distributed meetings. If yes, the field value will be 1 and if no, the field value will be 0.

Attribute Object

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

Attribute Data Type Description
description update string The attribute description.
enumValues update string The possible attribute values if the type is 5.
group update integer Defines the owner of the attribute. Values accepted in this field are:
  • 0 for call flow
  • 1 for DID
  • 2 for meeting room
type update integer The attribute type. Values accepted in this field are:
  • 0 for string (default)
  • 2 for integer
  • 3 for DTMF
  • 4 for role
  • 5 for choice
  • 6 for db reference
  • 7 for upload
value update string The value of the attribute.

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.

GET /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.

GET /meetings/{meetingNumber}

This request is enabled for Field Filtering.

Path Arguments

Parameter Data Type Description
meetingNumber required integer The meeting number.

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.

GET /meetings/{meetingNumber}/attributes

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

Path Arguments

Parameter Data Type Description
meetingNumber required integer The meeting number.

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.

PUT /meetings/{meetingNumber}

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

Parameter Data Type Description
meetingNumber required integer The meeting number.

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

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.

DELETE /meetings/{meetingNumber}

Path Arguments

Parameter Data Type Description
meetingNumber required integer The meeting number.

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, 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,
    "description": "Test Meeting",
    "didGroupReferences": [
        {
            "didGroupId": 219,
            "state": 0
        }
    ],
    "keychain": [
        {
            "accessCode": "463516",
            "id": 3464,
            "role": 3
        }
    ],
    "meetingNumber": 273751,
    "primaryDidGroupId": 219,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}
Attribute Data Type Description
attributes create update array Preset attributes that can be modified. Please refer to the Meeting Attributes section for a comprehensive list of attributes.
created read only integer The UNIX time stamp of the metting room creation time.
description create update string The meeting room description.
didGroupReferences create update array Data about the DID Group associated with the meeting room. This information includes the didGroupId and state. Refer to the table below for more information.
keychain create update array Contains the access codes and matching roles. Please refer to the table below for more information. The keychain array can be modified through a PUT request. When creating a PUT request, include accessCode and role.
meetingNumber create update integer The meeting number. This number is used in GET, PUT, and DELETE requests.
primaryDidGroupId create update integer The DID group associated with the meeting.
subscriberSid read only string The secure ID of the subscriber.

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.

Attribute Data Type Description
didGroupId create update integer The DID group ID.
state create update integer The state of the DID group. Values accepted in this field are:
  • 0 for active (default)
  • 1 for invalidated
  • 2 for disabled

Meeting Key Object

The keychain array holds the meeting access codes. The three access levels are host, participant, and listener.

Attribute Data Type Description
accessCode create update string The DTMF sequence that callers enter to access a meeting. This sequence is customizable.
id create update integer The ID of the access code and role association.
role create update integer The role associated with the access code. Values accepted in this field are:
  • 1 for host
  • 2 for participant
  • 3 for listener

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}' \
-u '[your_user_name]:[your_password]'

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

{
    "attributes": [],
    "created": 1544482680000,
    "description": "Test Meeting",
    "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.

/meetingRooms

To create a meeting room, a primaryDidGroupId value is 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.

Body Arguments

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

A required field to create a Meeting Room object is 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,
            "description": "Test Meeting",
            "didGroupReferences": [
                {
                    "didGroupId": 219,
                    "state": 0
                }
            ],
            "keychain": [
                {
                    "accessCode": "463516",
                    "id": 3464,
                    "role": 1
                }
            ],
            "meetingNumber": 273751,
            "primaryDidGroupId": 219,
            "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
        }
    ],
    "offset": 0,
    "total": 1
}

This request returns a list of meeting rooms.

GET /meetingRooms

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.

{
    "created": 1544482680000,
    "description": "Test Meeting",
    "didGroupReferences": [
        {
            "didGroupId": 219,
            "state": 0
        }
    ],
    "keychain": [
       {
            "accessCode": "463516",
            "id": 3464,
            "role": 1
        }
    ],
    "meetingNumber": 273751,
    "primaryDidGroupId": 219,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

This request returns information about a meeting room, targeted by MeetingNumber.

GET /meetingRooms/{meetingNumber}

This request is enabled for Field Filtering.

Path Arguments

Parameter Data Type Description
meetingNumber required integer The meeting room number.

Update Meeting Room

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

curl -X PUT \
'https://api.carrierx.com/conference/v1/meetingRooms/273751' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes": [], "created": 1544482680000, "description": "Another description", "description": "Test Meeting", "didGroupReferences": [{"didGroupId": 219, "state": 0}], keychain": [{"accessCode": "463516","id": 3464,"role": 1}], "meetingNumber": 273751, "primaryDidGroupId": 219, "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"}' \
-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": [
        {
            "accessCode": "463516",
            "id": 3464,
            "role": 1
        }
    ],
    "meetingNumber": 273751,
    "primaryDidGroupId": 219,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

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

PUT /meetingRooms/{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

Parameter Data Type Description
meetingNumber required integer The meeting room number.

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

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.

DELETE /meetingRooms/{meetingNumber}

Path Arguments

Parameter Data Type Description
meetingNumber required integer The meeting room number.

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

Attribute Data Type Description Where to Set
call_announceparticipantcount string Determines for which access levels the number of participants will be announced upon entering the meeting room. Enter the access levels as a string. Meeting Room object, DID Group object
call_associate_dtmf string Determines which access levels will be able to associate calls. Meeting Room object, DID Group object
call_associate_dtmf_binding string The DTMF sequence to associate audio. DID Group object
call_delay integer The number of seconds to delay before the call is answered. DID Group object, DID object
call_exit_dtmf string Determines which access levels will be able to enter the DTMF sequence to leave a call. The DTMF sequence is set as call_exit_dtmf_binding. Meeting Room object, DID Group object
call_exit_dtmf_binding string Determines the DTMF sequence that will trigger exiting a call when call_exit_dtmf is enabled. DID Group object
call_instructions_dtmf string Determines which access levels will be able to enter the DTMF sequence to access the help playback. Enter the access levels as a string for the field value. The DTMF sequence is set as call_instructions_dtmf_binding. Meeting Room object, DID Group object
call_instructions_dtmf_binding string The DTMF sequence that will trigger the help playback for the access levels designated in call_instructions_dtmf. DID Group object
call_jobcodeonenter string Determines whether or not the caller will be prompted for a job code prior to entering the meeting. Values accepted in this field are on and off. Meeting Room object, DID Group object
call_maxduration integer The maximum duration of the call. Meeting Room object, DID Group object
call_mute_dtmf string Determines which access levels can mute themselves. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
call_mute_dtmf_binding string The DTMF sequence that triggers self muting. DID Group object
call_operator_after integer Determines how many times an unsuccessful attempt can be made to enter the access code. Enter -1 to allow unlimited amounts of unsuccessful attempts. DID Group object
call_operator_dtmf string Determines which access levels can call the operator. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
call_operator_dtmf_binding string The DTMF sequence that triggers a call to the operator. DID Group object
call_participantsnumber_dtmf string Determines which access levels can enter the DTMF sequence to hear the number of participants currently in the conference. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
call_participantsnumber_dtmf_binding string The DTMF sequence that triggers stating the number of participants in the conference. DID Group object
conference_appspecific string Application-specific data. Meeting Room object, DID Group object
conference_callerdb string The callers database. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_country string The conference country. Meeting Room object, DID Group object
conference_distributed string Determines whether or not distributed conferencing is enabled. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_entryexittones_dtmf string Determines which access levels can change the entry and exit tone by entering a DMTF sequence. Entering the DTMF sequence will alternate through the following combinations: ON:ON, ON:OFF, OFF:ON, and OFF:OFF. Meeting Room object, DID Group object
conference_entryexittones_dtmf_binding string The DTMF sequence that triggers the change between the tone combinations outlined in conference_entryexittones_dtmf. DID Group object
conference_entrytones string Determines whether or not a noise will be played when a new participant joins the conference. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_exittones string Determines whether or not a noise will be played when a new participant exits the conference. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_hold_dtmf string Determines which access levels will be able to put a conference on hold. Meeting Room object, DID Group object
conference_hold_dtmf_binding string The DTMF sequence that will trigger putting a conference on hold. DID Group object
conference_hold_policy string Determines which access levels will be on hold at the beginning of the conference. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_jobcode_dtmf string Allows participants to enter the * key during a conference followed by a job code. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_jobcode_dtmf_binding string The DTMF sequence to trigger entering a job code. DID Group object
conference_language string Determines the language of the meeting. The default value is EN. Refer to the table below for all of the currently supported languages. Meeting Room object, DID Group object
conference_lock_dtmf string Determines which access levels can lock a conference, meaning that no more participants can join. Note that hosts are still able to join even if lock is enabled. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_lock_dtmf_binding string The DTMF sequence that triggers locking a conference. DID Group object
conference_maxcalls integer The maximum number of calls per conference. Meeting Room object, DID Group object
conference_maxcallsperrole string The maximum number of calls per role per conference. The following denotes that there can be an unlimited amount of calls from each role: -1:-1:-1. Meeting Room object, DID Group object
conference_maxduration integer The maximum duration of the conference. To enable the conference to endure indefinitely, assign the value -1. Meeting Room object, DID Group object
conference_mute_dtmf string Determines which access levels are able to mute other participants. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_mute_dtmf_binding string The DTMF sequence to trigger muting other participants. DID Group object
conference_mute_policy string Defines which roles will be muted at the beginning of the conference. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_qa_dtmf string Determines which access levels can start a Q&A session. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_qa_dtmf_binding string The DTMF sequence to trigger starting a Q&A session. DID Group object
conference_qa_policy string Determines which access levels will be muted when a Q&A session is started. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_realtime string Defines whether or not the conference generates real time notifications, which allows viewing attendee lists and controlling the conference from a computer. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_recording string Defines whether or not a recording will begin once the meeting starts. Values accepted in this field are on, off, and auto. auto means that the recording will begin as soon as the conference begins. Meeting Room object, DID Group object
conference_rollcall string Determines whether or not participants will be prompted to record their names upon entering the conference. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_rollcall_onenter string Determines whether or not the recordings of participants saying their names will be played upon entering the conference. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_rollcall_onexit string Determines whether or not recordings of the participants saying their names will be played upon exiting the conference. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_schedule string The conference schedule. Meeting Room object, DID Group object
conference_schedule_extend string The conference schedule extended maximum time in seconds. DID Group object
conference_schedule_extend_dtmf string Defines the access levels that will be able to extend a conference schedule. Meeting Room object, DID Group object
conference_schedule_extend_dtmf_binding string The DMTF sequence that will trigger extending the conference schedule. DID Group object
conference_schedule_hold integer The amount of time in seconds to wait before the scheduled conference begins. Meeting Room object, DID Group object
conference_schedule_remind integer The amount of time in seconds to wait before the scheduled conference reminder. Meeting Room object, DID Group object
conference_scheduled string Defines whether or not a conference is scheduled. Values accepted in this field are on and off. Meeting Room object, DID Group object
conference_start_how string Determines when the conference will begin. Values accepted in this field are first, moderator, and explicit. Meeting Room object, DID Group object
conference_start_wait integer The number of seconds to wait before starting a meeting when a moderator has not entered the meeting. Meeting Room object, DID Group object
conference_stop_how string Determines whether the meeting will end when the moderator exits, or when the last participant exits. Values accepted in this field are last and moderator. Meeting Room object, DID Group object
conference_stop_wait integer The number of seconds to wait before stopping the conference after the host disconnects. Meeting Room object, DID Group object
conference_video_policy string Determines which access levels will have video enabled at the beginning of a conference. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
conference_whitelist string Defines whether or not the conference has a white list. Values accepted in this field are on and off. Meeting Room object, DID Group object
dnis_welcomeprompt string The URL to a recorded greeting. DID Group object, DID object
polling_dtmf string Determines which access levels can start a polling vote. Meeting Room object, DID Group object
polling_dtmf_binding string The DTMF sequence to trigger starting a polling vote. DID Group object
recording_addr string The recording server address. DID Group object
recording_dtmf string Determines which access levels are able to start a recording. Enter the access levels as a string for the field value. Meeting Room object, DID Group object
recording_dtmf_binding string Defines the DTMF sequence that triggers starting a recording of the meeting. DID Group object
recording_metadata string Defines the recording metadata passing method. Values accepted in this field are contact and custom. DID Group object
recording_method string Determines the recording method. Values accepted in this field are: remote, remote+pin, local, and local+pin. DID Group object
recording_stop_how string Determines the recording method. Values accepted in this field are: last and moderator. Meeting Room object, DID Group object
recording_stop_wait integer Defines the amount of seconds to wait before stopping recording after the moderator has left the conference. Meeting Room object, DID Group object

conference_language

Code Language
EN English (default)
AR Argentinian
DE German
EL Greek
ES Spanish (Spain)
ES-LATAM Spanish (Latin America)
FR French
GB British English
HE Vietnamese
IT Italy
JA Japanese
KO Korean
NL Dutch
PT Portuguese (Portugal)
PT-BR Portuguese (Brazil)
RU Russian
TR Turkish
UA Ukrainian
UK Ukrainian (Ukraine)
ZH Chinese