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.932+0000",
   "id": "51839b40-e1b0-11e3-b343-0ab69cea9f8b",
   "distributionListId": "29e56500-e1b0-11e3-b343-0ab69cea9f8b",
   "userId": "d55af380-caf6-11e3-81cc-127b75e3b4bb"}],
 "createdAt": "2014-04-23T14:52:04.152+0000",
 "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.session().GET().json())
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.session.get)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/session" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \

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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    user = icm_client.users().POST(data={
        'email': 'craig.smith@acme.com',
        'name': 'Craig Smith'}).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  user = JSON.parse(
    icm_client.users.post(
      :email => 'craig.smith@acme.com',
      :name => 'Craig Smith'))
  puts JSON.pretty_generate(user)
rescue => e
  p e
end
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"}'
# 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.262+0000",
  "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 = icm_client.distribution_lists().POST(data={
        'name': 'To Just Craig Smith'}).json()
    print(dist_list)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing the previous example:
begin
  dist_list = JSON.parse(
    icm_client.distribution_lists.post(
      :name => 'To Just Craig Smith'))
  puts JSON.pretty_generate(dist_list)
rescue => e
  p e
end
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"}'
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-13T20:40:38.627+0000",
  "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 = icm_client.users(user['id']).subscriptions().POST(data={
        'distributionListId': dist_list['id']}).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the user and distribution
# list objects from the previous example:
begin
  sub = JSON.parse(
    icm_client.users(user['id']).subscriptions.post(
      :distributionListId => dist_list['id']))
  puts JSON.pretty_generate(sub)
rescue => e
  p e
end
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"}'
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-13T20:33:53.262+0000",
    "id": "2400c8e0-2329-11e4-8e47-685b358ea847",
    "email": "craig.smith@acme.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-13T20:40:38.627+0000",
    "id": "159e9330-232a-11e4-8e47-685b358ea847",
    "name": "To Just Craig Smith"
  },
  "createdAt": "2014-08-13T20:42:08.689+0000",
  "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 = icm_client.users(user['id']).devices().POST(data={
        'type': 'Android',
        'name': 'Android Nexus Fire 2',
        'deviceIdentifier': 'APA91bFpOikKATC523g5Z_4-1puPNa_oE8t1sTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf'}).json()
    print(reg)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the user object from the
# previous example:
begin
  reg = JSON.parse(
    icm_client.users(user['id']).devices.post(
      :type => 'Android',
      :name => 'Android Nexus Fire 2',
      :deviceIdentifier => 'APA91bFpOikKATC523g5Z_4-1puPNa_oE8t1sTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf'))
  puts JSON.pretty_generate(reg)
rescue => e
  p e
end
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"}'
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-06T16:54:23.115+0000",
  "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 = icm_client.confirmation_requests().POST(data={
        'name': 'Are you there?',
        'options': ['Yes', 'No']}).json()
    print(conf_req)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing the previous example:
begin
  conf_req = JSON.parse(
    icm_client.confirmation_requests.post(
      :name => 'Are you there?',
      :options => ['Yes', 'No']))
  puts JSON.pretty_generate(conf_req)
rescue => e
  p e
end
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"]}'
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [ ],
  "createdAt": "2014-08-13T21:35:07.728+0000",
  "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 = icm_client.message_templates().POST(data={
        'name': 'For Craig Smith Only',
        'subject': 'Hello, Craig. Are you there?',
        'body': 'Please confirm you are present.',
        'confirmationRequestId': conf_req['id'],
        'distributionListIds': [dist_list['id']]}).json()
    print(template)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the confirmation request
# and distribution list objects from the previous
# example:
begin
  template = JSON.parse(
    icm_client.message_templates.post(
      :name => 'For Craig Smith Only',
      :subject => 'Hello, Craig. Are you there?',
      :body => 'Please confirm you are present.',
      :confirmationRequestId => conf_req['id'],
      :distributionListIds => [dist_list['id']]))
  puts JSON.pretty_generate(template)
rescue => e
  p e
end
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"]}'
{
  "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.500+0000",
  "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.627+0000",
      "id": "159e9330-232a-11e4-8e47-685b358ea847",
      "name": "To Just Craig Smith"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-13T21:35:07.728+0000",
    "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 = icm_client.notifications().POST(data={
        'messageTemplateId': template['id']}).json()
    print(sent)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the message template object
# from the previous example:
begin
  sent = JSON.parse(
    icm_client.notifications.post(
      :messageTemplateId => template['id']))
  puts JSON.pretty_generate(sent)
rescue => e
  p e
end
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"}'
{
  "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.199+0000",
    "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.010+0000",
    "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.247+0000",
  "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.146+0000",
    "id": "b227cd00-2331-11e4-8e47-685b358ea847",
    "options": [
      "Yes",
      "No"
    ],
    "name": "Are you there?"
  },
  "image": 0,
  "audio": 0,
  "distributionLists": [
    {
      "createdAt": "2015-03-09T21:57:41.017+0000",
      "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.

 

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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.areas_of_interest().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for aoi in icm_client.areas_of_interest().LIST():
        print(aoi)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.areas_of_interest.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.areas_of_interest.list.each do |aoi|
    puts JSON.pretty_generate(aoi)
  end
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "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
    }
   },
   "createdAt": "2016-04-13T20:55:24.605+0000",
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Retrieves the list of all areas of interest. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of AOIs.)

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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    aoi = icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").GET().json()
    print(aoi)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  aoi = JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").get)
  puts JSON.pretty_generate(aoi)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "id": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
 "name": "CVG",
 "geometryType": "circle",
 "geometryValue": {
  "type": "Feature",
  "geometry": {
   "type": "Point",
   "coordinates": [
    -84.6672,
    39.0478
   ]
  },
  "properties": {
   "radiusInM": 3551
  }
 },
 "createdAt": "2016-04-13T18:44:49.494+0000",
 "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    aoi = icm_client.areas_of_interest().POST(data={
        'name': 'Madison Airport',
        'geometryType': 'circle',
        'geometryValue': {
            'type': 'Feature',
            'geometry': {
                'type': 'Point',
                'coordinates': [-89.34, 43.14]},
            'properties': {
                'radiusInM': 3000}}}).json()
    print(aoi)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  aoi = JSON.parse(
    icm_client.areas_of_interest.post(
      :name => 'Madison Airport',
      :geometryType => 'circle',
      :geometryValue => {
        :type => 'Feature',
        :geometry => {
          :type => 'Point',
          :coordinates => [-89.34, 43.14]},
        :properties => {
          :radiusInM => 3000}}))
  puts JSON.pretty_generate(aoi)
rescue => e
  p e
end
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}}}'
{
  "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
   }
  },
  "createdAt": "2016-05-25T14:06:42.385+0000",
  "permissions": [ "delete", "put", "get" ]
}

Create a new area of interest.

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

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(icm_client.areas_of_interest(aoi['id']).PUT(data={
        'name': 'MSN'}).json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the areas of interest object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.areas_of_interest(aoi['id']).put(
      :name => 'MSN'))
rescue => e
  p e
end
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"}'
{
  "geometryType": "circle",
  "name": "MSN",
  "id": "e83d84e6-2281-11e6-a729-83a644c48766",
  "geometryValue": {
   "type": "Feature",
   "geometry": {
    "type": "Point",
    "coordinates": [ -89.34, 43.14 ]
   },
   "properties": {
    "radiusInM": 3000
   }
  },
  "createdAt": "2016-05-25T14:06:42.385+0000",
  "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

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(icm_client.areas_of_interest(aoi['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the areas of interest object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.areas_of_interest(aoi['id']).delete)
rescue => e
  p e
end
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"

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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for trigger in icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers().LIST():
        print(trigger)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers.list.each do |trigger|
    puts JSON.pretty_generate(trigger)
  end
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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.925+0000",
     "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.358+0000",
    "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": null,
      "type": "regular",
      "loadSourceId": null,
      "id": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
      "createdAt": "2016-04-05T21:10:58.989+0000"
     }
    ]
   }
  ]
}

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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    trigger = icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("f215963c-228e-11e6-a729-f95bf9c34bbf").GET().json()
    print(trigger)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  trigger = JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("f215963c-228e-11e6-a729-f95bf9c34bbf").get)
  puts JSON.pretty_generate(trigger)
rescue => e
  p e
end
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=" \
{
  "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.925+0000",
   "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.358+0000",
  "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": null,
    "type": "regular",
    "loadSourceId": null,
    "id": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
    "createdAt": "2016-04-05T21:10:58.989+0000"
   }
  ]
}

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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    trigger = icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers().POST(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!'}).json()
    print(trigger)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  trigger = JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers.post(
      :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!'))
  puts JSON.pretty_generate(trigger)
rescue => e
  p e
end
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!"}'
{
  "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.925+0000",
   "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.446+0000",
  "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(icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers(trigger['id']).PUT(data={
        'name': 'Welcome 2016'}).json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the boundary trigger object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers(trigger['id']).put(
      :name => 'Welcome 2016'))
rescue => e
  p e
end
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"}'
{
  "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.925+0000",
   "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.446+0000",
  "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(icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers(trigger['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the boundary trigger object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers(trigger['id']).delete)
rescue => e
  p e
end
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"

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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("86ac7740-22a0-11e6-a729-356099d3635b").activities().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for activity in icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("86ac7740-22a0-11e6-a729-356099d3635b").activities().LIST():
        print(activity)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("86ac7740-22a0-11e6-a729-356099d3635b").activities.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("86ac7740-22a0-11e6-a729-356099d3635b").activities.list.each do |activity|
    puts JSON.pretty_generate(activity)
  end
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=" \
{
  "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.924+0000",
     "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.476+0000",
    "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    activity = icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("86ac7740-22a0-11e6-a729-356099d3635b").activities("527910b5-2345-11e6-a729-0da433599b2c").GET().json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  activity = JSON.parse(
    icm_client.areas_of_interest("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").boundary_triggers("86ac7740-22a0-11e6-a729-356099d3635b").activities("527910b5-2345-11e6-a729-0da433599b2c").get)
  puts JSON.pretty_generate(activity)
rescue => e
  p e
end
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=" \
{
  "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.924+0000",
   "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.476+0000",
  "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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    bell_schedules = icm_client.bell_schedules().GET(params={
        'limit': 1}).json()
    print(bell_schedules)
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for bell_schedule in icm_client.bell_schedules().LIST():
        print(bell_schedule)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  bell_schedules = JSON.parse(
    icm_client.bell_schedules.get(:params => {
      :limit => 1}))
  puts JSON.pretty_generate(bell_schedules)
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.bell_schedules.list.each do |bell_schedule|
    puts JSON.pretty_generate(bell_schedule)
  end
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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.635+0000",
      "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.

Response

The bell schedule response format is detailed here.

Get a Bell Schedule

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    bell_schedule = icm_client.bell_schedules("37c1fe0a-4b9c-11e7-8148-0242ac110002").GET().json()
    print(bell_schedule)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  bell_schedule = JSON.parse(
    icm_client.bell_schedules("37c1fe0a-4b9c-11e7-8148-0242ac110002").get)
  puts JSON.pretty_generate(bell_schedule)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/37c1fe0a-4b9c-11e7-8148-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
      "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.635+0000",
      "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.

Response

The bell schedule response format is detailed here.

