NAV
cURL python ruby

API Overview

InformaCast Mobile is Singlewire Software’s cloud-based, mobile device broadcast system that allows you to simultaneously send combinations of text, pre-recorded audio, and images to Android and iOS mobile endpoints such as cellular phones and tablets. While smart devices provide the richest interface and are the primary target, you can also send content via email, SMS messages to any cell phone, and audio calls to any telephone.

InformaCast Mobile (its web interface and Android and iOS mobile apps) is built upon a powerful representational state transfer (REST) application programming interface (API). Any operation supported by InformaCast Mobile can be achieved through its API, which uses the standard HTTP verbs of POST, GET, PUT, and DELETE to create, read, update, and delete resources, though not all verbs are available for all resources.

An API request is comprised of the application path (i.e. https://api.icmobile.singlewire.com/api/), the API’s version, a resource path, and optional query parameters. The following API request could be used with an HTTP GET to retrieve a user’s information. API Explorer Token Text Field

Pasting this request into a web browser yields all known information about this user.

Visit http://www.tutorialspoint.com/http/http_quick_guide.htm to learn more about formatting HTTP requests or responses.

{"permissions": ["get"],
 "lock": null,
 "securityGroups": [],
 "subscriptions": [
  {"createdAt": "2014-05-22T12:55:14.932Z",
   "id": "51839b40-e1b0-11e3-b343-0ab69cea9f8b",
   "distributionListId": "29e56500-e1b0-11e3-b343-0ab69cea9f8b",
   "userId": "d55af380-caf6-11e3-81cc-127b75e3b4bb"}],
 "createdAt": "2014-04-23T14:52:04.152Z",
 "id": "d55af380-caf6-11e3-81cc-127b75e3b4bb",
 "email":"george.harrison@gmail.com",
 "name":"George Harrison"}

Prerequisites

Before beginning to use the InformaCast Mobile API, you must have:

Mobile devices registering with InformaCast Mobile have the following prerequisites:

API Documentation

The documentation for the InformaCast Mobile API is separated into three panes:

The left Navigation pane includes a responsive table of contents that allows for easy navigation between InformaCast Mobile API’s operations and resources, and it also scrolls with you as you move through the content in the center pane.

The center Documentation pane includes definitions of certain aspects of InformaCast Mobile, explanations of each resource and its attributes, and the relevant HTTP request. The headings you may see pertaining to each resource include:

The Sample Requests pane on the right contains tab(s) of sample requests that pertain to the documentation in the center pane (currently, only cURL requests are shown, but we plan to add examples in other languages as we add support for different access libraries). The cURL examples should actually work if you copy and paste them into a shell window, although you may have to alter IDs and other values to match resources which actually exist in your account.

Terminology

When working with the InformaCast Mobile API, it’s useful to be familiar with certain terms:

API Explorer Tour

The API Explorer is your window into InformaCast Mobile’s API. You can use it to:

When viewing the API explorer, you can see the resources and attributes available to you. API Explorer Token Text Field

Resources are objects with associated attributes, relationships to other resources, and a set of methods that operate on them. Attributes are the building blocks of resources; they are comprised of the data you can affect. For example, users is a resource that is comprised of the following attributes: an unique ID, a name, whether the user’s account is locked and for how long, an email address, whether the user (if using the built-in Singlewire identity provider) must reset his password upon next login, and the unique ID associated with the load definition that created the user’s record, if applicable.

The set of methods for interacting with resources and attributes are the standard HTTP verbs of POST, GET, PUT, and DELETE. These are housed in tabs underneath a resource’s attributes along with a description of your action, the fields available for your request, the HTTP URI associated with your API request, and the response your API request generates once click the GET, POST, PUT, or DELETE buttons.

Using the GET tab of the users resource as an example, a description of your action is “Get one resource by id or an array of resources by filtering attribute with GET.” Leaving all of the fields on the GET tab blank and clicking the GET button, returns a list of all of your users. You can also see that the path parameter for your API request is /users.

API Explorer Token Text Field

A full API request could then be crafted from this information: https://api.icmobile.singlewire.com/api/v1/users. Pasting this along with a URL-encoded authentication token query parameter into a web browser would also yield a list of your users, without the nice formatting of the JSON response you get in the API Explorer.

API Explorer Token Text Field

Along with the application and resource path and perhaps query parameters for pagination and search, you can also see the API’s version number, v1, which must appear in your API requests:

https://api.icmobile.singlewire.com/api/v1/

As new API versions are made available, you can update your API requests to adopt the newer version. Any unmodified API requests will continue to reach older versions; however, they may eventually be deprecated and retired.

Sign into the API Explorer and familiarize yourself further by using the other resources, attributes, and methods.

Helpful Clients

The InformaCast Mobile API is built on a set of RESTful standards. You will want to find or use a familiar REST client for your programming language of choice. If you don’t already have a preferred REST client, here are a few suggestions to get you started:

Authentication

Authenticating with the API is how you prove that you should be able to use it, and authentication is controlled through submitting an authentication token with every API request you make. This token is associated with a user, that user has permissions and security group memberships, and if the permissions and memberships allow it, your API request is processed.

How you create a token depends on the kind of application you are building:

Either kind of token grants access to InformaCast Mobile, so it is important to keep it secure. This is particularly important for permanent tokens, because if such a token must be revoked due to a compromise, you will need to update your shared web application, or tell your clients to update their configured token.

Create a Token for Experimentation

If you just need a token suitable for experimental exploration of the API, use the following steps.

  1. Open a web browser and go to the API Explorer. The API Explorer page appears. API Explorer Token Text Field
  2. Click the Login link at the top of the page. The InformaCast Mobile Login page appears. API Explorer Token Text Field

  3. Log in. Once you have successfully logged in, you are returned to the API Explorer and the authentication token assigned to you for that browser session is displayed in the field to the right of the Resources dropdown menu (highlighted in the following picture). API Explorer Token Text Field

  4. Copy and paste this token into the commands that you want to try out against the API. See Use the Token for more information.

As noted in Authentication, if you are building an application that will interact with the API on behalf of an interactive user, you will want to embed a web browser and direct the user to the InformaCast Mobile login interface. Use query parameters to inform the API that your user is logging in within your application through the client ID and client secret assigned to your application.

Since the implementation of an OAuth2 login is complex, try building on top of an open-source solution, such as the Google Toolbox for Mac OAuth 2 Controller. This is the approach used in-house at Singlewire. The documentation for the library will explain how your client information is configured and how the token is obtained at the end of a successful login process. Even if you plan to roll out your own OAuth 2 client implementation from scratch, the source and documentation of a library like this will be a valuable resource.

Create a Permanent Token

If you need a token to be embedded permanently in an application that runs in a headless mode (i.e. without the ability to ask a user to periodically log in for it and which needs to stay logged in), you will need to create a permanent token for it. (Or, as noted in Authentication, your clients can do so, and paste the token into your application’s configuration interface, if the application will be logging in on their behalf.)

Use the following steps to create a permanent token.

  1. Open a web browser and go to InformaCast Mobile’s web interface.
  2. Create a user with an appropriate set of permissions to meet the needs of your application.
  3. Click the Users dropdown menu and go to Manage Users | user’s Name link | User Tokens tab. The Edit User Details page appears, displaying the contents of the User Tokens tab. User Tokens tab screen shot

  4. Click the Add button. The Add Token pop-up window appears. Add Token pop-up window screen shot

  5. Enter a name for your token in the Name field, e.g. InformaCast Mobile Plugin.

  6. Click the Save button. The Generated Security Token pop-up window appears. Generated Security Token pop-up window screen shot

  7. Copy and paste the token from the Generated Security Token pop-up window into your source code editor or application configuration window in order to embed it for future use.

  8. Click the Done button. You are returned to the Edit User Details page and you can see your newly added token. User Tokens tab with new token screen shot Manually generated tokens, like the one you just created, have no expiration date.

Use the Token

The examples in this section show how to retrieve the Session resource, which contains information about the login session associated with the authentication token.

As specified by OAuth 2’s Bearer Token Usage principles—on which the API relies—there are three methods for providing authorization for a request:

These methods are listed in decreasing order of convenience and preference. Wherever possible, the Authorization header method should be used. The other two methods are fallbacks for cases where that is simply not possible, and the final approach (e.g. URI query parameter) should only be used in testing and development contexts.

Authorization Header

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/session"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/session" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/session"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e

A token may be passed via an Authorization request header field as defined by RFC2617. Additional details and guidelines can be found here. Using an Authorization header is the preferred method, and should be used whenever possible.

Form-encoded Body Parameter

curl "https://api.icmobile.singlewire.com/api/v1/session" \
  -d "access_token=S35QCVBN6S6TUQKHOND%3D"
# When using a client library, the authentication
# header is taken care of for you, so there is no
# need to use a body parameter.
# When using a client library, the authentication
# header is taken care of for you, so there is no
# need to use a body parameter.

A token may be passed in the form body so long as the request is single-part and uses the x-www-form-urlencoded Content-Type. Additional criteria and guidelines can be found here. This approach can be used when it is not possible for you to set the Authorization header, as long as the other criteria are met. As discussed in the IETF guidelines, it is not possible to use this approach with the HTTP GET method.

URI Query Parameter

curl "https://api.icmobile.singlewire.com/api/v1/session?access_token=S35QCVBN6S6TUQKHOND%3D"
# When using a client library, the authentication
# header is taken care of for you, so there is no
# need to use a body parameter.
# When using a client library, the authentication
# header is taken care of for you, so there is no
# need to use a body parameter.

A token may be specified as an encoded query parameter and must be properly separated from additional query parameters using the & character. Additional details and guidelines can be found here. This method should be used as a last resort, when neither of the other methods are possible, because it suffers from security deficiencies even when used with all the Cache-Control headers recommended by the guidelines.

Assuming the token was valid, all three of the above methods would return something like the following:

{
  "accessToken": "S35QCVBN6S6TUQKHOND=",
  "userId": "723f0df0-25ff-11e3-bb04-2a16fd5e656f",
  "providerId": "a8105c2c-8e15-11e5-800a-efb9f24b4331",
  "providerName": "Yoyodyne",
  "email": "sallie.chin@yoyodyne.com",
  "name": "Sallie Chin",
  "isFusion": true,
  "isLicenseValid": true,
  "idleTimeout": 90,
  "idleTimeoutCustom": true
}

Choosing an acting Domain

Once you have created any Domains, all API requests are interpreted in the context of a particular Domain, described as the “Acting Domain.”

To specify the Domain in which a particular request should operate, you supply the desired Domain id value either as the request header x-singlewire-domain, or as the request parameter domain (the request parameter can either be a query parameter in the URL of any request, or a body parameter for requests using HTTP methods other than GET).

If you do not specify a value for either the x-singlewire-domain request header or the domain request parameter, the first Domain available to the user making the request, from a list sorted by Name Path, will be assumed.

If you specify both the request header and the request parameter, the domain request parameter value will be used, and the x-singlewire-domain header will be ignored. This allows the header to specify a longer-lived acting context, while special requests can occasionally act in a different Domain by adding the request parameter.

If the user associated with the request’s authentication token is not permitted to act in the specified Domain (or in the root Domain, if none was specified), the request will fail with a validation error.

Quick Start

Jump right in and learn the basic tenets of InformaCast Mobile.

InformaCast Mobile allows you to add users to its system, group these users into distributions lists, assign them permissions (such as read/write access for creating notifications), send them notifications comprised of message templates (or allow them to trigger notifications from their iOS or Android devices), and allow them to respond to their notifications through confirmation requests.

The following sections walk you quickly through the steps of sending a notification:

Create Your First User

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'email': 'craig.smith@acme.com',
    'name': 'Craig Smith'
}

try: 
    user = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/users" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"email": "craig.smith@acme.com", \
       "name": "Craig Smith"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'email': 'craig.smith@acme.com'
,
    'name': 'Craig Smith'

}

begin: 
    user = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(user)
rescue StandardError => e
    puts e
# This is a thin wrapper around rest-client;
# details on other ways you can use it are in
# http://www.rubydoc.info/github/rest-client/rest-client
{
  "lock": null,
  "name": "Craig Smith",
  "securityGroups": [ ],
  "passwordResetRequired": false,
  "createdAt": "2014-08-13T20:33:53.262Z",
  "email": "craig.smith@acme.com",
  "permissions": ["delete", "put", "get"],
  "subscriptions": [ ],
  "id": "2400c8e0-2329-11e4-8e47-685b358ea847"
}

Create a user named Craig Smith. Start him with nothing but the most basic permissions.

Create Your First Distribution List

# Continuing the previous example:
try:
    dist_list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(dist_list)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "To Just Craig Smith"}'
# Continuing the previous example:
begin:
    dist_list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(dist_list)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-13T20:40:38.627Z",
  "id": "159e9330-232a-11e4-8e47-685b358ea847",
  "name": "To Just Craig Smith"
}

In order for Craig Smith to receive a notification, he must first belong to a distribution list. Create a distribution list named To Just Craig Smith.

Subscribe a User to a Distribution List

# Continuing with the user and distribution
# list objects from the previous example:
try:
    sub = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/users/2400c8e0-2329-11e4-8e47-685b358ea847/subscriptions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"distributionListId": "159e9330-232a-11e4-8e47-685b358ea847"}'
# Continuing with the user and distribution
# list objects from the previous example:
begin:
    sub = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(sub)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-13T20:33:53.262Z",
    "id": "2400c8e0-2329-11e4-8e47-685b358ea847",
    "email": "craig.smith@acme.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-13T20:40:38.627Z",
    "id": "159e9330-232a-11e4-8e47-685b358ea847",
    "name": "To Just Craig Smith"
  },
  "createdAt": "2014-08-13T20:42:08.689Z",
  "distributionListId": "159e9330-232a-11e4-8e47-685b358ea847",
  "id": "4b4cf210-232a-11e4-8e47-685b358ea847",
  "userId": "2400c8e0-2329-11e4-8e47-685b358ea847"
}

Notifications are sent to distribution lists that may contain one or many users. In order for Craig Smith to get any notifications, he must belong to a distribution list.

Once subscribed, Craig Smith will now receive any notifications sent to that distribution list. Notice that this request contains the id values that were assigned to both of the resources you created in the first two sections. The user ID is part of the resource path to the subscription, and the distribution list ID is a POST parameter in the request body.

Register a User’s Device

# Continuing with the user object from the
# previous example:
try:
    reg = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(reg)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/users/2400c8e0-2329-11e4-8e47-685b358ea847/devices" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"type": "Android", \
       "name": "Android Nexus Fire 2", \
       "deviceIdentifier": "APA91bFpOikKATC523g5Z_4-1puPNa_oE8t1sTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf"}'
# Continuing with the user object from the
# previous example:
begin:
    reg = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(reg)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-06T16:54:23.115Z",
  "deviceIdentifier": "APA91bFpOikKATC523g5Z_4-1puPNa_oE8t1sTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf",
  "type": "Android",
  "name": "Android Nexus Fire 2",
  "disabled": false,
  "id": "511795b0-1d8a-11e4-a054-3c970e7ff560",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

Craig Smith wants to receive push notifications on his Android Device. Depending on the push notification service being used (e.g. APNS, GCM, SMS, etc.), different types of identifier information are needed to register the device.

Add a Confirmation Request

# Continuing the previous example:
try:
    conf_req = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(conf_req)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Are you there?", \
       "options": ["Yes", "No"]}'
# Continuing the previous example:
begin:
    conf_req = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(conf_req)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [ ],
  "createdAt": "2014-08-13T21:35:07.728Z",
  "id": "b227cd00-2331-11e4-8e47-685b358ea847",
  "options": ["Yes", "No"],
  "name": "Are you there?"
}

Message templates contain the building blocks of the notifications you will send to your users. Confirmation requests are one of those building blocks, and allow you to configure a response for your users to send back to you after receiving a notification. You can also configure an escalation notification to be sent if enough responses aren’t received.

Craig Smith will need to respond to his notification, so you will create a confirmation request before adding it to your message template.

This confirmation request allows Craig Smith to respond with Yes or No.

Create the Message Template

# Continuing with the confirmation request
# and distribution list objects from the previous
# example:
try:
    template = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(template)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/message-templates" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "For Craig Smith Only", \
       "subject": "Hello, Craig. Are you there?", \
       "body": "Please confirm you are present.", \
       "confirmationRequestId": "b227cd00-2331-11e4-8e47-685b358ea847", \
       "distributionListIds": ["159e9330-232a-11e4-8e47-685b358ea847"]}'
# Continuing with the confirmation request
# and distribution list objects from the previous
# example:
begin:
    template = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(template)
rescue StandardError => e
    puts e
{
  "distributionListIdsCustomizable": false,
  "subject": "Hello Craig. Are you there?",
  "distributionListIds": ["159e9330-232a-11e4-8e47-685b358ea847"],
  "confirmationRequestIdDisplay": "auto",
  "bodyDisplay": "auto",
  "audioDisplay": "auto",
  "name": "For Craig Smith Only",
  "imageCustomizable": false,
  "subjectCustomizable": false,
  "confirmationRequestIdCustomizable": false,
  "image": 0,
  "imageDisplay": "auto",
  "audioCustomizable": false,
  "audio": 0,
  "confirmationRequestId": "b227cd00-2331-11e4-8e47-685b358ea847",
  "createdAt": "2014-08-13T21:35:57.500Z",
  "permissions": ["delete", "put", "get"],
  "distributionListIdsDisplay": "auto",
  "subjectDisplay": "auto",
  "body": "Please confirm you are present.",
  "id": "cfd267c0-2331-11e4-8e47-685b358ea847",
  "distributionLists": [
    {
      "createdAt": "2014-08-13T20:40:38.627Z",
      "id": "159e9330-232a-11e4-8e47-685b358ea847",
      "name": "To Just Craig Smith"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-13T21:35:07.728Z",
    "id": "b227cd00-2331-11e4-8e47-685b358ea847",
    "options": ["Yes", "No"],
    "name": "Are you there?"
  },
  "bodyCustomizable": false
}

You now have all the pieces you need to create a message template. Message templates require a name (For Craig Smith Only) and subject (Hello Craig. Are you there?). You should also supply the id of the confirmation request you created, and a list containing the id of the distribution list you created.

Send the Notification

# Continuing with the message template object
# from the previous example:
try:
    sent = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(sent)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/notifications" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"messageTemplateId": "cfd267c0-2331-11e4-8e47-685b358ea847"}'
# Continuing with the message template object
# from the previous example:
begin:
    sent = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(sent)
rescue StandardError => e
    puts e
{
  "recipientCount": 1,
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "messageTemplateId": "b227cd00-2331-11e4-8e47-685b358ea847",
  "messageTemplate": {
    "imageDisplay": "auto",
    "userIdsDisplay": "auto",
    "imageCustomizable": false,
    "name": "For Craig Smith Only",
    "audioDisplay": "auto",
    "createdAt": "2015-03-09T21:57:41.199Z",
    "distributionListIds": [
      "159e9330-232a-11e4-8e47-685b358ea847"
    ],
    "subjectCustomizable": false,
    "confirmationRequestIdCustomizable": false,
    "distributionListIdsCustomizable": false,
    "bodyDisplay": "auto",
    "confirmationRequestId": "4ec6ffa0-c6a7-11e4-b374-de9e84057a63",
    "userIdsCustomizable": false,
    "id": "4ecf15f0-c6a7-11e4-b374-de9e84057a63",
    "bodyCustomizable": false,
    "distributionListIdsDisplay": "auto",
    "subjectDisplay": "auto",
    "audioCustomizable": false,
    "body": "Please confirm you are present.",
    "confirmationRequestIdDisplay": "auto",
    "subject": "Hello Craig. Are you there?"
  },
  "smsReceived": 0,
  "confirmationResults": {
    "Yes": 0,
    "No": 0
  },
  "initiator": {
    "createdAt": "2014-05-29T15:41:37.010Z",
    "id": "b8301520-e747-11e3-b541-c82a144feb17",
    "lock": {
      "end": null,
      "start": null
    },
    "passwordResetRequired": false,
    "name": "James Elliott",
    "email": "james.elliott@singlewire.com"
  },
  "createdAt": "2015-03-09T21:57:41.247Z",
  "distributionListIds": [
    "4eb35090-c6a7-11e4-b374-de9e84057a63"
  ],
  "confirmationRequestId": "b227cd00-2331-11e4-8e47-685b358ea847",
  "smsSent": 0,
  "id": "4ed668f0-c6a7-11e4-b374-de9e84057a63",
  "imageMimeType": null,
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2015-03-09T21:57:41.146Z",
    "id": "b227cd00-2331-11e4-8e47-685b358ea847",
    "options": [
      "Yes",
      "No"
    ],
    "name": "Are you there?"
  },
  "image": 0,
  "audio": 0,
  "distributionLists": [
    {
      "createdAt": "2015-03-09T21:57:41.017Z",
      "id": "4eb35090-c6a7-11e4-b374-de9e84057a63",
      "name": "To Just Craig Smith"
    }
  ],
  "body": "Please confirm you are present.",
  "userIds": null,
  "readCount": 0,
  "subject": "Hello Craig. Are you there?",
  "initiatorId": "b8301520-e747-11e3-b541-c82a144feb17"
}

Creating a notification is the same as sending it. It will be delivered to all users’ registered devices who are subscribed to the distribution list(s) associated with the notification.

There are various counters in the Notification object which can be checked over time to monitor the progress as users read (and, if there is an attached confirmation request, respond to) it.

Change Log

To view or subscribe to upcoming API changes, check out the API Developer Announcements.

Changes from 2021-09-22

Deprecated

Changes from 2021-08-04

Added

Changed

Changes from 2021-06-30

Added

Changed

Deprecated

Removed

Changes from 2021-05-12

Added

Changed

Changes from 2021-04-14

Added

Updated

Changes from 2020-12-09

Added

Updated

Changes from 2020-09-23

Updated

Changes from 2020-08-12

Added

Updated

Changes from 2020-06-24

Added

Changes from 2020-05-13

Changed

Limits have been applied to particular resources restricting how many may be created. Affected (limits noted):

Changes from 2020-04-01

Deprecated

Added

Changed

Changes from 2020-02-19

Removed

Added

Changes from 2019-12-16

Removed

Added

Changes from 2019-11-13

Deprecated

Removed

Changes from 2019-10-30

Added

Changed

Deprecated

 

Areas of Interest

Areas of Interest (AOIs) denote geographic regions that can distribute Notifications to Users currently found within the region.

alt text

A circular region around the Cincinnati Airport. As seen in the InformaCast Mobile administrative console, this AOI currently has one user within its bounds.

List All Areas of Interest

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
 "total": 3,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "id": "0b45d70c-01ba-11e6-91d9-01444c9150eb",
   "name": "MSN",
   "geometryType": "circle",
   "geometryValue": {
    "type": "Feature",
    "geometry": {
     "type": "Point",
     "coordinates": [
      -89.3362,
      43.1356
     ]
    },
    "properties": {
     "radiusInM": 3182
    }
   },
   "syncedDeviceTypes": [
       "mobile"
      ],
   "createdAt": "2016-04-13T20:55:24.605Z",
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Retrieves the list of all areas of interest. The visibility of AOIs may be limited by the permissions associated with the request, which are attributed through the user attached to the access token.

HTTP Request

GET /areas-of-interest

Produces

application/json

Query Parameters

To make this example more manageable, only the first user was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 3 areas available when the request was made. The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The AOI response format is detailed here.

Get an Area of Interest

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    aoi = requests.get(url, headers=headers).json()
    print(aoi)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    aoi = JSON.parse(HTTParty.get(url, headers: headers))
    puts(aoi)
rescue StandardError => e
    puts e
{
 "id": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
 "name": "CVG",
 "geometryType": "circle",
 "geometryValue": {
  "type": "Feature",
  "geometry": {
   "type": "Point",
   "coordinates": [
    -84.6672,
    39.0478
   ]
  },
  "properties": {
   "radiusInM": 3551
  }
 },
 "syncedDeviceTypes": [
        "mobile"
       ],
 "createdAt": "2016-04-13T18:44:49.494Z",
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Retrieves a single AOI by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /areas-of-interest/{aoiId}

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area to retrieve.

Response

The AOI response format is detailed here.

Create an Area of Interest

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Madison Airport',
    'geometryType': 'circle',
    'geometryValue': {
        'type': 'Feature',
        'geometry': {
            'type': 'Point',
            'coordinates': [-89.34, 43.14]
}
,
        'properties': {
            'radiusInM': 3000
}

}
,
    'syncedDeviceTypes': ['mobile']
}

