Conference API Reference

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

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.

Main Conventions

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

Authentication

The following curl command will return a list of all of the endpoints of the CarrierX account associated with the login credentials. Use your Core API token in the query below. The endpoint login and password values are listed in the returned JSON object.

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

The credentials of a specific endpoint are found in the properties attribute of the nested object. Locate the login and password values.

{
  "count": 1,
  "has_more": false,
  "items": [
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flexml",
          "out_sip_password": null,
          "out_sip_username": null,
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
              "api_url": "https://api.carrierx.com/flexml/v1",
              "container_sid": "null",
              "login": "sample_login",
              "password": "sample_password"
          },
          "transformations": [],
          "type": "flexml",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 1
}

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

Currently, CarrierX API requests use two types of authentication:

• Bearer token, used by the requests to the Core API.
• Basic HTTP authentication with login and password, used by the requests to the endpoint APIs (Conference, FlexML, and Mediator).

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

Requests

Sample request to create Conference endpoint

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

The requests in CarrierX API are made using the standard REST notation, typical for web services.

A simplest request will have the following structure:

• The request URL to which the request will be sent. The URL will be different for the Core API methods and for the main endpoint-related requests (conference, FlexML, mediator).
• The request method or the verb used for the REST over HTTP request.
• One or several headers or user/password authentication.
  • At least one header—-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'—is required to access the Core API.
  • For the requests to the conference, FlexML, or mediator endpoints, CarrierX uses the basic HTTP authentication with login and password (cURL -u option).

  Refer to the Authentication section for more details on this.

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

Other request may have additional structure elements which include:

• Path arguments are required with some methods to access specific objects (GET the object by secure ID, PATCH/PUT, and DELETE objects).
• Body payload is required with POST and PATCH/PUT. Even if the object method does not require any body arguments (e.g., POST for some objects), the payload must still include an empty object (--data-binary '{}').
  
• Query arguments may be either optional or required for some requests. Refer to the objects sections below to see which object methods require the presence of the query arguments. The optional query arguments available with some GET requests include pagination, result filtering, and field filtering.
• Form data is required with some POST methods, e.g., uploading a file to the container using multipart/form-data content type.

Request URL

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

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

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

Request Methods

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

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

POST

Sample POST request that creates a trunk

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

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

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

GET

Sample GET request that returns the currently logged-in partner

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

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

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

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

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

PATCH/PUT

Sample PATCH request that modifies or adds a new name record of the nested attributes object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name":"New Partner Name"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the nested object

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

Sample PATCH request that adds a new name2 record of the nested attributes object of the same Partner object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name2":"New Partner Name 2"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the modified nested object

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

Sample PATCH request that modifies the entire nested attributes object of the same Partner object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b?nested_objects=replace' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name3":"New Partner Name 3"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the nested object

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

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

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

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

1. If the existing nested object contains the same record (by key), the existing record will be replaced with the new value, provided in the PATCH request. The other nested object records will remain unmodified.

2. If the existing nested object does not contain the same record, a new record will be added to the object. The other nested object records will remain unmodified.

3. If the existing nested object contains the same record and the value of the incoming record is null, then the existing record will be removed. The other nested object records will remain unmodified.

4. If the PATCH request contains nested_objects=replace as a query attribute, the whole nested object will be replaced with a new one (i.e., all the old records and their values will be removed and only the new ones will be added).

PUT is used to modify the complete object and require to send the entire object (together with the nested objects, if there are any) in the request payload.

Both PATCH and PUT requests are aimed at a specific object and require the object secure ID as a part of the request path.

The successful PATCH/PUT request will return a 200 response with the serialized JSON copy of the modified object.

DELETE

Sample DELETE request that deletes an endpoint

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

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

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

Rate Limiting

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

Responses

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

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

HTTP Status Codes

Typical 200 status code in the response

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

The Conference API uses the following HTTP status codes:

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

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

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

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

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

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

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

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find token",
            "reference_sid": null
        }
    ]
}

The above status codes are common for all requests.

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

Response Objects

Typical formatted JSON object in the response

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

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

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

With jq, the request will look like this:

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

Pagination

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

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

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

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

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

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