Create a Bell Schedule

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    bell_schedule = icm_client.bell_schedules().POST(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'}]}).json()
    print(bell_schedule)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  bell_schedule = JSON.parse(
    icm_client.bell_schedules.post(
      :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'}]))
  puts JSON.pretty_generate(bell_schedule)
rescue => e
  p e
end
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"}]}'
{
  "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.635+0000",
  "numWeeks": 1,
  "endDate": "2018-05-25",
  "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
}

Creates a new bell schedule. 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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    bell_schedule = icm_client.bell_schedules("cc01447c-650f-11e8-a57e-332c8cdd597f").PUT(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'}]}).json()
    print(bell_schedule)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  bell_schedule = JSON.parse(
    icm_client.bell_schedules("cc01447c-650f-11e8-a57e-332c8cdd597f").put(
      :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'}]))
  puts JSON.pretty_generate(bell_schedule)
rescue => e
  p e
end
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"}]}'
{
  "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.635+0000",
  "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.bell_schedules("cc01447c-650f-11e8-a57e-332c8cdd597f").DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.bell_schedules("cc01447c-650f-11e8-a57e-332c8cdd597f").delete)
rescue => e
  p e
end
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"

{
  "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.
ringListName String The name of the ring list applied on entryNum day.
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 The description for the bell schedule exception.
ringListId String The id of the Ring List that overrides the bell schedule entries ring list between the bell schedule exceptions startDate and endDate.
startDate Date The start date of the bell schedule exception int 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.

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.

Collaboration Groups

Collaboration Groups serve as a means of initiating group conversations, such as via a conference call, a Cisco Webex Teams space, and in the future, social media platforms like Twitter and Facebook.

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 .

Get All Collaboration Groups

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.collaboration_groups().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.collaboration_groups().LIST():
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.collaboration_groups.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.collaboration_groups.list.each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "total": 1,
  "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.065+0000",
      "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.446+0000"
        }
      ],
      "userIds": [],
      "users": []
    },
    {
     "properties": {
      "mode": "specificSpace",
      "enableCreate": false,
      "specificSpace": {
       "spaceId": "Y2lzY29zcGFyazovL3VzL1JPT00vYjczY2Q2OTAtMmMyMS0xMWU3LTg4MjktMmRiY2EzYmYzMTE0"
      }
     },
     "permissions": ["delete", "put", "get"],
     "name": "Security Webex Team",
     "createdAt": "2017-04-13T13:21:56.273+0000",
     "type": "cisco-spark",
     "distributionListIds": [],
     "id": "2a9e9ad1-204c-11e7-b964-8f83c5e03f72",
     "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.

Response

The collaboration group response format is detailed here.

Get One Collaboration Group

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.collaboration_groups("e3579191-b556-11e5-ab29-bdfc7d2b6ed8").GET().json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.collaboration_groups("e3579191-b556-11e5-ab29-bdfc7d2b6ed8").get)
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "properties": {
    "joinPin": "1234",
    "createPin": null,
    "bypassIvr": false
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065+0000",
  "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.446+0000"
    }
  ],
  "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.

Response

The collaboration group response format is detailed here.

Create a Collaboration Group

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.collaboration_groups().POST(data={
        'name': 'Security Officers',
        'type': 'conference-call',
        'distributionListIds': ['3875f8ae-139c-11e6-9cd0-ef8b5b11547d'],
        'userIds': [],
        'properties': {
            'joinPin': '1234',
            'bypassIvr': false}}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.collaboration_groups.post(
      :name => 'Security Officers',
      :type => 'conference-call',
      :distributionListIds => ['3875f8ae-139c-11e6-9cd0-ef8b5b11547d'],
      :userIds => [],
      :properties => {
        :joinPin => '1234',
        :bypassIvr => false}))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
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}}'
{
  "properties": {
    "joinPin": "1234",
    "createPin": null,
    "bypassIvr": false
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065+0000",
  "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.446+0000"
    }
  ],
  "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, outbound-cap or outbound-rss. 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[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 = icm_client.collaboration_groups(list['id']).PUT(data={
        'properties': {
            'joinPin': '865301',
            'bypassIvr': true}}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the collaboration group object
# from the previous example:
begin
  list = JSON.parse(
    icm_client.collaboration_groups(list['id']).put(
      :properties => {
        :joinPin => '865301',
        :bypassIvr => true}))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
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}}'
{
  "properties": {
    "joinPin": "865301",
    "createPin": null,
    "bypassIvr": true
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065+0000",
  "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.446+0000"
    }
  ],
  "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, outbound-cap or outbound-rss. 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[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(icm_client.collaboration_groups(list['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the collaboration group object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.collaboration_groups(list['id']).delete)
rescue => e
  p e
end
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"

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

Webex Teams Integration API

To allow you to programatically add the InformaCast bot to existing Cisco Webex Teams spaces, the Webex Teams extension exposes some API endpoints through its proxy interface, which can be accessed through the InformaCast Mobile REST API.

List Webex Teams Spaces

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces").GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces").LIST():
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces").get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces").list.each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab//proxy/api/v1/spaces?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "next": null,
  "previous": null,
  "total": 2,
  "userLacksSparkSession": false,
  "data": [{
    "botIsMember": false,
    "userCanInvite": true,
    "type": "group",
    "created": "2015-12-07T18:03:30.969Z",
    "lastActivity": "2017-07-25T17:04:23.579Z",
    "title": "Security Webex Team",
    "botWasEvicted": false,
    "id": "Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4",
    "isLocked": true,
    "creatorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY"
  }]
}

Gets a list of all Webex Teams spaces 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.)

HTTP Request

GET /extensions/299036d0-188a-11e7-a184-fd464c9fabab/proxy/api/v1/spaces

Produces

application/json

Query Parameters

To make this example more manageable, only the first Webex Teams space 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.

Response

Attribute Type Description
id String The id of the Webex Teams space.
botIsMember Boolean Whether or not the InformaCast Bot is currently a member of the space.
userCanInvite Boolean A flag (a hint to the client) as to whether the currently authenticated user has permissions to invite the InformaCast Bot to this space.
isLocked Boolean Whether the current space is locked.
created String When the space was created.
lastActivity String When the last message was posted to this space.
title String The title of this space.
creatorId String The id of the entity that originally created this space.

Invite the Bot to a Space

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    space = icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4").POST().json()
    print(space)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  space = JSON.parse(
    icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4").post)
  puts JSON.pretty_generate(space)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab//proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "botIsMember": true,
  "userCanInvite": true,
  "type": "group",
  "created": "2015-12-07T18:03:30.969Z",
  "lastActivity": "2017-07-25T17:04:23.579Z",
  "title": "Security Webex Team",
  "botWasEvicted": false,
  "id": "Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4",
  "isLocked": true,
  "creatorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY"
}

Tells the InformaCast Mobile bot to add itself to the specified Webex Teams space.

HTTP Request

POST /extensions/299036d0-188a-11e7-a184-fd464c9fabab/proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4

Produces

application/json

Response

Attribute Type Description
id String The id of the Webex Teams space.
botIsMember Boolean Whether or not the InformaCast Bot is currently a member of the space.
userCanInvite Boolean A flag (a hint to the client) as to whether the currently authenticated user has permissions to invite the InformaCast Bot to this space.
isLocked Boolean Whether the space is locked.
created String When the space was created.
lastActivity String When the last message was posted to this space.
title String The title of this space.
creatorId String The id of the entity that originally created this space.

Remove the Bot from a Space

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    space = icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4").DELETE().json()
    print(space)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  space = JSON.parse(
    icm_client.extensions("299036d0-188a-11e7-a184-fd464c9fabab")("/proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4").delete)
  puts JSON.pretty_generate(space)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab//proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "botIsMember": false,
  "userCanInvite": true,
  "type": "group",
  "created": "2015-12-07T18:03:30.969Z",
  "lastActivity": "2017-07-25T17:04:23.579Z",
  "title": "Security Webex Team",
  "botWasEvicted": false,
  "id": "Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4",
  "isLocked": true,
  "creatorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY"
}

Tells the InformaCast Mobile bot to remove itself from the specified Webex Teams space.

HTTP Request

DELETE /extensions/299036d0-188a-11e7-a184-fd464c9fabab/proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4

Produces

application/json

Response

Attribute Type Description
id String The id of the Webex Teams space.
botIsMember Boolean Whether or not the InformaCast Bot is currently a member of the space.
userCanInvite Boolean A flag (a hint to the client) as to whether the currently authenticated user has permissions to invite the InformaCast Bot to this space.
isLocked Boolean Whether the space is locked.
created String When the space was created.
lastActivity String When the last message was posted to this space.
title String The title of this space.
creatorId String The id of the entity that originally created this space.

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.

List All Confirmation Requests

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.confirmation_requests().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for cr in icm_client.confirmation_requests().LIST():
        print(cr)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.confirmation_requests.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.confirmation_requests.list.each do |cr|
    puts JSON.pretty_generate(cr)
  end
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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.434+0000",
          "messageTemplateId": null,
          "body": "",
          "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
        }
      ],
      "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-04T13:53:57.566+0000",
      "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 notification 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.

Response

The confirmation request response format is detailed here.

Get a Confirmation Request

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    cr = icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").GET().json()
    print(cr)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  cr = JSON.parse(
    icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").get)
  puts JSON.pretty_generate(cr)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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.434+0000",
      "body": "",
      "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
    }
  ],
  "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-04T13:53:57.566+0000",
  "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.

Response

The confirmation request response format is detailed here.

Create a Confirmation Request

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    cr = icm_client.confirmation_requests().POST(data={
        'name': 'Are you safe?',
        'options': ['No, please call me!', 'Yes, I am safe.'],
        'initiate-tracking-options': [true, false]}).json()
    print(cr)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  cr = JSON.parse(
    icm_client.confirmation_requests.post(
      :name => 'Are you safe?',
      :options => ['No, please call me!', 'Yes, I am safe.'],
      :initiate-tracking-options => [true, false]))
  puts JSON.pretty_generate(cr)
rescue => e
  p e
end
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]}'
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [ ],
  "createdAt": "2014-08-11T16:22:14.333+0000",
  "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(icm_client.confirmation_requests(cr['id']).PUT(data={
        'name': 'Are you sure?',
        'options': ['Yes, I am sure.', 'No, I am not sure.']}).json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the confirmation request
# object from the previous example:
begin
  puts JSON.parse(
    icm_client.confirmation_requests(cr['id']).put(
      :name => 'Are you sure?',
      :options => ['Yes, I am sure.', 'No, I am not sure.']))
rescue => e
  p e
end
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."]}'
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [ ],
  "createdAt": "2014-08-11T16:22:14.333+0000",
  "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(icm_client.confirmation_requests(cr['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the confirmation request
# object from the previous example:
begin
  puts JSON.parse(
    icm_client.confirmation_requests(cr['id']).delete)
rescue => e
  p e
end
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"

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.
escalation­Rules Array[Escalation­Rule] A list of Escalation Rules attached to this confirmation request, which determine post-response 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.

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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for er in icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules().LIST():
        print(er)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules.list.each do |er|
    puts JSON.pretty_generate(er)
  end
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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.434+0000",
      "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    rule = icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules("4f062fa0-2160-11e4-ba87-3c970e7ff560").GET().json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  rule = JSON.parse(
    icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules("4f062fa0-2160-11e4-ba87-3c970e7ff560").get)
  puts JSON.pretty_generate(rule)
rescue => e
  p e
end
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=" \
{
  "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.434+0000",
  "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/{escalationRuleId}

Produces

application/json

Path Parameters

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

Response

The escalation rule response format is detailed here.

Create an Escalation Rule

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    rule = icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules().POST(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']}).json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  rule = JSON.parse(
    icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules.post(
      :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']))
  puts JSON.pretty_generate(rule)
rescue => e
  p e
end
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"]}'
{
  "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.885+0000",
  "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 = icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules(rule['id']).PUT(data={
        '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']}).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the escalation rule object