try: 
    aoi = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(aoi)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Madison Airport", \
       "geometryType": "circle", \
       "geometryValue": {"type": "Feature", \
         "geometry": {"type": "Point", \
           "coordinates": [-89.34, 43.14]}, \
         "properties": {"radiusInM": 3000}}, \
       "syncedDeviceTypes": ["mobile"]}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Madison Airport'
,
    'geometryType': 'circle'
,
    'geometryValue': {
        'type': 'Feature'
,
        'geometry': {
            'type': 'Point'
,
            'coordinates': [-89.34
, 43.14
]

}

,
        'properties': {
            'radiusInM': 3000

}


}

,
    'syncedDeviceTypes': ['mobile'
]

}

begin: 
    aoi = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(aoi)
rescue StandardError => e
    puts e
{
  "geometryType": "circle",
  "name": "Madison Airport",
  "id": "e83d84e6-2281-11e6-a729-83a644c48766",
  "geometryValue": {
   "type": "Feature",
   "geometry": {
    "type": "Point",
    "coordinates": [ -89.34, 43.14 ]
   },
   "properties": {
    "radiusInM": 3000
   }
  },
  "syncedDeviceTypes": [
         "mobile"
        ],
  "createdAt": "2016-05-25T14:06:42.385Z",
  "permissions": [ "delete", "put", "get" ]
}

Creates a new area of interest (limit: 20).

HTTP Request

POST /areas-of-interest

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
geometryType String N/A Option: circle. A circular region defined by center point given in latitude and longitude and a radius given in meters.
geometryValue[geometry][coordinates] array[number] N/A An array with the latitude and longitude of the feature
geometryValue[geometry][type] String N/A Option: Point. The type of feature.
geometryValue[properties][radiusInM] integer N/A For circular features, the radius of the circle in meters
geometryValue[type] String N/A Option: Feature. The type of geojson.
name String N/A The area’s display name
syncedDeviceTypes array[String] N/A Options: mobile desktop. The device types synced with the AOI, i.e. included in its count. Note: Submitting syncedDeviceTypes=mobile,desktop is equivalent to omitting the parameter.

Response

The AOI response format is detailed here.

Update an Area of Interest

# Continuing with the areas of interest object
# from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/e83d84e6-2281-11e6-a729-83a644c48766" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "MSN"}'
# Continuing with the areas of interest object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
  "geometryType": "circle",
  "name": "MSN",
  "id": "e83d84e6-2281-11e6-a729-83a644c48766",
  "geometryValue": {
   "type": "Feature",
   "geometry": {
    "type": "Point",
    "coordinates": [ -89.34, 43.14 ]
   },
   "properties": {
    "radiusInM": 3000
   }
  },
  "syncedDeviceTypes": [
         "mobile"
        ],
  "createdAt": "2016-05-25T14:06:42.385Z",
  "permissions": [ "delete", "put", "get" ]
}

Updates an existing area of interest.

HTTP Request

PUT /areas-of-interest/{aoiId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area to update.

Request Parameters

Parameter Type Default Description
geometryType String N/A Option: circle. A circular region defined by center point given in latitude and longitude and a radius given in meters.
geometryValue[geometry][type] String N/A Option: Point. The type of feature.
geometryValue[geometry][coordinates] array[number] N/A An array with the latitude and longitude of the feature
geometryValue[properties][radiusInM] integer N/A For circular features, the radius of the circle in meters
geometryValue[type] String N/A Option: Feature. The type of geojson.
name String N/A The area’s display name
syncedDeviceTypes array[String] N/A Options: mobile desktop. The device types synced with the AOI, i.e. included in its count. Note: Submitting syncedDeviceTypes=mobile,desktop is equivalent to omitting the parameter.

Response

The AOI response format is detailed here.

Remove an Area of Interest

# Continuing with the areas of interest object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/e83d84e6-2281-11e6-a729-83a644c48766" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the areas of interest object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted  e83d84e6-2281-11e6-a729-83a644c48766"
}

Deletes an existing area of interest.

HTTP Request

DELETE /areas-of-interest/{aoiId}

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area to delete.

Response

The deletion response format is detailed here.

Area of Interest Response

The JSON document used to represent an Area of Interest resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this area was created.
geometryType String Option: circle. A circular region defined by center point given in latitude and longitude and a radius given in meters.
geometryValue GeometryValue The geometry details. If present, this value determines the location, shape, and size of the area of interest.
id String The id of the area, for efficient retrieval, manipulation, or looking up sub-resources attached to the AOI
name String The area’s display name
syncedDeviceTypes array[String] Options: mobile desktop. The device types synced with the AOI, i.e. included in its count. Note: Submitting syncedDeviceTypes=mobile,desktop is equivalent to omitting the parameter.
permissions array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Geometry Value Response

A geometry value is represented by the following JSON document structure:

Attribute Type Description
geometry[coordinates] array[number] An array with the latitude and longitude of the feature
geometry[type] String Option: Point. The type of feature.
properties[radiusInM] integer For circular features, the radius of the circle in meters
type String Option: Feature. The type of geojson.

AOI Boundary Triggers

Boundary Triggers help create site-specific actions based on the presence or movement of Users within defined Areas of Interest (AOIs). Any action taken will also result in the creation of a Boundary Trigger Activity entry.

List All Boundary Triggers

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 1,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
   {
    "perUserThrottlingInSecs": 600,
    "areaOfInterestId": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
    "permissions": [
     "delete",
     "put",
     "get"
    ],
    "messageTemplateId": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
    "messageTemplate": {
     "imageDisplay": "auto",
     "userIdsDisplay": "auto",
     "imageCustomizable": false,
     "name": "Welcome to CVG",
     "audioDisplay": "auto",
     "createdAt": "2016-05-25T15:38:34.925Z",
     "distributionListIds": [],
     "subjectCustomizable": false,
     "confirmationRequestIdCustomizable": false,
     "distributionListIdsCustomizable": true,
     "areaOfInterestIdsCustomizable": true,
     "collaborationGroupIdsCustomizable": true,
     "bodyDisplay": "auto",
     "confirmationRequestId": null,
     "collaborationGroupIdsDisplay": "auto",
     "alertToneDisplay": "auto",
     "userIdsCustomizable": true,
     "id": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
     "collaborationGroupIds": [],
     "bodyCustomizable": false,
     "imageMimeType": null,
     "distributionListIdsDisplay": "auto",
     "confirmationRequest": null,
     "audioSize": 0,
     "imageHash": null,
     "audioHash": null,
     "subjectDisplay": "auto",
     "audioCustomizable": false,
     "imageSize": 0,
     "body": "Welcome to the Cincinnati International Airport. Your comfort and safety are important to use and we work to keep you informed of all local events.",
     "userIds": [],
     "confirmationRequestIdDisplay": "auto",
     "alertToneCustomizable": false,
     "areaOfInterestIds": [],
     "metadata": {},
     "subject": "Welcome to Cincinnati!",
     "alertTone": "default",
     "areaOfInterestIdsDisplay": "auto",
     "metadataCustomizable": false
    },
    "name": "Arrive at CVG",
    "createdAt": "2016-05-25T15:40:02.358Z",
    "distributionListIds": [],
    "id": "f215963c-228e-11e6-a729-f95bf9c34bbf",
    "notificationAction": "send-to-user",
    "action": "entered",
    "distributionLists": [],
    "body": null,
    "userIds": [
     "e4e7860d-fb72-11e5-93a8-7b0393df5405"
    ],
    "subject": null,
    "users": [
     {
      "email": "marc.loy@singlewire.com",
      "name": "Marc Loy",
      "passwordResetRequired": false,
      "type": "regular",
      "loadSourceId": null,
      "id": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
      "createdAt": "2016-04-05T21:10:58.989Z"
     }
    ]
   }
  ]
}

Retrieves the list of all boundary triggers (entering, exiting, or both) associated with the given area of interest. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of these triggers.)

HTTP Request

GET /areas-of-interest/{aoiId}/boundary-triggers

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the Area of Interest whose triggers are being looked up.

Query Parameters

To make this example more manageable, only the first trigger was requested using the API’s pagination parameters. The response reflects this, as well as the fact that this is the only trigger available when the request was made. If multiple triggers are available, the total count would contain the correct number of triggers regardless of how many were requested through pagination limits. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The boundary trigger response format is detailed here.

Get a Boundary Trigger

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/f215963c-228e-11e6-a729-f95bf9c34bbf"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    trigger = requests.get(url, headers=headers).json()
    print(trigger)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/f215963c-228e-11e6-a729-f95bf9c34bbf" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/f215963c-228e-11e6-a729-f95bf9c34bbf"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    trigger = JSON.parse(HTTParty.get(url, headers: headers))
    puts(trigger)
rescue StandardError => e
    puts e
{
  "perUserThrottlingInSecs": 600,
  "areaOfInterestId": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
  "permissions": [
   "delete",
   "put",
   "get"
  ],
  "messageTemplateId": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
  "messageTemplate": {
   "imageDisplay": "auto",
   "userIdsDisplay": "auto",
   "imageCustomizable": false,
   "name": "Welcome to CVG",
   "audioDisplay": "auto",
   "createdAt": "2016-05-25T15:38:34.925Z",
   "distributionListIds": [],
   "subjectCustomizable": false,
   "confirmationRequestIdCustomizable": false,
   "distributionListIdsCustomizable": true,
   "areaOfInterestIdsCustomizable": true,
   "collaborationGroupIdsCustomizable": true,
   "bodyDisplay": "auto",
   "confirmationRequestId": null,
   "collaborationGroupIdsDisplay": "auto",
   "alertToneDisplay": "auto",
   "userIdsCustomizable": true,
   "id": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
   "collaborationGroupIds": [],
   "bodyCustomizable": false,
   "imageMimeType": null,
   "distributionListIdsDisplay": "auto",
   "confirmationRequest": null,
   "audioSize": 0,
   "imageHash": null,
   "audioHash": null,
   "subjectDisplay": "auto",
   "audioCustomizable": false,
   "imageSize": 0,
   "body": "Welcome to the Cincinnati International Airport. Your comfort and safety are important to use and we work to keep you informed of all local events.",
   "userIds": [],
   "confirmationRequestIdDisplay": "auto",
   "alertToneCustomizable": false,
   "areaOfInterestIds": [],
   "metadata": {},
   "subject": "Welcome to Cincinnati!",
   "alertTone": "default",
   "areaOfInterestIdsDisplay": "auto",
   "metadataCustomizable": false
  },
  "name": "Arrive at CVG",
  "createdAt": "2016-05-25T15:40:02.358Z",
  "distributionListIds": [],
  "id": "f215963c-228e-11e6-a729-f95bf9c34bbf",
  "notificationAction": "send-to-user",
  "action": "entered",
  "distributionLists": [],
  "body": null,
  "userIds": [
   "e4e7860d-fb72-11e5-93a8-7b0393df5405"
  ],
  "subject": null,
  "users": [
   {
    "email": "marc.loy@singlewire.com",
    "name": "Marc Loy",
    "passwordResetRequired": false,
    "type": "regular",
    "loadSourceId": null,
    "id": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
    "createdAt": "2016-04-05T21:10:58.989Z"
   }
  ]
}

Retrieves a single boundary trigger by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /areas-of-interest/{aoiId}/boundary-triggers/{triggerId}

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area of interest.
triggerId The id of the trigger to retrieve.

Response

The boundary trigger response format is detailed here.

Create a Boundary Trigger

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Arrival Welcome',
    'action': 'entered',
    'per-user-throttling-in-secs': 300,
    'notification-action': 'send-to-user',
    'message-template-id': 'bdf85eab-228e-11e6-a729-513ce5b8ef20',
    'subject': 'Welcome to Cincinnati!'
}

try: 
    trigger = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(trigger)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Arrival Welcome", \
       "action": "entered", \
       "per-user-throttling-in-secs": 300, \
       "notification-action": "send-to-user", \
       "message-template-id": "bdf85eab-228e-11e6-a729-513ce5b8ef20", \
       "subject": "Welcome to Cincinnati!"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Arrival Welcome'
,
    'action': 'entered'
,
    'per-user-throttling-in-secs': 300
,
    'notification-action': 'send-to-user'
,
    'message-template-id': 'bdf85eab-228e-11e6-a729-513ce5b8ef20'
,
    'subject': 'Welcome to Cincinnati!'

}

begin: 
    trigger = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(trigger)
rescue StandardError => e
    puts e
{
  "perUserThrottlingInSecs": 300,
  "areaOfInterestId": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
  "permissions": [
   "delete",
   "put",
   "get"
  ],
  "messageTemplateId": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
  "messageTemplate": {
   "imageDisplay": "auto",
   "userIdsDisplay": "auto",
   "imageCustomizable": false,
   "name": "Welcome to CVG",
   "audioDisplay": "auto",
   "createdAt": "2016-05-25T15:38:34.925Z",
   "distributionListIds": [],
   "subjectCustomizable": false,
   "confirmationRequestIdCustomizable": false,
   "distributionListIdsCustomizable": true,
   "areaOfInterestIdsCustomizable": true,
   "collaborationGroupIdsCustomizable": true,
   "bodyDisplay": "auto",
   "confirmationRequestId": null,
   "collaborationGroupIdsDisplay": "auto",
   "alertToneDisplay": "auto",
   "userIdsCustomizable": true,
   "id": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
   "collaborationGroupIds": [],
   "bodyCustomizable": false,
   "imageMimeType": null,
   "distributionListIdsDisplay": "auto",
   "confirmationRequest": null,
   "audioSize": 0,
   "imageHash": null,
   "audioHash": null,
   "subjectDisplay": "auto",
   "audioCustomizable": false,
   "imageSize": 0,
   "body": "Welcome to the Cincinnati International Airport. Your comfort and safety are important to use and we work to keep you informed of all local events.",
   "userIds": [],
   "confirmationRequestIdDisplay": "auto",
   "alertToneCustomizable": false,
   "areaOfInterestIds": [],
   "metadata": {},
   "subject": "Welcome to Cincinnati!",
   "alertTone": "default",
   "areaOfInterestIdsDisplay": "auto",
   "metadataCustomizable": false
  },
  "name": "Welcome 3",
  "createdAt": "2016-05-25T17:51:16.446Z",
  "distributionListIds": [],
  "id": "476810c8-22a1-11e6-a729-bdd2c948c5a0",
  "notificationAction": "send-to-user",
  "action": "entered",
  "distributionLists": [],
  "body": null,
  "userIds": [],
  "subject": "Welcome to Cincinnati!",
  "users": []
}

Create a new Boundary Trigger.

HTTP Request

POST /areas-of-interest/{aoiId}/boundary-triggers

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area of interest.

Request Parameters

Parameter Type Default Description
action String N/A Option: entered, exited, both. Indicates if a notification should be sent out either when someone has entered or exited an area of interest.
body String N/A The body override of the Message Template
distribution­ListIds array[uuid] N/A When anyone from these Distribution lists crosses an area of interest, trigger this action.
message­TemplateId uuid N/A If a notification is being sent, the id of the Message Template to use.
name String N/A The trigger’s name. Maximum of 140 characters.
notification­Action String N/A Option: send-to-none, send-to-user, send-to-message-template-recipients. Indicates whether or not a notification should be sent out when someone has entered or exited an area of interest. The notication can be skipped, sent to the user, or to the recipients specified in the associated Message Template respectively.
perUser­Throttling­InSecs Integer N/A The amount of time that must pass before another boundary trigger will fire for that user.
subject String N/A The subject override of the Message Template
userIds array[uuid] N/A When any User from this list crosses an area of interest, trigger this action.

Response

The boundary trigger response format is detailed here.

Update a Boundary Trigger

# Continuing with the boundary trigger object
# from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/476810c8-22a1-11e6-a729-bdd2c948c5a0" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome 2016"}'
# Continuing with the boundary trigger object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
  "perUserThrottlingInSecs": 300,
  "areaOfInterestId": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
  "permissions": [
   "delete",
   "put",
   "get"
  ],
  "messageTemplateId": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
  "messageTemplate": {
   "imageDisplay": "auto",
   "userIdsDisplay": "auto",
   "imageCustomizable": false,
   "name": "Welcome to CVG",
   "audioDisplay": "auto",
   "createdAt": "2016-05-25T15:38:34.925Z",
   "distributionListIds": [],
   "subjectCustomizable": false,
   "confirmationRequestIdCustomizable": false,
   "distributionListIdsCustomizable": true,
   "areaOfInterestIdsCustomizable": true,
   "collaborationGroupIdsCustomizable": true,
   "bodyDisplay": "auto",
   "confirmationRequestId": null,
   "collaborationGroupIdsDisplay": "auto",
   "alertToneDisplay": "auto",
   "userIdsCustomizable": true,
   "id": "bdf85eab-228e-11e6-a729-513ce5b8ef20",
   "collaborationGroupIds": [],
   "bodyCustomizable": false,
   "imageMimeType": null,
   "distributionListIdsDisplay": "auto",
   "confirmationRequest": null,
   "audioSize": 0,
   "imageHash": null,
   "audioHash": null,
   "subjectDisplay": "auto",
   "audioCustomizable": false,
   "imageSize": 0,
   "body": "Welcome to the Cincinnati International Airport. Your comfort and safety are important to use and we work to keep you informed of all local events.",
   "userIds": [],
   "confirmationRequestIdDisplay": "auto",
   "alertToneCustomizable": false,
   "areaOfInterestIds": [],
   "metadata": {},
   "subject": "Welcome to Cincinnati!",
   "alertTone": "default",
   "areaOfInterestIdsDisplay": "auto",
   "metadataCustomizable": false
  },
  "name": "Welcome 2016",
  "createdAt": "2016-05-25T17:51:16.446Z",
  "distributionListIds": [],
  "id": "476810c8-22a1-11e6-a729-bdd2c948c5a0",
  "notificationAction": "send-to-user",
  "action": "entered",
  "distributionLists": [],
  "body": null,
  "userIds": [],
  "subject": "Welcome to Cincinnati!",
  "users": []
}

Updates an existing boundary trigger.

HTTP Request

PUT /areas-of-interest/{aoiId}/boundary-triggers/{triggerId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area of interest
triggerId The id of the trigger to update

Request Parameters

Parameter Type Default Description
action String N/A Option: entered, exited, both. Indicates if a notification should be sent out either when someone has entered or exited an area of interest.
body String N/A The body override of the Message Template
message­TemplateId uuid N/A If a notification is being sent, the id of the Message Template to use.
name String N/A The trigger’s name. Maximum of 140 characters.
notification­Action String N/A Option: send-to-none, send-to-user, send-to-message-template-recipients. Indicates whether or not a notification should be sent out when someone has entered or exited an area of interest. The notication can be skipped, sent to the user, or to the recipients specified in the associated Message Template respectively.
perUser­Throttling­InSecs Integer N/A The amount of time that must pass before another boundary trigger will fire for that user.
distribution­ListIds array[uuid] N/A When anyone from these Distribution lists crosses an area of interest, trigger this action.
subject String N/A The subject override of the Message Template
userIds array[uuid] N/A When any User from this list crosses an area of interest, trigger this action.

Response

The boundary trigger response format is detailed here.

Remove a Boundary Trigger

# Continuing with the boundary trigger object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/476810c8-22a1-11e6-a729-bdd2c948c5a0" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the boundary trigger object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted  476810c8-22a1-11e6-a729-bdd2c948c5a0"
}

Deletes an existing boundary trigger.

HTTP Request

DELETE /areas-of-interest/{aoiId}/boundary-triggers/{triggerId}

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area of interest
triggerId The id of the trigger to update

Response

The deletion response format is detailed here.

Boundary Trigger Response

The JSON document used to represent a User resource has the following content:

Attribute Type Description
action String Option: entered, exited, both. Indicates if a notification should be sent out either when someone has entered or exited an area of interest.
areaOf­InterestId uuid The id of the Area of Interest associated with this trigger.
body String The body override of the Message Template
distribution­ListIds array[uuid] When anyone from these Distribution lists crosses an area of interest, trigger this action.
id uuid The id of the user, for efficient retrieval, manipulation, or looking up sub-resources attached to the user.
message­Template Message Template The pre-fetched template, if one is being used.
message­TemplateId uuid If a notification is being sent, the id of the Message Template to use.
name String The trigger’s name. Maximum of 140 characters.
notification­Action String Option: send-to-none, send-to-user, send-to-message-template-recipients. Indicates whether or not a notification should be sent out when someone has entered or exited an area of interest. The notication can be skipped, sent to the user, or to the recipients specified in the associated Message Template respectively.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
perUser­Throttling­InSecs Integer The amount of time that must pass before another boundary trigger will fire for that user.
userIds array[uuid] When any User from this list crosses an area of interest, trigger this action.
subject String The subject override of the Message Template

AOI Boundary Trigger Activities

You can monitor boundary trigger events with Activities. Each activity entry includes the type of activity (enter or exit) and whether or not the triggered action was successful. Note that the activities represent a read-only log of triggered events and cannot themselves be altered or deleted.

List All Activities

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/86ac7740-22a0-11e6-a729-356099d3635b/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/86ac7740-22a0-11e6-a729-356099d3635b/activities?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/86ac7740-22a0-11e6-a729-356099d3635b/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 8,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
   {
    "id": "527910b5-2345-11e6-a729-0da433599b2c",
    "areaOfInterestId": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
    "boundaryTriggerId": "86ac7740-22a0-11e6-a729-356099d3635b",
    "reason": "exited",
    "status": "success",
    "device": {
     "deviceIdentifier": "simulator:63913053-1cfa-11e6-8356-774e67ffa4fc",
     "disabled": false,
     "name": "iPhone Simulator",
     "client": "",
     "createdAt": "2016-05-18T13:14:01.924Z",
     "type": "apns-sandbox",
     "build": "v2.9.0 D",
     "id": "63913053-1cfa-11e6-8356-774e67ffa4fc",
     "userId": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
     "os": "9.3",
     "user": {
      "id": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
      "name": "Marc Loy",
      "type": "regular",
      "email": "marc.loy@singlewire.com"
     }
    },
    "createdAt": "2016-05-26T13:25:32.476Z",
    "permissions": [
     "delete",
     "put",
     "get"
    ]
   }
  ]
}

Retrieves the list of all areas of interest.

HTTP Request

GET /areas-of-interest/{aoiId}/boundary-triggers/{triggerId}/activities

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the Area of Interest associated with the trigger being looked up.
triggerId The id of the Boundary Trigger whose activities are being looked up.

Query Parameters

To make this example more manageable, only the first user was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of eight areas available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The Activity response format is detailed here.

Get an Activity

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/86ac7740-22a0-11e6-a729-356099d3635b/activities/527910b5-2345-11e6-a729-0da433599b2c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    activity = requests.get(url, headers=headers).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/86ac7740-22a0-11e6-a729-356099d3635b/activities/527910b5-2345-11e6-a729-0da433599b2c" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/86ac7740-22a0-11e6-a729-356099d3635b/activities/527910b5-2345-11e6-a729-0da433599b2c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
{
  "id": "527910b5-2345-11e6-a729-0da433599b2c",
  "areaOfInterestId": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
  "boundaryTriggerId": "86ac7740-22a0-11e6-a729-356099d3635b",
  "reason": "exited",
  "status": "success",
  "device": {
   "deviceIdentifier": "simulator:63913053-1cfa-11e6-8356-774e67ffa4fc",
   "disabled": false,
   "name": "iPhone Simulator",
   "client": "",
   "createdAt": "2016-05-18T13:14:01.924Z",
   "type": "apns-sandbox",
   "build": "v2.9.0 D",
   "id": "63913053-1cfa-11e6-8356-774e67ffa4fc",
   "userId": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
   "os": "9.3",
   "user": {
    "id": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
    "name": "Marc Loy",
    "type": "regular",
    "email": "marc.loy@singlewire.com"
   }
  },
  "createdAt": "2016-05-26T13:25:32.476Z",
  "permissions": [
   "delete",
   "put",
   "get"
  ]
}

Retrieves a single AOI by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /areas-of-interest/{aoiId}/boundary-triggers/{triggerId}/activities/{activityId}

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the Area of Interest associated with the trigger being looked up.
triggerId The id of the Boundary Trigger associated with the activity being looked up.
activityId The id of the specific activity being looked up.

Response

The Activity response format is detailed here.

Area of Interest Response

The JSON document used to represent an Area of Interest resource has the following content:

Attribute Type Description
areaOfInterestId String The id of the area, for efficient retrieval, manipulation, or looking up sub-resources attached to the Area of Interest
boundaryTriggerId String The id of the boundary trigger, for efficient retrieval, manipulation, or looking up sub-resources attached to the Boundary Trigger
createdAt ISO 8601 date/time When this activity was created.
device Device The device that triggered the boundary condition.
id String The id of the activity
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
reason String Options: entered exited. Denotes the cause (entry/exit) of the trigger.
status String Options: success no-recipients. Denotes the success or failure of the triggered notification. Note that log-only triggers (notificationAction is send-to-none) are marked success upon activity creation.