The pagination parameters include:

limit

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

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

order

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

• attribute name + asc to sort the items in the response in the ascending or alphabetical order (default order).
• attribute name + desc to sort the items in the response in the descending or reverse-alphabetical order.
• shuffle to randomize the order of the items in the response.

offset

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

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

after/ before

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

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

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

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

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

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

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

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

• limit, offset, order: https://api.carrierx.com/core/v2/countries?limit=2&offset=2&order=common_name+desc

• after, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?after=bb2aacd2-23d3-418e-9ec0-2fc45c5f9d76&limit=1&order=date_stop+asc

• before, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?before=56fb6b94-811e-4952-b242-4e06f4e95b7e&limit=1&order=date_stop+desc

• after, before, limit, order: https://api.carrierx.com/core/v2/sms/message_drs?after=012e1d6a-75ac-43ec-bacc-68f1ef1c60a3&before=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=100&order=date_insert+desc

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

Pagination Response

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

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/core/v2/endpoints?exclude_fields=properties' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

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

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

Refer to the specific object to determine which fields can be included and excluded from the JSON responses.

include_fields and exclude_fields accept comma-separated strings as values.

Field Filtering Quick Reference

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.

• 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

{
    "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 Object

This object is used in attributeTemplates.

Get Call Flows

GET /callFlows
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]'

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

GET /callFlows/{id}
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]'

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

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
}

Get Calls

GET /calls
Returns calls which are currently active

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

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

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

Get Call by ID

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

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

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

Path Arguments

Update Call

PUT /calls/{id}
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]'

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

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

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
• presenterMedia
• role
• state

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

Delete Call

DELETE /calls/{id}
Hangs up the call, targeted by ID

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

Response 204 status 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",
    "description": "A test DID",
    "didGroupId": 219,
    "id": 220,
    "phoneNumber": "15162065319",
    "state": -1
}

Attribute Object

Create DID

POST /dids
Creates a DID

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

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

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

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

Body Arguments

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

Required fields to create a DID are:

• didGroupId
• phoneNumber

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

Get DIDs

GET /dids
Returns DIDs associated with the endpoint

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

Response 200 status 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",
            "description": "A test DID",
            "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

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

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

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

Update DID

PUT /dids/{id}
Updates the DID object, targeted by its ID, with the values in the request body

curl -X PUT \
'https://api.carrierx.com/conference/v1/dids/220' \
-H 'Content-Type: application/json' \
--data-binary '{"description":"DID new description"}' \
-u '[your_user_name]:[your_password]'

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

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

This request updates a DID, targeted by its ID.

A PUT request is used to update one or more attribute values. When using a PUT request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The DID ID is passed in the query URL, and the values to be modified are 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
• description
• didGroupId
• phoneNumber

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

Delete DID

DELETE /dids/{id}
Deletes a DID, targeted by its ID

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

Response 204 status code with an empty body

This request deletes a DID, targeted by its ID.

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

Attribute Object

Create DID Group

POST /didGroups
Creates a DID group

curl -X POST \
'https://api.carrierx.com/conference/v1/didGroups' \
-H 'Content-Type: application/json' \
--data-binary '{"callFlowId":"1", "name":"Test DID group"}' \
-u '[your_user_name]:[your_password]'

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