# from the previous example:
begin
  updated = JSON.parse(
    icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules(rule['id']).put(
      :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']))
  puts JSON.pretty_generate(updated)
rescue => e
  p e
end
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"]}'
{
  "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.885+0000",
  "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/{escalationRuleId}

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.
escalationRuleId 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(icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules(rule['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the escalation rule object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.confirmation_requests("c7bc65e0-1bde-11e4-9181-3c970e7ff560").escalation_rules(rule['id']).delete)
rescue => e
  p e
end
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"

require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts icm_client.confirmation_requests('c7bc65e0-1bde-11e4-9181-3c970e7ff560').
    escalation_rules('766bf750-218d-11e4-ba87-3c970e7ff560').delete
rescue => e
  p e
end
{
  "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/{escalationRuleId}

Produces

Path Parameters

Parameter Description
confirmationRequestId The id of the Confirmation Request to which the escalation rule is attached.
escalationRuleId 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.

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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    devices = icm_client.devices().GET(params={
        'limit': 2}).json()
    print(devices)
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for device in icm_client.devices().LIST():
        print(device)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  devices = JSON.parse(
    icm_client.devices.get(:params => {
      :limit => 2}))
  puts JSON.pretty_generate(devices)
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.devices.list.each do |device|
    puts JSON.pretty_generate(device)
  end
curl "https://api.icmobile.singlewire.com/api/v1/devices?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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"
    },
    "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    device = icm_client.devices("37c1fe0a-4b9c-11e7-8148-0242ac110002").GET().json()
    print(device)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  device = JSON.parse(
    icm_client.devices("37c1fe0a-4b9c-11e7-8148-0242ac110002").get)
  puts JSON.pretty_generate(device)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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,
  "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.

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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.device_groups().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for group in icm_client.device_groups().LIST():
        print(group)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.device_groups.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.device_groups.list.each do |group|
    puts JSON.pretty_generate(group)
  end
curl "https://api.icmobile.singlewire.com/api/v1/device-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "total": 1,
 "previous": null,
 "next": null,
 "data": [
   {
    "baseDeviceGroups": [{
      "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
      "name": "All Phones"
     }],
    "exclusionIds": ["37c132cc-4b9c-11e7-8148-0242ac110002"],
    "filterType": "OR",
    "additionIds": ["37c1fe0a-4b9c-11e7-8148-0242ac110002"],
    "additions": [{
      "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
      "name": "CiscoPhone-388382:SEP001D45E95D12",
      "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
      "isLicensed": true,
      "defunct": false
     }],
    "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": [{
      "description": "Cisco IP Phone: Auto 1033; DNs: ; SEP00270D5A39ED",
      "name": "CiscoPhone-388382:SEP00270D5A39ED",
      "id": "37c132cc-4b9c-11e7-8148-0242ac110002",
      "isLicensed": true,
      "defunct": false
     }],
    "createdAt": "2017-03-10T22:00:58.290+0000",
    "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.

Response

The Device Group response format is detailed here.

Get One Device Group

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    group = icm_client.device_groups("0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7").GET().json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  group = JSON.parse(
    icm_client.device_groups("0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7").get)
  puts JSON.pretty_generate(group)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "baseDeviceGroups": [{
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones"
  }],
 "exclusionIds": ["37c132cc-4b9c-11e7-8148-0242ac110002"],
 "filterType": "OR",
 "additionIds": ["37c1fe0a-4b9c-11e7-8148-0242ac110002"],
 "additions": [{
   "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
   "name": "CiscoPhone-388382:SEP001D45E95D12",
   "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
   "isLicensed": true,
   "defunct": false
  }],
 "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": [{
   "description": "Cisco IP Phone: Auto 1033; DNs: ; SEP00270D5A39ED",
   "name": "CiscoPhone-388382:SEP00270D5A39ED",
   "id": "37c132cc-4b9c-11e7-8148-0242ac110002",
   "isLicensed": true,
   "defunct": false
  }],
 "createdAt": "2017-03-10T22:00:58.290+0000",
 "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.

Response

The Device Group response format is detailed here.

Create a Device Group

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    group = icm_client.device_groups().POST(data={
        'exclusionIds': ['37c132cc-4b9c-11e7-8148-0242ac110002'],
        'filterType': 'OR',
        'additionIds': ['37c1fe0a-4b9c-11e7-8148-0242ac110002'],
        'filters': [{
            'value': 'john.doe@singlewire.com',
            'attribute': 'EndUserIdentifier',
            'comparison': 'EQUALS',
            'complement': false,
            'caseSensitive': false}],
        'name': 'A Large Test',
        'baseDeviceGroupIds': ['9fb8c937-fd05-11e6-a30e-e198ed79b70a']}).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  group = JSON.parse(
    icm_client.device_groups.post(
      :exclusionIds => ['37c132cc-4b9c-11e7-8148-0242ac110002'],
      :filterType => 'OR',
      :additionIds => ['37c1fe0a-4b9c-11e7-8148-0242ac110002'],
      :filters => [{
        :value => 'john.doe@singlewire.com',
        :attribute => 'EndUserIdentifier',
        :comparison => 'EQUALS',
        :complement => false,
        :caseSensitive => false}],
      :name => 'A Large Test',
      :baseDeviceGroupIds => ['9fb8c937-fd05-11e6-a30e-e198ed79b70a']))
  puts JSON.pretty_generate(group)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/device-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"exclusionIds": ["37c132cc-4b9c-11e7-8148-0242ac110002"], \
       "filterType": "OR", \
       "additionIds": ["37c1fe0a-4b9c-11e7-8148-0242ac110002"], \
       "filters": [{"value": "john.doe@singlewire.com", \
         "attribute": "EndUserIdentifier", \
         "comparison": "EQUALS", \
         "complement": false, \
         "caseSensitive": false}], \
       "name": "A Large Test", \
       "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"]}'
{
 "baseDeviceGroups": [{
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones"
  }],
 "exclusionIds": ["37c132cc-4b9c-11e7-8148-0242ac110002"],
 "filterType": "OR",
 "additionIds": ["37c1fe0a-4b9c-11e7-8148-0242ac110002"],
 "additions": [{
   "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
   "name": "CiscoPhone-388382:SEP001D45E95D12",
   "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
   "isLicensed": true,
   "defunct": false
  }],
 "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": [{
   "description": "Cisco IP Phone: Auto 1033; DNs: ; SEP00270D5A39ED",
   "name": "CiscoPhone-388382:SEP00270D5A39ED",
   "id": "37c132cc-4b9c-11e7-8148-0242ac110002",
   "isLicensed": true,
   "defunct": false
  }],
 "createdAt": "2017-03-10T22:00:58.290+0000",
 "id": "0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
}

Creates a new Device Group. In order to be useful, the filters 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[UUID] N/A The specific device ids that are excluded from the Device Group regardless of filters and other Device Groups.
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[UUID] N/A The specific Device ids that are in the Group regardless of filters and other Device Groups.
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.

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(icm_client.device_groups(group['id']).PUT(data={
        'exclusionIds': ['37c132cc-4b9c-11e7-8148-0242ac110002'],
        'filterType': 'OR',
        'additionIds': ['37c1fe0a-4b9c-11e7-8148-0242ac110002'],
        'filters': [{
            'value': 'john.doe@singlewire.com',
            'attribute': 'EndUserIdentifier',
            'comparison': 'EQUALS',
            'complement': false,
            'caseSensitive': false}],
        'name': 'A Large Test',
        'baseDeviceGroupIds': ['9fb8c937-fd05-11e6-a30e-e198ed79b70a']}).json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the device group object from
# the previous example:
begin
  puts JSON.parse(
    icm_client.device_groups(group['id']).put(
      :exclusionIds => ['37c132cc-4b9c-11e7-8148-0242ac110002'],
      :filterType => 'OR',
      :additionIds => ['37c1fe0a-4b9c-11e7-8148-0242ac110002'],
      :filters => [{
        :value => 'john.doe@singlewire.com',
        :attribute => 'EndUserIdentifier',
        :comparison => 'EQUALS',
        :complement => false,
        :caseSensitive => false}],
      :name => 'A Large Test',
      :baseDeviceGroupIds => ['9fb8c937-fd05-11e6-a30e-e198ed79b70a']))
rescue => e
  p e
end
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": ["37c132cc-4b9c-11e7-8148-0242ac110002"], \
       "filterType": "OR", \
       "additionIds": ["37c1fe0a-4b9c-11e7-8148-0242ac110002"], \
       "filters": [{"value": "john.doe@singlewire.com", \
         "attribute": "EndUserIdentifier", \
         "comparison": "EQUALS", \
         "complement": false, \
         "caseSensitive": false}], \
       "name": "A Large Test", \
       "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"]}'
{
 "baseDeviceGroups": [{
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones"
  }],
 "exclusionIds": ["37c132cc-4b9c-11e7-8148-0242ac110002"],
 "filterType": "OR",
 "additionIds": ["37c1fe0a-4b9c-11e7-8148-0242ac110002"],
 "additions": [{
   "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
   "name": "CiscoPhone-388382:SEP001D45E95D12",
   "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
   "isLicensed": true,
   "defunct": false
  }],
 "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": [{
   "description": "Cisco IP Phone: Auto 1033; DNs: ; SEP00270D5A39ED",
   "name": "CiscoPhone-388382:SEP00270D5A39ED",
   "id": "37c132cc-4b9c-11e7-8148-0242ac110002",
   "isLicensed": true,
   "defunct": false
  }],
 "createdAt": "2017-03-10T22:00:58.290+0000",
 "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[UUID] N/A The specific device ids that are excluded from the Device Group regardless of filters and other Device Groups.
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[UUID] N/A The specific Device ids that are in the Group regardless of filters and other Device Groups.
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.

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(icm_client.device_groups(group['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the device group object from
# the previous example:
begin
  puts JSON.parse(
    icm_client.device_groups(group['id']).delete)
rescue => e
  p e
end
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"

{
  "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[UUID] The specific device ids that are excluded from this device group regardless of filters and other device groups.
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[UUID] The specific device ids that are in the Group regardless of filters and other Device Groups.
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.
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).
textValue String A text value for comparison (some attributes use this, others use selectValue, see the InformaCast Documentation for more details).
selectValue String An enumeration value for comparison (some attributes use this, others use textValue, see the InformaCast Documentation for more details).
caseSensitive Boolean Controls whether comparisons should care about capitalization.

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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.extensions("551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration").GET(params={
        'sync': true}).json())
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.extensions("551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration").get(:params => {
      :sync => true}))
rescue => e
  p e
end
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=" \
{
  "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.extensions("551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration").PUT(data={
        'dialingPrefix': '#5',
        'volume': 0,
        'sync': true}).json())
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.extensions("551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialToIntercom/configuration").put(
      :dialingPrefix => '#5',
      :volume => 0,
      :sync => true))
rescue => e
  p e
end
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}'
{
  "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

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.distribution_lists().GET(params={
        'includeDomains': 'true',
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.distribution_lists().LIST(params={
            'includeDomains': 'true'}):
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.distribution_lists.get(:params => {
      :includeDomains => 'true',
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.distribution_lists.list(:params => {
      :includeDomains => 'true'}).each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-08-06T18:51:33.590+0000",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Everyone",
      "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.distribution_lists("59489180-41f1-11e5-aa08-aa951d8d7a3b").GET(params={
        'includeDomains': 'true'}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.distribution_lists("59489180-41f1-11e5-aa08-aa951d8d7a3b").get(:params => {
      :includeDomains => 'true'}))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "permissions": ["delete", "put", "get"],
  "id": "59489180-41f1-11e5-aa08-aa951d8d7a3b",
  "createdAt": "2015-08-13T19:27:34.552+0000",
  "name": "Parents Weekend",
  "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

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.distribution_lists().POST(data={
        'name': 'Administrators'}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.distribution_lists.post(
      :name => 'Administrators'))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Administrators"}'
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-13T16:16:53.249+0000",
  "id": "3cf58710-2305-11e4-b544-3c970e7ff560",
  "name": "Administrators",
  "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. In order to be useful, Users will need to be subscribed to the new list.

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(icm_client.distribution_lists(list['id']).PUT(data={
        'campaign': {
            'enrollmentEndDate': '2015-11-16T00:00:00.000+0000',
            'inactiveMessage': 'Sorry, registration for Parents Weekend has ended.'}}).json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the distribution list object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.distribution_lists(list['id']).put(
      :campaign => {
        :enrollmentEndDate => '2015-11-16T00:00:00.000+0000',
        :inactiveMessage => 'Sorry, registration for Parents Weekend has ended.'}))
rescue => e
  p e
end
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.000+0000", \
         "inactiveMessage": "Sorry, registration for Parents Weekend has ended."}}'
{
  "permissions": ["delete", "put", "get"],
  "id": "59489180-41f1-11e5-aa08-aa951d8d7a3b",
  "createdAt": "2015-08-13T19:27:34.552+0000",
  "name": "Parents Weekend",
  "campaign": {
    "enrollmentEndDate": null,
    "welcomeMessage": "Hi, mom and dad!",
    "inactiveMessage": "Sorry, registration for Parents Weekend has ended.",
    "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/"
    }
  ]
}

Modifies the name or campaign of a distribution list.

HTTP Request

PUT /distribution-lists/{distributionListId}

Consumes

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

Produces

application/json

Path Parameters

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

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 new name for the distribution list. May be up to 140 characters long.

Response

The distribution list response format is detailed here.

Remove a Distribution List

# Continuing with the distribution list object
# from the previous example:
try:
    print(icm_client.distribution_lists(list['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the distribution list object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.distribution_lists(list['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/3cf58710-2305-11e4-b544-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted {:name \"DistributionLists\"} 3cf58710-2305-11e4-b544-3c970e7ff560"
}

Removes a distribution list, discarding its membership information.

HTTP Request

DELETE /distribution-lists/{distributionListId}

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

Distribution List Response

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

Attribute Type Description
campaign[default­Notification­Days] Integer 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 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 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 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.
campaign[url] String The URL to give out that will enable people to sign up to receive SMS notifications from the distribution list even if they are not registered users of InformaCast Mobile. This is assigned when the campaign is created.
createdAt ISO 8601 date/time When this distribution list 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 Security Group belongs.
id String The id of this specific distribution list, allowing it to be manipulated or retrieved individually.
name String The distribution list 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.

Distribution List Domains

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

List All Distribution List Domains

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains().GET().json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for domain in icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains().LIST():
        print(domain)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains.get)
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains.list.each do |domain|
    puts JSON.pretty_generate(domain)
  end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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/",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441+0000"
    },
    {
      "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/",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522+0000"
    }
  ]
}

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

HTTP Request

GET /distribution-lists/{distributionListId}/domains

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Distribution List 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 Distribution List 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 Distribution List, any subdomains will be returned.

Response

The Domain response format is detailed here.

Check if a Domain contains a Distribution List

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    domain = icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains("f04e3599-295b-11e8-b54b-abb9a309846e").GET().json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  domain = JSON.parse(
    icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains("f04e3599-295b-11e8-b54b-abb9a309846e").get)
  puts JSON.pretty_generate(domain)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "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/",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522+0000"
}

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

HTTP Request

GET /distribution-lists/{distributionListId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List whose Domains are of interest.
id The id of the Domain you want to know whether the Distribution List belongs to.

Additionally, you can check if the Distribution List 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 Distribution List, any of their subdomains will be considered.

Response

If the Distribution List 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 Distribution List Domain

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    domain = icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains().POST(data={
        'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'}).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  domain = JSON.parse(
    icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains.post(
      :id => 'a4e9e56c-28df-11e8-8c38-738c606ef19c'))
  puts JSON.pretty_generate(domain)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
{
  "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/",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441+0000"
}

Puts the Distribution List 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 /distribution-lists/{distributionListId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
distributionListId String The id of the Distribution List 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 Distribution List out of a parent Domain?
id String n/a The id of the Domain to which the Distribution List should be added.
promote Boolean false Allow this request to proceed even if it will promote the Distribution List out of one or more child Domains?

A Distribution List 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 Distribution List 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 Distribution List Domain

# Continuing with the domain object from the
# previous example:
try:
    print(icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains(domain['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the domain object from the
# previous example:
begin
  puts JSON.parse(
    icm_client.distribution_lists("c54e4241-299b-11e8-94d3-2be9464da125").domains(domain['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain Distribution List c54e4241-299b-11e8-94d3-2be9464da125"
}

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

HTTP Request

DELETE /distribution-lists/{distributionListId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
distributionListId The id of the Distribution List whose Domain should be removed.
id The id of the Domain to be removed from the Distribution List.

Request Parameters

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

A Distribution List must always belong to at least one Domain, so if you try to remove the Distribution List from the only Domain that it belongs to, the request must either fail, or delete the Distribution List. 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 Distribution List out of its last Domain will delete the Distribution List.

Response

The deletion response format is detailed here.

Distribution List Subscriptions

Distribution List Subscriptions connect Distribution Lists to Users. When a Distribution List is included in the recipients of a Notification, all Users who are subscribed to that Distribution List will receive the notification, on all of their registered Devices.

List All Subscribers

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for sub in icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions().LIST():
        print(sub)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions.list.each do |sub|
    puts JSON.pretty_generate(sub)
  end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "total": 7,
  "partial": true,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "user": {
        "createdAt": "2014-08-04T14:30:36.459+0000",
        "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
        "email": "craig.smith@singlewire.com",
        "name": "Craig Smith"
      },
      "distributionList": {
        "createdAt": "2014-08-06T18:51:33.590+0000",
        "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
        "name": "Everyone"
      },
      "createdAt": "2014-08-06T18:51:36.216+0000",
      "subscriptionEndDate": null,
      "id": "b125a180-1d9a-11e4-a054-3c970e7ff560",
      "userId": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
      "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560"
    }
  ]
}

Retrieves all members of this distribution list. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. Generally, only administrative users will be able to view the members of distribution lists.)

HTTP Request

GET /distribution-lists/{distributionListId}/user-subscriptions

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List whose members should be listed.

Query Parameters

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

Response

The distribution list subscription response format is detailed here.

Get a Subscriber

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    sub = icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions("b125a180-1d9a-11e4-a054-3c970e7ff560").GET().json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  sub = JSON.parse(
    icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions("b125a180-1d9a-11e4-a054-3c970e7ff560").get)
  puts JSON.pretty_generate(sub)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions/b125a180-1d9a-11e4-a054-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-04T14:30:36.459+0000",
    "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
    "email": "craig.smith@singlewire.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590+0000",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-06T18:51:36.216+0000",
  "subscriptionEndDate": null,
  "id": "b125a180-1d9a-11e4-a054-3c970e7ff560",
  "userId": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
  "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560"
}

Get a distribution list subscription given the ids of the distribution list and subscription.

HTTP Request

GET /distribution-lists/{distributionListId}/user-subscriptions/{userSubscriptionId}

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List of interest.
userSubscriptionId The id of the specific subscription to retrieve.

Response

The distribution list subscription response format is detailed here.

Subscribe a User

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    sub = icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions().POST(data={
        'userId': 'e660d7b0-1be3-11e4-9181-3c970e7ff560'}).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  sub = JSON.parse(
    icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions.post(
      :userId => 'e660d7b0-1be3-11e4-9181-3c970e7ff560'))
  puts JSON.pretty_generate(sub)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"userId": "e660d7b0-1be3-11e4-9181-3c970e7ff560"}'
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-04T14:30:36.459+0000",
    "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
    "email": "craig.smith@singlewire.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590+0000",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-13T20:12:20.444+0000",
  "userId": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
  "id": "216c69c0-2326-11e4-b544-3c970e7ff560",
  "subscriptionEndDate": null,
  "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560"
}

Create a link between a User and a Distribution List so that the User will receive Notifications sent to that Distribution List.

HTTP Request

POST /distribution-lists/{distributionListId}/user-subscriptions

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List to which a new subscription is to be added.

Request Parameters

Parameter Type Default Description
userId String N/A The id of the User to subscribe to the distribution list.
subscription­EndDate ISO 8601 date/time N/A If specified, the time at which this subscription will become inactive.

Response

The distribution list subscription response format is detailed here.

Update a Subscriber

# Continuing with the user subscription object
# from the previous example:
try:
    updated = icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions(sub['id']).PUT(data={
        'subscriptionEndDate': '2015-09-16T14:00:00.000+0000'}).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the user subscription object
# from the previous example:
begin
  updated = JSON.parse(
    icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions(sub['id']).put(
      :subscriptionEndDate => '2015-09-16T14:00:00.000+0000'))
  puts JSON.pretty_generate(updated)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions/216c69c0-2326-11e4-b544-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"subscriptionEndDate": "2015-09-16T14:00:00.000+0000"}'
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-04T14:30:36.459+0000",
    "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
    "email": "craig.smith@singlewire.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590+0000",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-13T20:12:20.444+0000",
  "userId": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
  "id": "216c69c0-2326-11e4-b544-3c970e7ff560",
  "subscriptionEndDate": "2015-09-16T14:00:00.000+0000",
  "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560"
}

Updates an existing distribution list subscription’s subscriptionEndDate.

HTTP Request

PUT /distribution-lists/{distributionListId}/user-subscriptions/{subscriptionId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the distribution list whose subscription is to be updated.
subscriptionId The id of the subscription to update.

Request Parameters

Parameter Type Default Description
subscription­EndDate ISO 8601 date/time N/A If specified, the time at which this subscription will become inactive.

Response

The distribution list subscription response format is detailed here.

Remove a Subscriber

# Continuing with the user subscription object
# from the previous example:
try:
    print(icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions(sub['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the user subscription object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.distribution_lists("af94ef60-1d9a-11e4-a054-3c970e7ff560").user_subscriptions(sub['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions/b125a180-1d9a-11e4-a054-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted {:name \"DistributionListUserSubscriptions\"} b125a180-1d9a-11e4-a054-3c970e7ff560"
}

Deletes a subscriber, removing that association between a User and a Distribution List.

HTTP Request

DELETE /distribution-lists/{distributionListId}/user-subscriptions/{userSubscriptionId}

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List from which a subscription is to be removed.
userSubscriptionId The id of the specific subscription to delete.

Response

The deletion response format is detailed here.

Distribution List Subscription Response

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

Attribute Type Description
createdAt ISO 8601 date/time When this subscription was created.
distribution­List Distribution List When this Distribution List is a recipient of a Notification, the User attached to this subscription will be sent the Notification.
distribution­ListId String The id of the Distribution List above. This is what is actually stored; the expanded details about the Distribution List are returned as a convenience, to save clients from having to issue a separate request to look them up.
id String The id of this specific subscription, allowing it to be manipulated or retrieved individually.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
subscription­EndDate ISO 8601 date/time If specified, the time at which this subscription will become inactive.
user User The User to which Notifications should be delivered when the Distribution List attached to this subscription is listed as a recipient of the Notification.
userId String The id of the User above. This is what is actually stored; the expanded details about the User are returned as a convenience, to save clients from having to issue a separate request to look them up.

Domains

Domains allow for hierarchical delegation of authority over supported resources.

alt text

A sample of hierarchical organization of users in Domains.

Once you have created the Root Domain, the Domain features are active, and all API requests are interpreted in the context of a particular Domain, as described at the end of the Authentication section.

Domain-Enabled Resources

Only the following resources in InformaCast mobile are affected by Domains:

Over time, more resources will be added to this list, focusing first on those that will most benefit from hierarchical administration.

For Domain-enabled resources, any User Permissions and Security Group Permissions whose spec values do not tie them to a specfic resource by id will be Domain scoped when Domains are enabled. These permissions will be attached to a specific Domain (the acting Domain of the request in which the permission is created), which will restrict the permission to operate in that Domain and its subdomains. When first enabling Domains, only the Root Domain will exist, so all preexisting Domain-scoped permissions in the system will be assigned to the Root domain.

List All Domains

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains().GET(params={
        'limit': 10}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for domain in icm_client.domains().LIST():
        print(domain)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains.get(:params => {
      :limit => 10}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains.list.each do |domain|
    puts JSON.pretty_generate(domain)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains?limit=10" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "total": 4,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "id": "52640b89-13b0-11e8-a40a-6553f9413d68",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Stadium Staff",
   "path": "/190fde7f-1372-11e8-9e88-1dc5b905e369/52640b89-13b0-11e8-a40a-6553f9413d68/",
   "namePath": "/East Campus/Stadium Staff/",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2018-02-17T07:01:05.226+0000"
  },
  {
   "id": "6569f5f0-165e-11e8-a8ad-354db202cef7",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "West Campus",
   "path": "/6569f5f0-165e-11e8-a8ad-354db202cef7/",
   "namePath": "/West Campus/",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2018-02-20T16:52:11.898+0000"
  },
  {
   "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "parentId": null,
   "name": "Root",
   "path": "/",
   "namePath": "/",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2018-02-16T00:43:32.422+0000"
  },
  {
   "id": "190fde7f-1372-11e8-9e88-1dc5b905e369",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "East Campus",
   "path": "/190fde7f-1372-11e8-9e88-1dc5b905e369/",
   "namePath": "/East Campus/",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2018-02-16T23:35:40.247+0000"
  }
 ]
}

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

HTTP Request

GET /domains

Produces

application/json

Query Parameters

To make this example more manageable, only the first ten results were requested using the API’s pagination parameters. In fact, there were a total of 4 Domains available when the request was made, and we retrieved them all. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can filter requests using some Domain-specific query parameters:

Parameter Type Description
name String Returns only Domains whose names exactly match the supplied value
parent-id String Returns only direct children (subdomains) of the specified Domain
path-prefix String Returns any Domains whose path starts with the specified string, i.e. the Domain with that path, and any of its descendent subdomains at any depth

Response

The Domain response format is detailed here.

Get a Domain

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    perm = icm_client.domains("52640b89-13b0-11e8-a40a-6553f9413d68").GET().json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  perm = JSON.parse(
    icm_client.domains("52640b89-13b0-11e8-a40a-6553f9413d68").get)
  puts JSON.pretty_generate(perm)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/52640b89-13b0-11e8-a40a-6553f9413d68" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "id": "52640b89-13b0-11e8-a40a-6553f9413d68",
 "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
 "name": "Stadium Staff",
 "path": "/190fde7f-1372-11e8-9e88-1dc5b905e369/52640b89-13b0-11e8-a40a-6553f9413d68/",
 "namePath": "/East Campus/Stadium Staff/",
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "createdAt": "2018-02-17T07:01:05.226+0000"
}

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

HTTP Request

GET /domains/{domainId}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain to retrieve.

Response

The Domain response format is detailed here.

Create a Domain

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    domain = icm_client.domains().POST(data={
        'name': 'Theatre Staff',
        'parentId': '6569f5f0-165e-11e8-a8ad-354db202cef7'}).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  domain = JSON.parse(
    icm_client.domains.post(
      :name => 'Theatre Staff',
      :parentId => '6569f5f0-165e-11e8-a8ad-354db202cef7'))
  puts JSON.pretty_generate(domain)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Theatre Staff", \
       "parentId": "6569f5f0-165e-11e8-a8ad-354db202cef7"}'
{
  "id": "7289eb3a-15c2-11e8-ab27-5dc7a32779d0",
  "parentId": "6569f5f0-165e-11e8-a8ad-354db202cef7",
  "name": "Theatre Staff",
  "path": "/6569f5f0-165e-11e8-a8ad-354db202cef7/7289eb3a-15c2-11e8-ab27-5dc7a32779d0",
  "namePath": "/West Campus/Theatre Staff/",
  "permissions": [
   "delete",
   "put",
   "get"
  ],
  "createdAt": "2018-02-23T16:10:25.326+0000"
}

Create a new Domain.

HTTP Request

POST /domains

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 Domain’s display name
parentId uuid N/A The Domain inside of which this should be created as a sub-domain.

Once Domains have been enabled, a parentId value must always be supplied to identify the parent in which the new domain should be created. This may be the Root Domain in order to create a top-level Domain, or it could be another Domain to create a hierarchy.

The only time it is possible to create a Domain with a null value for parentId is when Domains are not enabled. In that case, creating a Domain named “Root” with a null parent enables the Domains feature.

Response

The Domain response format is detailed here.

Update a Domain

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("52640b89-13b0-11e8-a40a-6553f9413d68").PUT(data={
        'name': 'Stadium and Grounds Staff'}).json())
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("52640b89-13b0-11e8-a40a-6553f9413d68").put(
      :name => 'Stadium and Grounds Staff'))
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/52640b89-13b0-11e8-a40a-6553f9413d68" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Stadium and Grounds Staff"}'
{
 "id": "52640b89-13b0-11e8-a40a-6553f9413d68",
 "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
 "name": "Stadium and Grounds Staff",
 "path": "/190fde7f-1372-11e8-9e88-1dc5b905e369/52640b89-13b0-11e8-a40a-6553f9413d68/",
 "namePath": "/East Campus/Stadium and Grounds Staff/",
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "createdAt": "2018-02-17T07:01:05.226+0000"
}

Updates an existing Domain.

HTTP Request

PUT /domains/{domainId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain to update.

Request Parameters

Parameter Type Default Description
name String N/A The Domain’s display name

The only thing that can be updated for an existing Domain is the name. This will automatically update its name path, and the name paths of any of its descendant domains as well.

Response

The Domain response format is detailed here.

Remove a Domain

# Continuing with the domain object from the
# previous example:
try:
    print(icm_client.domains(domain['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the domain object from the
# previous example:
begin
  puts JSON.parse(
    icm_client.domains(domain['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/7289eb3a-15c2-11e8-ab27-5dc7a32779d0" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted  7289eb3a-15c2-11e8-ab27-5dc7a32779d0"
}

Deletes an existing Domain.

If the Domain has any permissions attached to it, or any resources for which it is the only Domain, or if it has any subdomains (there are Domains whose parent-id refer to the domain you are trying to delete), you must supply additional request parameters (described below) to explicitly cause those permissions, resources, or domains to be deleted as well, or the request will fail.

HTTP Request

DELETE /domains/{domainId}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain to delete

If the Domain has any children (subdomains), this request will fail with a validation error unless you have supplied a true value for the recursive request parameter described below.

If there are any User Permissions or Security Group Permissions whose domain-id matches domain you are trying to delete, or any resources whose only Domain is the one that you are trying to delete, this request will fail with corresponding validation errors unless you have supplied the value delete or delete-permissions for the orphans request parameter described below. If there are only permissions associated with the domain, then delete-permissions will allow it (and them) to be deleted. If there are actual resources that belong to the domain, you must specify a value of delete, which will allow them (as well as any permissions) to be deleted as part of deleting the domain.

If the specified Domain is the Root Domain, this request will fail with a validation error if there are any children regardless of the recursive parameter. If there are no subdomains, deleting the Root Domain will disable the Domains feature.

Request Parameters

Parameter Type Default Description
orphans string fail Option: delete, delete-permissions, fail. What to do if there are permissions or resources attached to this domain that would become orphaned by its deletion. If any exist, you must specify delete or delete-permissions causing them to be deleted as well, or the request to delete the domain will fail.
recursive boolean false Automatically delete any descendants of the Domain as well? If any exist, and this is not true, the request to delete the domain will fail.

Response

The deletion response format is detailed here.

Domain Response

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

Attribute Type Description
createdAt ISO 8601 date/time When this Domain was created.
id String The id of the Domain, for efficient retrieval, manipulation, creating or looking up subdomains
name String The Domain’s display name
namePath String A slash-delimited list of the names of all domains past the root to this domain, to show at a glance its location in the hierarchy; this is a convenience value which is for display only
parentId String The id of the Domain of which this is a sub-domain; only the Root domain will not have a parent
path String A slash-delimited list of the ids of all domains past the root to this domain, which can be used for hierarchical retrieval of its descendants using the path-prefix parameter in a List request
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Domain Distribution Lists

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

List All Domain Distribution Lists

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists().LIST():
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists.list.each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-08-06T18:51:33.590+0000",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Everyone",
      "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/"
        }
      ]
    }
  ]
}

Retrieves the list of all Distribution Lists in the Domain. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/distribution-lists

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Distribution Lists are to be listed.

Query Parameters

To make this example more manageable, only the first result was requested using the API’s pagination parameters. There were a total of 2 Distribution Lists assigned to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Distribution Lists whose names exactly match the supplied value.
recursive boolean If true, in addition to Distribution Lists that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Distribution List response format is detailed here.

Check if a Domain contains a Distribution List

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists("59489180-41f1-11e5-aa08-aa951d8d7a3b").GET().json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists("59489180-41f1-11e5-aa08-aa951d8d7a3b").get)
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "permissions": ["delete", "put", "get"],
  "id": "59489180-41f1-11e5-aa08-aa951d8d7a3b",
  "createdAt": "2015-08-13T19:27:34.552+0000",
  "name": "Parents Weekend",
  "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 Domain Distribution List by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /domains/{domainId}/distribution-lists/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Distribution Lists are of interest.
id The id of the Distribution List whose membership in the Domain is being checked.

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

Parameter Type Description
recursive boolean If true, in addition to Distribution Lists that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

If the Distribution List is part of the Domain (or a subdomain, if recursive is true), a response will be returned. The Distribution List 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 Domain Distribution List

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists().POST(data={
        'id': '3cf58710-2305-11e4-b544-3c970e7ff560'}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("3a0a7df2-3434-11e8-a93d-59d3fdc242ee").distribution_lists.post(
      :id => '3cf58710-2305-11e4-b544-3c970e7ff560'))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "3cf58710-2305-11e4-b544-3c970e7ff560"}'
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-13T16:16:53.249+0000",
  "id": "3cf58710-2305-11e4-b544-3c970e7ff560",
  "name": "Administrators",
  "domains": [
    {
     "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "West",
     "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
     "namePath": "/West/"
    }
  ]
}