Bell Schedules

Bell Schedules represent a weekly, bi-weekly, or tri-weekly cycle of daily event notifications. One can configure the date range within which a bell schedule is valid, the time zone for ring lists contained in this bell schedule, the number of weeks in a cycle, any ring lists with events set to fire on days within that cycle, and any exceptions on specific dates that may override the default ring list for that day in the cycle.

List all Bell Schedules

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    bell_schedules = requests.get(url, headers=headers, params=params).json()
    print(bell_schedules)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    bell_schedules = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(bell_schedules)
rescue StandardError => e
    puts e
{
  "total": 1,
  "previous": null,
  "next": null,
  "data": [
    {
      "description": "School Year 2017-2018",
      "bellScheduleExceptions": [
        {
          "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
          "description": "Snow Day",
          "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
          "startDate": "2018-01-03",
          "endDate": "2018-01-03",
          "ringListName": "Snow Day"
        }
      ],
      "timeZone": "America/Chicago",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "bellScheduleEntries": [
        {
          "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
          "entryNum": 0,
          "ringListName": "Monday"
        },
        {
          "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
          "entryNum": 1,
          "ringListName": "Tuesday"
        },
        {
          "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
          "entryNum": 2,
          "ringListName": "Wednesday"
        },
        {
          "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
          "entryNum": 3,
          "ringListName": "Thursday"
        },
        {
          "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
          "entryNum": 4,
          "ringListName": "Friday"
        }
      ],
      "name": "School Year 17-18",
      "startDate": "2017-08-28",
      "createdAt": "2018-05-31T20:18:35.635Z",
      "numWeeks": 1,
      "endDate": "2018-05-25",
      "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
    }
  ]
}

Retrieves a list of all bell schedules. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned.)

HTTP Request

GET /bell-schedules

Produces

application/json

Query Parameters

To make this example more manageable, only the first bell schedule was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of four available when the request was made. The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
assoc-sync-state Boolean If true, include the current synchronization state for fusion endpoints.
includeDomains Boolean If true, include the list of Domains to which each bell schedule belongs.

Response

The bell schedule response format is detailed here.

Get a Bell Schedule

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/37c1fe0a-4b9c-11e7-8148-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    bell_schedule = requests.get(url, headers=headers).json()
    print(bell_schedule)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/37c1fe0a-4b9c-11e7-8148-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/37c1fe0a-4b9c-11e7-8148-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    bell_schedule = JSON.parse(HTTParty.get(url, headers: headers))
    puts(bell_schedule)
rescue StandardError => e
    puts e
{
      "description": "School Year 2017-2018",
      "bellScheduleExceptions": [
        {
          "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
          "description": "Snow Day",
          "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
          "startDate": "2018-01-03",
          "endDate": "2018-01-03",
          "ringListName": "Snow Day"
        }
      ],
      "timeZone": "America/Chicago",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "bellScheduleEntries": [
        {
          "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
          "entryNum": 0,
          "ringListName": "Monday"
        },
        {
          "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
          "entryNum": 1,
          "ringListName": "Tuesday"
        },
        {
          "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
          "entryNum": 2,
          "ringListName": "Wednesday"
        },
        {
          "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
          "entryNum": 3,
          "ringListName": "Thursday"
        },
        {
          "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
          "entryNum": 4,
          "ringListName": "Friday"
        }
      ],
      "name": "School Year 17-18",
      "startDate": "2017-08-28",
      "createdAt": "2018-05-31T20:18:35.635Z",
      "numWeeks": 1,
      "endDate": "2018-05-25",
      "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
    }

Retrieves a single bell schedule by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /bell-schedules/{bellScheduleId}

Produces

application/json

Path Parameters

Parameter Description
bellScheduleId The id of the Bell Schedule to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the bell schedule belongs.

Response

The bell schedule response format is detailed here.

Create a Bell Schedule

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'School Year 17-18',
    'description': 'School Year 2017-2018',
    'startDate': '2017-08-28',
    'endDate': '2018-05-25',
    'timeZone': 'America/Chicago',
    'numWeeks': 1,
    'bellScheduleEntries': [{
        'entryNum': 0,
        'ringListId': 'f94d1622-6a65-11e8-9030-0d319c188f5d'
}
, {
        'entryNum': 1,
        'ringListId': '04e253b6-6a66-11e8-9030-055159f85cae'
}
, {
        'entryNum': 2,
        'ringListId': '0a5c4df9-6a66-11e8-9030-e5fd3c7e9500'
}
, {
        'entryNum': 3,
        'ringListId': '1140387c-6a66-11e8-9030-f52fea97f89c'
}
, {
        'entryNum': 4,
        'ringListId': '16240d3f-6a66-11e8-9030-bfa905b4cd81'
}
],
    'bellScheduleExceptions': [{
        'description': 'Snow Day',
        'ringListId': '68c1f806-650e-11e8-a57e-bf0edde4bce4',
        'startDate': '2018-01-03',
        'endDate': '2018-01-03'
}
]
}

try: 
    bell_schedule = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(bell_schedule)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "School Year 17-18", \
       "description": "School Year 2017-2018", \
       "startDate": "2017-08-28", \
       "endDate": "2018-05-25", \
       "timeZone": "America/Chicago", \
       "numWeeks": 1, \
       "bellScheduleEntries": [{"entryNum": 0, \
         "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d"}, {"entryNum": 1, \
         "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae"}, {"entryNum": 2, \
         "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500"}, {"entryNum": 3, \
         "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c"}, {"entryNum": 4, \
         "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81"}], \
       "bellScheduleExceptions": [{"description": "Snow Day", \
         "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4", \
         "startDate": "2018-01-03", \
         "endDate": "2018-01-03"}]}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'School Year 17-18'
,
    'description': 'School Year 2017-2018'
,
    'startDate': '2017-08-28'
,
    'endDate': '2018-05-25'
,
    'timeZone': 'America/Chicago'
,
    'numWeeks': 1
,
    'bellScheduleEntries': [{
        'entryNum': 0
,
        'ringListId': 'f94d1622-6a65-11e8-9030-0d319c188f5d'

}

, {
        'entryNum': 1
,
        'ringListId': '04e253b6-6a66-11e8-9030-055159f85cae'

}

, {
        'entryNum': 2
,
        'ringListId': '0a5c4df9-6a66-11e8-9030-e5fd3c7e9500'

}

, {
        'entryNum': 3
,
        'ringListId': '1140387c-6a66-11e8-9030-f52fea97f89c'

}

, {
        'entryNum': 4
,
        'ringListId': '16240d3f-6a66-11e8-9030-bfa905b4cd81'

}

]
,
    'bellScheduleExceptions': [{
        'description': 'Snow Day'
,
        'ringListId': '68c1f806-650e-11e8-a57e-bf0edde4bce4'
,
        'startDate': '2018-01-03'
,
        'endDate': '2018-01-03'

}

]

}

begin: 
    bell_schedule = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(bell_schedule)
rescue StandardError => e
    puts e
{
  "description": "School Year 2017-2018",
  "bellScheduleExceptions": [
    {
      "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
      "description": "Snow Day",
      "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
      "startDate": "2018-01-03",
      "endDate": "2018-01-03",
      "ringListName": "Snow Day"
    }
  ],
  "timeZone": "America/Chicago",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "bellScheduleEntries": [
    {
      "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
      "entryNum": 0,
      "ringListName": "Monday"
    },
    {
      "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
      "entryNum": 1,
      "ringListName": "Tuesday"
    },
    {
      "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
      "entryNum": 2,
      "ringListName": "Wednesday"
    },
    {
      "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
      "entryNum": 3,
      "ringListName": "Thursday"
    },
    {
      "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
      "entryNum": 4,
      "ringListName": "Friday"
    }
  ],
  "name": "School Year 17-18",
  "startDate": "2017-08-28",
  "createdAt": "2018-05-31T20:18:35.635Z",
  "numWeeks": 1,
  "endDate": "2018-05-25",
  "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
}

Creates a new bell schedule (limit: 3500). Once the schedule is created, it should begin firing at the next available time within the startDate and endDate.

HTTP Request

POST /bell-schedules

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the bell schedule.
description String null An optional description for the bell schedule.
startDate Date N/A The start date for your bell schedule in ISO 8601 YYYY-MM-DD format.
endDate Date N/A The end date for your bell schedule in ISO 8601 YYYY-MM-DD format.
timeZone String N/A A timezone such as “America/Chicago”. This list is too long to enumerate here.
numWeeks Integer N/A The number of weeks in a bell schedule. Value can only be 1, 2, or 3 which corresponds to a weekly, bi-weekly, or tri-weekly schedule respectively.
bellScheduleEntries Array[Object] [] An array of the configured ring list entries attached to a bell schedule. Please see here for detailed information about bell schedule entries.
bellScheduleExceptions Array[Object] [] An array of exceptions attached to the bell schedule. Please see here for detailed information about bell schedule exceptions.

Response

The bell schedule response format is detailed here.

Update a Bell Schedule

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'School Year 17-18',
    'description': 'School Year 2017-2018',
    'startDate': '2017-08-28',
    'endDate': '2018-05-25',
    'timeZone': 'America/Chicago',
    'numWeeks': 1,
    'bellScheduleEntries': [{
        'entryNum': 0,
        'ringListId': 'f94d1622-6a65-11e8-9030-0d319c188f5d'
}
, {
        'entryNum': 1,
        'ringListId': '04e253b6-6a66-11e8-9030-055159f85cae'
}
, {
        'entryNum': 2,
        'ringListId': '0a5c4df9-6a66-11e8-9030-e5fd3c7e9500'
}
, {
        'entryNum': 3,
        'ringListId': '1140387c-6a66-11e8-9030-f52fea97f89c'
}
, {
        'entryNum': 4,
        'ringListId': '16240d3f-6a66-11e8-9030-bfa905b4cd81'
}
],
    'bellScheduleExceptions': [{
        'description': 'Snow Day',
        'ringListId': '68c1f806-650e-11e8-a57e-bf0edde4bce4',
        'startDate': '2018-01-03',
        'endDate': '2018-01-03'
}
]
}

try: 
    bell_schedule = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(bell_schedule)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "School Year 17-18", \
       "description": "School Year 2017-2018", \
       "startDate": "2017-08-28", \
       "endDate": "2018-05-25", \
       "timeZone": "America/Chicago", \
       "numWeeks": 1, \
       "bellScheduleEntries": [{"entryNum": 0, \
         "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d"}, {"entryNum": 1, \
         "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae"}, {"entryNum": 2, \
         "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500"}, {"entryNum": 3, \
         "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c"}, {"entryNum": 4, \
         "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81"}], \
       "bellScheduleExceptions": [{"description": "Snow Day", \
         "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4", \
         "startDate": "2018-01-03", \
         "endDate": "2018-01-03"}]}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'School Year 17-18'
,
    'description': 'School Year 2017-2018'
,
    'startDate': '2017-08-28'
,
    'endDate': '2018-05-25'
,
    'timeZone': 'America/Chicago'
,
    'numWeeks': 1
,
    'bellScheduleEntries': [{
        'entryNum': 0
,
        'ringListId': 'f94d1622-6a65-11e8-9030-0d319c188f5d'

}

, {
        'entryNum': 1
,
        'ringListId': '04e253b6-6a66-11e8-9030-055159f85cae'

}

, {
        'entryNum': 2
,
        'ringListId': '0a5c4df9-6a66-11e8-9030-e5fd3c7e9500'

}

, {
        'entryNum': 3
,
        'ringListId': '1140387c-6a66-11e8-9030-f52fea97f89c'

}

, {
        'entryNum': 4
,
        'ringListId': '16240d3f-6a66-11e8-9030-bfa905b4cd81'

}

]
,
    'bellScheduleExceptions': [{
        'description': 'Snow Day'
,
        'ringListId': '68c1f806-650e-11e8-a57e-bf0edde4bce4'
,
        'startDate': '2018-01-03'
,
        'endDate': '2018-01-03'

}

]

}

begin: 
    bell_schedule = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(bell_schedule)
rescue StandardError => e
    puts e
{
  "description": "School Year 2017-2018",
  "bellScheduleExceptions": [
    {
      "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
      "description": "Snow Day",
      "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
      "startDate": "2018-01-03",
      "endDate": "2018-01-03",
      "ringListName": "Snow Day"
    }
  ],
  "timeZone": "America/Chicago",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "bellScheduleEntries": [
    {
      "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
      "entryNum": 0,
      "ringListName": "Monday"
    },
    {
      "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
      "entryNum": 1,
      "ringListName": "Tuesday"
    },
    {
      "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
      "entryNum": 2,
      "ringListName": "Wednesday"
    },
    {
      "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
      "entryNum": 3,
      "ringListName": "Thursday"
    },
    {
      "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
      "entryNum": 4,
      "ringListName": "Friday"
    }
  ],
  "name": "School Year 17-18",
  "startDate": "2017-08-28",
  "createdAt": "2018-05-31T20:18:35.635Z",
  "numWeeks": 1,
  "endDate": "2018-05-25",
  "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
}

Updates an existing bell schedule.

HTTP Request

PUT /bell-schedules/{bellScheduleId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
bellScheduleId The id of the Bell Schedule to update.

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the bell schedule.
description String null An optional description for the bell schedule.
startDate Date N/A The start date for your bell schedule in ISO 8601 YYYY-MM-DD format.
endDate Date N/A The end date for your bell schedule in ISO 8601 YYYY-MM-DD format.
timeZone String N/A A timezone such as “America/Chicago”. This list is too long to enumerate here.
numWeeks Integer N/A The number of weeks in a bell schedule. Value can only be 1, 2, or 3 which corresponds to a weekly, bi-weekly, or tri-weekly schedule respectively.
bellScheduleEntries Array[Object] [] An array of the configured ring list entries attached to a bell schedule. Please see here for detailed information about bell schedule entries.
bellScheduleExceptions Array[Object] [] An array of exceptions attached to the bell schedule. Please see here for detailed information about bell schedule exceptions.

Response

The bell schedule response format is detailed here.

Remove a Bell Schedule

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted cc01447c-650f-11e8-a57e-332c8cdd597f"
}

Deletes an existing bell schedule.

HTTP Request

DELETE /bell-schedules/{bellScheduleId}

Produces

application/json

Path Parameters

Parameter Description
bellScheduleId The id of the Bell Schedule to delete.

Response

The deletion response format is detailed here.

Bell Schedule Entries

Bell schedule entries are the configured ring list for a particular day within a rolling schedule. A bell schedule will respect the rolling schedule within the bounds of the bell schedules startDate and endDate.

For example: a bell schedule with numWeeks set to 1, and a startDate on a Wednesday will use the ring list entries in the following order: 2,3,4,5,6,0,1,2,3,4,5,6… These values correspond to the ring list entries entryNum.

A bell schedule entry does not have its own endpoint, and is strictly a nested resource within a bell schedule.

Attribute Type Description
ringListId String The id of the Ring List applied on entryNum day. If no rings are needed, this can be null.
ringListName String The name of the ring list applied on entryNum day. This is present in the response as a convenience, do not send it in a PUT or POST, it would be ignored.
entryNum Integer The day in a rolling schedule in which a ring list is applied. entryNum must be an integer between 0-20 which corresponds to a day in a rolling schedule. A rolling schedule can be one week (0-6), two weeks (0-13), or three weeks (0-20). Rolling schedules start on Monday, so 0 is the first Monday in the rolling schedule, 1 is the first Tuesday, etc.

Bell Schedule Exceptions

Bell schedule exceptions are overrides to one or more bell schedule entries attached to a bell schedule. For the dates bounded by the bell schedule exceptions startDate and endDate, the bell schedule will use the ring list defined in the bell schedule exception instead of the bell schedule entry.

A bell schedule exception does not have its own endpoint, and is strictly a nested resource within a bell schedule.

Attribute Type Description
id String The id of the Bell Schedule Exception.
description String null
ringListId String The id of the Ring List that overrides the bell schedule entries ring list between the bell schedule exception’s startDate and endDate. If no rings are needed, this can be null.
startDate Date The start date of the bell schedule exception in ISO 8601 YYYY-MM-DD format.
endDate Date The end date of the bell schedule exception in ISO 8601 YYYY-MM-DD format.
ringListName String The name of the ring list overriding the ring list of the bell schedule entry. This is present in the response as a convenience, do not send it in a PUT or POST, it would be ignored.

Bell Schedule Response

The JSON document used to represent a bell schedule resource has the following content:

Attribute Type Description
id String The id of this specific bell schedule, allowing it to be manipulated or retrieved individually.
name String The name of the bell schedule.
description String The description of the bell schedule.
numWeeks Integer The number of weeks in a bell schedule. Value can only be 1, 2, or 3 which corresponds to a weekly, bi-weekly, or tri-weekly schedule respectively.
startDate Date The start date of the bell schedule in ISO 8601 YYYY-MM-DD format.
endDate Date The end date of the bell schedule in ISO 8601 YYYY-MM-DD format.
timeZone String A timezone such as “America/Chicago”. This list is too long to enumerate here.
syncState Array[Object] The current endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
bellScheduleEntries Array[Object] An array of the configured ring list entries attached to a bell schedule. Please see here for detailed information about bell schedule entries.
bellScheduleExceptions Array[Object] An array of exceptions attached to the bell schedule. Please see here for detailed information about bell schedule exceptions.

Bell Schedule Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Bell Schedules are assigned to at least one Domain, and can be associated with more than one. This resource lets you see and adjust which Bell Schedules are assigned to which Domains.

List All Bell Schedule Domains

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "total": 2,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Vending",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
      "namePath": "/West Campus/Stadium/Vending/",
      "bellScheduleId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "bellScheduleId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Bell Schedule belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /bell-schedules/{bellScheduleId}/domains

Produces

application/json

Path Parameters

Parameter Description
bellScheduleId The id of the Bell Schedule whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Bell Schedule belonged to when the request was made, and both were returned. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the subdomains of any Domain attached to the specified Bell Schedule using a query parameter, and/or filter the results by matching on the Domain name:

Parameter Type Description
name String Returns only Domains whose names exactly match the supplied value.
recursive Boolean If true, in addition to Domains that are directly attached to the specified Bell Schedule, any subdomains will be returned.

Response

The domain response format is detailed here. Additionally, the id of the bell schedule whose domains were requested is returned under the key bellScheduleId inside each domain response.

Check if a Bell Schedule contains a Domain

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "bellScheduleId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Bell Schedule Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /bell-schedules/{bellScheduleId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
bellScheduleId The id of the Bell Schedule whose Domains are of interest.
id The id of the Domain you want to know whether the Bell Schedule belongs to.

Additionally, you can check if the Bell Schedule is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
recursive boolean If true, in addition to Domains that are directly attached to the specified Bell Schedule, any of their subdomains will be considered.

Response

If the Bell Schedule is part of the Domain (or its subdomains, if recursive is true), a response will be returned. The Domain response format is detailed here. If the list is not in the Domain, the response status will indicate that the requested resource cannot be found.

Add a Bell Schedule Domain

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "bellScheduleId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Bell Schedule into the specified Domain. As described below, this may be considered a promotion or demotion, which would require additional request parameters in order to validate.

HTTP Request

POST /bell-schedules/{bellScheduleId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
bellScheduleId String The id of the Bell Schedule to be added to the Domain.

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Bell Schedule out of a parent Domain?
id String n/a The id of the Domain to which the Bell Schedule should be added.
promote Boolean false Allow this request to proceed even if it will promote the Bell Schedule out of one or more child Domains?

A Bell Schedule is not allowed to be explicitly part of any Domain that it is implicitly granted membership to by belonging to a parent Domain. For example, if you take a Bell Schedule that is in Domains /West Campus/ and /East Campus/, and try to add it to /West Campus/Gym/ that request will fail because it is already implicitly in that domain through belonging to the parent /West Campus/ Domain. See the full explanation of promotion and demotion in the context of Domains and Users for more details and illustrations.

Remove a Bell Schedule Domain

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted Domain Bell Schedule c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Bell Schedule from the specified Domain. As described below, if this is the only Domain that the Bell Schedule currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Bell Schedule itself.

HTTP Request

DELETE /bell-schedules/{bellScheduleId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
bellScheduleId The id of the Bell Schedule whose Domain should be removed.
id The id of the Domain to be removed from the Bell Schedule.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Bell Schedule in no Domain.

A Bell Schedule must always belong to at least one Domain, so if you try to remove the Bell Schedule from the only Domain that it belongs to, the request must either fail, or delete the Bell Schedule. The request parameter orphans lets you control which of those takes place. The default, if you supply no instructions, is for the request to fail, and you will receive a validation error explaining why. If you pass a value of delete for the orphans request parameter, then taking a Bell Schedule out of its last Domain will delete the Bell Schedule.

Response

The deletion response format is detailed here.

Bell Schedules Bulk Exceptions

This resource is a shortcut for adding the same exception to multiple bell schedules in a single operation. It will adjust each schedule whose date ranges have any overlap with the exception to include the new exception in the appropriate place, shortening, removing, or splitting any existing exceptions which would have conflicted with the new one.

The only operation supported is POST.

Add an Exception to Multiple Bell Schedules

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules-bulk-exceptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'description': 'Snow Day',
    'startDate': '2021-02-04',
    'endDate': '2021-02-04',
    'ringListId': '68c1f806-650e-11e8-a57e-bf0edde4bce4',
    'bellScheduleIds': ['cc01447c-650f-11e8-a57e-332c8cdd597f', 'f94d1622-6a65-11e8-9030-0d319c188f5d']
}

try: 
    affected = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(affected)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules-bulk-exceptions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"description": "Snow Day", \
       "startDate": "2021-02-04", \
       "endDate": "2021-02-04", \
       "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4", \
       "bellScheduleIds": ["cc01447c-650f-11e8-a57e-332c8cdd597f", "f94d1622-6a65-11e8-9030-0d319c188f5d"]}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules-bulk-exceptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'description': 'Snow Day'
,
    'startDate': '2021-02-04'
,
    'endDate': '2021-02-04'
,
    'ringListId': '68c1f806-650e-11e8-a57e-bf0edde4bce4'
,
    'bellScheduleIds': ['cc01447c-650f-11e8-a57e-332c8cdd597f'
, 'f94d1622-6a65-11e8-9030-0d319c188f5d'
]

}

begin: 
    affected = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(affected)
rescue StandardError => e
    puts e
{
  "schedulesAffected": [
    {"id": "cc01447c-650f-11e8-a57e-332c8cdd597f",
     "name": "Pelham Elementary",
     "syncId": "cc01447c-650f-11e8-a57e-332c8cdd597f:1599612837889"},
    {"id": "f94d1622-6a65-11e8-9030-0d319c188f5d",
     "name": "Ridgemont High",
     "syncId": "f94d1622-6a65-11e8-9030-0d319c188f5d:1599610192210"}
  ]
}

Adds an exception with the specified date range and ring list (which can be null to suppress ringing entirely) to the specified bell schedules. In order to perform this operation the user must have POST permission to the /bell-schedules-bulk-exceptions resource but only needs GET permission to the ring list and bell schedules. This allows delegation of exception assignment without other bell schedule editing powers.

HTTP Request

POST /bell-schedules-bulk-exceptions

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
description String N/A A description for the exception to be added to each schedule.
startDate Date N/A The start date for the exception ISO 8601 YYYY-MM-DD format.
endDate Date N/A The end date for the exception in ISO 8601 YYYY-MM-DD format.
ringListId String null The id of the Ring List that overrides the bell schedule entries ring list between the exception’s startDate and endDate. If no rings are needed, this can be null.
bellScheduleIds Array of Strings N/A The ids of the Bell Schedules to which this exception should be added. If any schedule’s date range does not overlap the exception, it will be left unchanged. Required unless allBellSchedules is true.
allBellSchedules Boolean false If true, will apply the exception to all bell schedules, regardless of the value of bellScheduleIds.

Response

Information about the affected schedules is returned as a JSON document with a single attribute schedulesAffected attribute, which contains an array of objects with the following content:

Attribute Type Description
id String The id of a bell schedule to which the exception was added.
name String The name of the affected bell schedule.
syncId String The current sync ID of the bell schedule, which Fusion servers can use to verify their data is up to date.

Bell Schedule Cloning

This resource is used to make a copy of the Bell Schedule specified by id in the request path.

The only operation supported is POST.