{
    "attributes": [],
    "callFlowId": 1,
    "description": "",
    "id": 219,
    "name": "Test DID group",
    "state": -1,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

This request creates a DID group using the data passed in the query body.

Body Arguments

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

Required fields to create a DID group are:

• callFlowId
• name

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

Get DID Groups

GET /didGroups
Returns DID groups associated with the endpoint

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

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

GET /didGroups/{id}
Returns a DID group, targeted by ID

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

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

Update DID Group

PUT /didGroups/{id}
Updates the DID Group object, targeted by its ID, with the values in the request body

curl -X PUT \
'https://api.carrierx.com/conference/v1/didGroups/219' \
-H 'Content-Type: application/json' \
--data-binary '{"description":"Updated DID group description"}' \
-u '[your_user_name]:[your_password]'

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

{
    "attributes": [],
    "callFlowId": 1,
    "description": "Updated DID group description",
    "id": 219,
    "name": "Test DID group",
    "state": -1,
    "subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}

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

A PUT request is used to update one or more attribute values. When using a PUT request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The DID group ID is passed in the query URL, and the values to be modified are 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
• callFlowId
• description
• name

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

Delete DID Group

DELETE /didGroups/{id}
Deletes a DID group, targeted by its ID

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

Response 204 status code with an empty body

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

Path Arguments

Meetings

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

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

GET /meetings
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]'

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

GET /meetings/{meetingNumber}
Returns a meeting, targeted by meetingNumber

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

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

GET /meetings/{meetingNumber}/attributes
Returns meeting attributes for a specific meeting, targeted by meetingNumber

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

Response 200 status code with a serialized copy of the Meeting object attributes

[
    {
        "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 Attributes

PUT /meetings/{meetingNumber}/attributes/{name}
Updates the attributes of the Meeting object, targeted by meetingNumber, with the values in the request body

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

Response 200 status code with a serialized copy of the Meeting object attributes

[
    {
        "name": "conference_exittones",
        "value": "off"
    }
]

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

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

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

The only field that can be modified is value.

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

Delete Meeting

DELETE /meetings/{meetingNumber}
Deletes a meeting, targeted by meetingNumber

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

Response 204 status 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, 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"
}

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.

Create Meeting Room

POST /meetingRooms
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]'

Response 201 status code with a serialized copy of the 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.

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

GET /meetingRooms
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]'

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

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

Get Meeting Room by meetingNumber

GET /meetingRooms/{meetingNumber}
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]'

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

This request is enabled for Field Filtering.

Path Arguments

Update Meeting Room

PUT /meetingRooms/{meetingNumber}
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 '{"description": "Another description"}' \
-u '[your_user_name]:[your_password]'

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

A PUT request is used to update one or more attribute values. When using a PUT request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The meeting room meetingNumber is passed in the query URL, and the values to be modified are 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
• description
• didGroupReferences
• keychain
• meetingNumber
• primaryDidGroupId

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

Delete Meeting Room

DELETE /meetingRooms/{meetingNumber}
Deletes a meeting room, targeted by meetingNumber

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

Response 204 status code with an empty body

This request deletes a meeting room, targeted by meetingNumber.

Path Arguments

Subscribers

The subscriber is a real person or organization with a name, phone number, email address, etc. Subscribers can have meeting room information but they are not directly associated with the meeting room access codes.

Access codes are properties of meeting keys that belong to the meeting rooms. The meeting rooms, in their turn, belong to subscribers.

A subscriber can have a reference to another subscriber who created it, thus making up hierarchy.

Subscriber Object

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

Sample Subscriber object

{
    "authenticationToken": "MWMx0BU1YZE0MV==",
    "callback": {
        "id": 233944,
        "url": "http://mywebsite.com/conference/callback"
    },
    "created": 1586872518000,
    "details": "Some details about subscriber",
    "didGroupReferences": [
        {
            "didGroupId": 731,
            "state": 0
        }
    ],
    "email": "mail@carrierx.com",
    "externalId": -1,
    "firstName": "CarrierX",
    "lastName": "",
    "login": "test_carrierx_conference_135",
    "meetingRooms": [],
    "parentSid": "zzpF93QCVvfYYJb2KdPSzGW6lqGLB3qm",
    "phoneNumber": "9197473626",
    "role": 3,
    "sid": "rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1"
}

Callback Object

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.

Create Subscriber

POST /subscribers
Creates a subscriber

curl -X POST \
'https://api.carrierx.com/conference/v1/subscribers' \
-H 'Content-Type: application/json' \
--data-binary '{"login":"test_carrierx_conference_135","password":"my_test_password","firstName":"CarrierX"}' \
-u '[your_user_name]:[your_password]'

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

{
    "authenticationToken": "MWMx0BU1YZE0MV==",
    "created": 1586872518000,
    "didGroupReferences": [],
    "externalId": -1,
    "firstName": "CarrierX",
    "lastName": "",
    "login": "test_carrierx_conference_135",
    "parentSid": "zzpF93QCVvfYYJb2KdPSzGW6lqGLB3qm",
    "role": 3,
    "sid": "rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1"
}