Puts the Distribution List 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 /domains/{domainId}/distribution-lists

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain to which the Distribution List should be added.

Request Parameters

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

A Distribution List 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 Distribution List 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 Domain Distribution List

# Continuing with the distribution list object
# from the previous example:
try:
    print(icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").distribution_lists(list['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the distribution list object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").distribution_lists(list['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/distribution-lists/c54e4241-299b-11e8-94d3-2be9464da125" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain Distribution List c54e4241-299b-11e8-94d3-2be9464da125"
}

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

HTTP Request

DELETE /domains/{domainId}/distribution-lists/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Distribution List should be removed.
id String The id of the Distribution List to be removed from the Domain.

Request Parameters

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

A Distribution List must always belong to at least one Domain, so if you try to remove the Distribution List from the only Domain that it belongs to, the request must either fail, or delete the Distribution List. 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 Distribution List out of its last Domain will delete the Distribution List.

Response

The deletion response format is detailed here.

Domain Load Definitions

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

List All Domain Load Definitions

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions().LIST():
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions.list.each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "total": 2,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "permissions": [ "delete", "put", "get" ],
   "deletePolicy": "delete",
   "securityGroupUpdatePolicy": "update",
   "domains": [
    {
     "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "Library",
     "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
     "namePath": "/Library/"
    },
    {
     "id": "2921a72c-3358-11e8-98ef-0d6e2a08c440",
     "parentId": "db4a21db-3357-11e8-98ef-d996a385fab5",
     "name": "Book Store",
     "path": "/db4a21db-3357-11e8-98ef-d996a385fab5/2921a72c-3358-11e8-98ef-0d6e2a08c440/",
     "namePath": "/East Campus/Book Store/"
    }
   ],
   "name": "Staff",
   "domainUpdatePolicy": "update",
   "createdAt": "2017-07-18T18:40:18.246+0000",
   "id": "8bf05eaf-6be8-11e7-925b-49f9effcdeab",
   "distributionListUpdatePolicy": "update",
   "deviceUpdatePolicy": "update"
  },
  {
   "permissions": [ "delete", "put", "get" ],
   "deletePolicy": "retain",
   "securityGroupUpdatePolicy": "update",
   "domains": [
    {
     "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "Library",
     "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
     "namePath": "/Library/"
    },
    {
     "id": "b390b781-e373-11e8-9c1a-b7d5944444f4",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "Rec Center",
     "path": "/b390b781-e373-11e8-9c1a-b7d5944444f4/",
     "namePath": "/Rec Center/"
    }
   ],
   "name": "New Students",
   "domainUpdatePolicy": "update",
   "createdAt": "2019-03-14T13:59:51.954+0000",
   "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
   "distributionListUpdatePolicy": "update",
   "deviceUpdatePolicy": "update"
  }
 ]
}