Clone a Bell Schedule

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "description": "School Year 2017-2018",
  "bellScheduleExceptions": [
    {
      "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
      "description": "Snow Day",
      "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
      "startDate": "2018-01-03",
      "endDate": "2018-01-03",
      "ringListName": "Snow Day"
    }
  ],
  "timeZone": "America/Chicago",
  "permissions": [],
  "bellScheduleEntries": [
    {
      "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
      "entryNum": 0,
      "ringListName": "Monday"
    },
    {
      "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
      "entryNum": 1,
      "ringListName": "Tuesday"
    },
    {
      "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
      "entryNum": 2,
      "ringListName": "Wednesday"
    },
    {
      "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
      "entryNum": 3,
      "ringListName": "Thursday"
    },
    {
      "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
      "entryNum": 4,
      "ringListName": "Friday"
    }
  ],
  "name": "School Year 17-18 (Copy)",
  "startDate": "2017-08-28",
  "createdAt": "2018-05-31T20:19:35.635Z",
  "numWeeks": 1,
  "endDate": "2018-05-25",
  "id": "cd21447c-650f-11e8-a57e-111c8cdd59bb"
}

Creates a copy of the specified Bell Schedule. The name of the new copy is simply the original Bell Schedule’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /bell-schedules resource and GET permission to the Bell Schedule they wish to copy.

HTTP Request

POST /bell-schedules/{bellScheduleId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
bellScheduleId String The id of the Bell Schedule to copy.

Response

The Bell Schedule response format is detailed here.

Brandings

Provides access to Brandings resources for Fusion customers. Brandings provide a way to customize UI. One Branding can exist per Provider and are not ‘domainified’. Brandings are created when Providers are bootstrapped.

List All Brandings

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/brandings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    brandings = requests.get(url, headers=headers).json()
    print(brandings)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/brandings" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/brandings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    brandings = JSON.parse(HTTParty.get(url, headers: headers))
    puts(brandings)
rescue StandardError => e
    puts e
{
  "total": 1,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
    {
      "logo": "logoFile",
      "companyPhone": "+16085551212",
      "secondaryColor": "#123",
      "companyEmail": "bar@bazz.com",
      "primaryColor": "#456789",
      "companyName": "Foo",
      "customUrl": "https://www.quux.com"
    }
  ]
}

Retrieves a list of all Brandings.

HTTP Request

GET /brandings

Produces

application/json

Response

When a list is retrieved, the default response is wrapped in the pagination wrapper with totals, etc. This response example does not include the pagination wrapper.

Get a Branding

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/brandings/2601234b-a1e6-11ea-b7db-f3cc7d266a8e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    branding = requests.get(url, headers=headers).json()
    print(branding)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/brandings/2601234b-a1e6-11ea-b7db-f3cc7d266a8e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/brandings/2601234b-a1e6-11ea-b7db-f3cc7d266a8e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    branding = JSON.parse(HTTParty.get(url, headers: headers))
    puts(branding)
rescue StandardError => e
    puts e
{   
  "logo": "logoFile",
  "companyPhone": "+16085551212",
  "secondaryColor": "#123",
  "companyEmail": "bar@bazz.com",
  "primaryColor": "#456789",
  "companyName": "Foo",
  "customUrl": "https://www.quux.com"
}

Retrieves a single Branding by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /brandings/{id}

Produces

application/json

Path Parameters

Parameter Description
id The id of the Branding.

Response

The Brandings response format is detailed here.

Update a Branding

# Continuing with the branding object from
# the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/brandings/2601234b-a1e6-11ea-b7db-f3cc7d266a8e" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Changes to any branding"}'
# Continuing with the branding object from
# the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
{
 "logo": "logoFile",
 "companyPhone": "+16085551212",
 "secondaryColor": "#123",
 "companyEmail": "bar@bazz.com",
 "primaryColor": "#456789",
 "companyName": "Foo",
 "customUrl": "https://www.quux.com"
}

Updates an existing Branding.

HTTP Request

PUT /brandings/{id}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
Id The id of the Branding being altered.

Request Parameters

Name Type Required Doc
logo File false A logo file as a BMP, GIF, JPEG, PNG, TIF or TIFF.
primaryColor String false Hex color value for the Branding’s primary color.
secondaryColor String false Hex color value for the Branding’s secondary color.
companyName String false Name of the company that owns the Branding.
companyEmail String false The Branding contact’s email address.
companyPhone String false The Branding contact’s phone number.
customUrl String false A web link to custom help content for Brandings customers.

Response

The Brandings response format is detailed here.

Brandings Response

The JSON document used to represent a Brandings resource has the following content:

Attribute Type Description
permissions Array[String] Options: get put. What operations are possible on the Branding resource.
logo Integer Size of the logo for the Branding.
companyPhone String Company phone number.
createdAt ISO 8601 date/time When this Branding was created.
secondaryColor String The secondary color for the Branding. A Hex value like ’#abcdef’.
defaults Object An object including the default logo size, primary and secondary color for every Provider.
companyEmail String The saved company email value.
id UUID The unique identifier for a Branding.
primaryColor String The primary color for a Branding, a three- or six-character Hex value like ’#123’.
companyName String The name of the company associated with the Branding.
customUrl String An HTTP or HTTPS URL link to custom help content for the Branding.

Bulk Upload

The bulk upload endpoint is a moderately non-standard endpoint in the API. While its GET functionality is similar to that of other endpoints, its POST provides a URL to which .zip files can be delivered to an S3 bucket to proceed through the remainder of the bulk upload process.

List Bulk Uploads

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": true,
 "data": [
  {
   "directoryId": "e229c4ae-5f28-11ea-8aa8-053bf8c7b046",
   "permissions": [
    "delete",
    "get"
   ],
   "endpointId": "efea94d8-5f28-11ea-8aa8-4b0ddc9506ce",
   "status": "COMPLETE",
   "id": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
   "resourceType": "message-templates",
   "createdAt": "2020-03-05T21:33:21.670Z",
   "testMode": false
  }
 ]
}

Gets a list of all bulk uploads to the current user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Upload information is cleared daily, so records may not be retained.

HTTP Request

GET /bulk-upload

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Response

The bulk upload response format is detailed here.

Get a Bulk Upload Instance

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e

{
 "id": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
 "endpointId": "efea94d8-5f28-11ea-8aa8-4b0ddc9506ce",
 "directoryId": "e229c4ae-5f28-11ea-8aa8-053bf8c7b046",
 "createdAt": "2020-03-05T21:33:21.670Z",
 "testMode": false,
 "resourceType": "message-templates",
 "status": "COMPLETE",
 "permissions": [
  "delete",
  "get"
 ]
}

Retrieves a single bulk upload by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /bulk-upload/{bulkUploadId}

Produces

application/json

Path Parameters

Parameter Description
bulkUploadId The id of the bulk upload instance to retrieve.

Response

The bulk upload response format is detailed here.

Generate a POST URL

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'resourceType': 'message-templates'
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"resourceType": "message-templates"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'resourceType': 'message-templates'

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
 "url": "https://examplebucket.s3.us-east-2.amazonaws.com/40257fff-5f3b-11ea-8e69-21b3848f39e0.zip?x-amz-meta-resourcetype=message-templates&x-amz-meta-usebackup=true&x-amz-meta-endpointid=&x-amz-meta-directoryid=40257fff-5f3b-11ea-8e69-21b3848f39e0&x-amz-meta-testmode=true&x-amz-meta-provider=SarahFusion&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200305T234427Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=899&X-Amz-Credential=AKIAW7U2WXNLCHGMC6F7%2F20200305%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=998dc0cfd2d3ea43e2aee6faff4de4b17f8bf0b1d815b86f4de81276aff30691",
 "permissions": [
  "delete",
  "get"
 ]
}

Provides an authenticated URL to post a zip file to an S3 bucket.

HTTP Request

POST /bulk-upload

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
resourceType String N/A The type of resource to be bulk uploaded. The types currently supported are message-templates for Message Templates, Confirmation Requests (when appropriate), and Notification Profiles (when appropriate), device-groups for Device Groups (Fusion-only), ring-lists for Ring Lists, bell-schedules for Bell Schedules, dialing-configurations (a Fusion-only proxied resource), and speakers (another Fusion-only proxied resource).
endpointId String N/A The fusion server that the resource should be created on. Only used for proxied resources; these are currently speakers and dialing-configurations.

Response

Attribute Type Description
url String The url that points to the appropriate AWS S3 bucket.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Bulk Upload Response

The JSON document used to represent a Bulk Upload resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this bulk upload was initiated.
endpointId String The endpointId of the resource. Only exists for proxied resources (speakers).
id String The id of the bulk upload instance, for efficient retrieval, manipulation, or looking up sub-resources attached to the bulk upload.
resourceType String The resource type of the bulk upload. The types currently supported are message-templates for Message Templates, Confirmation Requests (when appropriate), and Notification Profiles (when appropriate), device-groups for Device Groups (Fusion-only), ring-lists for Ring Lists, bell-schedules for Bell Schedules, dialing-configurations (a Fusion-only proxied resource), and speakers (another Fusion-only proxied resource).
directoryId String The id of the directory in the S3 bucket associated with this resource.
testMode Boolean Whether or not the resources associated with the bulk upload were actually created or not.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Bulk Upload Commit

Bulk Upload Commit is called on an existing Bulk Upload instance. This can be used to create the resources associated with a test without needing to post resources to S3 again.

Commit a Bulk Upload Test

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/commit"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/commit" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/commit"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
{
 "id": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
 "endpointId": "efea94d8-5f28-11ea-8aa8-4b0ddc9506ce",
 "directoryId": "e229c4ae-5f28-11ea-8aa8-053bf8c7b046",
 "createdAt": "2020-03-05T21:33:21.670Z",
 "testMode": false,
 "resourceType": "message-templates",
 "status": "COMPLETE",
 "permissions": []
}

Takes an existing test bulk upload and commits the resources to the database.

HTTP Request

POST /bulk-upload/{bulkUploadId}/commit

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
bulkUploadId String N/A The id of the associated bulk upload.

Response

Attribute Type Description
id String The id of the associated bulk upload.
endpointId String The id of the endpoint to be committed to, if a proxied resource (speakers).
directoryId String The id of the directory in the S3 bucket associated with this resource.
createdAt ISO 8601 date/time When this bulk upload was initiated.
testMode Boolean Whether or not the bulk upload being committed had been committed previously.
resourceType String The resource type of the bulk upload. The types currently supported are message-templates for Message Templates, Confirmation Requests (when appropriate), and Notification Profiles (when appropriate), device-groups for Device Groups (Fusion-only), ring-lists for Ring Lists, bell-schedules for Bell Schedules, dialing-configurations (a Fusion-only proxied resource), and speakers (another Fusion-only proxied resource).
status String The status of the bulk upload being committed.
permissions Array[String] Which operations are possible on this resource, given the authentication token being used to access the API.

Bulk Upload Logs

Bulk Upload Logs are created to store information about each resource that is either created or ran as a test through a Bulk Upload.

List All Bulk Upload Logs

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/logs"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/logs" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/logs"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
{
 "total": 4,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "id": "f02d432c-5f28-11ea-8aa8-1569ae3ffa2c",
   "createdAt": "2020-03-05T21:33:22.108Z",
   "bulkUploadId": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
   "resourceCreated": true,
   "resourceName": "Example Hammer - Profile",
   "resourceResponse": null,
   "permissions": [
    "get"
   ]
  },
  {
   "id": "f02d432d-5f28-11ea-8aa8-c19ede5e8e35",
   "createdAt": "2020-03-05T21:33:22.108Z",
   "bulkUploadId": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
   "resourceCreated": false,
   "resourceName": "Example Hammer - Profile Desktop/IP Phone Display",
   "resourceResponse": "Must be a valid, six-digit hexadecimal color value e.g. #FFFFFF (mainWindow.backgroundColor), Must be one of the following values: Arial, ArialBlack, ComicSansMS, Courier, CourierNew, Georgia, Helvetica, Impact, Times, TimesNewRoman, TrebuchetMS, Verdana (mainWindow.subject.font), Must be one of the following values: 8, 9, 10, 11, 12, 14, 16, 18, 20, 24, 30 (mainWindow.subject.size)",
   "permissions": [
    "get"
   ]
  },
  {
   "id": "f02d432e-5f28-11ea-8aa8-d1a4866285e0",
   "createdAt": "2020-03-05T21:33:22.108Z",
   "bulkUploadId": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
   "resourceCreated": false,
   "resourceName": "Example Hammer - Profile Fusion Server",
   "resourceResponse": "One of the following files was missing from zip: mainAudio-40.wav, icon-40.jpg ()",
   "permissions": [
    "get"
   ]
  },
  {
   "id": "f02d6a3f-5f28-11ea-8aa8-47a83464eb34",
   "createdAt": "2020-03-05T21:33:22.108Z",
   "bulkUploadId": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
   "resourceCreated": true,
   "resourceName": "Example Hammer",
   "resourceResponse": null,
   "permissions": [
    "get"
   ]
  }
 ]
}

Gets a list of all bulk upload logs for a specific bulk upload instance to the current user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Upload information is cleared daily, so records may not be retained.

HTTP Request

GET /bulk-upload/{bulkUploadId}/logs

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
bulkUploadId String N/A The ID of the bulk upload the logs are associated with.

Response

The bulk upload response format is detailed here.

Get a Bulk Upload Instance

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/logs/f02d432c-5f28-11ea-8aa8-1569ae3ffa2c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/logs/f02d432c-5f28-11ea-8aa8-1569ae3ffa2c" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/bulk-upload/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/logs/f02d432c-5f28-11ea-8aa8-1569ae3ffa2c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e

{
 "id": "f02d432c-5f28-11ea-8aa8-1569ae3ffa2c",
 "createdAt": "2020-03-05T21:33:22.108Z",
 "bulkUploadId": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
 "resourceCreated": true,
 "resourceName": "Example Hammer - Profile",
 "resourceResponse": null,
 "permissions": [
  "get"
 ]
}

Retrieves a single bulk upload by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /bulk-upload/{bulkUploadId}/logs/{bulkUploadLogId}

Produces

application/json

Path Parameters

Parameter Description
bulkUploadId The id of the bulk upload log to retrieve.
bulkUploadLogId The id of the bulk upload instance log is associated with.

Response

The bulk upload response format is detailed here.

Bulk Upload Logs Response

The JSON document used to represent a Bulk Upload Log resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this bulk upload was initiated.
bulkUploadId String The id of the associated bulk upload instance.
id String The id of the bulk upload log, for efficient retrieval, manipulation, or looking up sub-resources attached to the bulk upload.
resourceCreated Boolean Whether or not the resource’s creation (or attempted creation) was successful.
resourceName String The name of the resource that was created (or attempted to be created).
resourceResponse String A string describing the response from the resource when it was created (or attempted to be created). This will be null on a success, but it will be a string of errors in the case of a failure.
permissions Array[String] Options: get. Which operations are possible on this resource, given the authentication token being used to access the API.

Collaboration Groups

Collaboration Groups serve as a means of initiating group conversations, such as via a conference call, a Cisco Webex Teams space, Twitter, Outbound CAP, and Outbound RSS. Other integrations will likely be added in the future.

Conference Call

A conference call collaboration group must define a Join PIN. This Join PIN will be sent to all of the collaboration group’s members’ text-capable devices, along with the conference call phone number to dial. The members’ phone-call devices will instead be called, and the person answering the call will be prompted to join the conference call without the need to enter a Join PIN.

Unless otherwise noted, conference calls can be joined via the campaign number defined in The Numbers Report (all outbound phone calls will originate from this number as well). A conference call based collaboration group can optionally be configured with a Create PIN or to Bypass IVR.

A Create PIN allows users to start the conference call by calling into the same number described above and entering a * followed by the Create PIN. When a Create PIN is specified and used in this way, calls are placed to the group’s phone-call devices, and a basic notification is sent to non-phone-call devices, giving them instructions on how to join the conference call. If no Create PIN is configured, users will not be able to start the collaboration group by calling, and will always need to do so by sending a Notification.

When Bypass IVR is selected in the collaboration group configuration, all phone-call devices will be dropped immediately into the conference call as soon as the call is answered. In other words, the users will not be prompted to join the call through an IVR (the default behavior). This holds true unless the user is asked to join multiple conference calls, in which case they would receive the IVR prompt regardless.

Cisco Webex Teams

A Cisco Webex Teams collaboration group two different modes: specificSpace and newSpace.

When a notification is sent to a newSpace, the Webex Teams integration will create a new Webex Teams space using the mandatory name field in newSpace.name. It will also suffix the name with a generated timestamp. Then, it will invite all of the users and distribution lists to join the Webex Teams space.

When a notification is sent to a specificSpace, it will invite the configured recipients to specificSpace.spaceId. Note that recipients are optional in this mode. Also, the InformaCast bot must be a member of this space.

To better construct the properties for these types of collaboration groups, please see the Webex Teams API .

Twitter

Twitter collaboration groups allow notifications to be sent as tweets for a specified Twitter account.

In order to create a Twitter collaboration group, you must specify the twitter collaboration group type and provide the required set of properties specified in the examples below.

Outbound CAP

Outbound CAP collaboration groups are used to reach endpoints that support receiving CAP notifications. Like outbound RSS collaboration groups, this is meant mostly for use with digital signage.

This particular variety of collaboration group has locations and connection configurations which allows for communication with endpoints that require authentication. Further, in order to further tailor notifications received by these endpoints, notification profiles can be used to send more information about any given notification to its CAP recipients.

Note that a connection configuration must be created in order to create an outbound CAP collaboration group. Likewise, when creating a collaboration group of this variety, ensure that you specify the outbound-cap collaboration group type.

Outbound RSS

Outbound RSS collaborations groups are meant to consume notifications and convert those into an RSS feed for consumption. This is primarily used for digital signage, which can take in RSS data and produce a feed of notifications that can be read by users.

When a new outbound RSS feed is created, a URL is generated. Based on selections during the creation process, this feed will either contain just the most recent message sent to the outbound RSS collaboration group or it will contain all the messages that have been sent to the feed. You may also disable the feed, which will prevent display, but will not stop notifications from being delivered to said feed.

In order to create an outbound RSS collaboration group, you must specify the outbound-rss collaboration group type, provide its view policy, and whether or not the feed is disabled.

Microsoft Teams

Using Microsoft Teams collaboration groups, send mass notifications to Teams channels. Collaboration groups do that by providing a collaboration group type, msteams-channel. Sending a notification to an msteams-channel collaboration group launches a notification to the corresponding Teams channel.

Type msteams-channel collaboration groups require InformaCast Fusion, the InformaCast bot must be added to a Microsoft Teams tenant and connected to a provider, and the Microsoft Teams Channel feature needs to be activated. Creating an msteams-channel collaboration group only works for teams that have a connected InformaCast bot.

Creating an msteams-channel collaboration group requires a unique set of request parameters, as seen in the example.

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'foo',
    'type': 'msteams-channel',
    'properties': {
        'channelId': 'bar',
        'channelName': 'bazz',
        'disabled': false,
        'teamId': 'buzz',
        'teamName': 'quux'
}

}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "foo", \
       "type": "msteams-channel", \
       "properties": {"channelId": "bar", \
         "channelName": "bazz", \
         "disabled": false, \
         "teamId": "buzz", \
         "teamName": "quux"}}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'foo'
,
    'type': 'msteams-channel'
,
    'properties': {
        'channelId': 'bar'
,
        'channelName': 'bazz'
,
        'disabled': false
,
        'teamId': 'buzz'
,
        'teamName': 'quux'

}


}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
{
  "total":1,
  "previous":null,
  "next":null,
  "partial":false,
  "data":[{
    "properties": {
        "channelId":"bar",
        "channelName":"bazz",
        "disabled":false,
        "teamId":"buzz",
        "teamName":"quux"
    },
    "permissions":["put","delete","get"],
    "name":"foo",
    "createdAt":"2021-01-13T12:00:00.000Z",
    "type":"msteams-channel",
    "distributionListIds":[],
    "id":"quuux",
    "distributionLists":[],
    "userIds":[],
    "users":[]}]
}

HTTP Request

POST /collaboration-groups

Request Parameters

Parameter Type Default Description
name String N/A The name to give the new collaboration group. May be up to 140 characters long.
type String N/A msteams-channel. Specifies the type of collaboration group.
properties[channelName] String N/A Required when type is msteams-channel.
properties[channelId] String N/A Required when type is msteams-channel.
properties[disabled] boolean N/A Required when type is msteams-channel.
properties[teamId] String N/A Required when type is msteams-channel.
properties[teamName] String N/A Required when type is msteams-channel.

Response

The collaboration group response format is detailed here.

Get All Collaboration Groups

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 3,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
    {
      "properties": {
        "joinPin": "1234",
        "createPin": null,
        "bypassIvr": false
      },
      "permissions": ["delete", "put", "get"],
      "name": "Security Officers",
      "createdAt": "2016-01-07T15:54:09.065Z",
      "type": "conference-call",
      "distributionListIds": ["3875f8ae-139c-11e6-9cd0-ef8b5b11547d"],
      "id": "e3579191-b556-11e5-ab29-bdfc7d2b6ed8",
      "distributionLists": [
        {
          "id": "3875f8ae-139c-11e6-9cd0-ef8b5b11547d",
          "name": "Security Officers",
          "campaign": null,
          "createdAt": "2016-05-06T15:07:16.446Z"
        }
      ],
      "userIds": [],
      "users": []
    },
    {
     "properties": {
      "mode": "specificSpace",
      "enableCreate": false,
      "specificSpace": {
       "spaceId": "Y2lzY29zcGFyazovL3VzL1JPT00vYjczY2Q2OTAtMmMyMS0xMWU3LTg4MjktMmRiY2EzYmYzMTE0"
      }
     },
     "permissions": ["delete", "put", "get"],
     "name": "Security Webex Team",
     "createdAt": "2017-04-13T13:21:56.273Z",
     "type": "cisco-spark",
     "distributionListIds": [],
     "id": "2a9e9ad1-204c-11e7-b964-8f83c5e03f72",
     "distributionLists": [],
     "userIds": [],
     "users": []
    },
    {
      "properties": {
       "handle": "acmeSchoolDistrict",
       "name": "Acme School District",
       "objectId": "1234567890123456789",
       "valid": true
       },
      "permissions": ["delete", "put", "get"],
      "name": "Acme School District Twitter Account",
      "createdAt": "2018-04-13T13:21:56.273Z",
      "type": "twitter",
      "distributionListIds": [],
      "id": "3aa99ad1-204c-22e7-b734-8f83c5e03f73",
      "distributionLists": [],
      "userIds": [],
      "users": []
    }
  ]
}

Gets a list of all collaboration groups available to the current user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Controlling access to collaboration groups allows administrators to decide with whom users can collaborate.)

HTTP Request

GET /collaboration-groups

Produces

application/json

Query Parameters

You can retrieve only collaboration groups of a specific type by adding a type query parameter whose value is the collaboration group type you are interested in. For example, to get only conference calls, ?type=conference-call.

To make this example more manageable, only the first collaboration group was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each collaboration group belongs.

Response

The collaboration group response format is detailed here.

Get One Collaboration Group

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
{
  "properties": {
    "joinPin": "1234",
    "createPin": null,
    "bypassIvr": false
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065Z",
  "type": "conference-call",
  "distributionListIds": ["3875f8ae-139c-11e6-9cd0-ef8b5b11547d"],
  "id": "e3579191-b556-11e5-ab29-bdfc7d2b6ed8",
  "distributionLists": [
    {
      "id": "3875f8ae-139c-11e6-9cd0-ef8b5b11547d",
      "name": "Security Officers",
      "campaign": null,
      "createdAt": "2016-05-06T15:07:16.446Z"
    }
  ],
  "userIds": [],
  "users": []
}

Retrieves a single collaboration group by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /collaboration-groups/{collaborationGroupId}

Produces

application/json

Path Parameters

Parameter Description
collaboration­GroupId The id of the collaboration group to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the collaboration group belongs.

Response

The collaboration group response format is detailed here.

Create a Collaboration Group

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Security Officers',
    'type': 'conference-call',
    'distributionListIds': ['3875f8ae-139c-11e6-9cd0-ef8b5b11547d'],
    'userIds': [],
    'properties': {
        'joinPin': '1234',
        'bypassIvr': false
}

}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Security Officers", \
       "type": "conference-call", \
       "distributionListIds": ["3875f8ae-139c-11e6-9cd0-ef8b5b11547d"], \
       "userIds": [], \
       "properties": {"joinPin": "1234", \
         "bypassIvr": false}}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Security Officers'
,
    'type': 'conference-call'
,
    'distributionListIds': ['3875f8ae-139c-11e6-9cd0-ef8b5b11547d'
]
,
    'userIds': []