This request creates a subscriber.

Body Arguments

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

Required fields to create a subscriber are:

• login
• password

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

Get Current Subscriber

GET /subscribers/whoami
Returns the currently active subscriber

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

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

{
    "authenticationToken": "MWMx0BU1YZE0MV==",
    "created": 1586872518000,
    "didGroupReferences": [],
    "externalId": -1,
    "firstName": "CarrierX",
    "lastName": "Company",
    "login": "test_carrierx_conference_135",
    "parentSid": "zzpF93QCVvfYYJb2KdPSzGW6lqGLB3qm",
    "role": 3,
    "sid": "rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1"
}

This request returns data for the currently active subscriber.

Get Subscribers

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

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

Response 200 status code with a list of Subscriber objects

{
    "last": 1,
    "offset": 0,
    "subscribers": [
        {
            "authenticationToken": "MWMx0BU1YZE0MV==",
            "created": 1586872518000,
            "didGroupReferences": [],
            "externalId": -1,
            "firstName": "CarrierX",
            "lastName": "",
            "login": "test_carrierx_conference_135",
            "parentSid": "zzpF93QCVvfYYJb2KdPSzGW6lqGLB3qm",
            "role": 3,
            "sid": "rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1"
        },
        {
            "authenticationToken": "MWMx0BU1YZE0MV=",
            "callback": {
                "id": 779127,
                "url": "https://mywebsite.com/new-url"
            },
            "created": 1603107611000,
            "details": "some details about subscriber",
            "didGroupReferences": [
                {
                    "didGroupId": 731,
                    "state": 0
                }
            ],
            "externalId": -1,
            "firstName": "John",
            "lastName": "Smith",
            "login": "test_john_smith_conference_164",
            "parentSid": "rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1",
            "phoneNumber": "9197473626",
            "role": 2,
            "sid": "6v9u9-p35vZo1Cxq0qKkQn9X57T5cfAj"
        }
    ],
    "total": 2
}

This request returns a list of subscribers.

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

Get Subscriber by SID

GET /subscribers/{sid}
Returns a subscriber, targeted by secure ID

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

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

{
    "authenticationToken": "MWMx0BU1YZE0MV==",
    "created": 1586872518000,
    "didGroupReferences": [],
    "externalId": -1,
    "firstName": "CarrierX",
    "lastName": "",
    "login": "test_carrierx_conference_135",
    "parentSid": "zzpF93QCVvfYYJb2KdPSzGW6lqGLB3qm",
    "role": 3,
    "sid": "rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1"
}

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

This request is enabled for Field Filtering.

Path Arguments

Update Subscriber

PUT /subscribers/{sid}
Updates the Subscriber object, targeted by secure ID, with the values in the request body

curl -X PUT \
'https://api.carrierx.com/conference/v1/subscribers/rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1' \
-H 'Content-Type: application/json' \
--data-binary '{"role":2,"lastName":"Company"}' \
-u '[your_user_name]:[your_password]'

Response 200 status code with a serialized copy of the updated Subscriber object

{
    "authenticationToken": "MWMx0BU1YZE0MV==",
    "created": 1586872518000,
    "didGroupReferences": [],
    "externalId": -1,
    "firstName": "CarrierX",
    "lastName": "Company",
    "login": "test_carrierx_conference_135",
    "parentSid": "zzpF93QCVvfYYJb2KdPSzGW6lqGLB3qm",
    "role": 2,
    "sid": "rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1"
}

This request updates a subscriber, targeted by secure ID.

A PUT request is used to update one or more attribute values. When using a PUT request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The subscriber secure ID is passed in the query URL, and the values to be modified are 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:

• callback
• details
• didGroupReferences
• email
• eventCallbackUrl
• ext
• firstName
• lastName
• login
• meetingRooms
• password
• phoneNumber
• role

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

Delete Subscriber

DELETE /subscribers/{sid}
Deletes a subscriber, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/conference/v1/subscribers/rB0M9.EzXfaO4keb-opANwfb7CHx1Ph1' \
-u '[your_user_name]:[your_password]'