Retrieves the list of all Load Definitions in the Domain. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/load-definitions

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Load Definitions are to be listed.

Query Parameters

There were a total of two load definitions assigned to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Load Definitions whose names exactly match the supplied value.
recursive boolean If true, in addition to Load Definitions that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Load Definition response format is detailed here.

Check if a Domain contains a Load Definition

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions("7030f7f4-4661-11e9-9372-ad3660dbb389").GET().json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions("7030f7f4-4661-11e9-9372-ad3660dbb389").get)
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "permissions": [ "delete", "put", "get" ],
 "deletePolicy": "retain",
 "securityGroupUpdatePolicy": "update",
 "domains": [
  {
   "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Library",
   "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
   "namePath": "/Library/"
  },
  {
   "id": "b390b781-e373-11e8-9c1a-b7d5944444f4",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Rec Center",
   "path": "/b390b781-e373-11e8-9c1a-b7d5944444f4/",
   "namePath": "/Rec Center/"
  }
 ],
 "name": "New Students",
 "domainUpdatePolicy": "update",
 "createdAt": "2019-03-14T13:59:51.954+0000",
 "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
 "distributionListUpdatePolicy": "update",
 "deviceUpdatePolicy": "update"
}

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

HTTP Request

GET /domains/{domainId}/load-definitions/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Load Definitions are of interest.
id The id of the Load Definition whose membership in the Domain is being checked.

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