,
    'properties': {
        'joinPin': '1234'
,
        'bypassIvr': false

}


}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
{
  "properties": {
    "joinPin": "1234",
    "createPin": null,
    "bypassIvr": false
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065Z",
  "type": "conference-call",
  "distributionListIds": ["3875f8ae-139c-11e6-9cd0-ef8b5b11547d"],
  "id": "e3579191-b556-11e5-ab29-bdfc7d2b6ed8",
  "distributionLists": [
    {
      "id": "3875f8ae-139c-11e6-9cd0-ef8b5b11547d",
      "name": "Security Officers",
      "campaign": null,
      "createdAt": "2016-05-06T15:07:16.446Z"
    }
  ],
  "userIds": [],
  "users": []
}

Creates a new collaboration group. As described above, depending on the nature of the group, user or distribution list IDs may need to be present in order for the group to be successfully created.

HTTP Request

POST /collaboration-groups

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A The name to give the new collaboration group. May be up to 140 characters long.
type String N/A Options: conference-call, cisco-spark, twitter, outbound-cap, outbound-rss or msteams-channel. Specifies the type of collaboration group.
distribution­ListIds Array[UUID] N/A A list of ids of Distribution Lists which should, by default, receive notifications based on this collaboration group.
user­Ids Array[UUID] N/A A list of ids of Users which should, by default, receive notifications based on this collaboration group.
proper­ties[bypassIvr] boolean N/A Optional when type is conference-call. Can be used to skip the IVR when there is only a single conference call to join for phone-call devices.
proper­ties[createPin] String N/A Optional when type is conference-call. Must be between 4 and 8 digits and be unique.
proper­ties[joinPin] String N/A Required when type is conference-call. Must be between 4 and 8 digits and be unique.
proper­ties[mode] String N/A Required when type is cisco-spark. Options: newSpace or specificSpace
proper­ties[newSpace][name] String N/A Required when type is cisco-spark and properties[mode] is newSpace. This is the prefix of the name of the Webex Teams space that will be created during send time.
proper­ties[specificSpace][spaceId] String N/A Required when type is cisco-spark and properties[mode] is specificSpace. This is the space id by which the notification will be posted to at send time.
proper­ties[accessToken] String N/A Required when type is twitter. This is the access token used for authenticating requests to twitter for the specified Twitter account.
proper­ties[accessTokenSecret] String N/A Required when type is twitter. This is the access token secret for the Twitter access token.
proper­ties[handle] String N/A Required when type is twitter. This is the Twitter account handle.
proper­ties[name] String N/A Required when type is twitter. This is the Twitter account name.
proper­ties[objectId] String N/A Required when type is twitter. This is the Twitter account ID.
proper­ties[valid] boolean N/A Required when type is twitter. This denotes whether the access token and access token secret are valid.
proper­ties[location] String N/A Required when type is outbound-cap. This is a description of the location of the event, which can be used by other systems for routing the CAP message to the correct location.
proper­ties[connection] String N/A The name of the connection configuration to use to send the CAP message. This value must match the name of a connection configuration defined on the Outbound CAP extension.
proper­ties[disabled] boolean N/A Required when type is outbound-rss.
proper­ties[displayPolicy] String N/A Required when type is outbound-rss. Must be either display-all or most-recent.

Response

The collaboration group response format is detailed here.

Update a Collaboration Group

# Continuing with the collaboration group object
# from the previous example:
try:
    list = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"joinPin": "865301", \
         "bypassIvr": true}}'
# Continuing with the collaboration group object
# from the previous example:
begin:
    list = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
{
  "properties": {
    "joinPin": "865301",
    "createPin": null,
    "bypassIvr": true
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065Z",
  "type": "conference-call",
  "distributionListIds": ["3875f8ae-139c-11e6-9cd0-ef8b5b11547d"],
  "id": "e3579191-b556-11e5-ab29-bdfc7d2b6ed8",
  "distributionLists": [
    {
      "id": "3875f8ae-139c-11e6-9cd0-ef8b5b11547d",
      "name": "Security Officers",
      "campaign": null,
      "createdAt": "2016-05-06T15:07:16.446Z"
    }
  ],
  "userIds": [],
  "users": []
}

Modifies the type or properties of a collaboration group.

HTTP Request

PUT /collaboration-groups/{collaborationGroupId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
collaborationGroupId The id of the collaboration group to update.

Request Parameters

Parameter Type Default Description
name String N/A The name to give the new collaboration group. May be up to 140 characters long.
type String N/A Options: conference-call, cisco-spark, twitter, outbound-cap, outbound-rss or msteams-channel. Specifies the type of collaboration group.
distribution­ListIds Array[UUID] N/A A list of ids of Distribution Lists which should, by default, receive notifications based on this collaboration group.
user­Ids Array[UUID] N/A A list of ids of Users which should, by default, receive notifications based on this collaboration group.
proper­ties[bypassIvr] boolean N/A Optional when type is conference-call. Can be used to skip the IVR when there is only a single conference call to join for phone-call devices.
proper­ties[createPin] String N/A Optional when type is conference-call. Must be between 4 and 8 digits and be unique.
proper­ties[joinPin] String N/A Required when type is conference-call. Must be between 4 and 8 digits and be unique.
proper­ties[mode] String N/A Required when type is cisco-spark. Options: newSpace or specificSpace
proper­ties[newSpace][name] String N/A Required when type is cisco-spark and properties[mode] is newSpace. This is the prefix of the name of the Webex Teams space that will be created during send time.
proper­ties[specificSpace][spaceId] String N/A Required when type is cisco-spark and properties[mode] is specificSpace. This is the space id by which the notification will be posted to at send time.
proper­ties[handle] String N/A Required when type is twitter. This is the Twitter account handle.
proper­ties[name] String N/A Required when type is twitter. This is the Twitter account name.
proper­ties[objectId] String N/A Required when type is twitter. This is the Twitter account ID.
proper­ties[valid] boolean N/A Required when type is twitter. This denotes whether the access token and access token secret are valid.
proper­ties[location] String N/A Required when type is outbound-cap. This is a description of the location of the event, which can be used by other systems for routing the CAP message to the correct location.
proper­ties[connection] String N/A The name of the connection configuration to use to send the CAP message. This value must match the name of a connection configuration defined on the Outbound CAP extension.
proper­ties[disabled] boolean N/A Required when type is outbound-rss.
proper­ties[displayPolicy] String N/A Required when type is outbound-rss. Must be either display-all or most-recent.

Response

The collaboration group response format is detailed here.

Remove a Collaboration Group

# Continuing with the collaboration group object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the collaboration group object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted {:name \"CollaborationGroups\"} e3579191-b556-11e5-ab29-bdfc7d2b6ed8"
}

Removes a collaboration group.

HTTP Request

DELETE /collaboration-groups/{collaborationGroupId}

Produces

application/json

Path Parameters

Parameter Description
collaborationGroupId The id of the collaboration group to delete.

Response

The deletion response format is detailed here.

Collaboration Group Response

The JSON document used to represent a collaboration group resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this collaboration group was created.
distribution­ListIds Array[String] The ids of the distribution lists which are members of the group.
distribution­Lists Array[DistributionList] The Distribution Lists that are members of the group.
id String The id of this specific collaboration group, allowing it to be manipulated or retrieved individually.
name String The collaboration group name. May be up to 140 characters long.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
type String Options: conference-call, cisco-spark, twitter, outbound-cap, outbound-rss or msteams-channel. Specifies the type of collaboration group.
userIds Array[String] The ids of the users which are members of the group.
users Array[User] The Users that are members of the group.
proper­ties[bypassIvr] boolean The conference call Skip IVR setting.
proper­ties[createPin] String The conference call Create PIN.
proper­ties[joinPin] String The conference call Join PIN.
proper­ties[mode] String The Cisco Webex Teams mode. Either newSpace or specificSpace.
proper­ties[newSpace][name] String The Webex Teams space name prefix of the Webex Teams space that will be created during send time.
proper­ties[specificSpace][spaceId] String The Webex Teams space id (that the InformaCast Bot belongs to) by which the notification will be posted to at send time.
proper­ties[handle] String The Twitter account handle.
proper­ties[name] String The Twitter account name.
proper­ties[objectId] String The Twitter account ID.
proper­ties[valid] boolean Whether the stored Twitter account tokens are valid.
proper­ties[location] String The Outbound CAP event location.
proper­ties[connection] String The name of the Outbound CAP connection configuration being used to send the CAP message.
proper­ties[disabled] boolean Whether or not the Outbound RSS feed is enabled/disabled.
proper­ties[displayPolicy] boolean The Outbound RSS feed display policy. Must be either display-all, which will show all active notifications in the feed, or most-recent, which will only show the most recent notification if it’s active, or an empty feed if the most recent notification is not active.

Collaboration Group Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Collaboration Groups are assigned to at least one Domain, and can be associated with more than one. This resource lets you see and adjust which Collaboration Groups are assigned to which Domains.

List All Collaboration Group Domains

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "total": 2,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Vending",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
      "namePath": "/West Campus/Stadium/Vending/",
      "collaborationGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "collaborationGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Collaboration Group belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /collaboration-groups/{collaborationGroupId}/domains

Produces

application/json

Path Parameters

Parameter Description
collaborationGroupId The id of the Collaboration Group whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Collaboration Group belonged to when the request was made, and both were returned. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the subdomains of any Domain attached to the specified Collaboration Group using a query parameter, and/or filter the results by matching on the Domain name:

Parameter Type Description
name String Returns only Domains whose names exactly match the supplied value.
recursive Boolean If true, in addition to Domains that are directly attached to the specified Collaboration Group, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the collaboration group whose domains were requested is returned under the key collaborationGroupId inside each domain response.

Check if a Collaboration Group contains a Domain

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "collaborationGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Collaboration Group Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /collaboration-groups/{collaborationGroupId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
collaborationGroupId The id of the Collaboration Group whose Domains are of interest.
id The id of the Domain you want to know whether the Collaboration Group belongs to.

Additionally, you can check if the Collaboration Group is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
recursive boolean If true, in addition to Domains that are directly attached to the specified Collaboration Group, any of their subdomains will be considered.

Response

If the Collaboration Group is part of the Domain (or its subdomains, if recursive is true), a response will be returned. The Domain response format is detailed here. If the list is not in the Domain, the response status will indicate that the requested resource cannot be found.

Add a Collaboration Group Domain

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "collaborationGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Collaboration Group into the specified Domain. As described below, this may be considered a promotion or demotion, which would require additional request parameters in order to validate.

HTTP Request

POST /collaboration-groups/{collaborationGroupId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
collaborationGroupId String The id of the Collaboration Group to be added to the Domain.

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Collaboration Group out of a parent Domain?
id String n/a The id of the Domain to which the Collaboration Group should be added.
promote Boolean false Allow this request to proceed even if it will promote the Collaboration Group out of one or more child Domains?

A Collaboration Group is not allowed to be explicitly part of any Domain that it is implicitly granted membership to by belonging to a parent Domain. For example, if you take a Collaboration Group that is in Domains /West Campus/ and /East Campus/, and try to add it to /West Campus/Gym/ that request will fail because it is already implicitly in that domain through belonging to the parent /West Campus/ Domain. See the full explanation of promotion and demotion in the context of Domains and Users for more details and illustrations.

Remove a Collaboration Group Domain

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted Domain Collaboration Group c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Collaboration Group from the specified Domain. As described below, if this is the only Domain that the Collaboration Group currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Collaboration Group itself.

HTTP Request

DELETE /collaboration-groups/{collaborationGroupId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
collaborationGroupId The id of the Collaboration Group whose Domain should be removed.
id The id of the Domain to be removed from the Collaboration Group.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Collaboration Group in no Domain.

A Collaboration Group must always belong to at least one Domain, so if you try to remove the Collaboration Group from the only Domain that it belongs to, the request must either fail, or delete the Collaboration Group. The request parameter orphans lets you control which of those takes place. The default, if you supply no instructions, is for the request to fail, and you will receive a validation error explaining why. If you pass a value of delete for the orphans request parameter, then taking a Collaboration Group out of its last Domain will delete the Collaboration Group.

Response

The deletion response format is detailed here.

Confirmation Requests

Confirmation requests provide a mechanism by which recipients of a Notification can be asked a question, with a list of options from which they may choose a response.

Confirmation requests may also have Escalation Rules attached to them, which can lead to further notifications being sent unless suitable responses are received within a specified time frame. Additionally, any Dynamic Replies attached may reply immediately to a confirmation response to provide confirmation feedback.

List All Confirmation Requests

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJoYWlsIiwiMzdmMGY1MDAtMWJlMC0xMWU0LTkxODEtM2M5NzBlN2ZmNTYwIl0=",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "escalationRules": [
        {
          "optionLabel": "Yes, I saw seen the intruder",
          "subject": "The intruder has been spotted!",
          "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
          "comparison": "LT",
          "image": null,
          "audio": null,
          "delay": 600,
          "comparisonValue": 5,
          "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
          "createdAt": "2014-08-11T14:03:45.434Z",
          "messageTemplateId": null,
          "body": "",
          "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
        }
      ],
      "dynamicReplies": [
        {
          "createdAt": "2014-08-11T14:17:48.343Z",
          "quota": 5,
          "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
          "id": "453b8e00-2162-11e4-986a-2707a9326e84",
          "optionLabel": "Yes, I saw the intruder",
          "first": "Let's get 'em, Gumshoes!",
          "rest": "Stand by. We're already on the case.",
          "every": null
        }
      ],
      "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-04T13:53:57.566Z",
      "expirationPeriod": 3600,
      "options": ["Yes, I saw the intruder", "No, I have not"],
      "initiateTrackingOptions": [true, false],
      "name": "Have you seen the intruder?"
    }
  ]
}

Retrieves all confirmation requests available to the user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Controlling access to confirmation requests allows administrators to decide which responses are available to notifications they send, although an even simpler approach is to tie an appropriate confirmation request to a Message Template and not allow it to be changed when sending notifications based on that template.)

HTTP Request

GET /confirmation-requests

Produces

application/json

Query Parameters

To make this example more concise, only the first confirmation request was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each confirmation request belongs.

Response

The confirmation request response format is detailed here.

Get a Confirmation Request

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    cr = requests.get(url, headers=headers).json()
    print(cr)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    cr = JSON.parse(HTTParty.get(url, headers: headers))
    puts(cr)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [
    {
      "optionLabel": "Yes, I saw the intruder",
      "subject": "The intruder has been spotted!",
      "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
      "comparison": "GT",
      "image": null,
      "audio": null,
      "delay": 600,
      "comparisonValue": 0,
      "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-11T14:03:45.434Z",
      "body": "",
      "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
    }
  ],
  "dynamicReplies": [
    {
      "createdAt": "2014-08-11T14:17:48.343Z",
      "quota": 5,
      "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "id": "453b8e00-2162-11e4-986a-2707a9326e84",
      "optionLabel": "Yes, I saw the intruder",
      "first": "Let's get 'em, Gumshoes!",
      "rest": "Stand by. We're already on the case.",
      "every": null
    }
  ],
  "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-04T13:53:57.566Z",
  "expirationPeriod": 3600,
  "options": ["Yes, I saw the intruder", "No, I have not"],
  "initiateTrackingOptions": [true, false],
  "name": "Have you seen the intruder?"
}

Retrieves a single confirmation request by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /confirmation-requests/{confirmationRequestId}

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the specific confirmation request to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this confirmation request belongs.

Response

The confirmation request response format is detailed here.

Create a Confirmation Request

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Are you safe?',
    'options': ['No, please call me!', 'Yes, I am safe.'],
    'initiate-tracking-options': [true, false]
}

try: 
    cr = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(cr)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Are you safe?", \
       "options": ["No, please call me!", "Yes, I am safe."], \
       "initiate-tracking-options": [true, false]}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Are you safe?'
,
    'options': ['No, please call me!'
, 'Yes, I am safe.'
]
,
    'initiate-tracking-options': [true
, false
]

}

begin: 
    cr = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(cr)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [ ],
  "createdAt": "2014-08-11T16:22:14.333Z",
  "id": "a7838ed0-2173-11e4-ba87-3c970e7ff560",
  "options": ["No, please call me!", "Atop Mount Olympus"],
  "initiateTrackingOptions": [true, false],
  "expirationPeriod": 36000,
  "name": "Are you safe?"
}

Creates a confirmation request

HTTP Request

POST /confirmation-requests

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A The name of the confirmation request, which is the prompt that will be presented to the user. May be up to 140 characters long, and should likely end with a question mark.
options Array[String] N/A A list of all the response choices that will be available to the recipient. At most 16 options may be provided.
initiate­Tracking­Options Array[boolean] N/A Matched with options you can specify which options should initiate tracking.
expiration­Period Integer 0 Duration in seconds for which the confirmation request will be active and responses will be accepted. Defaults to 0, which means the confirmation request is available to accept responses indefinitely.

Response

The confirmation request response format is detailed here.

Update a Confirmation Request

# Continuing with the confirmation request
# object from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/a7838ed0-2173-11e4-ba87-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Are you sure?", \
       "options": ["Yes, I am sure.", "No, I am not sure."]}'
# Continuing with the confirmation request
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [ ],
  "createdAt": "2014-08-11T16:22:14.333Z",
  "id": "a7838ed0-2173-11e4-ba87-3c970e7ff560",
  "options": ["Yes, I am sure.", "No, I am not sure."],
  "initiateTrackingOptions": [true, false],
  "expirationPeriod": 36000,
  "name": "Are you sure?"
}

Updates an existing confirmation request.

HTTP Request

PUT /confirmation-request/{confirmationRequestId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Required Default Description
confirmationRequestId true N/A The id of the confirmation request to update.

Request Parameters

Parameter Type Default Description
name String N/A The name of the confirmation request, which is the prompt that will be presented to the user. May be up to 140 characters long, and should likely end with a question mark.
options Array[String] N/A A list of all the response choices that will be available to the recipient. At most 16 options may be provided.
initiate­Tracking­Options Array[boolean] N/A Matched with options you can specify which options should initiate tracking.
expiration­Period Integer 0 Duration in seconds for which the confirmation request will be active and responses will be accepted. Defaults to 0, which means the confirmation request is available to accept responses indefinitely.

Response

The confirmation request response format is detailed here.

Remove a Confirmation Request

# Continuing with the confirmation request
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/a7838ed0-2173-11e4-ba87-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the confirmation request
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/a7838ed0-2173-11e4-ba87-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with confirmation request
# object from the previous example:
puts JSON.parse(icm_client.message_templates(cr['id']).delete)
{
  "status": 200,
  "message": "deleted {:name \"ConfirmationRequests\"} a7838ed0-2173-11e4-ba87-3c970e7ff560"
}

Removes a confirmation request

HTTP Request

DELETE /confirmation-requests/{confirmationRequestId}

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the confirmation request to delete.

Response

The deletion response format is detailed here.

Confirmation Request Response

The JSON document used to represent a confirmation request resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this confirmation request was created.
domains Array[Domain] When Domains are in use and includeDomains was true in your request, this response will list the Domains to which the confirmation request belongs.
escalation­Rules Array[Escalation­Rule] A list of Escalation Rules attached to this confirmation request, which determine post-response behavior.
dynamic­Replies Array[Dynamic­Reply] A list of Dynamic Replies attached to this confirmation request, which determine immediate reply behavior.
expiration­Period Integer The time in seconds after a notification is sent when this confirmation request expires and no longer accepts responses.
id String The id of this specific confirmation request, allowing it to be manipulated or retrieved individually, and providing access to its Escalation Rules.
name String The name of the confirmation request, which is the prompt that will be presented to the user. May be up to 140 characters long, and should likely end with a question mark.
options Array[String] A list of all the response choices that will be available to the recipient. At most 16 options may be present.
initiateTrackingOptions Array[boolean] Matched with options you can specify which options should initiate tracking.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Confirmation Request Cloning

This resource is used to make a copy of the Confirmation Request specified by id in the request path.

The only operation supported is POST.

Clone a Confirmation Request

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
{
    "dynamicReplies": [],
    "permissions": [],
    "initiateTrackingOptions": [
        false,
        false
    ],
    "escalationRules": [],
    "name": "Health Check - Status (Copy)",
    "createdAt": "2021-07-23T15:24:31.663Z",
    "expirationPeriod": null,
    "id": "14038c65-ebca-11eb-81b3-fdb244340480",
    "options": [
        "I am OK",
        "I am sick"
    ]
}

Creates a copy of the specified Confirmation Request. The name of the new copy is simply the original Confirmation Request’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /confirmation-requests resource and GET permission to the Confirmation Request they wish to copy.

HTTP Request

POST /confirmation-requests/{confirmationRequestId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
confirmationRequestId String The id of the Confirmation Request to copy.

Response

The confirmation request response format is detailed here.

Confirmation Request Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Confirmation Requests are assigned to at least one Domain, and can be associated with more than one. This resource lets you see and adjust which Confirmation Requests are assigned to which Domains.

List All Confirmation Request Domains

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "total": 2,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Vending",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
      "namePath": "/West Campus/Stadium/Vending/",
      "confirmationRequestId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "confirmationRequestId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Confirmation Request belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /confirmation-requests/{confirmationRequestId}/domains

Produces

application/json

Path Parameters

Parameter Description
confirmation­RequestId The id of the Confirmation Request whose associated Domains are to be listed.

Query Parameters

In this example, there were a total of 2 Domains that the specified Confirmation Request belonged to when the request was made, and both were returned. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the subdomains of any Domain attached to the specified Confirmation Request using a query parameter, and/or filter the results by matching on the Domain name:

Parameter Type Description
name String Returns only Domains whose names exactly match the supplied value.
recursive Boolean If true, in addition to Domains that are directly attached to the specified Confirmation Request, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the confirmation request whose domains were requested is returned under the key confirmationRequestId inside each domain response.

Check if a Confirmation Request contains a Domain

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "confirmationRequestId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Confirmation Request Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /confirmation requests/{confirmationRequestId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
confirmation­RequestId The id of the Confirmation Request whose Domains are of interest.
id The id of the Domain you want to know whether the Confirmation Request belongs to.

Additionally, you can check if the Confirmation Request is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
recursive boolean If true, in addition to Domains that are directly attached to the specified Confirmation Request, any of their subdomains will be considered.

Response

If the Confirmation Request is part of the Domain (or its subdomains, if recursive is true), a response will be returned. The Domain response format is detailed here. If the list is not in the Domain, the response status will indicate that the requested resource cannot be found.

Add a Confirmation Request Domain

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "confirmationRequestId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Confirmation Request into the specified Domain. As described below, this may be considered a promotion or demotion, which would require additional request parameters in order to validate.

HTTP Request

POST /confirmation requests/{confirmationRequestId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
confirmation­RequestId String The id of the Confirmation Request to be added to the Domain.

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Confirmation Request out of a parent Domain?
id String n/a The id of the Domain to which the Confirmation Request should be added.
promote Boolean false Allow this request to proceed even if it will promote the Confirmation Request out of one or more child Domains?

A Confirmation Request is not allowed to be explicitly part of any Domain that it is implicitly granted membership to by belonging to a parent Domain. For example, if you take a Confirmation Request that is in Domains /West Campus/ and /East Campus/, and try to add it to /West Campus/Gym/ that request will fail because it is already implicitly in that domain through belonging to the parent /West Campus/ Domain. See the full explanation of promotion and demotion in the context of Domains and Users for more details and illustrations.

Remove a Confirmation Request Domain

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted Domain Confirmation Request c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Confirmation Request from the specified Domain. As described below, if this is the only Domain that the Confirmation Request currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Confirmation Request itself.

HTTP Request

DELETE /confirmation-requests/{confirmationRequestId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
confirmationRequestId The id of the Confirmation Request whose Domain should be removed.
id The id of the Domain to be removed from the Confirmation Request.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Confirmation Request in no Domain.

A Confirmation Request must always belong to at least one Domain, so if you try to remove the Confirmation Request from the only Domain that it belongs to, the request must either fail, or delete the Confirmation Request. The request parameter orphans lets you control which of those takes place. The default, if you supply no instructions, is for the request to fail, and you will receive a validation error explaining why. If you pass a value of delete for the orphans request parameter, then taking a Confirmation Request out of its last Domain will delete the Confirmation Request.

Response

The deletion response format is detailed here.

Dynamic Replies

Dynamic replies provide a way to cause a text reply to be immediately sent when a user responds to a Notification with attached Confirmation Requests.

List All Dynamic Replies

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
     "createdAt": "2020-10-14T22:49:39.332Z",
     "quota": 5,
     "confirmationRequestId": "0a6b60a0-0e4a-11eb-986a-55883885ddfb",
     "id": "8a88ecd8-0e6f-11eb-986a-2707a9326e84",
     "optionLabel": "I need assistance",
     "first": "Help is on the way!",
     "rest": "Uh oh.",
     "every": null
    }
  ]
}

This configuration means that the first 5 responses received that confirm with I need assistance will immediately receive a text reply saying Help is on the way!. Any additional confirmation responses (sixth and subsequent people) who respond I need assistance will immediately receive the text reply Uh oh.

Retrieves a list of the dynamic replies attached to a specific Confirmation Request.

HTTP Request

GET /confirmation-requests/{confirmationRequestId}/dynamic-replies

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the confirmation request whose dynamic replies are being examined.

Query Parameters

To make this example more concise, only the first dynamic reply was requested using the API’s pagination parameters. The response reflects this, although in this case there was in fact only one dynamic reply available. The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The dynamic reply response format is detailed here.

Get a Dynamic Reply

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies/8a88ecd8-0e6f-11eb-986a-2707a9326e84"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    reply = requests.get(url, headers=headers).json()
    print(reply)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies/8a88ecd8-0e6f-11eb-986a-2707a9326e84" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies/8a88ecd8-0e6f-11eb-986a-2707a9326e84"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    reply = JSON.parse(HTTParty.get(url, headers: headers))
    puts(reply)
rescue StandardError => e
    puts e
{
 "permissions": ["put", "delete", "get"],
 "createdAt": "2020-10-14T22:49:39.332Z",
 "quota": 5,
 "confirmationRequestId": "0a6b60a0-0e4a-11eb-986a-55883885ddfb",
 "id": "8a88ecd8-0e6f-11eb-986a-2707a9326e84",
 "optionLabel": "I need assistance",
 "first": "Help is on the way!",
 "every": null,
 "rest": "Uh oh."
}

Retrieves a particular dynamic reply based on its id and the id of its confirmation request. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /confirmation-requests/{confirmationRequestId}/dynamic-replies/{id}

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request that contains this dynamic reply.
id The id of the specific dynamic reply to retrieve.

Response

The dynamic reply response format is detailed here.

Create a Dynamic Reply

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'optionLabel': 'I am safe: outside building',
    'every': 'Get inside!'
}