Parameter Type Description
recursive boolean If true, in addition to Load Definitions that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

If the Load Definition is part of the Domain (or a subdomain, if recursive is true), a response will be returned. The Load Definition 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 Domain Load Definition

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions().POST(data={
        'id': '7030f7f4-4661-11e9-9372-ad3660dbb389'}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions.post(
      :id => '7030f7f4-4661-11e9-9372-ad3660dbb389'))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "7030f7f4-4661-11e9-9372-ad3660dbb389"}'
{
 "permissions": [ "delete", "put", "get" ],
 "deletePolicy": "retain",
 "securityGroupUpdatePolicy": "update",
 "domains": [
  {
   "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Library",
   "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
   "namePath": "/Library/"
  },
  {
   "id": "b390b781-e373-11e8-9c1a-b7d5944444f4",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Rec Center",
   "path": "/b390b781-e373-11e8-9c1a-b7d5944444f4/",
   "namePath": "/Rec Center/"
  }
 ],
 "name": "New Students",
 "domainUpdatePolicy": "update",
 "createdAt": "2019-03-14T13:59:51.954+0000",
 "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
 "distributionListUpdatePolicy": "update",
 "deviceUpdatePolicy": "update"
}

Puts the Load Definition 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 /domains/{domainId}/load-definitions

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain to which the Load Definition should be added.

Request Parameters

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

A Load Definition 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 Load Definition 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 Domain Load Definition

# Continuing with the load definition object
# from the previous example:
try:
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions(list['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the load definition object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").load_definitions(list['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain Load Definition 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

DELETE /domains/{domainId}/load-definitions/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Load Definition should be removed.
id String The id of the Load Definition to be removed from the Domain.

Request Parameters

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

A Load Definition must always belong to at least one Domain, so if you try to remove the Load Definition from the only Domain that it belongs to, the request must either fail, or delete the Load Definition. 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 Load Definition out of its last Domain will delete the Load Definition.

Response

The deletion response format is detailed here.

Domain Scenarios

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

List All Domain Scenarios

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").scenarios().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").scenarios().LIST():
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").scenarios.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").scenarios.list.each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/scenarios?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "id": "4d244d53-9450-11e9-8a98-29ad15a64fbc",
   "name": "Snow Day",
   "icon": null,
   "backgroundColor": "#1791CE",
   "domains": [
    {
     "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "North Campus",
     "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/",
     "namePath": "/North Campus/"
    }
   ],
   "createdAt": "2019-06-21T18:13:42.403+0000",
   "permissions": [
    "put",
    "delete",
    "get"
   ]
  }
 ]
}

Retrieves the list of all Scenarios in the Domain. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/scenarios

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Scenarios are to be listed.

Query Parameters

There was one scenario assigned to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Scenario whose names exactly match the supplied value.
recursive boolean If true, in addition to Scenarios that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Scenario response format is detailed here.

Check if a Domain contains a Scenario

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("2e5dbaf2-45c1-11e9-88d0-ddb588624ce9").scenarios("4d244d53-9450-11e9-8a98-29ad15a64fbc").GET().json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("2e5dbaf2-45c1-11e9-88d0-ddb588624ce9").scenarios("4d244d53-9450-11e9-8a98-29ad15a64fbc").get)
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/scenarios/4d244d53-9450-11e9-8a98-29ad15a64fbc" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "id": "4d244d53-9450-11e9-8a98-29ad15a64fbc",
 "name": "Snow Day",
 "icon": null,
 "backgroundColor": "#1791CE",
 "domains": [
  {
   "id": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "North Campus",
   "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/",
   "namePath": "/North Campus/"
  }
 ],
 "createdAt": "2019-06-21T18:13:42.403+0000",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

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

HTTP Request

GET /domains/{domainId}/scenarios/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Scenarios are of interest.
id The id of the Scenario whose membership in the Domain is being checked.

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

Parameter Type Description
recursive boolean If true, in addition to Scenarios that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

If the Scenario is part of the Domain (or a subdomain, if recursive is true), a response will be returned. The Distribution List 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 Domain Scenario

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("8b5ec352-6ce3-11e9-8128-731ed9098c36").scenarios().POST(data={
        'id': '4d244d53-9450-11e9-8a98-29ad15a64fbc'}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("8b5ec352-6ce3-11e9-8128-731ed9098c36").scenarios.post(
      :id => '4d244d53-9450-11e9-8a98-29ad15a64fbc'))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/scenarios" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "4d244d53-9450-11e9-8a98-29ad15a64fbc"}'
{
 "id": "4d244d53-9450-11e9-8a98-29ad15a64fbc",
 "name": "Snow Day",
 "icon": null,
 "backgroundColor": "#1791CE",
 "domains": [
  {
   "id": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "North Campus",
   "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/",
   "namePath": "/North Campus/"
  },
  {
   "id": "8b5ec352-6ce3-11e9-8128-731ed9098c36",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "East Campus",
   "path": "/8b5ec352-6ce3-11e9-8128-731ed9098c36/",
   "namePath": "/East Campus/"
  }
 ],
 "createdAt": "2019-06-21T18:13:42.403+0000",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

Puts the Scenario 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 /domains/{domainId}/scenarios

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain to which the Scenario should be added.

Request Parameters

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

A Scenario 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 Scenario 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 Domain Scenario

# Continuing with the scenario object from
# the previous example:
try:
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").scenarios(list['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the scenario object from
# the previous example:
begin
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").scenarios(list['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/scenarios/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain Scenario 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

DELETE /domains/{domainId}/scenarios/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Scenario should be removed.
id String The id of the Scenario to be removed from the Domain.

Request Parameters

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

A Scenario must always belong to at least one Domain, so if you try to remove the Scenario from the only Domain that it belongs to, the request must either fail, or delete the Scenario. 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 Scenario out of its last Domain will delete the Scenario.

Response

The deletion response format is detailed here.

Domain Security Groups

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

List All Domain Security Groups

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for group in icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups().LIST():
        print(group)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups.list.each do |group|
    puts JSON.pretty_generate(group)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJhZHJpYW4gYWRzaGVhZCIsImZiNTA3YTMwLTAxNTktMTFlNC1iYzNkLTY4NWIzNThlYTg0NyJd",
  "data": [
    {
      "id": "c54e4241-299b-11e8-94d3-2be9464da125",
      "name": "Custodial Staff",
      "superGroup": false,
      "permissions": [
          "delete",
          "put",
          "get"
      ],
      "createdAt": "2018-03-17T04:29:24.171+0000"
    }
  ]
}

Retrieves the list of all Security Groups in the Domain. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/security-groups

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Security Groups are to be listed.

Query Parameters

To make this example more manageable, only the first result was requested using the API’s pagination parameters. There were a total of 2 Security Groups assigned to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Security Groups whose names exactly match the supplied value.
recursive boolean If true, in addition to Security Groups that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Security Group response format is detailed here.

Check if a Domain contains a Security Group

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    group = icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups("c54e4241-299b-11e8-94d3-2be9464da125").GET().json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  group = JSON.parse(
    icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups("c54e4241-299b-11e8-94d3-2be9464da125").get)
  puts JSON.pretty_generate(group)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups/c54e4241-299b-11e8-94d3-2be9464da125" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "id": "c54e4241-299b-11e8-94d3-2be9464da125",
  "name": "Custodial Staff",
  "superGroup": false,
  "permissions": [
      "delete",
      "put",
      "get"
  ],
  "createdAt": "2018-03-17T04:29:24.171+0000"
}

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

HTTP Request

GET /domains/{domainId}/security-groups/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Security Groups are of interest.
id The id of the Security Group whose membership in the Domain is being checked.

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

Parameter Type Description
recursive boolean If true, in addition to Security Groups that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

Add a Domain Security Group

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    group = icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups().POST(data={
        'id': 'c54e4241-299b-11e8-94d3-2be9464da125'}).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  group = JSON.parse(
    icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups.post(
      :id => 'c54e4241-299b-11e8-94d3-2be9464da125'))
  puts JSON.pretty_generate(group)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "c54e4241-299b-11e8-94d3-2be9464da125"}'
{
  "id": "c54e4241-299b-11e8-94d3-2be9464da125",
  "name": "Custodial Staff",
  "superGroup": false,
  "permissions": [
      "delete",
      "put",
      "get"
  ],
  "createdAt": "2018-03-17T04:29:24.171+0000"
}

Puts the Security 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 /domains/{domainId}/security-groups

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain to which the Security Group should be added.

Request Parameters

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

A Security 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 Security 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 Domain Security Group