try: 
    reply = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(reply)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"optionLabel": "I am safe: outside building", \
       "every": "Get inside!"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'optionLabel': 'I am safe: outside building'
,
    'every': 'Get inside!'

}

begin: 
    reply = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(reply)
rescue StandardError => e
    puts e
{
 "confirmationRequestId": "0a6b60a0-0e4a-11eb-986a-55883885ddfb",
 "id": "254ee0b1-12ec-11eb-b89c-b1714049c798",
 "optionLabel": "I am safe: outside building",
 "createdAt": "2020-10-20T15:51:41.244Z",
 "every": "Get inside!",
 "permissions": ["put", "delete", "get"]
}

This reply will be sent whenever a confirmation response of I am safe: outside building is received and will say Get inside!

Adds a trigger to be immediately sent when a user responds to a Notification with a Confirmation Request specifically matching the expected optionLabel field.

HTTP Request

POST /confirmation-requests/{confirmationRequestId}/dynamic-replies

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request to which the dynamic reply should be attached.

Request Parameters

Parameter Type Description
optionLabel String Which confirmation response option to reply to
quota Integer (Required for quota-based replies only) The first quota respondents will receive the first reply text. All others will receive the rest text.
first String Can only be used when a quota and rest are specified. The text with which to immediately reply to the first quota respondents.
rest String Once quota number of respondents have confirmed with the optionLabel specified, we reply with the rest text to all subsequent confirmations of that optionLabel option.
every String Used without quota, first or rest, to reply in the same way to all matching confirmation responses.

Response

The dynamic reply response format is detailed here.

Update a Dynamic Reply

# Continuing with the dynamic reply object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies/254ee0b1-12ec-11eb-b89c-b1714049c798" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"optionLabel": "I am safe: outside the building", \
       "every": "All Clear: Everyone can return to the building."}'
# Continuing with the dynamic reply object
# from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
{
   "confirmationRequestId": "0a6b60a0-0e4a-11eb-986a-55883885ddfb",
   "id": "254ee0b1-12ec-11eb-b89c-b1714049c798",
   "createdAt": "2020-10-20T15:51:41.244Z",
   "optionLabel": "I am safe: outside building",
   "every": "All Clear: Everyone can return to the building.",
   "permissions": ["put", "delete", "get"]
}

Modifies an existing dynamic reply.

HTTP Request

PUT /confirmation-request/{confirmationRequestId}/dynamic-replies/{id}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request to which the dynamic reply is attached.
id The id of the specific dynamic reply to update.

Request Parameters

Parameter Type Description
optionLabel String Which confirmation response option to reply to
quota Integer (Required for quota-based replies only) The first quota respondents will receive the first reply text. All others will receive the rest text.
first String Can only be used when a quota and rest are specified. The text with which to immediately reply to the first quota respondents.
rest String Once quota number of respondents have confirmed with the optionLabel specified, we reply with the rest text to all subsequent confirmations of that optionLabel option.
every String Used without quota, first or rest, to reply in the same way to all matching confirmation responses.

Response

The dynamic reply response format is detailed here.

Delete a Dynamic Reply

# Continuing with the dynamic reply object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies/254ee0b1-12ec-11eb-b89c-b1714049c798" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the dynamic reply object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted {:name \"ConfirmationRequestDynamicReply\"} 254ee0b1-12ec-11eb-b89c-b1714049c798"
}

Removes a dynamic reply from a confirmation request.

HTTP Request

DELETE /confirmation-requests/{confirmationRequestId}/dynamic-replies/{id}

Produces

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request to which the dynamic reply is attached.
id The id of the specific dynamic reply to delete.

Response

The deletion response format is detailed here.

Dynamic Reply Response

The JSON document used to represent an dynamic reply resource has the following content:

Attribute Type Description
id String The id of this specific dynamic reply, allowing it to be manipulated or retrieved individually.
optionLabel String Which confirmation response option to reply to
quota Integer (Required for quota-based replies only) The first quota respondents will receive the first reply text. All others will receive the rest text.
first String Can only be used when a quota and rest are specified. The text with which to immediately reply to the first quota respondents.
rest String Once quota number of respondents have confirmed with the optionLabel specified, we reply with the rest text to all subsequent confirmations of that optionLabel option.
every String Used without quota, first or rest, to reply in the same way to all matching confirmation responses.

Escalation Rules

Escalation rules provide a way to cause followup messages to be automatically sent some time after a Notification, depending on the kinds of responses that have been made to an attached Confirmation Request.

List All Escalation Rules

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "optionLabel": "Yes, I have seen the intruder",
      "subject": "The intruder has been spotted!",
      "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
      "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"],
      "comparison": "GT",
      "image": null,
      "audio": null,
      "delay": 600,
      "comparisonValue": 0,
      "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-11T14:03:45.434Z",
      "permissions": ["delete", "put", "get"],
      "body": "",
      "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
    }
  ]
}

This rule will cause a notification saying The intruder has been spotted! to be sent out ten minutes after the original notification, as long as at least one recipient has responded Yes, I have seen the intruder.

Retrieves a list of the escalation rules attached to a specific Confirmation Request.

HTTP Request

GET /confirmation-requests/{confirmationRequestId}/escalation-rules

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the confirmation request whose escalation rules are being examined.

Query Parameters

To make this example more concise, only the first escalation rule was requested using the API’s pagination parameters. The response reflects this, although in this case there was in fact only one escalation rule available. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The escalation rule response format is detailed here.

Get an Escalation Rule

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules/4f062fa0-2160-11e4-ba87-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    rule = requests.get(url, headers=headers).json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules/4f062fa0-2160-11e4-ba87-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules/4f062fa0-2160-11e4-ba87-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    rule = JSON.parse(HTTParty.get(url, headers: headers))
    puts(rule)
rescue StandardError => e
    puts e
{
  "optionLabel": "Yes, I have seen the intruder",
  "subject": "The intruder has been spotted!",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"],
  "comparison": "GT",
  "image": null,
  "audio": null,
  "delay": 600,
  "comparisonValue": 0,
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-11T14:03:45.434Z",
  "messageTemplateId": null,
  "permissions": ["delete", "put", "get"],
  "body": "",
  "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
}

Retrieves a particular escalation rule based on its id and the id of its confirmation request. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /confirmation-requests/{confirmationRequestId}/escalation-rules/{id}

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request that contains this escalation rule.
id The id of the specific escalation rule to retrieve.

Response

The escalation rule response format is detailed here.

Create an Escalation Rule

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'comparisonValue': 1,
    'comparison': 'LT',
    'delay': 3600,
    'optionLabel': 'Yes, I have seen the intruder',
    'subject': 'Still no sightings',
    'distributionListIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff560'],
    'deviceGroupIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff561']
}

try: 
    rule = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"comparisonValue": 1, \
       "comparison": "LT", \
       "delay": 3600, \
       "optionLabel": "Yes, I have seen the intruder", \
       "subject": "Still no sightings", \
       "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"], \
       "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"]}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'comparisonValue': 1
,
    'comparison': 'LT'
,
    'delay': 3600
,
    'optionLabel': 'Yes, I have seen the intruder'
,
    'subject': 'Still no sightings'
,
    'distributionListIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff560'
]
,
    'deviceGroupIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff561'
]

}

begin: 
    rule = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(rule)
rescue StandardError => e
    puts e
{
  "optionLabel": "Yes, I have seen the intruder",
  "subject": "Still no sightings",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"],
  "comparison": "LT",
  "image": null,
  "audio": null,
  "delay": 3600,
  "comparisonValue": 1,
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-11T19:26:58.885Z",
  "permissions": ["delete", "put", "get"],
  "body": null,
  "id": "766bf750-218d-11e4-ba87-3c970e7ff560"
}

This rule will cause a notification saying Still no sightings to be sent out one hour after the original notification, as long as no recipients have responded Yes, I have seen the intruder.

Adds a trigger to be evaluated when a certain amount of time has elapsed since sending a Notification with a Confirmation Request. At that time, the responses which have been received to the confirmation request are compared with the escalation rule, and if the rule is matched, a followup notification is sent.

HTTP Request

POST /confirmation-requests/{confirmationRequestId}/escalation-rules

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request to which the escalation rule should be attached.

Request Parameters

Parameter Type Description
audio Blob Audio content to be sent if the rule triggers. Binary stream of audio in μ-law format. The size of the audio and image data combined must not exceed 10 MiB.
body String Optional detailed body text to be sent if the rule triggers. This may be up to 10,000 characters long.
comparison String Options: GT, LT, EQ, NE. Controls the type of comparison to be performed between the number of responses which match optionLabel and the value of comparisonValue. The rule will trigger if this comparison result is greater than, less than, equal, or not equal, respectively.
comparison­Value Integer The value to which the number of responses matching optionLabel should be compared.
delay Integer The number of seconds after sending the notification at which this rule should be evaluated. At that time, the number of responses matching optionLabel is compared with comparisonValue, and if the relationship is as described by comparison, this rule causes a new notification to be sent.
distribution­ListIds Array[String] The ids of the Distribution Lists to which this escalation message will be sent if the rule matches when delay has elapsed since sending the original notification.
device­GroupIds Array[String] The ids of the Device Groups to which this escalation message will be sent if the rule matches when delay has elapsed since sending the original notification.
image Blob Binary stream of an image to be sent if the rule triggers. The size of the image and audio data combined must not exceed 10 MiB.
optionLabel String The Confirmation Request option to be counted when delay has elapsed and the rule triggers. The number of user responses matching this value is compared with comparisonValue, and if their relationship is as described by comparison, the escalation message is sent.
subject String The subject to use for the escalation message which is sent if this rule is triggered.

Response

The escalation rule response format is detailed here.

Update an Escalation Rule

# Continuing with the escalation rule object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules/766bf750-218d-11e4-ba87-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"comparisonValue": 0, \
       "comparison": "GT", \
       "delay": 3600, \
       "optionLabel": "No, I have not", \
       "subject": "We have at least one negative response.", \
       "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"], \
       "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"]}'
# Continuing with the escalation rule object
# from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
{
  "optionLabel": "No, I have not",
  "subject": "We have at least one negative response.",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"],
  "comparison": "GT",
  "image": null,
  "audio": null,
  "delay": 3600,
  "comparisonValue": 0,
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-11T19:26:58.885Z",
  "messageTemplateId": null,
  "permissions": ["delete", "put", "get"],
  "body": null,
  "id": "766bf750-218d-11e4-ba87-3c970e7ff560"
}

Modifies an existing escalation rule.

HTTP Request

PUT /confirmation-request/{confirmationRequestId}/escalation-rules/{id}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request to which the escalation rule is attached.
id The id of the specific escalation rule to update.

Request Parameters

Parameter Type Description
audio Blob Audio content to be sent if the rule triggers. Binary stream of audio in μ-law format. The size of the audio and image data combined must not exceed 10 MiB.
body String Optional detailed body text to be sent if the rule triggers. This may be up to 10,000 characters long.
comparison String Options: GT, LT, EQ, NE. Controls the type of comparison to be performed between the number of responses which match optionLabel and the value of comparisonValue. The rule will trigger if this comparison result is greater than, less than, equal, or not equal, respectively.
comparison­Value Integer The value to which the number of responses matching optionLabel should be compared.
delay Integer The number of seconds after sending the notification at which this rule should be evaluated. At that time, the number of responses matching optionLabel is compared with comparisonValue, and if the relationship is as described by comparison, this rule causes a new notification to be sent.
distribution­ListIds Array[String] The ids of the Distribution Lists to which this escalation message will be sent if the rule matches when delay has elapsed since sending the original notification.
device­GroupIds Array[String] The ids of the Device Groups to which this escalation message will be sent if the rule matches when delay has elapsed since sending the original notification.
image Blob Binary stream of an image to be sent if the rule triggers. The size of the image and audio data combined must not exceed 10 MiB.
optionLabel String The Confirmation Request option to be counted when delay has elapsed and the rule triggers. The number of user responses matching this value is compared with comparisonValue, and if their relationship is as described by comparison, the escalation message is sent.
subject String The subject to use for the escalation message which is sent if this rule is triggered.

Response

The escalation rule response format is detailed here.

Delete an Escalation Rule

# Continuing with the escalation rule object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules/766bf750-218d-11e4-ba87-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the escalation rule object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted {:name \"ConfirmationRequestEscalationRules\"} 766bf750-218d-11e4-ba87-3c970e7ff560"
}

Removes an escalation rule from a confirmation request.

HTTP Request

DELETE /confirmation-requests/{confirmationRequestId}/escalation-rules/{id}

Produces

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request to which the escalation rule is attached.
id The id of the specific escalation rule to delete.

Response

The deletion response format is detailed here.

Escalation Rule Response

The JSON document used to represent an escalation rule resource has the following content:

Attribute Type Description
audio Blob Audio content to be sent if the rule triggers. Binary stream of audio in μ-law format. The size of the audio and image data combined must not exceed 10 MiB.
body String Optional detailed body text to be sent if the rule triggers. This may be up to 10,000 characters long.
comparison String Options: GT, LT, EQ, NE. Controls the type of comparison to be performed between the number of responses which match optionLabel and the value of comparisonValue. The rule will trigger if this comparison result is greater than, less than, equal, or not equal, respectively.
comparison­Value Integer The value to which the number of responses matching optionLabel should be compared.
confirmation­RequestId String The id of the Confirmation Request this escalation rule is attached to.
createdAt ISO 8601 date/time When this escalation rule was created.
delay Integer The number of seconds after sending the notification at which this rule should be evaluated. At that time, the number of responses matching optionLabel is compared with comparisonValue, and if the relationship is as described by comparison, this rule causes a new notification to be sent.
distribution­ListIds Array[String] The ids of the Distribution Lists to which an escalation message will be sent if the rule matches when delay has elapsed since sending the original notification.
device­GroupIds Array[String] The ids of the Device Groups to which an escalation message will be sent if the rule matches when delay has elapsed since sending the original notification.
image Blob Binary stream of an image to be sent if the rule triggers. The size of the image and audio data combined must not exceed 10 MiB.
id String The id of this specific escalation rule, allowing it to be manipulated or retrieved individually.
optionLabel String The Confirmation Request option to be counted when delay has elapsed and the rule triggers. The number of user responses matching this value is compared with comparisonValue, and if their relationship is as described by comparison, the escalation message is sent.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
subject String The subject to use for the escalation message which is sent if this rule is triggered.

CUCM Clusters

Specifies Cisco Unified Communications Manager Cluster Configurations for use with InformaCast Fusion

Get All CUCM Clusters

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 2,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "secureConnection": false,
      "axlUser": "axlUser",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": null,
      "name": "East Cluster",
      "capfAddress": null,
      "createdAt": "2021-02-15T22:35:07.475Z",
      "nextAuthenticationUrl": null,
      "id": "0e171a6a-6fde-11eb-bd50-0b5d975a5196",
      "tftpAddress": null,
      "snmpVersion": "3",
      "capfPort": null,
      "axlAddress": null,
      "snmpUsername": "Test",
      "snmpCommunity": null,
      "cucmClusterFusionServers": [
        {
          "cucmClusterFusionServerId": "0e17688b-6fde-11eb-bd50-d99a29f7761d",
          "endpointId": "085cd868-6fdd-11eb-bd50-9bb27a3cc62a",
          "endpointName": "Fusion3"
        }
      ],
      "axlId": "ucm125"
    },
    {
      "secureConnection": true,
      "axlUser": "axlUser",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": 69,
      "name": "West Cluster",
      "capfAddress": "172.30.207.49",
      "createdAt": "2021-02-12T19:45:00.617Z",
      "nextAuthenticationUrl": null,
      "id": "cb16ec29-6d6a-11eb-a9cf-e19ac9da2489",
      "tftpAddress": "172.30.207.49",
      "snmpVersion": "2",
      "capfPort": 3804,
      "axlAddress": "172.30.207.49",
      "snmpUsername": null,
      "snmpCommunity": "ICVA",
      "cucmClusterFusionServers": [
        {
          "cucmClusterFusionServerId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
          "endpointId": "7676f63f-6fba-11eb-b0f8-e51408f3ba06",
          "endpointName": "Fusion"
        },
        {
          "cucmClusterFusionServerId": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab",
          "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
          "endpointName": "Fusion2"
        }
      ],
      "axlId": null
    }
  ]
}

Gets a list of all CUCM cluster configurations available to the current user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Controlling access to CUCM clusters allows only those acting in an administrative capacity to modify these settings.)

HTTP Request

GET /cucm-clusters

Produces

application/json

Query Parameters

The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Default Description
assoc-sync-state Boolean false If true, include the current synchronization state for fusion endpoints.

Response

The CUCM Cluster response format is detailed here.

Get One CUCM Cluster

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    cluster = requests.get(url, headers=headers).json()
    print(cluster)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    cluster = JSON.parse(HTTParty.get(url, headers: headers))
    puts(cluster)
rescue StandardError => e
    puts e
{
      "secureConnection": true,
      "axlUser": "axlUser",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": 69,
      "name": "West Cluster",
      "capfAddress": "172.30.207.49",
      "createdAt": "2021-02-12T19:45:00.617Z",
      "nextAuthenticationUrl": null,
      "id": "cb16ec29-6d6a-11eb-a9cf-e19ac9da2489",
      "tftpAddress": "172.30.207.49",
      "snmpVersion": "2",
      "capfPort": 3804,
      "axlAddress": "172.30.207.49",
      "snmpUsername": null,
      "snmpCommunity": "ICVA",
      "cucmClusterFusionServers": [
        {
          "cucmClusterFusionServerId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
          "endpointId": "7676f63f-6fba-11eb-b0f8-e51408f3ba06",
          "endpointName": "Fusion"
        },
        {
          "cucmClusterFusionServerId": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab",
          "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
          "endpointName": "Fusion2"
        }
      ],
      "axlId": null
    }

Retrieves a single CUCM Cluster by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /cucm-clusters/{cucmClusterId}

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster to retrieve.

Response

The CUCM Cluster response format is detailed here.

Create a CUCM Cluster

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Example Cluster',
    'axlUser': 'AXL User',
    'axlPassword': 'AXL Password',
    'axlAddress': '1.1.1.1,2.2.2.2',
    'snmpVersion': '2',
    'snmpCommunity': 'ICVA',
    'secureConnection': false,
    'nextAuthenticationUrl': 'http://cucm.domain.org:8080/ccmcip/authenticate.jsp'
}

try: 
    cluster = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(cluster)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Cluster", \
       "axlUser": "AXL User", \
       "axlPassword": "AXL Password", \
       "axlAddress": "1.1.1.1,2.2.2.2", \
       "snmpVersion": "2", \
       "snmpCommunity": "ICVA", \
       "secureConnection": false, \
       "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Example Cluster'
,
    'axlUser': 'AXL User'
,
    'axlPassword': 'AXL Password'
,
    'axlAddress': '1.1.1.1,2.2.2.2'
,
    'snmpVersion': '2'
,
    'snmpCommunity': 'ICVA'
,
    'secureConnection': false
,
    'nextAuthenticationUrl': 'http://cucm.domain.org:8080/ccmcip/authenticate.jsp'

}

begin: 
    cluster = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(cluster)
rescue StandardError => e
    puts e
{
      "secureConnection": true,
      "axlUser": "AXL User",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": 69,
      "name": "Example Cluster",
      "capfAddress": null,
      "createdAt": "2021-02-12T19:45:00.617Z",
      "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp",
      "id": "f16f8ef0-708a-11eb-9c8c-17221dd62a89",
      "tftpAddress": null,
      "snmpVersion": "2",
      "capfPort": null,
      "axlAddress": "1.1.1.1,2.2.2.2",
      "snmpUsername": null,
      "snmpCommunity": "ICVA",
      "cucmClusterFusionServers": [],
      "axlId": null
    }

Creates a new CUCM Cluster global configuration, which can be shared across multiple Fusion Servers

HTTP Request

POST /cucm-clusters

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A The name to give the new CUCM Cluster. May be up to 255 characters long.
axlUser String N/A The username with which InformaCast Fusion will attempt to contact the Administrative XML (AXL) service. Used to discover and configure phones.
axlPassword String N/A The password with which InformaCast Fusion will attempt to contact the Administrative XML (AXL) service.
axlAddress String N/A A comma-delimited list of IP Addresses that InformaCast Fusion will try when contacting the Administrative XML (AXL) service. These will always be tried in priority order, from left to right.
snmpVersion String N/A Specifies the version of SNMP InformaCast Fusion will use when discovering phones. Valid values are “2” or “3”.
snmpCommunity String N/A Only used with SNMP Version 2. The community name that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
snmpUsername String N/A Only used with SNMP Version 3. The username that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
snmpAuthPassword String N/A Only used with SNMP Version 3. The authentication password that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
snmpEncryptPassword String N/A Only used with SNMP Version 3. The privacy password that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
secureConnection Boolean false If true, will make Computer Telephony Integration (CTI) connections using Transport Layer Security (TLS)
capfAddress String N/A Only used when secureConnection is true. The address of the Certificate Authority Proxy Function (CAPF) Service, used for generating certificates.
capfPort Number N/A Only used when secureConnection is true. The port of the Certificate Authority Proxy Function (CAPF) Service, used for generating certificates.
tftpAddress String N/A Only used when secureConnection is true. The address of the Trivial File Transfer Protocol (TFTP) Service, used for downloading certificates.
tftpPort Number N/A Only used when secureConnection is true. The port of the Trivial File Transfer Protocol (TFTP) Service, used for downloading certificates.
nextAuthenticationUrl String N/A If InformaCast Fusion determines that it should not attempt to handle a phone authentication request, it will redirect those authentication requests to this location.

Response

The CUCM Cluster response format is detailed here.

Update a CUCM Cluster

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Example Cluster Prime',
    'axlUser': 'AXL User Prime',
    'axlPassword': 'AXL Password Prime',
    'axlAddress': '1.1.1.1,2.2.2.2,3.3.3.3',
    'snmpVersion': '2',
    'snmpCommunity': 'ICVA2',
    'secureConnection': false,
    'nextAuthenticationUrl': 'http://cucm.domain.org:8080/ccmcip/authenticate.jsp'
}

try: 
    cluster = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(cluster)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Cluster Prime", \
       "axlUser": "AXL User Prime", \
       "axlPassword": "AXL Password Prime", \
       "axlAddress": "1.1.1.1,2.2.2.2,3.3.3.3", \
       "snmpVersion": "2", \
       "snmpCommunity": "ICVA2", \
       "secureConnection": false, \
       "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Example Cluster Prime'
,
    'axlUser': 'AXL User Prime'
,
    'axlPassword': 'AXL Password Prime'
,
    'axlAddress': '1.1.1.1,2.2.2.2,3.3.3.3'
,
    'snmpVersion': '2'
,
    'snmpCommunity': 'ICVA2'
,
    'secureConnection': false
,
    'nextAuthenticationUrl': 'http://cucm.domain.org:8080/ccmcip/authenticate.jsp'

}

begin: 
    cluster = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(cluster)
rescue StandardError => e
    puts e
{
      "secureConnection": true,
      "axlUser": "AXL User Prime",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": 69,
      "name": "Example Cluster Prime",
      "capfAddress": null,
      "createdAt": "2021-02-12T19:45:00.617Z",
      "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp",
      "id": "f16f8ef0-708a-11eb-9c8c-17221dd62a89",
      "tftpAddress": null,
      "snmpVersion": "2",
      "capfPort": null,
      "axlAddress": "1.1.1.1,2.2.2.2,3.3.3.3",
      "snmpUsername": null,
      "snmpCommunity": "ICVA2",
      "cucmClusterFusionServers": [],
      "axlId": null
    }

Updates a new CUCM Cluster global configuration, which can be shared across multiple Fusion Servers

HTTP Request

PUT /cucm-clusters/{cucmClusterId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster to update.

Request Parameters

Parameter Type Default Description
name String N/A The name to give the new CUCM Cluster. May be up to 255 characters long.
axlUser String N/A The username with which InformaCast Fusion will attempt to contact the Administrative XML (AXL) service. Used to discover and configure phones.
axlPassword String N/A The password with which InformaCast Fusion will attempt to contact the Administrative XML (AXL) service.
axlAddress String N/A A comma-delimited list of IP Addresses that InformaCast Fusion will try when contacting the Administrative XML (AXL) service. These will always be tried in priority order, from left to right.
snmpVersion String N/A Specifies the version of SNMP InformaCast Fusion will use when discovering phones. Valid values are “2” or “3”.
snmpCommunity String N/A Only used with SNMP Version 2. The community name that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
snmpUsername String N/A Only used with SNMP Version 3. The username that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
snmpAuthPassword String N/A Only used with SNMP Version 3. The authentication password that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
snmpEncryptPassword String N/A Only used with SNMP Version 3. The privacy password that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
secureConnection Boolean false If true, will make Computer Telephony Integration (CTI) connections using Transport Layer Security (TLS)
capfAddress String N/A Only used when secureConnection is true. The address of the Certificate Authority Proxy Function (CAPF) Service, used for generating certificates.
capfPort Number N/A Only used when secureConnection is true. The port of the Certificate Authority Proxy Function (CAPF) Service, used for generating certificates.
tftpAddress String N/A Only used when secureConnection is true. The address of the Trivial File Transfer Protocol (TFTP) Service, used for downloading certificates.
tftpPort Number N/A Only used when secureConnection is true. The port of the Trivial File Transfer Protocol (TFTP) Service, used for downloading certificates.
nextAuthenticationUrl String N/A The location that will be redirected to if InformaCast Fusion determines that it should not attempt to handle a phone push authentication request.

Response

The CUCM Cluster response format is detailed here.

Remove a CUCM Cluster

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted f16f8ef0-708a-11eb-9c8c-17221dd62a89"
}

Removes a CUCM Cluster, discarding its configuration.

HTTP Request

DELETE /cucm-clusters/{cucmClusterId}

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster to delete.

Response

The deletion response format is detailed here.

CUCM Cluster Response Format

The JSON document used to represent a CUCM Cluster resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this CUCM cluster was created.
id String The id of this specific CUCM cluster, allowing it to be manipulated or retrieved individually.
name String The cluster name. May be up to 255 characters long.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
syncState Array[Object] The current endpoint’s sync state. Only applicable for Fusion Servers that this cluster is configured for, and if query param assoc-sync-state is true.
axlUser String The username with which InformaCast Fusion will attempt to contact the Administrative XML (AXL) service. Used to discover and configure phones.
axlAddress String A comma-delimited list of IP Addresses that InformaCast Fusion will try when contacting the Administrative XML (AXL) service. These will always be tried in priority order, from left to right.
snmpVersion String Specifies the version of SNMP InformaCast Fusion will use when discovering phones. Valid values are “2” or “3”.
snmpCommunity String Only used with SNMP Version 2. The community name that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
snmpUsername String Only used with SNMP Version 3. The username that was created in CUCM for InformaCast Fusion. SNMP is used to obtain the IP addresses of registered phones when building the phone cache.
secureConnection Boolean If true, will make Computer Telephony Integration (CTI) connections using Transport Layer Security (TLS)
capfAddress String Only used when secureConnection is true. The address of the Certificate Authority Proxy Function (CAPF) Service, used for generating certificates.
capfPort Number Only used when secureConnection is true. The port of the Certificate Authority Proxy Function (CAPF) Service, used for generating certificates.
tftpAddress String Only used when secureConnection is true. The address of the Trivial File Transfer Protocol (TFTP) Service, used for downloading certificates.
tftpPort Number Only used when secureConnection is true. The address of the Trivial File Transfer Protocol (TFTP) Service, used for downloading certificates.
nextAuthenticationUrl String The location that will be redirected to if InformaCast Fusion determines that it should not attempt to handle a phone push authentication request.
axlId String If this cluster was imported from an earlier version of InformaCast Fusion, will display the CUCM cluster ID from the AXL service
cucmClusterFusionServers Array[Object] The current cluster’s configured CUCM Cluster Fusion Servers.

CUCM Cluster Fusion Servers Format

The JSON document used to represent a CUCM Cluster Fusion Server Configuration has the following content:

Attribute Type Description
cucmClusterFusionServerId String ID of this record.
endpointId String ID of the Fusion Server configured for this cluster.
endpointName String Name of the Fusion Server configured for this cluster.

CUCM Cluster Fusion Servers

Specifies Specific Fusion Servers configurations for a previously configured Cisco Unified Communications Manager Cluster.

Get All Fusion Server configurations for a CUCM Cluster

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    servers = requests.get(url, headers=headers, params=params).json()
    print(servers)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    servers = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(servers)
rescue StandardError => e
    puts e
{
  "total": 2,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "jtapiStaticTerminalsEnabled": false,
      "createdAt": "2021-02-15T18:25:00.363Z",
      "cmAddress": "172.30.207.49",
      "syncId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab:1613413642770",
      "cmUsername": "cmUser",
      "endpointId": "7676f63f-6fba-11eb-b0f8-e51408f3ba06",
      "id": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
      "jtapiPhoneActivationEnabled": false,
      "makeCtiConnection": true,
      "syncState": [
        {
          "name": "Fusion",
          "status": "complete",
          "updatedAt": "2021-02-15T18:30:23.189Z",
          "errors": null
        }
      ],
      "endpoint": {
        "id": "7676f63f-6fba-11eb-b0f8-e51408f3ba06",
        "name": "Fusion"
      },
      "cucmClusterId": "f16f8ef0-708a-11eb-9c8c-17221dd62a89"
    },
    {
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "jtapiStaticTerminalsEnabled": false,
      "createdAt": "2021-02-15T18:25:00.323Z",
      "cmAddress": "172.30.207.49",
      "syncId": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab:1613413676919",
      "cmUsername": "JamieDA2",
      "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
      "id": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab",
      "jtapiPhoneActivationEnabled": false,
      "makeCtiConnection": true,
      "syncState": [
        {
          "name": "Fusion2",
          "status": "complete",
          "updatedAt": "2021-02-15T18:28:26.217Z",
          "errors": null
        }
      ],
      "endpoint": {
        "id": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
        "name": "Fusion2"
      },
      "cucmClusterId": "f16f8ef0-708a-11eb-9c8c-17221dd62a89"
    }
  ]
}

Gets a list of all Fusion Server configurations for a particular CUCM cluster available to the current user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Controlling access to CUCM clusters allows only those acting in an administrative capacity to modify these settings.)

HTTP Request

GET /cucm-clusters/{cucmClusterId}/fusion-servers

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster to retrieve.

Query Parameters

The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Default Description
assoc-sync-state Boolean false If true, include the current synchronization state for the fusion endpoint associated with this configuration.

Response

The CUCM Cluster Fusion Server configuration response format is detailed here.

Get one Fusion Server configuration for a CUCM Cluster

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    server = requests.get(url, headers=headers).json()
    print(server)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    server = JSON.parse(HTTParty.get(url, headers: headers))
    puts(server)
rescue StandardError => e
    puts e
{
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "jtapiStaticTerminalsEnabled": false,
  "createdAt": "2021-02-15T18:25:00.323Z",
  "cmAddress": "172.30.207.49",
  "syncId": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab:1613413676919",
  "cmUsername": "JamieDA2",
  "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
  "id": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab",
  "jtapiPhoneActivationEnabled": false,
  "makeCtiConnection": true,
  "syncState": [
    {
      "name": "Fusion2",
      "status": "complete",
      "updatedAt": "2021-02-15T18:28:26.217Z",
      "errors": null
    }
  ],
  "endpoint": {
    "id": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
    "name": "Fusion2"
  },
  "cucmClusterId": "f16f8ef0-708a-11eb-9c8c-17221dd62a89"
}

Retrieves a single CUCM Cluster Fusion server configuration by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /cucm-clusters/{cucmClusterId}/fusion-servers/{cucmClusterFusionServerId}

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster to retrieve.
cucmClusterFusionServerId The id of the CUCM Cluster Fusion Server Configuration to retrieve.

Response

The CUCM Cluster Fusion Server configuration response format is detailed here.

Create a CUCM Cluster Fusion Server Configuration

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'endpointId': '817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa',
    'cmAddress': '1.1.1.1,2.2.2.2',
    'cmUsername': 'cmUser',
    'cmPassword': 'cmPassword',
    'jtapiPhoneActivationEnabled': false,
    'jtapiStaticTerminalsEnabled': false,
    'makeCtiConnection': true,
    'allowRestartForJTAPIUpdate': true
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa", \
       "cmAddress": "1.1.1.1,2.2.2.2", \
       "cmUsername": "cmUser", \
       "cmPassword": "cmPassword", \
       "jtapiPhoneActivationEnabled": false, \
       "jtapiStaticTerminalsEnabled": false, \
       "makeCtiConnection": true, \
       "allowRestartForJTAPIUpdate": true}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'endpointId': '817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa'
,
    'cmAddress': '1.1.1.1,2.2.2.2'
,
    'cmUsername': 'cmUser'
,
    'cmPassword': 'cmPassword'
,
    'jtapiPhoneActivationEnabled': false
,
    'jtapiStaticTerminalsEnabled': false
,
    'makeCtiConnection': true
,
    'allowRestartForJTAPIUpdate': true

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "jtapiStaticTerminalsEnabled": false,
  "createdAt": "2021-02-15T18:25:00.363Z",
  "cmAddress": "1.1.1.1,2.2.2.2",
  "syncId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab:1613413642770",
  "cmUsername": "cmUser",
  "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
  "id": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
  "jtapiPhoneActivationEnabled": false,
  "makeCtiConnection": true,
  "endpoint": {
    "id": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
    "name": "Fusion2"
  },
  "cucmClusterId": "cb16ec29-6d6a-11eb-a9cf-e19ac9da2489",
  "ctiCertificates": [{"applicationUser": "appUser",
                       "instanceId": "instanceId",
                       "id": "f2dee550-70a9-11eb-9c8c-17221dd62a89"}]
}

Creates a new CUCM Cluster Fusion Server configuration, with fields that need to be unique to a single Fusion Server

HTTP Request

POST /cucm-clusters/{cucmClusterId}/fusion-servers

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster associated with this Fusion Server configuration.

Request Parameters

Parameter Type Default Description
endpointId String N/A The Fusion Server ID with which this configuration should be associated
cmAddress String N/A A comma-delimited list of IP Addresses used to connect to the CUCM CTIManager service. These will always be tried in priority order, from left to right.
cmUsername String N/A The username used to connect to the CUCM CTIManager service.
cmPassword String N/A The password used to connect to the CUCM CTIManager service.
makeCtiConnection Boolean false Allows CTI connections to this CUCM cluster and makes this CUCM cluster the ‘Primary’ cluster for this Fusion Server. A Fusion Server must have exactly one Primary Cluster. Setting this value to true will unset it for any other CUCM cluster assigned to this Fusion Server.
jtapiPhoneActivationEnabled Boolean false Only used when makeCtiConnection is true. If true, phones are activated via JTAPI requests sent by InformaCast to the primary CUCM cluster. If false, phones are activated via HTTP requests sent from InformaCast to IP phones.
jtapiStaticTerminalsEnabled Boolean false Only used when jtapiPhoneActivationEnabled is true. If true, will eager create telephony terminals for all phones associated with the cluster and assigned to this Fusion Server by Activation Group, speeding up activation time. If false, terminals are created during activation and discarded afterward.
allowRestartForJTAPIUpdate Boolean false If true, will allow this operation even if the JTAPI version of the CUCM Cluster and Fusion Server do not match, which will restart the Fusion Server automatically when saved. Otherwise, throws a validation error if they do not match.

Response

The CUCM Cluster Fusion Server configuration response format is detailed here.

Update a CUCM Cluster Fusion Server Configuration

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'endpointId': '817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa',
    'cmAddress': '1.1.1.1,2.2.2.2,3.3.3.3',
    'cmUsername': 'cmUser',
    'cmPassword': 'cmPassword',
    'jtapiPhoneActivationEnabled': false,
    'jtapiStaticTerminalsEnabled': false,
    'makeCtiConnection': true,
    'allowRestartForJTAPIUpdate': true
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa", \
       "cmAddress": "1.1.1.1,2.2.2.2,3.3.3.3", \
       "cmUsername": "cmUser", \
       "cmPassword": "cmPassword", \
       "jtapiPhoneActivationEnabled": false, \
       "jtapiStaticTerminalsEnabled": false, \
       "makeCtiConnection": true, \
       "allowRestartForJTAPIUpdate": true}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'endpointId': '817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa'
,
    'cmAddress': '1.1.1.1,2.2.2.2,3.3.3.3'
,
    'cmUsername': 'cmUser'
,
    'cmPassword': 'cmPassword'
,
    'jtapiPhoneActivationEnabled': false
,
    'jtapiStaticTerminalsEnabled': false
,
    'makeCtiConnection': true
,
    'allowRestartForJTAPIUpdate': true

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "jtapiStaticTerminalsEnabled": false,
  "createdAt": "2021-02-15T18:25:00.363Z",
  "cmAddress": "1.1.1.1,2.2.2.2,3.3.3.3",
  "syncId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab:1613413642770",
  "cmUsername": "cmUserPrime",
  "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
  "id": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
  "jtapiPhoneActivationEnabled": false,
  "makeCtiConnection": true,
  "endpoint": {
    "id": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
    "name": "Fusion2"
  },
  "cucmClusterId": "cb16ec29-6d6a-11eb-a9cf-e19ac9da2489"
}

Updates an existing CUCM Cluster Fusion Server configuration, with fields that need to be unique to a single Fusion Server

HTTP Request

PUT /cucm-clusters/{cucmClusterId}/fusion-servers/{cucmClusterFusionServerId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster associated with this Fusion Server configuration.
cucmClusterFusionServerId The id of the CUCM Cluster Fusion Server Configuration to retrieve.

Request Parameters

Parameter Type Default Description
endpointId String N/A The Fusion Server ID with which this configuration should be associated. This value may not be changed on subsequent requests.
cmAddress String N/A A comma-delimited list of IP Addresses used to connect to the CUCM CTIManager service. These will always be tried in priority order, from left to right.
cmUsername String N/A The username used to connect to the CUCM CTIManager service.
cmPassword String N/A The password used to connect to the CUCM CTIManager service.
makeCtiConnection Boolean false Allows CTI connections to this CUCM cluster and makes this CUCM cluster the 'Primary’ cluster for this Fusion Server.
jtapiPhoneActivationEnabled Boolean false If true, phones are activated via JTAPI requests sent by InformaCast to the primary CUCM cluster. If false, phones are activated via HTTP requests sent from InformaCast to IP phones.
jtapiStaticTerminalsEnabled Boolean false Only used when jtapiPhoneActivationEnabled is true. If true, will eager create telephony terminals for all phones associated with the cluster and assigned to this Fusion Server by Activation Group, speeding up activation time. If false, terminals are created during activation and discarded afterward.
allowRestartForJTAPIUpdate Boolean false If true, will allow this operation even if the JTAPI version of the Cluster and Fusion’s do not match, which will restart the cluster automatically when saved. Otherwise, throws a validation error if they do not match.

Response

The CUCM Cluster Fusion Server response format is detailed here.

Remove a CUCM Cluster Fusion Server Configuration

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers/1d278a0f-6fbb-11eb-b0f8-918d446445ab"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers/1d278a0f-6fbb-11eb-b0f8-918d446445ab" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers/1d278a0f-6fbb-11eb-b0f8-918d446445ab"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted 1d278a0f-6fbb-11eb-b0f8-918d446445ab"
}

Removes a CUCM Cluster Fusion Server Configuration.

HTTP Request

DELETE /cucm-clusters/{cucmClusterId}/fusion-servers/{cucmClusterFusionServerId}

Produces

application/json

Path Parameters

Parameter Description
cucmClusterId The id of the CUCM Cluster associated with this Configuration.
cucmClusterFusionServerId The id of the CUCM Cluster Fusion Server Configuration to retrieve.

Response

The deletion response format is detailed here.

CUCM Cluster Fusion Server Configuration Response Format

The JSON document used to represent a CUCM Cluster Fusion Server configuration resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this CUCM cluster Fusion Server config was created.
id String The id of this specific CUCM cluster Fusion Server config, allowing it to be manipulated or retrieved individually.
name String The CUCM cluster name. May be up to 255 characters long.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
syncState Array[Object] The current endpoint’s sync state. Only applicable for Fusion Servers that this cluster is configured for, and if query param assoc-sync-state is true.
endpointId String The Fusion Server ID with which this configuration should be associated. This value may not be changed on subsequent requests.
endpoint Object An object containing the ID and name of the Fusion Server associated with this configuration
cmAddress String A comma-delimited list of IP Addresses used to connect to the CUCM CTIManager service. These will always be tried in priority order, from left to right.
cmUsername String The username used to connect to the CUCM CTIManager service.
makeCtiConnection Boolean Allows CTI connections to this CUCM cluster and makes this CUCM cluster the 'Primary’ cluster for this Fusion Server.
jtapiPhoneActivationEnabled Boolean If true, phones will be activated via Call Manager over CTI using the JTAPI protocol. If false, phones will be activated via HTTP.
jtapiStaticTerminalsEnabled Boolean Only used when jtapiPhoneActivationEnabled is true. If true, will eager create telephony terminals for all phones associated with the cluster and assigned to this Fusion Server by Activation Group, speeding up activation time. If false, terminals are created during activation and discarded afterward.

Devices

Fusion Only

Provides a unified view of all endpoint devices connected to any Fusion server. This can be used to test filters, get individual device identifiers, etc.

List All Devices

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    devices = requests.get(url, headers=headers, params=params).json()
    print(devices)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/devices?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    devices = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(devices)
rescue StandardError => e
    puts e
{
  "total": 2,
  "previous": null,
  "next": null,
  "data": [{
    "name": "CiscoPhone-388382:SEP001D45E95D12",
    "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
    "attributes": {
      "PartitionNames": "[]",
      "HasDisplay": "true",
      "DirectoryNumbers": "[]",
      "InformaCast4StyleRegExTarget": "name=SEP001D45E95D12\ndesc=12002\ncss=pnp system test\npool=Default\naddr=172.20.127.86\ntype=336",
      "Location": "Hub_None",
      "CallManagerDevicePool": "Default",
      "CallManagerDeviceType": "336",
      "Description": "12002",
      "IPAddress": "172.20.127.86",
      "CallManagerCSS": "pnp system test",
      "Name": "SEP001D45E95D12",
      "InformaCastDeviceType": "CiscoIPPhone",
      "CallManagerClusterName": "BulkPhones",
      "EndUserIdentifier": "jim.bob@acme.com"
    },
    "activationGroupId": null,
    "defunct": false,
    "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
    "isLicensed": true
  }]
}

Retrieves a list of all Fusion devices. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned.)

HTTP Request

GET /devices

Produces

application/json

Query Parameters

As usual, the number of responses can be controlled using the API’s pagination parameters. In this case, although up to two devices were requested, there were only two available. The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The device response format is detailed here.

Get a Device

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    device = requests.get(url, headers=headers).json()
    print(device)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    device = JSON.parse(HTTParty.get(url, headers: headers))
    puts(device)
rescue StandardError => e
    puts e
{
  "name": "CiscoPhone-388382:SEP001D45E95D12",
  "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
  "attributes": {
    "PartitionNames": "[]",
    "HasDisplay": "true",
    "DirectoryNumbers": "[]",
    "InformaCast4StyleRegExTarget": "name=SEP001D45E95D12\ndesc=12002\ncss=pnp system test\npool=Default\naddr=172.20.127.86\ntype=336",
    "Location": "Hub_None",
    "CallManagerDevicePool": "Default",
    "CallManagerDeviceType": "336",
    "Description": "12002",
    "IPAddress": "172.20.127.86",
    "CallManagerCSS": "pnp system test",
    "Name": "SEP001D45E95D12",
    "InformaCastDeviceType": "CiscoIPPhone",
    "CallManagerClusterName": "BulkPhones",
    "EndUserIdentifier": "jim.bob@acme.com"
  },
  "defunct": false,
  "activationGroupId": null,
  "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
  "isLicensed": true
}

Retrieves a single device by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /devices/{deviceId}

Produces

application/json

Path Parameters

Parameter Description
deviceId The id of the Device of interest.

Response

The device response format is detailed here.

Device Response

The JSON document used to represent a device resource has the following content:

Attribute Type Description
id String The id of this specific device, allowing it to be manipulated or retrieved individually.
name String The name of the device.
description String The description of the device.
defunct Boolean Whether the device is defunct (meaning no Fusion server currently knows about it, but it remains assigned to one or more device groups).
isLicensed Boolean Whether the device is currently licensed to be used.
attributes Object The specific device attributes as they come from a Fusion Server/CUCM. EndUserIdentifier is special: if specified, the device will be attached to the user, if any, whose email matches.
activationGroupId String Used only with multicast-capable devices; the id of the activation group the device belongs to.

Device Groups

Fusion Only

Device Groups are named groups of Devices, and are the recipients of Notifications.

Device Groups are commonly composed of a set of filters that will match certain Devices.

Get All Device Groups

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
 "total": 1,
 "previous": null,
 "next": null,
 "data": [
   {
    "baseDeviceGroups": [{
      "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
      "activationGroupIds": ["75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"],
      "name": "All Phones"
     }],
    "exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
    "filterType": "OR",
    "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
    "additions": [{
      "axlError": false,
      "defunct": false,
      "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
      "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
      "icopId": "CiscoPhone-External:SEP381C1ABA7908",
      "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
      "isLicensed": true,
      "type": "phones"
     }],
    "permissions": ["delete", "put", "get"],
    "filters": [{
      "value": "john.doe@singlewire.com",
      "attribute": "EndUserIdentifier",
      "comparison": "EQUALS",
      "complement": false,
      "caseSensitive": false
     }],
    "name": "A Large Test",
    "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"],
    "exclusions": [{
      "axlError": false,
      "defunct": false,
      "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
      "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
      "icopId": "CiscoPhone-External:SEP381C1ABA7908",
      "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
      "isLicensed": true,
      "type": "phones"
     }],
    "activationGroupIds": ["77828af8-8345-11ea-ac1d-104a7db133de",
                           "92a45d3e-8345-11ea-ac1d-104a7db133de"],
    "activationGroups": [{
      "name": "Primary",
      "id": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"
    },{
      "name": "Secondary",
      "id": "92a45d3e-8345-11ea-ac1d-104a7db133de"
      }],
    "multicastConfigs": [{
      "activationGroupId": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0",
      "address": "224.0.0.1",
      "port": 2345,
      "type": "poly-ucs",
      "channel": 1
    },{
      "activationGroupId": "92a45d3e-8345-11ea-ac1d-104a7db133de",
      "address": "224.0.0.1",
      "port": 2346,
      "type": "poly-ucs",
      "channel": 1
    }],
    "createdAt": "2017-03-10T22:00:58.290Z",
    "id": "0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
   }
 ]
}