# Continuing with the security group object
# from the previous example:
try:
    print(icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups(group['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the security group object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.domains("90de0f6a-28df-11e8-8c38-e9fe0f3683de").security_groups(group['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups/c54e4241-299b-11e8-94d3-2be9464da125" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain Security Group c54e4241-299b-11e8-94d3-2be9464da125"
}

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

HTTP Request

DELETE /domains/{domainId}/security-groups/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Security Group should be removed.
id String The id of the Security Group to be removed from the Domain.

Request Parameters

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

A Security Group must always belong to at least one Domain, so if you try to remove the Security Group from the only Domain that it belongs to, the request must either fail, or delete the Security 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 Security Group out of its last Domain will delete the Security Group.

Response

The deletion response format is detailed here.

Domain Security Group Permissions

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, any open-ended Security Group Permissions are scoped (restricted) to apply only to a specific domain. This resource lets you find out which Security Group Permissions are scoped to a particular Domain.

List All Domain Security Group Permissions

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("69dab71b-12b2-11e8-bfe3-41154f2b6534").security_group_permissions().GET(params={
        'limit': 2}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for perm in icm_client.domains("69dab71b-12b2-11e8-bfe3-41154f2b6534").security_group_permissions().LIST():
        print(perm)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("69dab71b-12b2-11e8-bfe3-41154f2b6534").security_group_permissions.get(:params => {
      :limit => 2}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("69dab71b-12b2-11e8-bfe3-41154f2b6534").security_group_permissions.list.each do |perm|
    puts JSON.pretty_generate(perm)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/security-group-permissions?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "total": 120,
  "previous": null,
  "next": "2",
  "partial": true,
  "data": [
    {
      "id": "ab9ae477-dddb-11e6-a7a8-03b54b63f7b0",
      "securityGroupId": "8144e135-dddb-11e6-a7a8-ef9a4cfd53b5",
      "verb": "put",
      "spec": "/load-definitions/*/security-group-mappings/*",
      "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
      "securityGroup": {
          "id": "8144e135-dddb-11e6-a7a8-ef9a4cfd53b5",
          "name": "West Office",
          "superGroup": false,
          "createdAt": "2017-01-19T00:09:11.773+0000"
        },
        "permissions": [
          "delete",
          "put",
          "get"
        ],
        "createdAt": "2017-01-19T00:10:22.801+0000"
    },
    {
      "id": "ab9b0b88-dddb-11e6-a7a8-7b42f33ea4b7",
      "securityGroupId": "8144e135-dddb-11e6-a7a8-ef9a4cfd53b5",
      "verb": "get",
      "spec": "/notifications/*/recipients/*",
      "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
      "securityGroup": {
        "id": "8144e135-dddb-11e6-a7a8-ef9a4cfd53b5",
        "name": "West Office",
        "superGroup": false,
        "createdAt": "2017-01-19T00:09:11.773+0000"
      },
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2017-01-19T00:10:22.802+0000"
    }
  ]
}

These permissions mean that security group West Office can create update User Loader security group mappings and list all recipients of all notifications in the specified Domain. Since an unpredictable set of securityGroupId values might be present in results, the corresponding Security Group information is returned.

Retrieves the list of all Domain Security Group Permissions. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/security-group-permissions

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Security Group Permissions are to be listed.

Query Parameters

To make this example more manageable, only the first two results were requested using the API’s pagination parameters. There were a total of 120 Security Group Permissions scoped to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the permissions attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
recursive boolean If true, in addition to Security Group Permissions that are directly attached to the specified Domain, any permissions attached to its subdomains will be returned.

Response

The Domains Security Group Permissions response format is detailed here.

If recursive is true, an unpredictable set of domainId values might be returned, so the corresponding Domain information will be added to the response as well.

Get a Domain Security Group Permission

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    perm = icm_client.domains("69dab71b-12b2-11e8-bfe3-41154f2b6534").security_group_permissions("ab9b0b88-dddb-11e6-a7a8-7b42f33ea4b7").GET().json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  perm = JSON.parse(
    icm_client.domains("69dab71b-12b2-11e8-bfe3-41154f2b6534").security_group_permissions("ab9b0b88-dddb-11e6-a7a8-7b42f33ea4b7").get)
  puts JSON.pretty_generate(perm)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/security-group-permissions/ab9b0b88-dddb-11e6-a7a8-7b42f33ea4b7" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "id": "ab9b0b88-dddb-11e6-a7a8-7b42f33ea4b7",
  "securityGroupId": "8144e135-dddb-11e6-a7a8-ef9a4cfd53b5",
  "verb": "get",
  "spec": "/notifications/*/recipients/*",
  "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
  "securityGroup": {
    "id": "8144e135-dddb-11e6-a7a8-ef9a4cfd53b5",
    "name": "West Office",
    "superGroup": false,
    "createdAt": "2017-01-19T00:09:11.773+0000"
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2017-01-19T00:10:22.802+0000"
}

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

HTTP Request

GET /domains/{domainId}/security-group-permissions/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Security Group Permission is of interest.
id The id of the Security Group Permission scoped to the specified Domain to retrieve.

Response

The Domains Security Group Permissions response format is detailed here.

Domains Security Group Permissions Response

The JSON document used to represent a Domain Security Group Permission resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this permission was created.
domain Object When a recursive list is returned, for convenience this returns the actual Domain that the permission is scoped to.
domainId String The maximum scope at which the permission can be applied: for Domain-enabled resources, only those belonging to the specified Domain or its subdomains are affected by the permission.
id String The id of the Security Group Permission that is scoped to the Domain.
permissions Array[String] Options: get put delete. What operations are possible on this permission resource itself.
securityGroup Object For convenience, provides information (name, super-group flag, creation timestamp) about the security group to which the permsision applies.
securityGroupId String The id of the Security Group to which this permission applies.
spec String Identifies the path to the resource(s) the security group is being permitted to act on.
verb String Options: get post put delete. The action (HTTP method) which is permitted on the resource(s) identified by spec.

Domain Sites

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

List All Domain Sites

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").sites().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").sites().LIST():
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").sites.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").sites.list.each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/sites?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "id": "896437cf-9458-11e9-bb63-07b12ce3e3e2",
   "name": "North Campus",
   "domains": [
    {
     "id": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "North Campus",
     "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/",
     "namePath": "/North Campus/"
    }
   ],
   "createdAt": "2019-06-21T19:12:39.459+0000",
   "permissions": [
    "put",
    "delete",
    "get"
   ]
  }
 ]
}

Retrieves the list of all Sites in the Domain. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/sites

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Sites are to be listed.

Query Parameters

There was one site assigned to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Site whose names exactly match the supplied value.
recursive boolean If true, in addition to Sites that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Site response format is detailed here.

Check if a Domain contains a Site

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("2e5dbaf2-45c1-11e9-88d0-ddb588624ce9").sites("896437cf-9458-11e9-bb63-07b12ce3e3e2").GET().json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("2e5dbaf2-45c1-11e9-88d0-ddb588624ce9").sites("896437cf-9458-11e9-bb63-07b12ce3e3e2").get)
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/sites/896437cf-9458-11e9-bb63-07b12ce3e3e2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "id": "896437cf-9458-11e9-bb63-07b12ce3e3e2",
 "name": "North Campus",
 "domains": [
  {
   "id": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "North Campus",
   "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/",
   "namePath": "/North Campus/"
  }
 ],
 "createdAt": "2019-06-21T19:12:39.459+0000",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

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

HTTP Request

GET /domains/{domainId}/sites/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Sites are of interest.
id The id of the Site whose membership in the Domain is being checked.

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

Parameter Type Description
recursive boolean If true, in addition to Sites that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

If the Site is part of the Domain (or a subdomain, if recursive is true), a response will be returned. The Distribution List 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 Domain Site

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("8b5ec352-6ce3-11e9-8128-731ed9098c36").sites().POST(data={
        'id': '896437cf-9458-11e9-bb63-07b12ce3e3e2'}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("8b5ec352-6ce3-11e9-8128-731ed9098c36").sites.post(
      :id => '896437cf-9458-11e9-bb63-07b12ce3e3e2'))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/sites" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "896437cf-9458-11e9-bb63-07b12ce3e3e2"}'
{
 "id": "896437cf-9458-11e9-bb63-07b12ce3e3e2",
 "name": "North Campus",
 "domains": [
  {
   "id": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "North Campus",
   "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/",
   "namePath": "/North Campus/"
  }
  {
   "id": "8b5ec352-6ce3-11e9-8128-731ed9098c36",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "East Campus",
   "path": "/8b5ec352-6ce3-11e9-8128-731ed9098c36/",
   "namePath": "/East Campus/"
  }
 ],
 "createdAt": "2019-06-21T19:12:39.459+0000",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

Puts the Site 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 /domains/{domainId}/sites

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain to which the Site should be added.

Request Parameters

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

A Site 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 Site 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 Domain Site

# Continuing with the site object from the
# previous example:
try:
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").sites(list['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the site object from the
# previous example:
begin
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").sites(list['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/sites/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain Site 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

DELETE /domains/{domainId}/sites/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Site should be removed.
id String The id of the Site to be removed from the Domain.

Request Parameters

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

A Site must always belong to at least one Domain, so if you try to remove the Site from the only Domain that it belongs to, the request must either fail, or delete the Site. 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 Site out of its last Domain will delete the Site.

Response

The deletion response format is detailed here.

Domain Site Roles

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

List All Domain Site Roles

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles().GET(params={
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for list in icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles().LIST():
        print(list)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles.get(:params => {
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles.list.each do |list|
    puts JSON.pretty_generate(list)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "total": 2,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "name": "Site Role 1",
   "permissions": [ "delete", "put", "get" ],
   "domains": [
    {
     "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "Library",
     "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
     "namePath": "/Library/"
    },
    {
     "id": "2921a72c-3358-11e8-98ef-0d6e2a08c440",
     "parentId": "db4a21db-3357-11e8-98ef-d996a385fab5",
     "name": "Book Store",
     "path": "/db4a21db-3357-11e8-98ef-d996a385fab5/2921a72c-3358-11e8-98ef-0d6e2a08c440/",
     "namePath": "/East Campus/Book Store/"
    }
   ],
  },
 ]
}

Retrieves the list of all Site Roles in the Domain. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/site-roles

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Site Roles are to be listed.

Query Parameters

There were a total of two site roles assigned to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Site Roles whose names exactly match the supplied value.
recursive boolean If true, in addition to Site Roles that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Site Role response format is detailed here.

Check if a Domain contains a Site Role

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles("7030f7f4-4661-11e9-9372-ad3660dbb389").GET().json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles("7030f7f4-4661-11e9-9372-ad3660dbb389").get)
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
 "permissions": [ "delete", "put", "get" ],
 "domains": [
  {
   "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Library",
   "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
   "namePath": "/Library/"
  },
  {
   "id": "b390b781-e373-11e8-9c1a-b7d5944444f4",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Rec Center",
   "path": "/b390b781-e373-11e8-9c1a-b7d5944444f4/",
   "namePath": "/Rec Center/"
  }
 ],
 "name": "Site Role 1",
 "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
}

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

HTTP Request

GET /domains/{domainId}/site-roles/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Site Roles are of interest.
id The id of the Site Role whose membership in the Domain is being checked.

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

Parameter Type Description
recursive boolean If true, in addition to Site Roles that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

If the Site Role is part of the Domain (or a subdomain, if recursive is true), a response will be returned. The Distribution List 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 Domain Site Role

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    list = icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles().POST(data={
        'id': '7030f7f4-4661-11e9-9372-ad3660dbb389'}).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  list = JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles.post(
      :id => '7030f7f4-4661-11e9-9372-ad3660dbb389'))
  puts JSON.pretty_generate(list)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "7030f7f4-4661-11e9-9372-ad3660dbb389"}'
{
 "permissions": [ "delete", "put", "get" ],
 "domains": [
  {
   "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Library",
   "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
   "namePath": "/Library/"
  },
  {
   "id": "b390b781-e373-11e8-9c1a-b7d5944444f4",
   "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "name": "Rec Center",
   "path": "/b390b781-e373-11e8-9c1a-b7d5944444f4/",
   "namePath": "/Rec Center/"
  }
 ],
 "name": "Site Role 1",
 "createdAt": "2019-03-14T13:59:51.954+0000",
 "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
}

Puts the Site Role 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 /domains/{domainId}/site-roles

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain to which the Site Role should be added.

Request Parameters

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

A Site Role 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 Site Role 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 Domain Site Role