Gets a list of all Device Groups available to the current user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Controlling access to device groups allows administrators to decide to whom users can send notifications.)

HTTP Request

GET /device-groups

Produces

application/json

Query Parameters

To make this example more manageable, only the first Device Group was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
include-device-counts Boolean If true, includes the matching device counts.
assoc-sync-state Boolean If true, include the current synchronization state for fusion endpoints.
includeDomains Boolean If true, include the list of Domains to which each device group belongs.

Response

The Device Group response format is detailed here.

Get One Device Group

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    group = requests.get(url, headers=headers).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    group = JSON.parse(HTTParty.get(url, headers: headers))
    puts(group)
rescue StandardError => e
    puts e
{
 "baseDeviceGroups": [{
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "activationGroupIds": ["75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"],
   "name": "All Phones"
  }],
 "exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "filterType": "OR",
 "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "additions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "permissions": ["delete", "put", "get"],
 "filters": [{
   "value": "john.doe@singlewire.com",
   "attribute": "EndUserIdentifier",
   "comparison": "EQUALS",
   "complement": false,
   "caseSensitive": false
  }],
 "name": "A Large Test",
 "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"],
 "exclusions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "activationGroupIds": ["77828af8-8345-11ea-ac1d-104a7db133de",
                        "92a45d3e-8345-11ea-ac1d-104a7db133de"],
 "activationGroups": [{
   "name": "Primary",
   "id": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"
  },{
   "name": "Secondary",
   "id": "92a45d3e-8345-11ea-ac1d-104a7db133de"
  }],
 "multicastConfigs": [{
   "activationGroupId": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0",
    "address": "224.0.0.1",
    "port": 2345,
    "type": "poly-ucs",
    "channel": 1
  },{
    "activationGroupId": "92a45d3e-8345-11ea-ac1d-104a7db133de",
    "address": "224.0.0.1",
    "port": 2346,
    "type": "poly-ucs",
    "channel": 1
  }],
 "createdAt": "2017-03-10T22:00:58.290Z",
 "id": "0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
}

Retrieves a single Device Group by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /device-groups/{deviceGroupId}

Produces

application/json

Path Parameters

Parameter Description
deviceGroupId The id of the Device Group to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the device group belongs.

Response

The Device Group response format is detailed here.

Create a Device Group

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'exclusionIds': ['CiscoPhone-External:SEP381C1ABA7908'],
    'filterType': 'OR',
    'additionIds': ['CiscoPhone-External:SEP381C1ABA7908'],
    'filters': [{
        'value': 'john.doe@singlewire.com',
        'attribute': 'EndUserIdentifier',
        'comparison': 'EQUALS',
        'complement': false,
        'caseSensitive': false
}
],
    'name': 'A Large Test',
    'baseDeviceGroupIds': ['9fb8c937-fd05-11e6-a30e-e198ed79b70a']
}

try: 
    group = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"], \
       "filterType": "OR", \
       "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"], \
       "filters": [{"value": "john.doe@singlewire.com", \
         "attribute": "EndUserIdentifier", \
         "comparison": "EQUALS", \
         "complement": false, \
         "caseSensitive": false}], \
       "name": "A Large Test", \
       "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"]}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'exclusionIds': ['CiscoPhone-External:SEP381C1ABA7908'
]
,
    'filterType': 'OR'
,
    'additionIds': ['CiscoPhone-External:SEP381C1ABA7908'
]
,
    'filters': [{
        'value': 'john.doe@singlewire.com'
,
        'attribute': 'EndUserIdentifier'
,
        'comparison': 'EQUALS'
,
        'complement': false
,
        'caseSensitive': false

}

]
,
    'name': 'A Large Test'
,
    'baseDeviceGroupIds': ['9fb8c937-fd05-11e6-a30e-e198ed79b70a'
]

}

begin: 
    group = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(group)
rescue StandardError => e
    puts e
{
 "baseDeviceGroups": [{
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones"
  }],
 "exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "filterType": "OR",
 "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "additions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "permissions": ["delete", "put", "get"],
 "filters": [{
   "value": "john.doe@singlewire.com",
   "attribute": "EndUserIdentifier",
   "comparison": "EQUALS",
   "complement": false,
   "caseSensitive": false
  }],
 "name": "A Large Test",
 "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"],
 "exclusions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "createdAt": "2017-03-10T22:00:58.290Z",
 "id": "0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
}

Creates a new Device Group (limit: 3500). In order to be useful, the filters (limit: 200 per Device Group) or additions should match at least one Device

HTTP Request

POST /device-groups

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A The name to give the new Device Group. May be up to 140 characters long.
exclusionIds Array[String] N/A The specific device icop_ids that are excluded from the Device Group regardless of filters and other Device Groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
filterType String N/A Controls how the filters that define rules for dynamically determining the Devices in this Device Group are combined (i.e. AND or OR, REJECT, ACCEPT, or LOGICAL_EXPRESSION). If this device group is also configured with baseDeviceGroupIds, the filters will further adjust the devices in the group.
additionIds Array[String] N/A The specific Device icop_ids that are in the Group regardless of filters and other Device Groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
filters Array[Object] N/A Defines rules to dynamically determine the Devices in this Device Group, combined as specified by filterType. If this Device Group is also filtered with baseDeviceGroupIds, these filters will further adjust the devices in the group. The filters format is detailed here.
baseDevice­GroupIds Array[UUID] N/A If present, contains the list of Device Group ids that form the starting Devices for this Device Group. The base Device Groups’ associations with Activation Groups will be carried over to the new Device Group; these carried over associations cannot be removed from the new Device Group unless they no longer exist in the base Device Groups.
activation­GroupIds Array[UUID] N/A If present, contains the list of Activation Group ids that form the starting pool of Devices for this Device Group. Currently, this only affects what Poly® phones are included in the starting pool of Devices; all other device types are included in the pool regardless of what Activation Group the belong to.

Response

The Device Group response format is detailed here.

Update a Device Group

# Continuing with the device group object from
# the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"], \
       "filterType": "OR", \
       "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"], \
       "filters": [{"value": "john.doe@singlewire.com", \
         "attribute": "EndUserIdentifier", \
         "comparison": "EQUALS", \
         "complement": false, \
         "caseSensitive": false}], \
       "name": "A Large Test", \
       "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"]}'
# Continuing with the device group object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
 "baseDeviceGroups": [{
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones"
  }],
 "exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "filterType": "OR",
 "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "additions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "permissions": ["delete", "put", "get"],
 "filters": [{
   "value": "john.doe@singlewire.com",
   "attribute": "EndUserIdentifier",
   "comparison": "EQUALS",
   "complement": false,
   "caseSensitive": false
  }],
 "name": "A Large Test",
 "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"],
 "exclusions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "activationGroups": [],
 "activationGroupIds": [],
 "createdAt": "2017-03-10T22:00:58.290Z",
 "id": "0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
}

Modifies the details of the Device Group.

HTTP Request

PUT /device-groups/{deviceGroupId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
deviceGroupId The id of the device group to update.

Request Parameters

Parameter Type Default Description
name String N/A The new name to give the Device Group. May be up to 140 characters long.
exclusionIds Array[String] N/A The specific device icop_ids that are excluded from the Device Group regardless of filters and other Device Groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
filterType String N/A Controls how the filters that define rules for dynamically determining the Devices in this Device Group are combined (i.e. AND or OR, REJECT, ACCEPT, or LOGICAL_EXPRESSION). If this device group is also configured with baseDeviceGroupIds, the filters will further adjust the devices in the group.
additionIds Array[String] N/A The specific Device icop_ids that are in the Group regardless of filters and other Device Groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
filters Array[Object] N/A Defines rules to dynamically determine the Devices in this Device Group, combined as specified by filterType. If this Device Group is also filtered with baseDeviceGroupIds, these filters will further adjust the devices in the group. The filters format is detailed here.
baseDevice­GroupIds Array[UUID] N/A If present, contains the list of Device Group ids that form the starting Devices for this Device Group.
activation­GroupIds Array[UUID] N/A If present, contains the list of Activation Group ids that form the starting pool of Devices for this Device Group. Currently, this only affects what Poly® phones are included in the starting pool of Devices; all other device types are included in the pool regardless of what Activation Group the belong to.

Response

The Device Group response format is detailed here.

Remove a Device group

# Continuing with the device group object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/3cf58710-2305-11e4-b544-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the device group object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted {:name \"DeviceGroups\"} 3cf58710-2305-11e4-b544-3c970e7ff560"
}

Removes a Device Group, discarding its Device information.

HTTP Request

DELETE /device-groups/{deviceGroupId}

Produces

application/json

Path Parameters

Parameter Description
deviceGroupId The id of the Device Group to delete.

Response

The deletion response format is detailed here.

Device Group Response

The JSON document used to represent a Device Group resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this device group was created.
id String The id of this specific device group, allowing it to be manipulated or retrieved individually.
name String The device group name. May be up to 140 characters long.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
syncState Array[Object] The current endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
exclusionIds Array[String] The specific device icop_ids that are excluded from this device group regardless of filters and other device groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
exclusions Array[Object] The specific devices that are excluded from this device group regardless of filters and other device groups.
filterType String Controls how the filters that define rules for dynamically determining the Devices in this device group are combined (i.e. AND or OR, REJECT, ACCEPT, or LOGICAL_EXPRESSION). If this device group is also configured with baseDeviceGroupIds, the filters will further adjust the devices in the group.
additionIds Array[String] The specific device icop_ids that are in the Group regardless of filters and other Device Groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
additions Array[Object] The specific devices that are in the group regardless of filters and other device groups.
filters Array[Object] Defines rules to dynamically determine the Devices in this Device Group, combined as specified by filterType. If this Device Group is also filtered with baseDeviceGroupIds, these filters will further adjust the devices in the group. The filters format is detailed here.
baseDevice­GroupIds Array[UUID] If present, contains a list of Device Group ids that form the starting Devices for this Device Group.
baseDevice­Groups Array[Object] If present, contains a list of Device Groups that form the starting devices for this Device Group.
activation­GroupIds Array[Object] If present, contains a list ‘id’s of the Activation Groups whose Poly® phones can be added to this device group using additionIds or via rules used in the filters attribute.
activation­Groups Array[Object] If present, contains a list of Activation Groups whose Poly® phones can be added to this device group using additionIds or via rules used in the filters attribute. The format of the elements of this attribute is detailed here.
multicastConfigs Array[Object] If present, contains the configurations that will be used for delivering audio notifications to the multicast capable members of this Device Group. The format of the elements of this attribute is detailed here.
numIdns Number Number of matching IDNs. Included if query contains the include-device-counts set to true.
numPhones Number Number of matching phones. Included if query contains the include-device-counts set to true.
numPlugins Number Number of matching plugins. Included if query contains the include-device-counts set to true.
numSpeakers Number Number of matching speakers. Included if query contains the include-device-counts set to true.

Device Group Filters Format

The JSON document used to represent a Device Group Filter has the following content (see the InformaCast Documentation for more details):

Attribute Type Description
attribute String The attribute to filter.
complement Boolean Controls whether the filter’s meaning is reversed. If true, it will match devices that do not meet the specified criteria. (You might use this when it is simpler to specify what to exclude; you can think of it as adding “does not” in front of the rule.)
comparison String The comparison used for the filter (BEGINS_WITH, CONTAINS, ENDS_WITH, EQUALS, or MATCHES_REGEX; legal values depend on the attribute).
value String A text value for the comparison.
caseSensitive Boolean Controls whether comparisons should care about capitalization.

Activation Group Elements Format

The JSON document used to represent an Activation Group associated with a Device Group has the following format:

Attribute Type Description
name String The name of the Activation Group
id String The id of the Activaion Group

Multicast Configurations Format

The JSON document that describes an individual configuration used by a Device Group when delivering audio to its multicast capable members has the following format:

Attribute Type Description
activation­GroupId String The id of the Activation Group whose members will be set up to use this configuration in order to receive audio notifications sent to the Device Group where they also appear as members.
address String The multicast address to which the audio notifications will be sent.
port Number The network port to which the audio notifications will be sent.
type String The type of multicast audio format which will be used for encoding the audio notifications; currently supported formats are poly-ucs, which corresponds to the format used for Group Paging supported by Poly® phones with UCS firmware, and gms, which corresponds to the RTP ulaw format.
channel Number If the type attribute’s value is set to poly, specifies the channel number the Poly® group members will be subscribed to in order to receive audio notifications.

Device Group Domains

Fusion Only

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Device Groups are assigned to at least one Domain, and can be associated with more than one. This resource lets you see and adjust which Device Groups are assigned to which Domains.

List All Device Group Domains

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "total": 2,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Vending",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
      "namePath": "/West Campus/Stadium/Vending/",
      "deviceGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "deviceGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Device Group belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /device-groups/{deviceGroupId}/domains

Produces

application/json

Path Parameters

Parameter Description
deviceGroupId The id of the Device Group whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Device Group belonged to when the request was made, and both were returned. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the subdomains of any Domain attached to the specified Device Group using a query parameter, and/or filter the results by matching on the Domain name:

Parameter Type Description
name String Returns only Domains whose names exactly match the supplied value.
recursive Boolean If true, in addition to Domains that are directly attached to the specified Device Group, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the device group whose domains were requested is returned under the key deviceGroupId inside each domain response.

Check if a Device Group contains a Domain

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "deviceGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Device Group Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /device-groups/{deviceGroupId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
deviceGroupId The id of the Device Group whose Domains are of interest.
id The id of the Domain you want to know whether the Device Group belongs to.

Additionally, you can check if the Device Group is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
recursive boolean If true, in addition to Domains that are directly attached to the specified Device Group, any of their subdomains will be considered.

Response

If the Device Group is part of the Domain (or its subdomains, if recursive is true), a response will be returned. The Domain response format is detailed here. If the list is not in the Domain, the response status will indicate that the requested resource cannot be found.

Add a Device Group Domain

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "deviceGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Device Group into the specified Domain. As described below, this may be considered a promotion or demotion, which would require additional request parameters in order to validate.

HTTP Request

POST /device-groups/{deviceGroupId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
deviceGroupId String The id of the Device Group to be added to the Domain.

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Device Group out of a parent Domain?
id String n/a The id of the Domain to which the Device Group should be added.
promote Boolean false Allow this request to proceed even if it will promote the Device Group out of one or more child Domains?

A Device Group is not allowed to be explicitly part of any Domain that it is implicitly granted membership to by belonging to a parent Domain. For example, if you take a Device Group that is in Domains /West Campus/ and /East Campus/, and try to add it to /West Campus/Gym/ that request will fail because it is already implicitly in that domain through belonging to the parent /West Campus/ Domain. See the full explanation of promotion and demotion in the context of Domains and Users for more details and illustrations.

Remove a Device Group Domain

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
{
  "status": 200,
  "message": "deleted Domain Device Group c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Device Group from the specified Domain. As described below, if this is the only Domain that the Device Group currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Device Group itself.

HTTP Request

DELETE /device-groups/{deviceGroupId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
deviceGroupId The id of the Device Group whose Domain should be removed.
id The id of the Domain to be removed from the Device Group.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Device Group in no Domain.

A Device Group must always belong to at least one Domain, so if you try to remove the Device Group from the only Domain that it belongs to, the request must either fail, or delete the Device Group. The request parameter orphans lets you control which of those takes place. The default, if you supply no instructions, is for the request to fail, and you will receive a validation error explaining why. If you pass a value of delete for the orphans request parameter, then taking a Device Group out of its last Domain will delete the Device Group.

Response

The deletion response format is detailed here.

Device Group Cloning

Fusion Only

This resource is used to make a copy of the Device Group specified by id in the request path.

The only operation supported is POST.

Clone a Device Group

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/6ec13410-1bdf-11e4-9181-3c970e7ff560/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/6ec13410-1bdf-11e4-9181-3c970e7ff560/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/device-groups/6ec13410-1bdf-11e4-9181-3c970e7ff560/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
{
 "baseDeviceGroups": [{
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "activationGroupIds": ["75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"],
   "name": "All Phones"
  }],
 "exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "filterType": "OR",
 "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"],
 "additions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "permissions": [],
 "filters": [{
   "value": "john.doe@singlewire.com",
   "attribute": "EndUserIdentifier",
   "comparison": "EQUALS",
   "complement": false,
   "caseSensitive": false
  }],
 "name": "A Large Test (Copy)",
 "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"],
 "exclusions": [{
   "axlError": false,
   "defunct": false,
   "description": "Cisco IP Phone: Auto 105022; DNs: 105022, 105000; SEP381C1ABA7908",
   "deviceIdentifier": "CiscoPhone-External:SEP381C1ABA7908",
   "icopId": "CiscoPhone-External:SEP381C1ABA7908",
   "id": "9e6e7322-d65a-11e9-9733-3fbe4605e265",
   "isLicensed": true,
   "type": "phones"
  }],
 "activationGroupIds": ["77828af8-8345-11ea-ac1d-104a7db133de",
                        "92a45d3e-8345-11ea-ac1d-104a7db133de"],
 "activationGroups": [{
   "name": "Primary",
   "id": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"
 },{
   "name": "Secondary",
   "id": "92a45d3e-8345-11ea-ac1d-104a7db133de"
   }],
 "multicastConfigs": [{
   "activationGroupId": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0",
   "address": "224.0.0.1",
   "port": 2345,
   "type": "poly-ucs",
   "channel": 1
 },{
   "activationGroupId": "92a45d3e-8345-11ea-ac1d-104a7db133de",
   "address": "224.0.0.1",
   "port": 2346,
   "type": "poly-ucs",
   "channel": 1
 }],
 "createdAt": "2017-03-10T22:11:58.290Z",
 "id": "7c098693-bdcb-4995-8280-2727e0620bd7"
}

Creates a copy of the specified Device Group. The name of the new copy is simply the original Device Group’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /device-groups resource and GET permission to the Device Group they wish to copy.

HTTP Request

POST /device-groups/{deviceGroupId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
deviceGroupId String The id of the Device Group to copy.

Response

The Device Group response format is detailed here.

Dial-To-Intercom

Fusion Only

Dial-to-intercom calls allow you to dial another person’s extension and be immediately connected with full-duplex intercom functionality and no action required for the receiving phone.

Get Dial-To-Intercom Configuration

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'sync': true
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration?sync=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "id": 1,
  "dialingPrefix": "#5",
  "volume": 0,
  "maxDuration": 600,
  "messagePriority": 1,
  "permissions": [
      "get",
      "put"
  ]
}

Retrieves the Dial-To-Intercom configuration. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Admin/DialToIntercom/configuration

Produces

application/json

Path Parameters

None

Dial To Intercom Response

Attribute Type Description
id Integer Database ID (for display only). This field will be ignored if included in the body of the data submitted on a PUT or POST
dialingPrefix String The dialing prefix used to identify the phone call as an intercom call. (e.g. *, #, #5, etc.)
volume Integer (0=As_Is, 30=Low, 60=Medium, 100=Maximum): The speaker volume level that will be used on the receiving phone during the intercom session
maxDuration Integer (60-99999): The max duration (seconds) allowed for an intercom broadcast
messagePriority Integer The message priority given for an intercom broadcast

Update Dial-To-Intercom Configuration

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'dialingPrefix': '#5',
    'volume': 0,
    'sync': true
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration?sync=true" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"dialingPrefix": "#5", \
       "volume": 0}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'dialingPrefix': '#5'
,
    'volume': 0
,
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
  "id": 1,
  "dialingPrefix": "#5",
  "volume": 0,
  "maxDuration": 600,
  "messagePriority": 1
}

Updates the Dial-To-Intercom configuration.

HTTP Request

PUT /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Admin/DialToIntercom/configuration

Consumes

application/json

Produces

application/json

Path Parameters

None

Request Parameters

Parameter Type Default Description
dialingPrefix String N/A The dialing prefix used to identify the phone call as an intercom call. (e.g. *, #, #5, etc.)
volume Integer N/A (0=As_Is, 30=Low, 60=Medium, 100=Maximum): The speaker volume level that will be used on the receiving phone during the intercom session
maxDuration Integer N/A (60-99999): The max duration (seconds) allowed for an intercom broadcast
messagePriority Integer N/A The message priority given for an intercom broadcast

Response

The response format is detailed here.

Distribution Lists

Distribution Lists are named groups of Users, and are the recipients of Notifications. Notifications can be sent to users directly, but are more commonly sent to users within distribution lists.

Distribution lists can also have Campaigns associated with them, which allow people who are not registered users of InformaCast Mobile to subscribe to notifications sent to the distribution list. This is done using a self-service interface, with which these outside parties can register their SMS number. Each campaign once created will be assigned a URL, which provides the interface needed for people to register for the campaign. Campaigns can be assigned enrollment end dates, after which point the self-service interface will no longer accept new registrations, and will instead display a configurable inactive message explaining why the registration attempt has been rejected.

Get All Distribution Lists

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true',
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Everyone",
      "isSubscribable": true,
      "campaign": null,
      "domains": [
        {
         "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
         "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
         "name": "West",
         "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
         "namePath": "/West/"
        }
      ]
    }
  ]
}

Gets a list of all distribution lists available to the current user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Controlling access to distribution lists allows administrators to decide to whom users can send notifications.)

HTTP Request

GET /distribution-lists

Produces

application/json

Query Parameters

To make this example more manageable, only the first distribution list was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
assoc-sync-state Boolean If true, include the current synchronization state for fusion endpoints.
includeDomains Boolean If true, include the list of Domains to which each distribution list belongs.

Response

The distribution list response format is detailed here.

Get One Distribution List

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true'
}

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "id": "59489180-41f1-11e5-aa08-aa951d8d7a3b",
  "createdAt": "2015-08-13T19:27:34.552Z",
  "name": "Parents Weekend",
  "isSubscribable": false,
  "campaign": {
    "enrollmentEndDate": null,
    "welcomeMessage": "Hi, mom and dad!",
    "inactiveMessage": "You were too late.",
    "defaultNotificationDays": null,
    "url": "http://admin.icmobile.singlewire.com/anonymous/036347b0-41f1-11e5-ba5e-aa951d8d7a3b/list/59489180-41f1-11e5-aa08-aa951d8d7a3b"
   },
  "domains": [
    {
     "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "West",
     "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
     "namePath": "/West/"
    }
  ]
}

Retrieves a single distribution list by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /distribution-lists/{distributionListId}

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the distribution list to retrieve.

Query Parameters

Parameter Type Description
assoc-sync-state Boolean If true, include the current synchronization state for fusion endpoints.
includeDomains Boolean If true, include the list of Domains to which this distribution list belongs.

Response

The distribution list response format is detailed here.

Create a Distribution List

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Administrators'
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Administrators"}'
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Administrators'

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-13T16:16:53.249Z",
  "id": "3cf58710-2305-11e4-b544-3c970e7ff560",
  "name": "Administrators",
  "isSubscribable": false,
  "domains": [
    {
     "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "West",
     "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
     "namePath": "/West/"
    }
  ]
}

Creates a new, empty, distribution list (limit: 3500). In order to be useful, Users will need to be subscribed to the new list (limit: 100,000 per Distribution List).\nUsers can also subscribe to the Distribution List if isSubscribable is set to true.

HTTP Request

POST /distribution-lists

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
campaign[default­Notification­Days] Integer N/A If there is a campaign, this number of days will be suggested to users on its self-service registration page as a good number of days to subscribe; they can override it if they desire. An empty value means the subscription never expires.
campaign[en­rollment­EndDate] ISO 8601 date/time N/A If there is a campaign, this value can be specified to establish a date after which self-service registrations will no longer be accepted. An empty value means the campaign is open-ended and will accept registrations indefinitely.
campaign[in­active­Message] String N/A If there is a campaign, the text to display on its registration page after the enrollment end date to explain why registration is no longer available.
campaign[wel­comeMessage] String N/A If there is a campaign, the text to display on its registration page to explain the purpose of the distribution list to members of the general public who would like to sign up to receive notifications.
name String N/A The name to give the new distribution list. May be up to 140 characters long.

Response

The distribution list response format is detailed here.

Update a Distribution List

# Continuing with the distribution list object
# from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"campaign": {"enrollmentEndDate": "2015-11-16T00:00:00.000Z", \
         "inactiveMessage": "Sorry, registration for Parents Weekend has ended."}}'
# Continuing with the distribution list object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
{
  "permissions": ["delete", "put", "get"],
  "id": "59489180-41f1-11e5-aa08-aa951d8d7a3b",
  "createdAt": "2015-08-13T19:27:34.552Z",
  "name": "Parents Weekend",
  "isSubscribable": false,
  "campaign": {
    "enrollmentEndDate": null,
    "welcomeMessage": "Hi, mom and dad!",