# Continuing with the site role object from
# the previous example:
try:
    print(icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles(list['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the site role object from
# the previous example:
begin
  puts JSON.parse(
    icm_client.domains("d3651b0a-3357-11e8-98ef-81eb3ce85bec").site_roles(list['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain Site Role 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

DELETE /domains/{domainId}/site-roles/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Site Role should be removed.
id String The id of the Site Role to be removed from the Domain.

Request Parameters

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

A Site Role must always belong to at least one Domain, so if you try to remove the Site Role from the only Domain that it belongs to, the request must either fail, or delete the Site Role. 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 Site Role out of its last Domain will delete the Site Role.

Response

The deletion response format is detailed here.

Domain Users

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

List All Domain Users

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    print(icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users().GET(params={
        'transitive': true,
        'limit': 1}).json())
except RequestException as e:
    print('Unexpected error!', e)
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
    for user in icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users().LIST(params={
            'transitive': true}):
        print(user)
# While you can get the low-level pagination
# structures this way:
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  puts JSON.parse(
    icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users.get(:params => {
      :transitive => true,
      :limit => 1}))
rescue => e
  p e
end
#
# It is more convenient to let the client
# library do the pagination and lazy loading
# for you:
  icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users.list(:params => {
      :transitive => true}).each do |user|
    puts JSON.pretty_generate(user)
  end
curl "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users?transitive=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "total": 4,
  "partial": true,
  "previous": null,
  "next": "WyJhZHJpYW4gYWRzaGVhZCIsImZiNTA3YTMwLTAxNTktMTFlNC1iYzNkLTY4NWIzNThlYTg0NyJd",
  "data": [
    {
      "lock": { "start": "2014-03-16T14:00:00.000+0000", "end": "2014-09-16T14:00:00.000+0000" },
      "name": "Al Smith",
      "securityGroups": [
        {
          "createdAt": "2014-05-16T14:50:23.126+0000",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "id": "68a3db60-dd09-11e3-8c49-b8e856327746",
          "securityGroupId": "3aa5dec0-dd09-11e3-b17e-b8e856327746"
        }
      ],
      "passwordResetRequired": false,
      "createdAt": "2014-05-16T14:50:22.656+0000",
      "email": "al.smith@acme.edu",
      "type": "regular",
      "idleTimeout": null,
      "permissions": ["delete", "put", "get"],
      "subscriptions": [
        {
          "createdAt": "2014-05-19T19:09:21.020+0000",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
          "id": "152f93c0-df89-11e3-93bc-685b358ea847"
        },
        {
          "createdAt": "2014-07-22T19:15:42.057+0000",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
          "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
        }
      ],
      "source": "direct",
      "securityGroupId": null,
      "id": "685c2400-dd09-11e3-8c49-b8e856327746"
    }
  ]
}

Retrieves the list of all Users in the Domain. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /domains/{domainId}/users

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated Users are to be listed.

Query Parameters

To make this example more manageable, only the first result was requested using the API’s pagination parameters. There were a total of 4 Users assigned to the specified Domain when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the users attached to any ancestors of the specified Domain, or who can act in the Domain through one or more Security Groups, using query parameters, and you can filter the results by matching on the User name:

Parameter Type Description
compact boolean Ignored unless transitive is true. For transitive queries, setting compact to true will suppress the additional source information described below, and ensure that each User appears in the response only once.
name String Returns only Users whose names exactly match the supplied value.
recursive boolean If true, in addition to Users that are directly attached to the specified Domain, any attached to its ancestors will be returned.
transitive boolean If true, in addition to Users that are directly attached to the specified Domain, any attached to ancestors of the Domain, or to Security Groups that are attached to the Domain and its ancestors, will be returned (transitive takes precedence over recursive, so passing true for both is the same as just passing true for transitive).

Response

The User response format is detailed here.

If recursive is true you get back the list of all Users that are visible from the chosen Domain, because they are either a member of the Domain directly, or they are a member of one of its subdomains.

If transitive is true, you get back the list of all Users that can act in the chosen Domain, either because they are a direct member of the Domain or one of its ancestors, or because they belong to a Security Group that is attached to the domain or one of its ancestors. For transitive requests (unless you suppress this by setting compact to true) in addition to the normal User response attributes, information explaining why the user is able to act in the Domain is added. The same user might appear in the response list more than once, with different sources cited, as detailed below.

The possible source values are:

Source Meaning
direct The user is directly attached to the Domain.
group The user is attached to a Security Group that is attached to the specified Domain.
parent The user is attached to a parent (ancestor) Domain of the specified Domain, either directly or through a Security Group.

When source is group (or parent, if the parent Domain was included because of a Security Group), information about the Security Group is included in the response as well:

Attribute Type Description
source String Option: direct, parent, group. The reason the user can act in the domain.
securityGroup Object When source is group or parent, this may contain a Security Group response describing the group through which the user is able to act in the Domain.
securityGroupId String When source is group or parent, this is the id of the Security Group through which the user is able to act in the Domain.

Note that the consideration of parent Domains for transitive requests is always performed, so when transitive is specified, recursive has no meaning.

Check if a Domain contains a User

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    user = icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users("685c2400-dd09-11e3-8c49-b8e856327746").GET().json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  user = JSON.parse(
    icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users("685c2400-dd09-11e3-8c49-b8e856327746").get)
  puts JSON.pretty_generate(user)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users/685c2400-dd09-11e3-8c49-b8e856327746" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
{
  "lock": { "start": "2014-03-16T14:00:00.000+0000", "end": "2014-09-16T14:00:00.000+0000" },
  "name": "Al Smith",
  "securityGroups": [
    {
      "createdAt": "2014-05-16T14:50:23.126+0000",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "id": "68a3db60-dd09-11e3-8c49-b8e856327746",
      "securityGroupId": "3aa5dec0-dd09-11e3-b17e-b8e856327746"
    }
  ],
  "passwordResetRequired": false,
  "createdAt": "2014-05-16T14:50:22.656+0000",
  "email": "al.smith@acme.edu",
  "type": "regular",
  "idleTimeout": null,
  "permissions": ["delete", "put", "get"],
  "subscriptions": [
    {
      "createdAt": "2014-05-19T19:09:21.020+0000",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
      "id": "152f93c0-df89-11e3-93bc-685b358ea847"
    },
    {
      "createdAt": "2014-07-22T19:15:42.057+0000",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
      "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
    }
  ],
  "id": "685c2400-dd09-11e3-8c49-b8e856327746"
}

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

HTTP Request

GET /domains/{domainId}/users/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Users are of interest.
id The id of the User whose membership in the Domain is being checked.

Additionally, you can check if the user is attached to any subdomains of the specified Domain, or can act in the Domain through one or more Security Groups using query parameters:

Parameter Type Description
recursive boolean If true, in addition to Users that are directly attached to the specified Domain, any attached to its subdomains will be considered.
transitive boolean If true, in addition to Users that are directly attached to the specified Domain, any attached to Security Groups that are attached to the Domain or its subdomains will be considered (transitive implies recursive, so passing true for both is the same as just passing true for transitive).

Response

If the User can act in the Domain, a response will be returned. The User response format is detailed here. If they cannot, the response status will indicate that the requested resource cannot be found.

If transitive is true, in addition to the normal User response attributes, information explaining why the user is able to act in the Domain is added. The possible source values are:

Source Meaning
direct The user is directly attached to the Domain.
parent The user is attached to a parent Domain of the specified Domain.
group The user is attached to a Security Group that is attached to the specified Domain, or to one of its parent Domains.

When source is group, information about the Security Group is included in the response as well:

Attribute Type Description
source String Option: direct, parent, group. The reason the user can act in the domain.
securityGroup Object When source is group, this will contain a Security Group response describing the group through which the user is able to act in the Domain.
securityGroupId String When source is group, this is the id of the Security Group through which the user is able to act in the Domain.

Add a Domain User

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    user = icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users().POST(data={
        'id': '685c2400-dd09-11e3-8c49-b8e856327746'}).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  user = JSON.parse(
    icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users.post(
      :id => '685c2400-dd09-11e3-8c49-b8e856327746'))
  puts JSON.pretty_generate(user)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "685c2400-dd09-11e3-8c49-b8e856327746"}'
{
  "lock": { "start": "2014-03-16T14:00:00.000+0000", "end": "2014-09-16T14:00:00.000+0000" },
  "name": "Al Smith",
  "securityGroups": [
    {
      "createdAt": "2014-05-16T14:50:23.126+0000",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "id": "68a3db60-dd09-11e3-8c49-b8e856327746",
      "securityGroupId": "3aa5dec0-dd09-11e3-b17e-b8e856327746"
    }
  ],
  "passwordResetRequired": false,
  "createdAt": "2014-05-16T14:50:22.656+0000",
  "email": "al.smith@acme.edu",
  "type": "regular",
  "idleTimeout": null,
  "permissions": ["delete", "put", "get"],
  "subscriptions": [
    {
      "createdAt": "2014-05-19T19:09:21.020+0000",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
      "id": "152f93c0-df89-11e3-93bc-685b358ea847"
    },
    {
      "createdAt": "2014-07-22T19:15:42.057+0000",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
      "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
    }
  ],
  "id": "685c2400-dd09-11e3-8c49-b8e856327746"
}

Puts the User 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 /domains/{domainId}/users

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain to which the User should be added.

Request Parameters

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

For details on the use of promote and demote, see the following section.

Promotion and Demotion of Users

The concepts of promotion an demotion relate to Domain hierarchies. Consider a set of domains /, /West Campus/, /West Campus/Library/ /West Campus/Gym/, and /East Campus/.

alt text

A campus example with hierarchical Domains.

These form a hierarchy, and membership in a parent Domain automatically confers membership in any children of that domain. For example, Amy, a user in Domain / is automatically in every Domain that exists. Don, A user in domain /West Campus/ is also automatically in /West Campus/Library/ and /West Campus/Gym/.

A user may belong to multiple domains. Consider Fay in the diagram below. She is a member of both the /West Campus/ and /East Campus/ Domains.

alt text

A User in two Domains.

However, a user is not allowed to be explicitly part of any Domain that they are implicitly granted membership to by belonging to a parent Domain. If try to add Eli to /West Campus/Gym/ that request will fail because he is already implicitly in that domain because of his membership in the parent /West Campus/ Domain.

In order to actually add Eli to /West Campus/Gym/ you need to set the request parameter demote to true, which will take him out of /West Campus/ when adding him to /West Campus/Gym/.

alt text

A demoted user taken from a parent Domain and added to a child.

The restriction works in the other direction as well. If you try to add Fay to the root Domain, /, the request will fail because she is in two of Root’s child Domains. In order to actually do it, you need to set the request parameter promote to true, which will take Fay out of the conflicting child Domains, leaving her only in the Domain /.

alt text

A promoted user taken from two child Domains and added to common parent.

It is worth noting that Users (and other resources) can participate in multiple domains at multiple levels, not just at the same level. For example, Eli could be a member of both the /West Campus/Gym/ and /East Campus domains.

alt text

A user in two domains at differing levels of the hierarchy.

You are also not restricted in how many levels you traverse for a given promotion or demotion. In the example above, Amy could be demoted directly to /West Campus/Gym/ and Leo could be promoted directly to /.

Remove a Domain User

# Continuing with the user object from the
# previous example:
try:
    print(icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users(user['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the user object from the
# previous example:
begin
  puts JSON.parse(
    icm_client.domains("9ca35dab-28df-11e8-8c38-235a5737f6bb").users(user['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users/685c2400-dd09-11e3-8c49-b8e856327746" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
  "status": 200,
  "message": "deleted Domain User 685c2400-dd09-11e3-8c49-b8e856327746"
}

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

HTTP Request

DELETE /domains/{domainId}/users/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the User should be removed.
id String The id of the User to be removed from the Domain.

Request Parameters

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

A User must always belong to at least one Domain, so if you try to remove the User from the only Domain that it belongs to, the request must either fail, or delete the User. 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 User out of its last Domain will delete the User.

Response

The deletion response format is detailed here.

Domain User Permissions

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, any open-ended User Permissions are scoped (restricted) to apply only to a specific domain. This resource lets you find out which User Permissions are scoped to a particular Domain.

List All Domain User Permissions

# While you can get the low-level pagination
# structures this way:
from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token