NAV
cURL python ruby

API Overview

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

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

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

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

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

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

Prerequisites

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

Mobile devices registering with InformaCast Mobile have the following prerequisites:

API Documentation

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

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

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

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

Terminology

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

API Explorer Tour

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

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

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

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

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

API Explorer Token Text Field

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

API Explorer Token Text Field

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

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

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

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

Helpful Clients

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

Authentication

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

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

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

Create a Token for Experimentation

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

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

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

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

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

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

Create a Permanent Token

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

Use the following steps to create a permanent token.

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

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

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

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

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

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

Use the Token

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

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

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

Authorization Header

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/session" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)

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

require 'httparty'
require 'json'

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

}

begin: 
    user = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(user)
rescue StandardError => e
    puts e
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"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    user = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
# This is a thin wrapper around rest-client;
# details on other ways you can use it are in
# http://www.rubydoc.info/github/rest-client/rest-client
{
  "lock": null,
  "name": "Craig Smith",
  "securityGroups": [ ],
  "passwordResetRequired": false,
  "createdAt": "2014-08-13T20:33:53.262Z",
  "email": "craig.smith@acme.com",
  "permissions": ["delete", "put", "get"],
  "subscriptions": [ ],
  "id": "2400c8e0-2329-11e4-8e47-685b358ea847"
}

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

Create Your First Distribution List

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

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

Subscribe a User to a Distribution List

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

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

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

Register a User’s Device

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

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

Add a Confirmation Request

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

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

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

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

Create the Message Template

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

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

Send the Notification

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

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

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

Change Log

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

Changes from 2024-02-21

Added

Changes from 2023-12-13

Changes from 2023-09-20

Changes from 2023-08-09

Old New
/V1/ActivationGroups /Fusion/V1/ActivationGroups
/V1/Admin/Telephony /Fusion/V1/Admin/Telephony
/V1/Admin/TtsLexicon /Fusion/V1/Admin/TtsLexicon
/V1/Admin/TtsVoices /Fusion/V1/Admin/TtsVoices
/V1/Bells /Fusion/V1/Bells
/V1/Endpoints /Fusion/V1/Endpoints
/V1/Messages /Fusion/V1/Messages
/V1/Plugins/NightBell /Fusion/V1/Plugins/NightBell
/V1/RecipientGroups /Fusion/V1/RecipientGroups
/V1/ScheduledBroadcasts /Fusion/V1/ScheduledBroadcasts
/V1/Plugins/CallAware /Fusion/V1/Plugins/CallAware
/V1/Plugins/M2M /Fusion/V1/Plugins/M2M
/V1/Plugins/NightBell /Fusion/V1/Plugins/NightBell

Changes from 2023-06-28

Changes from 2023-05-16

BREAKING CHANGE

Added

Changes from 2023-02-22

Changed

BREAKING CHANGE As announced last fall, there is a significant change to the way that site information is communicated for scenarios. This was previously implemented using a single site field which could be answered with a site ID or name. To improve consistency, and to add support for more detailed location information, site fields are being removed from scenarios, and instead a location object will be submitted when creating scenario notifications. This location object will at minimum contain a site object specifying the site ID, but can also contain building, floor, and zone objects (again, specifying their IDs) for increasing levels of detail.

Rather than using a site field, scenarios will indicate that they support location information with a new locationEnabled boolean attribute. When locationEnabled is true, the text that clients should use to prompt for location information will be configured using the new attribute locationQuestionName, and a backwards-compatible variable in which a summary of the location object will be made available for customizing notification text will be configured using the new attribute locationVariable. Default answers for site, building, floor, and zone can be configured using the new attributes defaultSiteId, defaultBuildingId, defaultFloorId, and defaultZoneId (an example of increased flexibility; previously it was only possible to specify a default site).

Existing scenarios which have site fields will be migrated automatically to use locationEnabled instead, and the values of locationQuestionName, locationVariable, and defaultSiteId will be set up from the former site question.

To offer backwards compatibility with older mobile clients, for several releases after the switch to using location a synthetic site question will be reported in the fields response for any location-enabled scenario. (This fake site field can be recognized because it is the only site field that will exist in a scenario, will have an id of 55ca36de-4b3c-11ed-aeff-17a043a08a03, and will always have the highest rank.) Clients that do not yet know how to send the location object will be able to continue sending this field instead. Code that has been updated to send location values must filter out this question, since it is redundant with sending location, and attempts to send both location and a site field will result in a validation failure. Applications should be updated to send the more flexible location object as soon as possible. A few releases after location is supported, this backwards compatibility mode will be removed: the synthetic site question will stop appearing in the fields, and will no longer be accepted when sending a scenario notificaiton.

NOTE We had previously planned on using a rank of 0 for the fake site question, but this turned out to create compatibility problems with older versions of some mobile apps, so we changed to this approach for better compatibility during the transition period.

Even during the period of backwards compatibility, it will not be possible to configure scenarios to have actual site fields using the scenarios API. The administrative web application will be updated to use the new locationEnabled and related attributes described above, and any other integrations which directly manipulate scenario resources will need to make the same changes.

Added

Changes from 2022-12-14

Added

Changes from 2022-11-02

Changed

Added

Changes from 2022-09-21

Changed

Changes from 2022-08-10

Added

Changes from 2022-06-29

Changes from 2022-06-01

Changed

Changes from 2022-05-18

Changed

Removed

Changes from 2022-02-23

Deprecated

Added

Changes from 2021-12-15

Removed

Changes from 2021-11-03

Added

Changed

Removed

Changes from 2021-09-22

Deprecated

Changes from 2021-08-04

Added

Changed

Changes from 2021-06-30

Added

Changed

Deprecated

Removed

Changes from 2021-05-12

Added

Changed

Changes from 2021-04-14

Added

Updated

Changes from 2020-12-09

Added

Updated

Changes from 2020-09-23

Updated

Changes from 2020-08-12

Added

Updated

Changes from 2020-06-24

Added

Changes from 2020-05-13

Changed

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

Changes from 2020-04-01

Deprecated

Added

Changed

Changes from 2020-02-19

Removed

Added

Changes from 2019-12-16

Removed

Added

Changes from 2019-11-13

Deprecated

Removed

Changes from 2019-10-30

Added

Changed

Deprecated

 

Alarms

Alarms are a resource which receive and store information on the health of InformaCast.

id Type Description
dcaca6f6-9d71-11eb-b775-0242ac110003 fusion_server_red Alerts you when on-premises server(s) have entered/exited a severely degraded state of service.
cdcf1a88-9d71-11eb-b775-0242ac110003 fusion_server_yellow Alerts you when on-premises server(s) have entered/exited a mildly degraded state of service.
e2125942-9d71-11eb-b775-0242ac110003 license_violation Alerts you when your instance of InformaCast is in violation of your organization’s license.
91b26697-934f-11ec-b6a2-99eae723bd46 phone_cache_update_failed Alerts you when InformaCast fails to build a list of registered Cisco IP phones for Unified CM.
a25f212f-9d71-11eb-b775-0242ac110003 sis_loader_failed Alerts you when InformaCast encounters errors during an import of data from your Student Information System (SIS).
f28b0080-9d71-11eb-b775-0242ac110003 speakers_unregistered Alerts you when on-premises server(s) have detected that their number of registered speakers is below your organization’s set amount.
4f2a8452-71bc-11ed-aa23-9bc083285fdb fusion_delta_sync_error_event Alerts you when on-premises server(s) have failed to synchronize information they pulled from the InformaCast cloud.
5bcebefb-4d8c-11ee-85bb-c5b3d0db8947 token_expiration Alerts you when on-premises server(s) have failed to synchronize information they pulled from the InformaCast cloud.

List Alarms

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 4,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
   {
    "id": "dcaca6f6-9d71-11eb-b775-0242ac110003",
    "status": "OK",
    "type": "fusion_server_red",
    "muted": true,
    "updatedAt": "2021-09-08T13:41:16.807Z",
    "createdAt": "2021-04-14T22:36:32.409Z",
    "permissions": [
     "put",
     "get"
    ]
   }
  ]
}

Gets a list of all alarms 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 /alarms

Produces

application/json

Query Parameters

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

Parameter Type Description
includeThresholds Boolean If true, include the list of Alarm Thresholds associated with the alarm. Only available for the speaker registration alarm.
includeActions Boolean If true, include the list Alarm Action ids associated with the alarm.

Response

The alarm response format is detailed here.

Get an Alarm

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/f28b0080-9d71-11eb-b775-0242ac110003"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/f28b0080-9d71-11eb-b775-0242ac110003" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/alarms/f28b0080-9d71-11eb-b775-0242ac110003"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "f28b0080-9d71-11eb-b775-0242ac110003",
 "status": "ACTIVE",
 "type": "speakers_unregistered",
 "muted": false,
 "updatedAt": "2021-09-08T13:41:16.807Z",
 "createdAt": "2021-04-14T22:37:09.099Z",
 "permissions": [
  "put",
  "get"
 ]
}

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

HTTP Request

GET /alarms/{alarmId}

Produces

application/json

Path Parameters

Parameter Description
alarmId The id of the alarm to retrieve.

Query Parameters

Parameter Type Description
includeThresholds Boolean If true, include the list of Alarm Thresholds associated with the alarm. Only available for the speaker registration alarm.
includeActions Boolean If true, include the list Alarm Action ids associated with the alarm.

Response

The alarm response format is detailed here.

Update an Alarm

# Continuing with the alarm object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/f28b0080-9d71-11eb-b775-0242ac110003" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"muted": true}'
# Continuing with the alarm object from the
# previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "f28b0080-9d71-11eb-b775-0242ac110003",
 "status": "ACTIVE",
 "type": "speakers_unregistered",
 "muted": true,
 "updatedAt": "2021-09-08T13:41:16.807Z",
 "createdAt": "2021-04-14T22:37:09.099Z",
 "permissions": [
  "put",
  "get"
 ]
}

Updates an existing alarm. Note that only muted and alarmThresholds may be updated as part of an update.

HTTP Request

PUT /alarms/{alarmId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
alarmId The id of the alarm to update.

Request Parameters

Parameter Type Default Description
id String N/A The id of the alarm.
muted Boolean N/A Mutes an alarm, which prevents actions from being sent.
alarmThresholds Array[Alarm Thresholds] N/A The alarm thresholds of the alarm.

Response

The alarm response format is detailed here.

Alarm Thresholds

Alarm Thresholds contain information about the number of devices that can unregister before we activate the alarm. Only necessary on alarms which need to monitor device registration, eg. speakers.

Alarm Thresholds do not have their own endpoint, and are instead nested inside of an array in alarm resources.

Attribute Type Description
id String The id of the threshold.
alarmId String The id of the associated alarm.
endpointId String The id of the fusion server this threshold should be set to. Allows customization of thresholds if different servers have different speaker counts.
threshold String The number of devices that can unregister before we send an alarm notification.

Alarm Response

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

Attribute Type Description
createdAt ISO 8601 date/time When this alarm was created.
updatedAt ISO 8601 date/time When this alarm was last updated.
id String The id of the alarm, for efficient retrieval or manipulation of the alarm. Not writable.
status String The status of the alarm, one of OK and ACTIVE, where ACTIVE indicates the alarm has detected a problem in the system. Not writable.
type String A snake case description of the type of alarm associated with the resource.
muted String Whether the alarm will send notifications when its state changes.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Alarm Actions

Alarm Actions are a resource that stores the notification details to be sent when an alarm is triggered.

Information about the action that should be triggered when an event occurs. Includes configuration for a message to be sent when a system health check fails.

List Alarm Actions

Gets a list of all alarm actions of a specific alarm available to the current user.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/cdcf1a88-9d71-11eb-b775-0242ac110003/actions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/cdcf1a88-9d71-11eb-b775-0242ac110003/actions" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/alarms/cdcf1a88-9d71-11eb-b775-0242ac110003/actions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
"total": 2,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
            {
            "permissions": [
                "put",
                "delete",
                "get"
            ],
            "messageTemplateId": "bc7768e2-1ca0-11ec-aa38-592256cda945",
            "alarmId": "dcaca6f6-9d71-11eb-b775-0242ac110003",
            "collaborationGroups": [],
            "messageTemplate": {
                "imageDisplay": "auto",
                "optOut": false,
                "inferredMessageType": "Text",
                "userIdsDisplay": "auto",
                "ttsVoiceIdCustomizable": false,
                "imageCustomizable": false,
                "ttsVoiceIdDisplay": "auto",
                "imageFiles": [],
                "ttsCustomContent": "",
                "deviceGroupIdsDisplay": "auto",
                "collaborationGroups": [],
                "ttsCustomContentCustomizable": true,
                "incidentPlanId": null,
                "name": "sendstonoone",
                "audioDisplay": "auto",
                "expiration": null,
                "createdAt": "2021-09-23T19:02:02.393Z",
                "distributionListIds": [],
                "subjectCustomizable": true,
                "confirmationRequestIdCustomizable": false,
                "voice": {
                    "id": "751de142-841a-11ea-a32f-17f989f7588d",
                    "name": "Joanna",
                    "gender": "Female",
                    "language": "en-US",
                    "engine": "neural",
                    "synthesisProvider": "Amazon Polly"
                },
                "distributionListIdsCustomizable": true,
                "deviceGroupIds": [],
                "syncId": "bc7768e2-1ca0-11ec-aa38-592256cda945:1632423769247",
                "areaOfInterestIdsCustomizable": true,
                "areasOfInterest": [],
                "deviceGroupIdsCustomizable": true,
                "collaborationGroupIdsCustomizable": true,
                "audioFiles": [],
                "bodyDisplay": "auto",
                "expirationCustomizable": false,
                "confirmationRequestId": null,
                "incidentPlanIdDisplay": "auto",
                "collaborationGroupIdsDisplay": "auto",
                "alertToneDisplay": "auto",
                "userIdsCustomizable": true,
                "ttsVoiceId": "751de142-841a-11ea-a32f-17f989f7588d",
                "id": "bc7768e2-1ca0-11ec-aa38-592256cda945",
                "notificationProfileId": "66405cdb-cde9-11eb-8059-87f0c8f1aa98",
                "collaborationGroupIds": [],
                "ttsType": "none",
                "bodyCustomizable": true,
                "imageMimeType": null,
                "distributionListIdsDisplay": "auto",
                "confirmationRequest": null,
                "ttsCustomContentDisplay": "auto",
                "image": 0,
                "subjectDisplay": "auto",
                "audio": 0,
                "distributionLists": [],
                "audioCustomizable": false,
                "incidentPlan": null,
                "expirationDisplay": "auto",
                "incidentPlanIdCustomizable": false,
                "body": "body",
                "userIds": [],
                "confirmationRequestIdDisplay": "auto",
                "deviceGroups": [],
                "followUp": false,
                "alertToneCustomizable": false,
                "areaOfInterestIds": [],
                "metadata": {},
                "subject": "subject",
                "alertTone": "default",
                "users": [],
                "areaOfInterestIdsDisplay": "auto",
                "metadataCustomizable": false
            },
            "createdAt": "2021-09-21T14:48:40.549Z",
            "distributionListIds": [],
            "deviceGroupIds": [],
            "areasOfInterest": [],
            "id": "02a29a4d-1aeb-11ec-9499-8bf44620b8b8",
            "collaborationGroupIds": [],
            "distributionLists": [],
            "userIds": [],
            "deviceGroups": [],
            "triggerOnStatus": "ACTIVE",
            "areaOfInterestIds": [],
            "users": []
        },
    ]
}

HTTP Request

GET /alarms/{alarmId}/actions

Produces

application/json

Query Parameters

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

Path Parameters

Attribute Type Description
alarmId String The id of the alarm you want to get all the actions of.

Get Alarm Actions

The action triggered for each alarm type. Stores notification details.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/cdcf1a88-9d71-11eb-b775-0242ac110003/actions/136ccc57-1d71-11ec-aa38-c99a03e48334"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/cdcf1a88-9d71-11eb-b775-0242ac110003/actions/136ccc57-1d71-11ec-aa38-c99a03e48334" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/alarms/cdcf1a88-9d71-11eb-b775-0242ac110003/actions/136ccc57-1d71-11ec-aa38-c99a03e48334"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
    "permissions": [
        "put",
        "delete",
        "get"
    ],
    "messageTemplateId": "66f2bbfe-cde9-11eb-8059-e189c5a04e8b",
    "alarmId": "cdcf1a88-9d71-11eb-b775-0242ac110003",
    "collaborationGroups": [],
    "messageTemplate": {
        "imageDisplay": "auto",
        "optOut": false,
        "inferredMessageType": "Text",
        "userIdsDisplay": "auto",
        "ttsVoiceIdCustomizable": true,
        "imageCustomizable": false,
        "ttsVoiceIdDisplay": "auto",
        "imageFiles": [
            {
                "fileName": "all-clear.png",
                "size": 18003,
                "contentType": "image/png",
                "metadata": {
                    "data": {
                        "sampleFormat": "UnsignedIntegral",
                        "bitsPerSample": "8 8 8 8",
                        "planarConfiguration": "PixelInterleaved"
                    },
                    "width": 960,
                    "chroma": {
                        "blackIsZero": true,
                        "numChannels": 4,
                        "colorSpaceType": "RGB"
                    },
                    "height": 660,
                    "dimension": {
                        "imageOrientation": "Normal",
                        "pixelAspectRatio": 1.0,
                        "verticalPixelSize": 0.35285816,
                        "horizontalPixelSize": 0.35285816
                    },
                    "compression": {
                        "lossless": true,
                        "compressionTypeName": "deflate",
                        "numProgressiveScans": 1
                    },
                    "transparency": {
                        "alpha": "nonpremultipled"
                    }
                }
            }
        ],
        "ttsCustomContent": null,
        "deviceGroupIdsDisplay": "auto",
        "collaborationGroups": [],
        "ttsCustomContentCustomizable": true,
        "incidentPlanId": null,
        "name": "All Clear",
        "audioDisplay": "auto",
        "expiration": null,
        "createdAt": "2021-06-15T14:53:10.319Z",
        "distributionListIds": [],
        "subjectCustomizable": true,
        "confirmationRequestIdCustomizable": false,
        "distributionListIdsCustomizable": true,
        "deviceGroupIds": [],
        "syncId": "66f2bbfe-cde9-11eb-8059-e189c5a04e8b:1623768790807",
        "areaOfInterestIdsCustomizable": true,
        "areasOfInterest": [],
        "deviceGroupIdsCustomizable": true,
        "collaborationGroupIdsCustomizable": true,
        "audioFiles": [],
        "bodyDisplay": "auto",
        "expirationCustomizable": true,
        "confirmationRequestId": null,
        "incidentPlanIdDisplay": "auto",
        "collaborationGroupIdsDisplay": "auto",
        "alertToneDisplay": "auto",
        "userIdsCustomizable": true,
        "ttsVoiceId": null,
        "id": "66f2bbfe-cde9-11eb-8059-e189c5a04e8b",
        "notificationProfileId": "66405cdb-cde9-11eb-8059-87f0c8f1aa98",
        "collaborationGroupIds": [],
        "ttsType": "none",
        "bodyCustomizable": true,
        "imageMimeType": null,
        "distributionListIdsDisplay": "auto",
        "confirmationRequest": null,
        "ttsCustomContentDisplay": "auto",
        "image": 18003,
        "subjectDisplay": "auto",
        "audio": 0,
        "distributionLists": [],
        "audioCustomizable": true,
        "incidentPlan": null,
        "expirationDisplay": "auto",
        "incidentPlanIdCustomizable": false,
        "body": "The situation is under control and the all-clear notification has been issued. Normal activities may be resumed. If you have any questions or concerns, please call <INSERT NUMBER HERE>.",
        "userIds": [],
        "confirmationRequestIdDisplay": "auto",
        "deviceGroups": [],
        "followUp": false,
        "alertToneCustomizable": false,
        "areaOfInterestIds": [],
        "metadata": null,
        "subject": "ALL CLEAR! Resume normal activities.",
        "alertTone": "all-clear1",
        "users": [],
        "areaOfInterestIdsDisplay": "auto",
        "metadataCustomizable": true
    },
    "createdAt": "2021-09-24T19:53:23.605Z",
    "distributionListIds": [],
    "deviceGroupIds": [],
    "areasOfInterest": [],
    "id": "136ccc57-1d71-11ec-aa38-c99a03e48334",
    "collaborationGroupIds": [],
    "distributionLists": [],
    "userIds": [
        "f7a6d830-cdea-11eb-8059-ddbbbdf7035e"
    ],
    "deviceGroups": [],
    "triggerOnStatus": "ACTIVE",
    "areaOfInterestIds": [],
    "users": [
        {
            "email": "admin@dev.com",
            "name": "admin",
            "createdAt": "2021-06-15T15:04:22.588Z",
            "type": "regular",
            "selfRegistered": false,
            "idleTimeout": 720,
            "loadSourceId": null,
            "id": "f7a6d830-cdea-11eb-8059-ddbbbdf7035e",
            "isLicensed": true,
            "isLocked": false
        }
    ]
}

HTTP Request

GET /alarms/{alarmId}/actions/{id}

Produces

application/json

Path Parameters

Parameter Description
id The id of the Alarm Actions.
alarmId The id of the Alarm.

Create Alarm Action

Create an alarm action.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/e2125942-9d71-11eb-b775-0242ac110003/actions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'alarmId': 'e2125942-9d71-11eb-b775-0242ac110003'
,
    'triggerOnStatus': 'ACTIVE'
,
    'messageTemplateId': '66f2bbfe-cde9-11eb-8059-e189c5a04e8b'
,
    'userIds': ['f7a6d830-cdea-11eb-8059-ddbbbdf7035e'
]

}

begin: 
    role = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/e2125942-9d71-11eb-b775-0242ac110003/actions" \
  -X “POST” \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"alarmId": "e2125942-9d71-11eb-b775-0242ac110003", \
       "triggerOnStatus": "ACTIVE", \
       "messageTemplateId": "66f2bbfe-cde9-11eb-8059-e189c5a04e8b", \
       "userIds": ["f7a6d830-cdea-11eb-8059-ddbbbdf7035e"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/alarms/e2125942-9d71-11eb-b775-0242ac110003/actions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'alarmId': 'e2125942-9d71-11eb-b775-0242ac110003',
    'triggerOnStatus': 'ACTIVE',
    'messageTemplateId': '66f2bbfe-cde9-11eb-8059-e189c5a04e8b',
    'userIds': ['f7a6d830-cdea-11eb-8059-ddbbbdf7035e']
}

try: 
    role = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
   "permissions":[
      "put",
      "delete",
      "get"
   ],
   "messageTemplateId":"66f2bbfe-cde9-11eb-8059-e189c5a04e8b",
   "alarmId":"dcaca6f6-9d71-11eb-b775-0242ac110003",
   "collaborationGroups":[],
   "messageTemplate":{
      "imageDisplay":"auto",
      "optOut":false,
      "inferredMessageType":"Text",
      "userIdsDisplay":"auto",
      "ttsVoiceIdCustomizable":true,
      "imageCustomizable":false,
      "ttsVoiceIdDisplay":"auto",
      "imageFiles":[
         {
            "fileName":"all-clear.png",
            "size":18003,
            "contentType":"image/png",
            "metadata":{
               "data":{
                  "sampleFormat":"UnsignedIntegral",
                  "bitsPerSample":"8 8 8 8",
                  "planarConfiguration":"PixelInterleaved"
               },
               "width":960,
               "chroma":{
                  "blackIsZero":true,
                  "numChannels":4,
                  "colorSpaceType":"RGB"
               },
               "height":660,
               "dimension":{
                  "imageOrientation":"Normal",
                  "pixelAspectRatio":1.0,
                  "verticalPixelSize":0.35285816,
                  "horizontalPixelSize":0.35285816
               },
               "compression":{
                  "lossless":true,
                  "compressionTypeName":"deflate",
                  "numProgressiveScans":1
               },
               "transparency":{
                  "alpha":"nonpremultipled"
               }
            }
         }
      ],
      "ttsCustomContent":null,
      "deviceGroupIdsDisplay":"auto",
      "collaborationGroups":[],
      "ttsCustomContentCustomizable":true,
      "incidentPlanId":null,
      "name":"All Clear",
      "audioDisplay":"auto",
      "expiration":null,
      "createdAt":"2021-06-15T14:53:10.319Z",
      "distributionListIds":[],
      "subjectCustomizable":true,
      "confirmationRequestIdCustomizable":false,
      "distributionListIdsCustomizable":true,
      "deviceGroupIds":[],
      "syncId":"66f2bbfe-cde9-11eb-8059-e189c5a04e8b:1623768790807",
      "areaOfInterestIdsCustomizable":true,
      "areasOfInterest":[],
      "deviceGroupIdsCustomizable":true,
      "collaborationGroupIdsCustomizable":true,
      "audioFiles":[],
      "bodyDisplay":"auto",
      "expirationCustomizable":true,
      "confirmationRequestId":null,
      "incidentPlanIdDisplay":"auto",
      "collaborationGroupIdsDisplay":"auto",
      "alertToneDisplay":"auto",
      "userIdsCustomizable":true,
      "ttsVoiceId":null,
      "id":"66f2bbfe-cde9-11eb-8059-e189c5a04e8b",
      "notificationProfileId":"66405cdb-cde9-11eb-8059-87f0c8f1aa98",
      "collaborationGroupIds":[  ],
      "ttsType":"none",
      "bodyCustomizable":true,
      "imageMimeType":null,
      "distributionListIdsDisplay":"auto",
      "confirmationRequest":null,
      "ttsCustomContentDisplay":"auto",
      "image":18003,
      "subjectDisplay":"auto",
      "audio":0,
      "distributionLists":[],
      "audioCustomizable":true,
      "incidentPlan":null,
      "expirationDisplay":"auto",
      "incidentPlanIdCustomizable":false,
      "body":"The situation is under control and the all-clear notification has been issued. Normal activities may be resumed. If you have any questions or concerns, please call <INSERT NUMBER HERE>.",
      "userIds":[],
      "confirmationRequestIdDisplay":"auto",
      "deviceGroups":[ ],
      "followUp":false,
      "alertToneCustomizable":false,
      "areaOfInterestIds":[],
      "metadata":null,
      "subject":"ALL CLEAR! Resume normal activities.",
      "alertTone":"all-clear1",
      "users":[],
      "areaOfInterestIdsDisplay":"auto",
      "metadataCustomizable":true
   },
   "createdAt":"2021-09-24T20:09:06.940Z",
   "distributionListIds":[ ],
   "deviceGroupIds":[],
   "areasOfInterest":[],
   "id":"45b24bf7-1d73-11ec-aa38-4f12b8864b56",
   "collaborationGroupIds":[],
   "distributionLists":[],
   "userIds":[
      "f7a6d830-cdea-11eb-8059-ddbbbdf7035e"
   ],
   "deviceGroups":[],
   "triggerOnStatus":"ACTIVE",
   "areaOfInterestIds":[],
   "users":[
      {
         "email":"admin@dev.com",
         "name":"admin",
         "createdAt":"2021-06-15T15:04:22.588Z",
         "type":"regular",
         "selfRegistered":false,
         "idleTimeout":720,
         "loadSourceId":null,
         "id":"f7a6d830-cdea-11eb-8059-ddbbbdf7035e",
         "isLicensed":true,
         "isLocked":false
      }
   ]
}

HTTP Request

POST /alarms/{alarmId}/actions/

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
alarmId The id of the Alarm.
Attribute Type Default Description
alarmId String N/A The id of the alarm.
triggerOnStatus String N/A The status of the alarm, one of OK and ACTIVE, for which the alarm action should be sent.
messageTemplateId String N/A The id of the message template with which the alarm action is associated. If left empty, a blank message template will be used and we’ll notify the admin distribution list. When blank, custom recipient ids are not allowed.
areaOfInterestIds Array[String] N/A The list of ids for areas of interest that should be attached to this scenario notification.
collaborationGroupIds Array[String] N/A The list of ids for collaboration groups that should be attached to this scenario notification.
deviceGroupIds Array[String] N/A The list of ids for device groups (fusion only) that should be attached to this scenario notification.
distributionListIds Array[String] N/A The list of ids for distribution lists that should be attached to this scenario notification.
userIds Array[String] N/A The list of ids for users that should be attached to this scenario notification.

Update Alarm Action

Update an alarm action.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/actions/66f2bbfe-cde9-11eb-8059-e189c5a04e8b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'alarmId': 'dcaca6f6-9d71-11eb-b775-0242ac110003'
,
    'id': '66f2bbfe-cde9-11eb-8059-e189c5a04e8b'
,
    'userIds': ['66ce1cf4-cde9-11eb-8059-113eda5e75d7'
, 'f7a6d830-cdea-11eb-8059-ddbbbdf7035e'
]

}

begin: 
    role = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/actions/66f2bbfe-cde9-11eb-8059-e189c5a04e8b" \
  -X “PUT” \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"alarmId": "dcaca6f6-9d71-11eb-b775-0242ac110003", \
       "id": "66f2bbfe-cde9-11eb-8059-e189c5a04e8b", \
       "userIds": ["66ce1cf4-cde9-11eb-8059-113eda5e75d7", "f7a6d830-cdea-11eb-8059-ddbbbdf7035e"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/actions/66f2bbfe-cde9-11eb-8059-e189c5a04e8b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'alarmId': 'dcaca6f6-9d71-11eb-b775-0242ac110003',
    'id': '66f2bbfe-cde9-11eb-8059-e189c5a04e8b',
    'userIds': ['66ce1cf4-cde9-11eb-8059-113eda5e75d7', 'f7a6d830-cdea-11eb-8059-ddbbbdf7035e']
}

try: 
    role = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
   "updatedAt":"2021-09-24T20:09:07.159Z",
   "permissions":[
      "put",
      "get"
   ],
   "muted":false,
   "alarmActionIds":[
      "45b24bf7-1d73-11ec-aa38-4f12b8864b56"
   ],
   "createdAt":"2021-04-14T22:36:32.409Z",
   "type":"fusion_server_red",
   "status":"OK",
   "id":"dcaca6f6-9d71-11eb-b775-0242ac110003",
   "alarmThresholds":[]
}

HTTP Request

PUT /alarms/{alarmId}/actions/{id}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
alarmId The id of the Alarm.
id The id of the Alarm Action.
Attribute Type Default Description
id String N/A The id of the alarm action.
alarmId String N/A The id of the alarm.
triggerOnStatus String N/A The status of the alarm, one of OK and ACTIVE, for which the alarm action should be sent.
messageTemplateId String N/A The id of the message template with which the alarm action is associated. If left empty, a blank message template will be used.
areaOfInterestIds Array[String] N/A The list of ids for areas of interest that should be attached to this scenario notification.
collaborationGroupIds Array[String] N/A The list of ids for collaboration groups that should be attached to this scenario notification.
deviceGroupIds Array[String] N/A The list of ids for device groups (fusion only) that should be attached to this scenario notification.
distributionListIds Array[String] N/A The list of ids for distribution lists that should be attached to this scenario notification.
userIds Array[String] N/A The list of ids for users that should be attached to this scenario notification.

Delete Alarm Action

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/actions/66f2bbfe-cde9-11eb-8059-e189c5a04e8b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.delete(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/actions/66f2bbfe-cde9-11eb-8059-e189c5a04e8b" \
  -X “DELETE” \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/actions/66f2bbfe-cde9-11eb-8059-e189c5a04e8b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.delete(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
   "status":200,
   "message":"deleted 66f2bbfe-cde9-11eb-8059-e189c5a04e8b"
}

HTTP Request

DELETE /alarms/{alarmId}/actions/{id}

Produces

application/json

Path Parameters

Parameter Description
alarmId The id of the Alarm.
id The id of the Alarm Action.

Alarm Action Response

The JSON document used to represent an Alarm Action resource has the following content:

Attribute Type Description
id String The id of the alarm action.
alarmId String The id of the alarm.
triggerOnStatus String The status of the alarm, one of OK and ACTIVE, for which the alarm action should be sent.
messageTemplateId String N/A
areaOfInterestIds Array[String] N/A
collaborationGroupIds Array[String] N/A
deviceGroupIds Array[String] N/A
distributionListIds Array[String] N/A
userIds Array[String] N/A

Alarm Events

Alarm Events are a subreasource of alarm. Alarm Events are triggered for each alarm type. The Alarm Event holds onto information about what status was entered and when it was triggered.

List Alarm Events

Gets a list of all alarm events of a specific alarm available to the current user.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/events"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'limit': 1

}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/events?limit=1" \
  -X “GET” \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/events"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'limit': 1
}

try: 
    role = requests.get(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
      "total": 2,
      "partial": false,
      "previous": null,
      "next": null,
      "data": [
                {
                  "permissions": [
                      "get"
                  ],
                  "id": "dcaghrf6-9d71-11eb-b775-0242ac110003",
                  "createdAt": "2020-03-05T21:33:21.670Z",
                  "status": "ACTIVE"
                },
               ]
}

HTTP Request

GET /alarms/{alarmId}/events

Produces

application/json

Query Parameters

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

Path Parameters

Attribute Type Description
alarmId String The id of alarm for which events are retrieved.

Get Alarm Events

The events triggered for each alarm type. Stores information about the entered status and the time and date the event was triggered.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/events/r94ja6f6-9d71-11eb-b775-0242ac110003"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/events/r94ja6f6-9d71-11eb-b775-0242ac110003" \
  -X “GET” \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/alarms/dcaca6f6-9d71-11eb-b775-0242ac110003/events/r94ja6f6-9d71-11eb-b775-0242ac110003"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
                  "get"
                 ],
  "id": "r94ja6f6-9d71-11eb-b775-0242ac110003",
  "createdAt": "2020-03-05T21:33:21.670Z",
  "status": "ACTIVE"
}

HTTP Request

GET /alarms/{alarmId}/events/{id}

Produces

application/json

Path Parameters

Parameter Description
id The id of the Alarm Event.
alarmId The id of the Alarm.

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

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 3,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "id": "0b45d70c-01ba-11e6-91d9-01444c9150eb",
   "name": "MSN",
   "geometryType": "circle",
   "geometryValue": {
    "type": "Feature",
    "geometry": {
     "type": "Point",
     "coordinates": [
      -89.3362,
      43.1356
     ]
    },
    "properties": {
     "radiusInM": 3182
    }
   },
   "syncedDeviceTypes": [
       "mobile"
      ],
   "createdAt": "2016-04-13T20:55:24.605Z",
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

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

HTTP Request

GET /areas-of-interest

Produces

application/json

Query Parameters

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

Response

The AOI response format is detailed here.

Get an Area of Interest

require 'httparty'
require 'json'

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

begin: 
    aoi = JSON.parse(HTTParty.get(url, headers: headers))
    puts(aoi)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    aoi = requests.get(url, headers=headers).json()
    print(aoi)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "cd2ec764-01a7-11e6-91d9-339e9d3d9df4",
 "name": "CVG",
 "geometryType": "circle",
 "geometryValue": {
  "type": "Feature",
  "geometry": {
   "type": "Point",
   "coordinates": [
    -84.6672,
    39.0478
   ]
  },
  "properties": {
   "radiusInM": 3551
  }
 },
 "syncedDeviceTypes": [
        "mobile"
       ],
 "createdAt": "2016-04-13T18:44:49.494Z",
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

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

HTTP Request

GET /areas-of-interest/{aoiId}

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area to retrieve.

Response

The AOI response format is detailed here.

Create an Area of Interest

require 'httparty'
require 'json'

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

}

,
        'properties': {
            'radiusInM': 3000

}


}

,
    'syncedDeviceTypes': ['mobile'
]

}

begin: 
    aoi = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(aoi)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Madison Airport", \
       "geometryType": "circle", \
       "geometryValue": {"type": "Feature", \
         "geometry": {"type": "Point", \
           "coordinates": [-89.34, 43.14]}, \
         "properties": {"radiusInM": 3000}}, \
       "syncedDeviceTypes": ["mobile"]}'
import requests
from requests.exceptions import RequestException
import json

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

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

try: 
    aoi = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(aoi)
except RequestException as e:
    print('Unexpected error!', e)
{
  "geometryType": "circle",
  "name": "Madison Airport",
  "id": "e83d84e6-2281-11e6-a729-83a644c48766",
  "geometryValue": {
   "type": "Feature",
   "geometry": {
    "type": "Point",
    "coordinates": [ -89.34, 43.14 ]
   },
   "properties": {
    "radiusInM": 3000
   }
  },
  "syncedDeviceTypes": [
         "mobile"
        ],
  "createdAt": "2016-05-25T14:06:42.385Z",
  "permissions": [ "delete", "put", "get" ]
}

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

HTTP Request

POST /areas-of-interest

Consumes

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

Produces

application/json

Request Parameters

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

Response

The AOI response format is detailed here.

Update an Area of Interest

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

Updates an existing area of interest.

HTTP Request

PUT /areas-of-interest/{aoiId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area to update.

Request Parameters

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

Response

The AOI response format is detailed here.

Remove an Area of Interest

# Continuing with the areas of interest object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/e83d84e6-2281-11e6-a729-83a644c48766" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the areas of interest object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted  e83d84e6-2281-11e6-a729-83a644c48766"
}

Deletes an existing area of interest.

HTTP Request

DELETE /areas-of-interest/{aoiId}

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area to delete.

Response

The deletion response format is detailed here.

Area of Interest Response

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

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

Geometry Value Response

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

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

AOI Boundary Triggers

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

List All Boundary Triggers

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The boundary trigger response format is detailed here.

Get a Boundary Trigger

require 'httparty'
require 'json'

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

begin: 
    trigger = JSON.parse(HTTParty.get(url, headers: headers))
    puts(trigger)
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

The boundary trigger response format is detailed here.

Create a Boundary Trigger

require 'httparty'
require 'json'

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

}

begin: 
    trigger = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(trigger)
rescue StandardError => e
    puts e
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!"}'
import requests
from requests.exceptions import RequestException
import json

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

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

Create a new Boundary Trigger.

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
aoiId The id of the area of interest.

Request Parameters

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

Response

The boundary trigger response format is detailed here.

Update a Boundary Trigger

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

Updates an existing boundary trigger.

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The boundary trigger response format is detailed here.

Remove a Boundary Trigger

# Continuing with the boundary trigger object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/areas-of-interest/cd2ec764-01a7-11e6-91d9-339e9d3d9df4/boundary-triggers/476810c8-22a1-11e6-a729-bdd2c948c5a0" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the boundary trigger object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted  476810c8-22a1-11e6-a729-bdd2c948c5a0"
}

Deletes an existing boundary trigger.

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

Boundary Trigger Response

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

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

AOI Boundary Trigger Activities

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

List All Activities

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

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

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

Retrieves the list of all areas of interest.

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The Activity response format is detailed here.

Get an Activity

require 'httparty'
require 'json'

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

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

The Activity response format is detailed here.

Area of Interest Response

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

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

Bell Schedules

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

List all Bell Schedules

require 'httparty'
require 'json'

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

}

begin: 
    bell_schedules = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(bell_schedules)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /bell-schedules

Produces

application/json

Query Parameters

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

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

Response

The bell schedule response format is detailed here.

Get a Bell Schedule

require 'httparty'
require 'json'

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

begin: 
    bell_schedule = JSON.parse(HTTParty.get(url, headers: headers))
    puts(bell_schedule)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/37c1fe0a-4b9c-11e7-8148-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /bell-schedules/{bellScheduleId}

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The bell schedule response format is detailed here.

Create a Bell Schedule

require 'httparty'
require 'json'

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

}

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

}

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

}

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

}

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

}

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

}

]

}

begin: 
    bell_schedule = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(bell_schedule)
rescue StandardError => e
    puts e
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"}]}'
import requests
from requests.exceptions import RequestException
import json

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

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

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

HTTP Request

POST /bell-schedules

Consumes

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

Produces

application/json

Request Parameters

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

Response

The bell schedule response format is detailed here.

Update a Bell Schedule

require 'httparty'
require 'json'

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

}

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

}

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

}

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

}

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

}

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

}

]

}

begin: 
    bell_schedule = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(bell_schedule)
rescue StandardError => e
    puts e
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"}]}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    bell_schedule = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(bell_schedule)
except RequestException as e:
    print('Unexpected error!', e)
{
  "description": "School Year 2017-2018",
  "bellScheduleExceptions": [
    {
      "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
      "description": "Snow Day",
      "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
      "startDate": "2018-01-03",
      "endDate": "2018-01-03",
      "ringListName": "Snow Day"
    }
  ],
  "timeZone": "America/Chicago",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "bellScheduleEntries": [
    {
      "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
      "entryNum": 0,
      "ringListName": "Monday"
    },
    {
      "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
      "entryNum": 1,
      "ringListName": "Tuesday"
    },
    {
      "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
      "entryNum": 2,
      "ringListName": "Wednesday"
    },
    {
      "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
      "entryNum": 3,
      "ringListName": "Thursday"
    },
    {
      "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
      "entryNum": 4,
      "ringListName": "Friday"
    }
  ],
  "name": "School Year 17-18",
  "startDate": "2017-08-28",
  "createdAt": "2018-05-31T20:18:35.635Z",
  "updatedAt": "2018-05-32T09:21:34.457Z",
  "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

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted cc01447c-650f-11e8-a57e-332c8cdd597f"
}

Deletes an existing bell schedule.

HTTP Request

DELETE /bell-schedules/{bellScheduleId}

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

Bell Schedule Entries

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

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

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

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

Bell Schedule Exceptions

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

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

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

Bell Schedule Response

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

Attribute Type Description
id String The id of this specific bell schedule, allowing it to be manipulated or retrieved individually.
name String The name of the bell schedule.
description String The description of the bell schedule.
numWeeks Integer The number of weeks in a bell schedule. Value can only be 1, 2, or 3 which corresponds to a weekly, bi-weekly, or tri-weekly schedule respectively.
startDate Date The start date of the bell schedule in ISO 8601 YYYY-MM-DD format.
endDate Date The end date of the bell schedule in ISO 8601 YYYY-MM-DD format.
timeZone String A timezone such as “America/Chicago”. This list is too long to enumerate here.
syncState Array[Object] The endpoints’ sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
endpointSyncState Object The specific endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state-for-endpoint 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.
createdAt ISO 8601 date/time When this bell schedule was created.
updatedAt ISO 8601 date/time When this bell schedule was last updated.

Bell Schedule Domains

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

List All Bell Schedule Domains

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /bell-schedules/{bellScheduleId}/domains

Produces

application/json

Path Parameters

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

Query Parameters

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

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

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

Response

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

Check if a Bell Schedule contains a Domain

require 'httparty'
require 'json'

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

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "bellScheduleId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

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

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

Response

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

Add a Bell Schedule Domain

require 'httparty'
require 'json'

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

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "bellScheduleId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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

HTTP Request

POST /bell-schedules/{bellScheduleId}/domains

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Remove a Bell Schedule Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Bell Schedule c54e4241-299b-11e8-94d3-2be9464da125"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Response

The deletion response format is detailed here.

Bell Schedules Bulk Exceptions

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

The only operation supported is POST.

Add an Exception to Multiple Bell Schedules

require 'httparty'
require 'json'

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

}

begin: 
    affected = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(affected)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules-bulk-exceptions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"description": "Snow Day", \
       "startDate": "2021-02-04", \
       "endDate": "2021-02-04", \
       "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4", \
       "bellScheduleIds": ["cc01447c-650f-11e8-a57e-332c8cdd597f", "f94d1622-6a65-11e8-9030-0d319c188f5d"]}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    affected = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(affected)
except RequestException as e:
    print('Unexpected error!', e)
{
  "schedulesAffected": [
    {"id": "cc01447c-650f-11e8-a57e-332c8cdd597f",
     "name": "Pelham Elementary",
     "syncId": "cc01447c-650f-11e8-a57e-332c8cdd597f:1599612837889"},
    {"id": "f94d1622-6a65-11e8-9030-0d319c188f5d",
     "name": "Ridgemont High",
     "syncId": "f94d1622-6a65-11e8-9030-0d319c188f5d:1599610192210"}
  ]
}

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

HTTP Request

POST /bell-schedules-bulk-exceptions

Consumes

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

Produces

application/json

Request Parameters

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

Response

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

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

Bell Schedule Cloning

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

The only operation supported is POST.

Clone a Bell Schedule

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

POST /bell-schedules/{bellScheduleId}/clone

Produces

application/json

Request Parameters

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

Response

The Bell Schedule response format is detailed here.

Brandings

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

List All Brandings

require 'httparty'
require 'json'

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

begin: 
    brandings = JSON.parse(HTTParty.get(url, headers: headers))
    puts(brandings)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/brandings" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    brandings = requests.get(url, headers=headers).json()
    print(brandings)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
    {
      "logo": "logoFile",
      "companyPhone": "+16085551212",
      "secondaryColor": "#123",
      "companyEmail": "bar@bazz.com",
      "primaryColor": "#456789",
      "companyName": "Foo",
      "customUrl": "https://www.quux.com"
    }
  ]
}

Retrieves a list of all Brandings.

HTTP Request

GET /brandings

Produces

application/json

Response

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

Get a Branding

require 'httparty'
require 'json'

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

begin: 
    branding = JSON.parse(HTTParty.get(url, headers: headers))
    puts(branding)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/brandings/2601234b-a1e6-11ea-b7db-f3cc7d266a8e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    branding = requests.get(url, headers=headers).json()
    print(branding)
except RequestException as e:
    print('Unexpected error!', e)
{   
  "logo": "logoFile",
  "companyPhone": "+16085551212",
  "secondaryColor": "#123",
  "companyEmail": "bar@bazz.com",
  "primaryColor": "#456789",
  "companyName": "Foo",
  "customUrl": "https://www.quux.com"
}

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

HTTP Request

GET /brandings/{id}

Produces

application/json

Path Parameters

Parameter Description
id The id of the Branding.

Response

The Brandings response format is detailed here.

Update a Branding

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

Updates an existing Branding.

HTTP Request

PUT /brandings/{id}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
Id The id of the Branding being altered.

Request Parameters

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

Response

The Brandings response format is detailed here.

Brandings Response

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

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

Bulk Upload

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

List Bulk Uploads

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": true,
 "data": [
  {
   "directoryId": "e229c4ae-5f28-11ea-8aa8-053bf8c7b046",
   "permissions": [
    "delete",
    "get"
   ],
   "endpointId": "efea94d8-5f28-11ea-8aa8-4b0ddc9506ce",
   "status": "COMPLETE",
   "id": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
   "resourceType": "message-templates",
   "createdAt": "2020-03-05T21:33:21.670Z",
   "testMode": false
  }
 ]
}

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

HTTP Request

GET /bulk-upload

Consumes

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

Produces

application/json

Response

The bulk upload response format is detailed here.

Get a Bulk Upload Instance

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)

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

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

HTTP Request

GET /bulk-upload/{bulkUploadId}

Produces

application/json

Path Parameters

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

Response

The bulk upload response format is detailed here.

Generate a POST URL

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"resourceType": "message-templates"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "url": "https://examplebucket.s3.us-east-2.amazonaws.com/40257fff-5f3b-11ea-8e69-21b3848f39e0.zip?x-amz-meta-resourcetype=message-templates&x-amz-meta-usebackup=true&x-amz-meta-endpointid=&x-amz-meta-directoryid=40257fff-5f3b-11ea-8e69-21b3848f39e0&x-amz-meta-testmode=true&x-amz-meta-provider=SarahFusion&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200305T234427Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=899&X-Amz-Credential=AKIAW7U2WXNLCHGMC6F7%2F20200305%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=998dc0cfd2d3ea43e2aee6faff4de4b17f8bf0b1d815b86f4de81276aff30691",
 "permissions": [
  "delete",
  "get"
 ]
}

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

HTTP Request

POST /bulk-upload

Consumes

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

Produces

application/json

Request Parameters

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

Response

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

Bulk Upload Response

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

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

Bulk Upload Commit

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

Commit a Bulk Upload Test

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/commit" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "efcb9b27-5f28-11ea-8aa8-0bb2f3879538",
 "endpointId": "efea94d8-5f28-11ea-8aa8-4b0ddc9506ce",
 "directoryId": "e229c4ae-5f28-11ea-8aa8-053bf8c7b046",
 "createdAt": "2020-03-05T21:33:21.670Z",
 "testMode": false,
 "resourceType": "message-templates",
 "status": "COMPLETE",
 "permissions": []
}

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

HTTP Request

POST /bulk-upload/{bulkUploadId}/commit

Consumes

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

Produces

application/json

Request Parameters

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

Response

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

Bulk Upload Logs

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

List All Bulk Upload Logs

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/efcb9b27-5f28-11ea-8aa8-0bb2f3879538/logs" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /bulk-upload/{bulkUploadId}/logs

Consumes

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

Produces

application/json

Request Parameters

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

Response

The bulk upload response format is detailed here.

Get a Bulk Upload Instance

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/bulk-upload/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/logs/f02d432c-5f28-11ea-8aa8-1569ae3ffa2c" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

The bulk upload response format is detailed here.

Bulk Upload Logs Response

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

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

Collaboration Groups

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

Conference Call

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

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

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

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

Cisco Webex Teams

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

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

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

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

Twitter

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

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

Outbound CAP

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

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

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

Outbound RSS

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

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

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

Microsoft Teams

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

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

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

require 'httparty'
require 'json'

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

}


}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "foo", \
       "type": "msteams-channel", \
       "properties": {"channelId": "bar", \
         "channelName": "bazz", \
         "disabled": false, \
         "teamId": "buzz", \
         "teamName": "quux"}}'
import requests
from requests.exceptions import RequestException
import json

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

}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total":1,
  "previous":null,
  "next":null,
  "partial":false,
  "data":[{
    "properties": {
        "channelId":"bar",
        "channelName":"bazz",
        "disabled":false,
        "teamId":"buzz",
        "teamName":"quux"
    },
    "permissions":["put","delete","get"],
    "name":"foo",
    "createdAt":"2021-01-13T12:00:00.000Z",
    "type":"msteams-channel",
    "distributionListIds":[],
    "id":"quuux",
    "distributionLists":[],
    "userIds":[],
    "users":[]}]
}

HTTP Request

POST /collaboration-groups

Request Parameters

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

Response

The collaboration group response format is detailed here.

Get All Collaboration Groups

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /collaboration-groups

Produces

application/json

Query Parameters

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

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

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

Response

The collaboration group response format is detailed here.

Get One Collaboration Group

require 'httparty'
require 'json'

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

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "properties": {
    "joinPin": "1234",
    "createPin": null,
    "bypassIvr": false
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065Z",
  "type": "conference-call",
  "distributionListIds": ["3875f8ae-139c-11e6-9cd0-ef8b5b11547d"],
  "id": "e3579191-b556-11e5-ab29-bdfc7d2b6ed8",
  "distributionLists": [
    {
      "id": "3875f8ae-139c-11e6-9cd0-ef8b5b11547d",
      "name": "Security Officers",
      "campaign": null,
      "createdAt": "2016-05-06T15:07:16.446Z"
    }
  ],
  "userIds": [],
  "users": []
}

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

HTTP Request

GET /collaboration-groups/{collaborationGroupId}

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The collaboration group response format is detailed here.

Create a Collaboration Group

require 'httparty'
require 'json'

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

}


}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
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}}'
import requests
from requests.exceptions import RequestException
import json

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

}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "properties": {
    "joinPin": "1234",
    "createPin": null,
    "bypassIvr": false
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Security Officers",
  "createdAt": "2016-01-07T15:54:09.065Z",
  "type": "conference-call",
  "distributionListIds": ["3875f8ae-139c-11e6-9cd0-ef8b5b11547d"],
  "id": "e3579191-b556-11e5-ab29-bdfc7d2b6ed8",
  "distributionLists": [
    {
      "id": "3875f8ae-139c-11e6-9cd0-ef8b5b11547d",
      "name": "Security Officers",
      "campaign": null,
      "createdAt": "2016-05-06T15:07:16.446Z"
    }
  ],
  "userIds": [],
  "users": []
}

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

HTTP Request

POST /collaboration-groups

Consumes

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

Produces

application/json

Request Parameters

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

Response

The collaboration group response format is detailed here.

Update a Collaboration Group

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

Modifies the type or properties of a collaboration group.

HTTP Request

PUT /collaboration-groups/{collaborationGroupId}

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The collaboration group response format is detailed here.

Remove a Collaboration Group

# Continuing with the collaboration group object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/e3579191-b556-11e5-ab29-bdfc7d2b6ed8" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the collaboration group object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"CollaborationGroups\"} e3579191-b556-11e5-ab29-bdfc7d2b6ed8"
}

Removes a collaboration group.

HTTP Request

DELETE /collaboration-groups/{collaborationGroupId}

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

Collaboration Group Response

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

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

Collaboration Group Domains

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

List All Collaboration Group Domains

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /collaboration-groups/{collaborationGroupId}/domains

Produces

application/json

Path Parameters

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

Query Parameters

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

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

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

Response

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

Check if a Collaboration Group contains a Domain

require 'httparty'
require 'json'

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

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "collaborationGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

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

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

Response

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

Add a Collaboration Group Domain

require 'httparty'
require 'json'

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

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "collaborationGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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

HTTP Request

POST /collaboration-groups/{collaborationGroupId}/domains

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Remove a Collaboration Group Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/collaboration-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Collaboration Group c54e4241-299b-11e8-94d3-2be9464da125"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Response

The deletion response format is detailed here.

Confirmation Requests

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

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

List All Confirmation Requests

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /confirmation-requests

Produces

application/json

Query Parameters

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

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

Response

The confirmation request response format is detailed here.

Get a Confirmation Request

require 'httparty'
require 'json'

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

begin: 
    cr = JSON.parse(HTTParty.get(url, headers: headers))
    puts(cr)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /confirmation-requests/{confirmationRequestId}

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The confirmation request response format is detailed here.

Create a Confirmation Request

require 'httparty'
require 'json'

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

}

begin: 
    cr = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(cr)
rescue StandardError => e
    puts e
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]}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    cr = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(cr)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [ ],
  "createdAt": "2014-08-11T16:22:14.333Z",
  "id": "a7838ed0-2173-11e4-ba87-3c970e7ff560",
  "options": ["No, please call me!", "Atop Mount Olympus"],
  "initiateTrackingOptions": [true, false],
  "expirationPeriod": 36000,
  "name": "Are you safe?"
}

Creates a confirmation request

HTTP Request

POST /confirmation-requests

Consumes

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

Produces

application/json

Request Parameters

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

Response

The confirmation request response format is detailed here.

Update a Confirmation Request

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

Updates an existing confirmation request.

HTTP Request

PUT /confirmation-request/{confirmationRequestId}

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The confirmation request response format is detailed here.

Remove a Confirmation Request

# Continuing with the confirmation request
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/a7838ed0-2173-11e4-ba87-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

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

Removes a confirmation request

HTTP Request

DELETE /confirmation-requests/{confirmationRequestId}

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

Confirmation Request Response

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

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

Confirmation Request Cloning

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

The only operation supported is POST.

Clone a Confirmation Request

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "dynamicReplies": [],
    "permissions": [],
    "initiateTrackingOptions": [
        false,
        false
    ],
    "escalationRules": [],
    "name": "Health Check - Status (Copy)",
    "createdAt": "2021-07-23T15:24:31.663Z",
    "expirationPeriod": null,
    "id": "14038c65-ebca-11eb-81b3-fdb244340480",
    "options": [
        "I am OK",
        "I am sick"
    ]
}

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

HTTP Request

POST /confirmation-requests/{confirmationRequestId}/clone

Produces

application/json

Request Parameters

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

Response

The confirmation request response format is detailed here.

Confirmation Request Domains

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

List All Confirmation Request Domains

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /confirmation-requests/{confirmationRequestId}/domains

Produces

application/json

Path Parameters

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

Query Parameters

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

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

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

Response

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

Check if a Confirmation Request contains a Domain

require 'httparty'
require 'json'

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

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "confirmationRequestId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

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

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

Response

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

Add a Confirmation Request Domain

require 'httparty'
require 'json'

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

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "confirmationRequestId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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

HTTP Request

POST /confirmation requests/{confirmationRequestId}/domains

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Remove a Confirmation Request Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Confirmation Request c54e4241-299b-11e8-94d3-2be9464da125"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Response

The deletion response format is detailed here.

CUCM Clusters

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

Get All CUCM Clusters

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /cucm-clusters

Produces

application/json

Query Parameters

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

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

Response

The CUCM Cluster response format is detailed here.

Get One CUCM Cluster

require 'httparty'
require 'json'

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

begin: 
    cluster = JSON.parse(HTTParty.get(url, headers: headers))
    puts(cluster)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    cluster = requests.get(url, headers=headers).json()
    print(cluster)
except RequestException as e:
    print('Unexpected error!', e)
{
      "secureConnection": true,
      "axlUser": "axlUser",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": 69,
      "name": "West Cluster",
      "capfAddress": "172.30.207.49",
      "createdAt": "2021-02-12T19:45:00.617Z",
      "updatedAt": "2021-02-15T22:35:07.475Z",
      "nextAuthenticationUrl": null,
      "id": "cb16ec29-6d6a-11eb-a9cf-e19ac9da2489",
      "tftpAddress": "172.30.207.49",
      "snmpVersion": "2",
      "capfPort": 3804,
      "axlAddress": "172.30.207.49",
      "snmpUsername": null,
      "snmpCommunity": "ICVA",
      "cucmClusterFusionServers": [
        {
          "cucmClusterFusionServerId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
          "endpointId": "7676f63f-6fba-11eb-b0f8-e51408f3ba06",
          "endpointName": "Fusion"
        },
        {
          "cucmClusterFusionServerId": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab",
          "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
          "endpointName": "Fusion2"
        }
      ],
      "axlId": null
    }

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

HTTP Request

GET /cucm-clusters/{cucmClusterId}

Produces

application/json

Path Parameters

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

Response

The CUCM Cluster response format is detailed here.

Create a CUCM Cluster

require 'httparty'
require 'json'

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

}

begin: 
    cluster = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(cluster)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Cluster", \
       "axlUser": "AXL User", \
       "axlPassword": "AXL Password", \
       "axlAddress": "1.1.1.1,2.2.2.2", \
       "snmpVersion": "2", \
       "snmpCommunity": "ICVA", \
       "secureConnection": false, \
       "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    cluster = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(cluster)
except RequestException as e:
    print('Unexpected error!', e)
{
      "secureConnection": true,
      "axlUser": "AXL User",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": 69,
      "name": "Example Cluster",
      "capfAddress": null,
      "createdAt": "2021-02-12T19:45:00.617Z",
      "updatedAt": "2021-02-15T22:35:07.475Z",
      "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp",
      "id": "f16f8ef0-708a-11eb-9c8c-17221dd62a89",
      "tftpAddress": null,
      "snmpVersion": "2",
      "capfPort": null,
      "axlAddress": "1.1.1.1,2.2.2.2",
      "snmpUsername": null,
      "snmpCommunity": "ICVA",
      "cucmClusterFusionServers": [],
      "axlId": null
    }

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

HTTP Request

POST /cucm-clusters

Consumes

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

Produces

application/json

Request Parameters

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

Response

The CUCM Cluster response format is detailed here.

Update a CUCM Cluster

require 'httparty'
require 'json'

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

}

begin: 
    cluster = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(cluster)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Cluster Prime", \
       "axlUser": "AXL User Prime", \
       "axlPassword": "AXL Password Prime", \
       "axlAddress": "1.1.1.1,2.2.2.2,3.3.3.3", \
       "snmpVersion": "2", \
       "snmpCommunity": "ICVA2", \
       "secureConnection": false, \
       "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    cluster = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(cluster)
except RequestException as e:
    print('Unexpected error!', e)
{
      "secureConnection": true,
      "axlUser": "AXL User Prime",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "tftpPort": 69,
      "name": "Example Cluster Prime",
      "capfAddress": null,
      "createdAt": "2021-02-12T19:45:00.617Z",
      "updatedAt": "2021-02-15T22:35:07.475Z",
      "nextAuthenticationUrl": "http://cucm.domain.org:8080/ccmcip/authenticate.jsp",
      "id": "f16f8ef0-708a-11eb-9c8c-17221dd62a89",
      "tftpAddress": null,
      "snmpVersion": "2",
      "capfPort": null,
      "axlAddress": "1.1.1.1,2.2.2.2,3.3.3.3",
      "snmpUsername": null,
      "snmpCommunity": "ICVA2",
      "cucmClusterFusionServers": [],
      "axlId": null
    }

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

HTTP Request

PUT /cucm-clusters/{cucmClusterId}

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The CUCM Cluster response format is detailed here.

Remove a CUCM Cluster

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted f16f8ef0-708a-11eb-9c8c-17221dd62a89"
}

Removes a CUCM Cluster, discarding its configuration.

HTTP Request

DELETE /cucm-clusters/{cucmClusterId}

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

CUCM Cluster Response Format

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

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

CUCM Cluster Fusion Servers Format

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

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

CUCM Cluster Fusion Servers

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

Get All Fusion Server configurations for a CUCM Cluster

require 'httparty'
require 'json'

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

}

begin: 
    servers = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(servers)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

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

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

Response

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

Get one Fusion Server configuration for a CUCM Cluster

require 'httparty'
require 'json'

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

begin: 
    server = JSON.parse(HTTParty.get(url, headers: headers))
    puts(server)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    server = requests.get(url, headers=headers).json()
    print(server)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "jtapiStaticTerminalsEnabled": false,
  "createdAt": "2021-02-15T18:25:00.323Z",
  "updatedAt": "2021-02-15T18:25:00.363Z",
  "cmAddress": "172.30.207.49",
  "syncId": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab:1613413676919",
  "cmUsername": "JamieDA2",
  "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
  "id": "1d216f8a-6fbb-11eb-b0f8-933bf79c7bab",
  "jtapiPhoneActivationEnabled": false,
  "makeCtiConnection": true,
  "syncState": [
    {
      "name": "Fusion2",
      "status": "complete",
      "updatedAt": "2021-02-15T18:28:26.217Z",
      "errors": null
    }
  ],
  "endpoint": {
    "id": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
    "name": "Fusion2"
  },
  "cucmClusterId": "f16f8ef0-708a-11eb-9c8c-17221dd62a89"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

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

Create a CUCM Cluster Fusion Server Configuration

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa", \
       "cmAddress": "1.1.1.1,2.2.2.2", \
       "cmUsername": "cmUser", \
       "cmPassword": "cmPassword", \
       "jtapiPhoneActivationEnabled": false, \
       "jtapiStaticTerminalsEnabled": false, \
       "makeCtiConnection": true, \
       "allowRestartForJTAPIUpdate": true}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "jtapiStaticTerminalsEnabled": false,
  "createdAt": "2021-02-15T18:25:00.363Z",
  "updatedAt": "2021-02-15T18:25:00.363Z",
  "cmAddress": "1.1.1.1,2.2.2.2",
  "syncId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab:1613413642770",
  "cmUsername": "cmUser",
  "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
  "id": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
  "jtapiPhoneActivationEnabled": false,
  "makeCtiConnection": true,
  "endpoint": {
    "id": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
    "name": "Fusion2"
  },
  "cucmClusterId": "cb16ec29-6d6a-11eb-a9cf-e19ac9da2489",
  "ctiCertificates": [{"applicationUser": "appUser",
                       "instanceId": "instanceId",
                       "id": "f2dee550-70a9-11eb-9c8c-17221dd62a89"}]
}

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

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

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

Update a CUCM Cluster Fusion Server Configuration

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/cb16ec29-6d6a-11eb-a9cf-e19ac9da2489/fusion-servers/1d216f8a-6fbb-11eb-b0f8-933bf79c7bab" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa", \
       "cmAddress": "1.1.1.1,2.2.2.2,3.3.3.3", \
       "cmUsername": "cmUser", \
       "cmPassword": "cmPassword", \
       "jtapiPhoneActivationEnabled": false, \
       "jtapiStaticTerminalsEnabled": false, \
       "makeCtiConnection": true, \
       "allowRestartForJTAPIUpdate": true}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "jtapiStaticTerminalsEnabled": false,
  "createdAt": "2021-02-15T18:25:00.363Z",
  "updatedAt": "2021-02-15T19:12:32.321Z",
  "cmAddress": "1.1.1.1,2.2.2.2,3.3.3.3",
  "syncId": "1d278a0f-6fbb-11eb-b0f8-918d446445ab:1613413642770",
  "cmUsername": "cmUserPrime",
  "endpointId": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
  "id": "1d278a0f-6fbb-11eb-b0f8-918d446445ab",
  "jtapiPhoneActivationEnabled": false,
  "makeCtiConnection": true,
  "endpoint": {
    "id": "817b3e8b-6fba-11eb-b0f8-0bc70adb4bfa",
    "name": "Fusion2"
  },
  "cucmClusterId": "cb16ec29-6d6a-11eb-a9cf-e19ac9da2489"
}

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

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The CUCM Cluster Fusion Server response format is detailed here.

Remove a CUCM Cluster Fusion Server Configuration

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/cucm-clusters/f16f8ef0-708a-11eb-9c8c-17221dd62a89/fusion-servers/1d278a0f-6fbb-11eb-b0f8-918d446445ab" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted 1d278a0f-6fbb-11eb-b0f8-918d446445ab"
}

Removes a CUCM Cluster Fusion Server Configuration.

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

CUCM Cluster Fusion Server Configuration Response Format

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

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

Devices

Fusion Only

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

List All Devices

require 'httparty'
require 'json'

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

}

begin: 
    devices = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(devices)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/devices?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /devices

Produces

application/json

Query Parameters

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

Response

The device response format is detailed here.

Get a Device

require 'httparty'
require 'json'

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

begin: 
    device = JSON.parse(HTTParty.get(url, headers: headers))
    puts(device)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /devices/{deviceId}

Produces

application/json

Path Parameters

Parameter Description
deviceId The id of the Device of interest.

Response

The device response format is detailed here.

Device Response

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

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

Device Groups

Fusion Only

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

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

Get All Device Groups

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /device-groups

Produces

application/json

Query Parameters

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

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

Response

The Device Group response format is detailed here.

Get One Device Group

require 'httparty'
require 'json'

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

begin: 
    group = JSON.parse(HTTParty.get(url, headers: headers))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /device-groups/{deviceGroupId}

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The Device Group response format is detailed here.

Create a Device Group

require 'httparty'
require 'json'

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

}

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

}

begin: 
    group = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"exclusionIds": ["CiscoPhone-External:SEP381C1ABA7908"], \
       "filterType": "OR", \
       "additionIds": ["CiscoPhone-External:SEP381C1ABA7908"], \
       "filters": [{"value": "john.doe@singlewire.com", \
         "attribute": "EndUserIdentifier", \
         "comparison": "EQUALS", \
         "complement": false, \
         "caseSensitive": false}], \
       "name": "A Large Test", \
       "baseDeviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"]}'
import requests
from requests.exceptions import RequestException
import json

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

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

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

HTTP Request

POST /device-groups

Consumes

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

Produces

application/json

Request Parameters

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

Response

The Device Group response format is detailed here.

Update a Device Group

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

Modifies the details of the Device Group.

HTTP Request

PUT /device-groups/{deviceGroupId}

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The Device Group response format is detailed here.

Remove a Device group

# Continuing with the device group object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/3cf58710-2305-11e4-b544-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the device group object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"DeviceGroups\"} 3cf58710-2305-11e4-b544-3c970e7ff560"
}

Removes a Device Group, discarding its Device information.

HTTP Request

DELETE /device-groups/{deviceGroupId}

Produces

application/json

Path Parameters

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

Response

The deletion response format is detailed here.

Device Group Response

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

Attribute Type Description
createdAt ISO 8601 date/time When this device group was created.
updatedAt ISO 8601 date/time When this device group was last updated.
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 endpoints’ sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
endpointSyncState Object The specific endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state-for-endpoint is true.
exclusionIds Array[String] The specific device icop_ids that are excluded from this device group regardless of filters and other device groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
exclusions Array[Object] The specific devices that are excluded from this device group regardless of filters and other device groups.
filterType String Controls how the filters that define rules for dynamically determining the Devices in this device group are combined (i.e. AND or OR, REJECT, ACCEPT, or LOGICAL_EXPRESSION). If this device group is also configured with baseDeviceGroupIds, the filters will further adjust the devices in the group.
additionIds Array[String] The specific device icop_ids that are in the Group regardless of filters and other Device Groups. This is either the MAC Address (for speakers and idns) or the device identifier (for all other devices).
additions Array[Object] The specific devices that are in the group regardless of filters and other device groups.
filters Array[Object] Defines rules to dynamically determine the Devices in this Device Group, combined as specified by filterType. If this Device Group is also filtered with baseDeviceGroupIds, these filters will further adjust the devices in the group. The filters format is detailed here.
baseDevice­GroupIds Array[UUID] If present, contains a list of Device Group ids that form the starting Devices for this Device Group.
baseDevice­Groups Array[Object] If present, contains a list of Device Groups that form the starting devices for this Device Group.
activation­GroupIds Array[Object] If present, contains a list ‘id’s of the Activation Groups whose Poly® phones can be added to this device group using additionIds or via rules used in the filters attribute.
activation­Groups Array[Object] If present, contains a list of Activation Groups whose Poly® phones can be added to this device group using additionIds or via rules used in the filters attribute. The format of the elements of this attribute is detailed here.
multicastConfigs Array[Object] If present, contains the configurations that will be used for delivering audio notifications to the multicast capable members of this Device Group. The format of the elements of this attribute is detailed here.
numIdns Number Number of matching IDNs. Included if query contains the include-device-counts set to true.
numPhones Number Number of matching phones. Included if query contains the include-device-counts set to true.
numPlugins Number Number of matching plugins. Included if query contains the include-device-counts set to true.
numSpeakers Number Number of matching speakers. Included if query contains the include-device-counts set to true.

Device Group Filters Format

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

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

Activation Group Elements Format

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

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

Multicast Configurations Format

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

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

Device Group Domains

Fusion Only

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

List All Device Group Domains

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

GET /device-groups/{deviceGroupId}/domains

Produces

application/json

Path Parameters

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

Query Parameters

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

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

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

Response

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

Check if a Device Group contains a Domain

require 'httparty'
require 'json'

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

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Grounds",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "namePath": "/West Campus/Stadium/Grounds/",
  "deviceGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

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

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

Response

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

Add a Device Group Domain

require 'httparty'
require 'json'

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

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "name": "Vending",
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "namePath": "/West Campus/Stadium/Vending/",
  "deviceGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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

HTTP Request

POST /device-groups/{deviceGroupId}/domains

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Remove a Device Group Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Device Group c54e4241-299b-11e8-94d3-2be9464da125"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Response

The deletion response format is detailed here.

Device Group Cloning

Fusion Only

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

The only operation supported is POST.

Clone a Device Group

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/device-groups/6ec13410-1bdf-11e4-9181-3c970e7ff560/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

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

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

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

HTTP Request

POST /device-groups/{deviceGroupId}/clone

Produces

application/json

Request Parameters

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

Response

The Device Group response format is detailed here.

Dial-To-Intercom

Fusion Only

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

Get Dial-To-Intercom Configuration

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
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}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-08-06T18:51:33.590Z",
      "updatedAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Everyone",
      "loadSourceId": null,
      "isSubscribable": true,
      "campaign": null,
      "domains": [
        {
         "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
         "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
         "name": "West",
         "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
         "namePath": "/West/"
        }
      ]
    }
  ]
}

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

HTTP Request

GET /distribution-lists

Produces

application/json

Query Parameters

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

Parameter Type Description
assoc-sync-state Boolean If true, include the current synchronization state for fusion endpoints.
assoc-sync-state-for-endpoint String Include the current synchronization state for a specific fusion endpoint.
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

require 'httparty'
require 'json'

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

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "id": "59489180-41f1-11e5-aa08-aa951d8d7a3b",
  "createdAt": "2015-08-13T19:27:34.552Z",
  "updatedAt": "2015-08-13T19:27:34.552Z",
  "name": "Parents Weekend",
  "loadSourceId": null,
  "isSubscribable": false,
  "campaign": {
    "enrollmentEndDate": null,
    "welcomeMessage": "Hi, mom and dad!",
    "inactiveMessage": "You were too late.",
    "defaultNotificationDays": null,
    "url": "http://admin.icmobile.singlewire.com/anonymous/036347b0-41f1-11e5-ba5e-aa951d8d7a3b/list/59489180-41f1-11e5-aa08-aa951d8d7a3b"
   },
  "domains": [
    {
     "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "West",
     "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
     "namePath": "/West/"
    }
  ]
}

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

HTTP Request

GET /distribution-lists/{distributionListId}

Produces

application/json

Path Parameters

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

Query Parameters

Parameter Type Description
assoc-sync-state Boolean If true, include the current synchronization state for fusion endpoints.
assoc-sync-state-for-endpoint String Include the current synchronization state for a specific fusion endpoint.
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

require 'httparty'
require 'json'

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

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Administrators"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-13T16:16:53.249Z",
  "updatedAt": "2014-08-13T16:16:53.249Z",
  "id": "3cf58710-2305-11e4-b544-3c970e7ff560",
  "name": "Administrators",
  "loadSourceId": null,
  "isSubscribable": false,
  "domains": [
    {
     "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "West",
     "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
     "namePath": "/West/"
    }
  ]
}

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

HTTP Request

POST /distribution-lists

Consumes

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

Produces

application/json

Request Parameters

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

Response

The distribution list response format is detailed here.

Update a Distribution List

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

# Continuing with the distribution list object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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.
updatedAt ISO 8601 date/time When this distribution list was last updated.
isSubscribable Boolean Whether the Distribution List can be subscribed to by users in Self Service mode.
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 endpoints’ sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
endpointSyncState Object The specific endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state-for-endpoint is true.
loadSourceId String The loadSourceId of this distribution list. Contains a Load Definition id if and only if it was created in tandem with a school import loader.

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

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "distributionListId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "distributionListId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the 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. Additionally, the id of the distribution list whose domains were requested is returned under the key distributionListId inside each domain response.

Check if a Domain contains a Distribution List

require 'httparty'
require 'json'

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

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

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

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "distributionListId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

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

require 'httparty'
require 'json'

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

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
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"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "distributionListId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 7,
  "partial": true,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "user": {
        "createdAt": "2014-08-04T14:30:36.459Z",
        "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
        "email": "craig.smith@singlewire.com",
        "name": "Craig Smith"
      },
      "distributionList": {
        "createdAt": "2014-08-06T18:51:33.590Z",
        "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
        "name": "Everyone"
      },
      "createdAt": "2014-08-06T18:51:36.216Z",
      "updatedAt": "2014-08-06T18:51:36.216Z",
      "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions/b125a180-1d9a-11e4-a054-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    sub = JSON.parse(HTTParty.get(url, headers: headers))
    puts(sub)
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions/b125a180-1d9a-11e4-a054-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    sub = requests.get(url, headers=headers).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-04T14:30:36.459Z",
    "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
    "email": "craig.smith@singlewire.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590Z",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-06T18:51:36.216Z",
  "updatedAt": "2014-08-06T18:51:36.216Z",
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'userId': 'e660d7b0-1be3-11e4-9181-3c970e7ff560'

}

begin: 
    sub = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(sub)
rescue StandardError => e
    puts e
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"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/user-subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'userId': 'e660d7b0-1be3-11e4-9181-3c970e7ff560'
}

try: 
    sub = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-04T14:30:36.459Z",
    "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
    "email": "craig.smith@singlewire.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590Z",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-13T20:12:20.444Z",
  "updatedAt": "2014-08-13T20:12:20.444Z",
  "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 (limit: 100,000 per 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:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
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.000Z"}'
# Continuing with the user subscription object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-04T14:30:36.459Z",
    "id": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
    "email": "craig.smith@singlewire.com",
    "name": "Craig Smith"
  },
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590Z",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-13T20:12:20.444Z",
  "updatedAt": "2014-08-14T21:13:41.213Z",
  "userId": "e660d7b0-1be3-11e4-9181-3c970e7ff560",
  "id": "216c69c0-2326-11e4-b544-3c970e7ff560",
  "subscriptionEndDate": "2015-09-16T14:00:00.000Z",
  "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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the user subscription object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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.
updatedAt ISO 8601 date/time When this subscription was last updated.
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.

Distribution List SCIM Groups

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

List All SCIM Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total":1,
  "previous":null,
  "next":null,
  "partial":false,
  "data": [
    {
      "id": "d80aa1de-8026-11eb-a543-53c5fa2d317e",
      "name": "SCIM Group",
      "memberCount": 1,
      "createdAt": "2021-03-08T15:56:28.662Z",
      "permissions": ["put","delete","get"]
    }
  ]
}

Retrieves all member SCIM Groups of this distribution list.

HTTP Request

GET /distribution-lists/{distributionListId}/scim-groups

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List whose member SCIM Groups should be listed.

Response

The distribution list SCIM group response format is detailed here.

Update Distribution List SCIM Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'scimGroupId': '70c0be09-6662-11eb-b962-b1e9a4e7ca6e'

}

begin: 
    sub = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(sub)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"scimGroupId": "70c0be09-6662-11eb-b962-b1e9a4e7ca6e"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'scimGroupId': '70c0be09-6662-11eb-b962-b1e9a4e7ca6e'
}

try: 
    sub = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "70c0be09-6662-11eb-b962-b1e9a4e7ca6e",
  "name": "Group Name",
  "memberCount": 6,
  "createdAt": "2021-02-03T20:57:34.944Z",
  "permissions": ["put","delete","get"]
}

Create a link between a SCIM Group and a Distribution List so that the SCIM User will receive Notifications sent to that Distribution List (limit: 100,000 per Distribution List).

HTTP Request

POST /distribution-lists/{distributionListId}/scim-groups

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 SCIM group is to be added.

Request Parameters

Parameter Type Default Description
scimGroupId String N/A The id of the SCIM Group to add to the distribution list.

Response

The distribution list SCIM group response format is detailed here.

Remove Distribution List SCIM Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups/d0b13a1e-67d6-11eb-bde7-a53355563835"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups/d0b13a1e-67d6-11eb-bde7-a53355563835" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups/d0b13a1e-67d6-11eb-bde7-a53355563835"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status":200,
  "message":"deleted d0b13a1e-67d6-11eb-bde7-a53355563835"
}

Removes the association between a SCIM Group and a Distribution List.

HTTP Request

DELETE /distribution-lists/{distributionListId}/scim-groups/{scimGroupId}

Produces

application/json

Path Parameters

Parameter Description
distributionListId The id of the Distribution List from which the SCIM group is to be removed.
scimGroupId The id of the specific SCIM group to delete.

Response

The deletion response format is detailed here.

Distribution List SCIM Groups Response

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

Attribute Type Description
createdAt ISO 8601 date/time When this SCIM Group was created.
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.
name String The name of the SCIM Group.
memberCount Integer The number of members in the SCIM Group.

Distribution List Cloning

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

The only operation supported is POST.

Clone a Distribution List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/distribution-lists/af94ef60-1d9a-11e4-a054-3c970e7ff560/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [],
  "createdAt": "2014-08-06T19:51:33.590Z",
  "id": "ccc6e68f-9a81-4b58-b02a-b71ad62007cf",
  "name": "Everyone (Copy)",
  "isSubscribable": true,
  "campaign": null,
  "domains": [
    {
     "id": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
     "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
     "name": "West",
     "path": "/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/",
     "namePath": "/West/"
    }
  ]
}

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

Note that subscribable distribution lists and distribution lists that have a campaign attached cannot be copied.

HTTP Request

POST /distribution-lists/{distributionListId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
distributionListId String The id of the Distribution List to copy.

Response

The Distribution List response format is detailed here.

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

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains?limit=10" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "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.226Z"
  },
  {
   "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.898Z"
  },
  {
   "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "parentId": null,
   "name": "Root",
   "path": "/",
   "namePath": "/",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2018-02-16T00:43:32.422Z"
  },
  {
   "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.247Z"
  }
 ]
}

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
parentId String Returns only direct children (subdomains) of the specified Domain
pathPrefix 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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/52640b89-13b0-11e8-a40a-6553f9413d68"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    perm = JSON.parse(HTTParty.get(url, headers: headers))
    puts(perm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/52640b89-13b0-11e8-a40a-6553f9413d68" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/52640b89-13b0-11e8-a40a-6553f9413d68"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    perm = requests.get(url, headers=headers).json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
{
 "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.226Z"
}

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Theatre Staff'
,
    'parentId': '6569f5f0-165e-11e8-a8ad-354db202cef7'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
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"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Theatre Staff',
    'parentId': '6569f5f0-165e-11e8-a8ad-354db202cef7'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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.326Z"
}

Creates a new Domain (limit: 200).

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/52640b89-13b0-11e8-a40a-6553f9413d68"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Stadium and Grounds Staff'

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
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"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/52640b89-13b0-11e8-a40a-6553f9413d68"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Stadium and Grounds Staff'
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "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.226Z"
}

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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/7289eb3a-15c2-11e8-ab27-5dc7a32779d0" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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 its descendants, in the case of a recursive deletion attempt), or any resources whose only Domain is the one that you are trying to delete (or its descendants), this request will fail with corresponding validation errors unless you have supplied the value delete, delete-permissions, or promote 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 either delete, which will allow them (as well as any permissions) to be deleted as part of deleting the domain, or promote, which will promote the would-be-orphaned resources to the parent of the domain being deleted, along with deleting any orphaned permissions.

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, promote. 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 promote causing the resources to be moved to the parent of the domain being deleted (any orphaned permissions will still be deleted), 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 Bell Schedules

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

List All Domain Bell Schedules

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/bell-schedules?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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",
      "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "bellScheduleEntries": [
        {
          "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
          "entryNum": 0,
          "ringListName": "Monday"
        },
        {
          "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
          "entryNum": 1,
          "ringListName": "Tuesday"
        },
        {
          "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
          "entryNum": 2,
          "ringListName": "Wednesday"
        },
        {
          "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
          "entryNum": 3,
          "ringListName": "Thursday"
        },
        {
          "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
          "entryNum": 4,
          "ringListName": "Friday"
        }
      ],
      "name": "School Year 17-18",
      "startDate": "2017-08-28",
      "createdAt": "2018-05-31T20:18:35.635Z",
      "numWeeks": 1,
      "endDate": "2018-05-25",
      "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
    }
  ]
}

Retrieves the list of all Bell Schedules 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}/bell-schedules

Produces

application/json

Path Parameters

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

Query Parameters

There was one bell schedule 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 find out the entire set of Domains to which each returned Bell Schedule belongs, request the Bell Schedules attached to any subdomains of the specified Domain, and/or filter the results by matching on the Bell Schedule name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Bell Schedule belongs.
name String Returns only Bell Schedule whose names exactly match the supplied value.
recursive boolean If true, in addition to Bell Schedules that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Bell Schedule response format is detailed here. Additionally, the id of the domain whose bell schedules were requested is returned under the key domainId inside each response.

Check if a Domain contains a Bell Schedule

require 'httparty'
require 'json'

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

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/bell-schedules/cc01447c-650f-11e8-a57e-332c8cdd597f" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "description": "School Year 2017-2018",
 "bellScheduleExceptions": [
   {
     "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
     "description": "Snow Day",
     "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
     "startDate": "2018-01-03",
     "endDate": "2018-01-03",
     "ringListName": "Snow Day"
   }
 ],
 "timeZone": "America/Chicago",
 "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
 "permissions": [
   "delete",
   "put",
   "get"
 ],
 "bellScheduleEntries": [
   {
     "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
     "entryNum": 0,
     "ringListName": "Monday"
   },
   {
     "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
     "entryNum": 1,
     "ringListName": "Tuesday"
   },
   {
     "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
     "entryNum": 2,
     "ringListName": "Wednesday"
   },
   {
     "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
     "entryNum": 3,
     "ringListName": "Thursday"
   },
   {
     "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
     "entryNum": 4,
     "ringListName": "Friday"
   }
 ],
 "name": "School Year 17-18",
 "startDate": "2017-08-28",
 "createdAt": "2018-05-31T20:18:35.635Z",
 "numWeeks": 1,
 "endDate": "2018-05-25",
 "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Bell Schedules are of interest.
id The id of the Bell Schedule whose membership in the Domain is being checked.

Query Parameters

Additionally, you can find out the exact set of domains to which the Bell Schedule belongs, or check if the Bell Schedule is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Bell Schedule belongs.
recursive boolean If true, in addition to Bell Schedules that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'cc01447c-650f-11e8-a57e-332c8cdd597f'

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/bell-schedules" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "cc01447c-650f-11e8-a57e-332c8cdd597f"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/bell-schedules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'cc01447c-650f-11e8-a57e-332c8cdd597f'
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "description": "School Year 2017-2018",
 "bellScheduleExceptions": [
   {
     "id": "788b62cb-69c3-11e8-9e0e-37bff5ca251f",
     "description": "Snow Day",
     "ringListId": "68c1f806-650e-11e8-a57e-bf0edde4bce4",
     "startDate": "2018-01-03",
     "endDate": "2018-01-03",
     "ringListName": "Snow Day"
   }
 ],
 "timeZone": "America/Chicago",
 "domainId": "8b5ec352-6ce3-11e9-8128-731ed9098c36",
 "permissions": [
   "delete",
   "put",
   "get"
 ],
 "bellScheduleEntries": [
   {
     "ringListId": "f94d1622-6a65-11e8-9030-0d319c188f5d",
     "entryNum": 0,
     "ringListName": "Monday"
   },
   {
     "ringListId": "04e253b6-6a66-11e8-9030-055159f85cae",
     "entryNum": 1,
     "ringListName": "Tuesday"
   },
   {
     "ringListId": "0a5c4df9-6a66-11e8-9030-e5fd3c7e9500",
     "entryNum": 2,
     "ringListName": "Wednesday"
   },
   {
     "ringListId": "1140387c-6a66-11e8-9030-f52fea97f89c",
     "entryNum": 3,
     "ringListName": "Thursday"
   },
   {
     "ringListId": "16240d3f-6a66-11e8-9030-bfa905b4cd81",
     "entryNum": 4,
     "ringListName": "Friday"
   }
 ],
 "name": "School Year 17-18",
 "startDate": "2017-08-28",
 "createdAt": "2018-05-31T20:18:35.635Z",
 "numWeeks": 1,
 "endDate": "2018-05-25",
 "id": "cc01447c-650f-11e8-a57e-332c8cdd597f"
}

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

HTTP Request

POST /domains/{domainId}/bell-schedules

Produces

application/json

Path Parameters

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

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Bell Schedule out of a parent Domain?
id String n/a The id of the Bell Schedule to be added to the Domain.
include­Domains Boolean false If true, include the list of Domains to which each Bell Schedule belongs in the response.
promote Boolean false Allow this request to proceed even if it will promote the Bell Schedule out of one or more child Domains?

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

Remove a Domain Bell Schedule

# Continuing with the bell schedule object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/bell-schedules/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the bell schedule object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Bell Schedule 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Bell Schedule should be removed.
id String The id of the Bell Schedule 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 Bell Schedule in no Domain.

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

Response

The deletion response format is detailed here.

Domain Collaboration Groups

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

List All Domain Collaboration Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/collaboration-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "properties": {
        "joinPin": "9911",
        "bypassIvr": false,
        "createPin": null
      },
      "permissions": [
        "delete",
        "get"
      ],
      "name": "Other",
      "createdAt": "2020-01-08T18:05:19.324Z",
      "type": "conference-call",
      "distributionListIds": [
          "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb"
      ],
      "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
      "id": "6e5049e9-3241-11ea-b861-27f86e6b26d5",
      "distributionLists": [
          {
              "campaign": null,
              "name": "Administrator Alerts",
              "syncId": "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb:1576098207765",
              "id": "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb",
              "createdAt": "2019-12-11T21:03:27.762Z",
              "isSubscribable": false
          }
      ],
      "userIds": [],
      "users": []
    }
  ]
}

Retrieves the list of all Collaboration 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}/collaboration-groups

Produces

application/json

Path Parameters

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

Query Parameters

There was one collaboration group 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 find out the entire set of Domains to which each returned Collaboration Group belongs, request the Collaboration Groups attached to any subdomains of the specified Domain, and/or filter the results by matching on the Collaboration Group name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Collaboration Group belongs.
name String Returns only Collaboration Group whose names exactly match the supplied value.
recursive boolean If true, in addition to Collaboration Groups that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Collaboration Group response format is detailed here. Additionally, the id of the domain whose collaboration groups were requested is returned under the key domainId inside each response.

Check if a Domain contains a Collaboration Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/collaboration-groups/6e5049e9-3241-11ea-b861-27f86e6b26d5"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/collaboration-groups/6e5049e9-3241-11ea-b861-27f86e6b26d5" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/collaboration-groups/6e5049e9-3241-11ea-b861-27f86e6b26d5"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "properties": {
    "joinPin": "9911",
    "bypassIvr": false,
    "createPin": null
  },
  "permissions": [
    "delete",
    "get"
  ],
  "name": "Other",
  "createdAt": "2020-01-08T18:05:19.324Z",
  "type": "conference-call",
  "distributionListIds": [
      "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb"
  ],
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "id": "6e5049e9-3241-11ea-b861-27f86e6b26d5",
  "distributionLists": [
      {
          "campaign": null,
          "name": "Administrator Alerts",
          "syncId": "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb:1576098207765",
          "id": "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb",
          "createdAt": "2019-12-11T21:03:27.762Z",
          "isSubscribable": false
      }
  ],
  "userIds": [],
  "users": []
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

Additionally, you can find out the exact set of domains to which the Collaboration Group belongs, or check if the Collaboration Group is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Collaboration Group belongs.
recursive boolean If true, in addition to Collaboration Groups that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '6e5049e9-3241-11ea-b861-27f86e6b26d5'

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/collaboration-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "6e5049e9-3241-11ea-b861-27f86e6b26d5"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/collaboration-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '6e5049e9-3241-11ea-b861-27f86e6b26d5'
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "properties": {
    "joinPin": "9911",
    "bypassIvr": false,
    "createPin": null
  },
  "permissions": [
    "delete",
    "get"
  ],
  "name": "Other",
  "createdAt": "2020-01-08T18:05:19.324Z",
  "type": "conference-call",
  "distributionListIds": [
      "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb"
  ],
  "domainId": "8b5ec352-6ce3-11e9-8128-731ed9098c36",
  "id": "6e5049e9-3241-11ea-b861-27f86e6b26d5",
  "distributionLists": [
      {
          "campaign": null,
          "name": "Administrator Alerts",
          "syncId": "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb:1576098207765",
          "id": "ad8d7f21-1c59-11ea-ac18-c73360b3d8bb",
          "createdAt": "2019-12-11T21:03:27.762Z",
          "isSubscribable": false
      }
  ],
  "userIds": [],
  "users": []
}

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

HTTP Request

POST /domains/{domainId}/collaboration-groups

Produces

application/json

Path Parameters

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

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Collaboration Group out of a parent Domain?
id String n/a The id of the Collaboration Group to be added to the Domain.
include­Domains Boolean false If true, include the list of Domains to which each Collaboration Group belongs in the response.
promote Boolean false Allow this request to proceed even if it will promote the Collaboration Group out of one or more child Domains?

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

Remove a Domain Collaboration Group

# Continuing with the collaboration group object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/collaboration-groups/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the collaboration group object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Collaboration Group 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Collaboration Group should be removed.
id String The id of the Collaboration 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 Collaboration Group in no Domain.

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

Response

The deletion response format is detailed here.

Domain Confirmation Requests

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

List All Domain Confirmation Requests

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/confirmation-requests?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
    "permissions": ["delete", "put", "get"],
    "escalationRules": [
      {
        "optionLabel": "Yes, I saw seen the intruder",
        "subject": "The intruder has been spotted!",
        "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
        "comparison": "LT",
        "image": null,
        "audio": null,
        "delay": 600,
        "comparisonValue": 5,
        "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
        "createdAt": "2014-08-11T14:03:45.434Z",
        "messageTemplateId": null,
        "body": "",
        "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
      }
    ],
    "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
    "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
    "createdAt": "2014-08-04T13:53:57.566Z",
    "expirationPeriod": 3600,
    "options": ["Yes, I saw the intruder", "No, I have not"],
    "initiateTrackingOptions": [true, false],
    "name": "Have you seen the intruder?"
  }
 ]
}

Retrieves the list of all Confirmation Requests 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}/confirmation-requests

Produces

application/json

Path Parameters

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

Query Parameters

There was one confirmation request 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 find out the entire set of Domains to which each returned Confirmation Request belongs, request the Confirmation Requests attached to any subdomains of the specified Domain, and/or filter the results by matching on the Confirmation Request name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Confirmation Request belongs.
name String Returns only Confirmation Request whose names exactly match the supplied value.
recursive boolean If true, in addition to Confirmation Requests that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Confirmation Request response format is detailed here. Additionally, the id of the domain whose confirmation requests were requested is returned under the key domainId inside each response.

Check if a Domain contains a Confirmation Request

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "escalationRules": [
    {
      "optionLabel": "Yes, I saw the intruder",
      "subject": "The intruder has been spotted!",
      "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
      "comparison": "GT",
      "image": null,
      "audio": null,
      "delay": 600,
      "comparisonValue": 0,
      "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-11T14:03:45.434Z",
      "body": "",
      "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
    }
  ],
  "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "domainId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
  "createdAt": "2014-08-04T13:53:57.566Z",
  "expirationPeriod": 3600,
  "options": ["Yes, I saw the intruder", "No, I have not"],
  "initiateTrackingOptions": [true, false],
  "name": "Have you seen the intruder?"
}

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

HTTP Request

GET /domains/{domainId}/confirmation-requests/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Confirmation Requests are of interest.
id The id of the Confirmation Request whose membership in the Domain is being checked.

Query Parameters

Additionally, you can find out the exact set of domains to which the Confirmation Request belongs, or check if the Confirmation Request is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Confirmation Request belongs.
recursive boolean If true, in addition to Confirmation Requests that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'c7bc65e0-1bde-11e4-9181-3c970e7ff560'
,
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/confirmation-requests" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560", \
       "includeDomains": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/confirmation-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'c7bc65e0-1bde-11e4-9181-3c970e7ff560',
    'includeDomains': true
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": ["delete", "put", "get"],
 "escalationRules": [
   {
     "optionLabel": "Yes, I saw the intruder",
     "subject": "The intruder has been spotted!",
     "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
     "comparison": "GT",
     "image": null,
     "audio": null,
     "delay": 600,
     "comparisonValue": 0,
     "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
     "createdAt": "2014-08-11T14:03:45.434Z",
     "body": "",
     "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
   }
 ],
 "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
 "domainId": "8b5ec352-6ce3-11e9-8128-731ed9098c36",
 "createdAt": "2014-08-04T13:53:57.566Z",
 "expirationPeriod": 3600,
 "options": ["Yes, I saw the intruder", "No, I have not"],
 "initiateTrackingOptions": [true, false],
 "name": "Have you seen the intruder?",
 "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.459Z",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

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

HTTP Request

POST /domains/{domainId}/confirmation-requests

Produces

application/json

Path Parameters

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

Request Parameters

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

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

Remove a Domain Confirmation Request

# Continuing with the confirmation request
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/confirmation-requests/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the confirmation request
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Confirmation Request 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Confirmation Request should be removed.
id String The id of the Confirmation Request 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 Confirmation Request in no Domain.

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

Response

The deletion response format is detailed here.

Domain Device Groups

Fusion Only

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

List All Domain Device Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/device-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

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

Retrieves the list of all Device 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}/device-groups

Produces

application/json

Path Parameters

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

Query Parameters

There was one device group 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 find out the entire set of Domains to which each returned Device Group belongs, request the Device Groups attached to any subdomains of the specified Domain, and/or filter the results by matching on the Device Group name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Device Group belongs.
name String Returns only Device Group whose names exactly match the supplied value.
recursive boolean If true, in addition to Device Groups that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Device Group response format is detailed here. Additionally, the id of the domain whose device groups were requested is returned under the key domainId inside each response.

Check if a Domain contains a Device Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/device-groups/0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

Additionally, you can find out the exact set of domains to which the Device Group belongs, or check if the Device Group is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Device Group belongs.
recursive boolean If true, in addition to Device Groups that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7'

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/device-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/device-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '0aa9c9a4-05dd-11e7-aa6b-8b0e17d53fc7'
}

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

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

HTTP Request

POST /domains/{domainId}/device-groups

Produces

application/json

Path Parameters

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

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Device Group out of a parent Domain?
id String n/a The id of the Device Group to be added to the Domain.
include­Domains Boolean false If true, include the list of Domains to which each Device Group belongs in the response.
promote Boolean false Allow this request to proceed even if it will promote the Device Group out of one or more child Domains?

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

Remove a Domain Device Group

# Continuing with the device group object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/device-groups/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the device group object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Device Group 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Device Group should be removed.
id String The id of the Device 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 Device Group in no Domain.

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

Response

The deletion response format is detailed here.

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true,
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "domainId": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
      "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, find out the entire set of Domains to which each returned Distribution List belongs, and/or filter the results by matching on the Distribution List name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each distribution list belongs.
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. Additionally, the id of the domain whose distribution lists were requested is returned under the key domainId inside each response.

Check if a Domain contains a Distribution List

require 'httparty'
require 'json'

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

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists/59489180-41f1-11e5-aa08-aa951d8d7a3b?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "id": "59489180-41f1-11e5-aa08-aa951d8d7a3b",
  "domainId": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
  "createdAt": "2015-08-13T19:27:34.552Z",
  "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.

Query Parameters

Additionally, you can find out the exact set of domains to which the Distribution List belongs, or check if the Distribution List is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the message template belongs.
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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '3cf58710-2305-11e4-b544-3c970e7ff560'
,
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
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", \
       "includeDomains": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/3a0a7df2-3434-11e8-a93d-59d3fdc242ee/distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '3cf58710-2305-11e4-b544-3c970e7ff560',
    'includeDomains': true
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "id": "3cf58710-2305-11e4-b544-3c970e7ff560",
  "domainId": "3a0a7df2-3434-11e8-a93d-59d3fdc242ee",
  "createdAt": "2015-08-13T19:27:34.552Z",
  "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/"
    }
  ]
}

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.
include­Domains Boolean false If true, include the list of Domains to which each Distribution List belongs in the response.
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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the distribution list object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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 Incident Plans

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

List All Domain Incident Plans

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true,
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
   {
     "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
     "name": "IT Outage",
     "description": "Network connections interrupted - Updates will follow",
     "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/"
       }
     ],
     "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
     "createdAt": "2021-05-27T15:03:50.605Z",
     "permissions": [
         "put",
         "delete",
         "get"
     ]
   }
 ]
}

Retrieves the list of all Incident Plans 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}/incident-plans

Produces

application/json

Path Parameters

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

Query Parameters

There was only one incident plan 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 Incident Plans attached to any subdomains of the specified Domain, find out the entire set of Domains to which each returned Incident Plan belongs, and/or filter the results by matching on the Incident Plan name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Incident Plan belongs.
name String Returns only Incident Plans whose names exactly match the supplied value.
recursive boolean If true, in addition to Incident Plans that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Incident Plan response format is detailed here. Additionally, the id of the domain whose Incident Plans were requested is returned under the key domainId inside each response.

Check if a Domain contains an Incident Plan

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true
}

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "name": "IT Outage",
  "description": "Network connections interrupted - Updates will follow",
  "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/"
    }
  ],
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "createdAt": "2021-05-27T15:03:50.605Z",
  "permissions": [
      "put",
      "delete",
      "get"
  ]
}

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

HTTP Request

GET /domains/{domainId}/incident-plans/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Incident Plans are of interest.
id The id of the Incident Plan whose membership in the Domain is being checked.

Query Parameters

Additionally, you can find out the exact set of domains to which the Incident Plan belongs, or check if the Incident Plan is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Incident Plan belongs.
recursive boolean If true, in addition to Incident Plans that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'bebd604d-befc-11eb-9006-654fb6bb8702'

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "bebd604d-befc-11eb-9006-654fb6bb8702"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'bebd604d-befc-11eb-9006-654fb6bb8702'
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "permissions": [
      "delete",
      "get"
  ]
}

Puts the Incident Plan 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}/incident-plans

Produces

application/json

Path Parameters

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

Request Parameters

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

A Incident Plan 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 Incident Plan 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 Incident Plan

# Continuing with the incident plan object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the incident plan object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Incident Plan bebd604d-befc-11eb-9006-654fb6bb8702"
}

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

HTTP Request

DELETE /domains/{domainId}/incident-plans/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Incident Plan should be removed.
id String The id of the Incident Plan 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 Incident Plan in no Domain.

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

Response

The deletion response format is detailed here.

Domain Incidents

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Incidents are assigned to the acting domain of the User when they triggered the Incident. This resource lets you see which Incidents occurred in which Domains.

List All Domain Incidents

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incidents"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incidents?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/incidents"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 7,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
   {
     "permissions": [
        "get"
     ],
     "messageTemplateId": null,
     "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/"
       }
     ],
     "messageTemplate": null,
     "notificationId": null,
     "createdAt": "2021-05-24T17:11:39.792Z",
     "notificationCreatedAt": null,
     "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
     "id": "1ab1311b-bcb3-11eb-9359-d58236cfba24",
     "incidentPlan": {
       "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
       "name": "IT Outage",
       "domains": [
         {
           "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
           "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
           "name": "Library",
           "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
           "namePath": "/Library/"
         }
       ],
       "description": "Network connections interrupted - Updates will follow"
     },
     "scenario": null,
     "endedAt": "2021-05-25T16:21:16.201Z"
   }
 ]
}

Retrieves the list of all Incidents 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}/incidents

Produces

application/json

Path Parameters

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

Query Parameters

There were seven Incidents assigned to the specified Domain when the request was made, and we asked for only the first to be returned in order to save space. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can find out the entire set of Domains to which each returned Incident belongs, or request the Incidents attached to any subdomains of the specified Domain, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Incident belongs.
recursive boolean If true, in addition to Incidents that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Incident response format is detailed here. Additionally, the id of the domain whose Incidents were requested is returned under the key domainId inside each response.

Check if a Domain contains a Incident

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/incidents/1ab1311b-bcb3-11eb-9359-d58236cfba24"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/incidents/1ab1311b-bcb3-11eb-9359-d58236cfba24" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/incidents/1ab1311b-bcb3-11eb-9359-d58236cfba24"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
     "get"
  ],
  "messageTemplateId": null,
  "messageTemplate": null,
  "notificationId": null,
  "createdAt": "2021-05-24T17:11:39.792Z",
  "notificationCreatedAt": null,
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "id": "1ab1311b-bcb3-11eb-9359-d58236cfba24",
  "incidentPlan": {
    "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
    "name": "IT Outage",
    "description": "Network connections interrupted - Updates will follow"
  },
  "scenario": null,
  "endedAt": "2021-05-25T16:21:16.201Z"
}

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

HTTP Request

GET /domains/{domainId}/incidents/{id}

Produces

application/json

Path Parameters

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

Query Parameters

Additionally, you can find out the exact set of domains to which the Incident belongs, or check if the Incident is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Incident belongs.
recursive boolean If true, in addition to Incidents that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true,
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "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.246Z",
   "id": "8bf05eaf-6be8-11e7-925b-49f9effcdeab",
   "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "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.954Z",
   "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
   "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "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, find out the entire set of Domains to which each returned Load Definition belongs, and/or filter the results by matching on the Load Definition name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Load Definition belongs
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. Additionally, the id of the domain whose load definitions were requested is returned under the key domainId inside each response.

Check if a Domain contains a Load Definition

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions/7030f7f4-4661-11e9-9372-ad3660dbb389"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions/7030f7f4-4661-11e9-9372-ad3660dbb389?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions/7030f7f4-4661-11e9-9372-ad3660dbb389"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true
}

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "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.954Z",
 "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
 "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
 "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.

Query Parameters

Additionally, you can find out the exact set of domains to which the Load Definition belongs, or check if the Load Definition is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Load Definition belongs.
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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '7030f7f4-4661-11e9-9372-ad3660dbb389'
,
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
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", \
       "includeDomains": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '7030f7f4-4661-11e9-9372-ad3660dbb389',
    'includeDomains': true
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "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.954Z",
 "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
 "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
 "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.
include­Domains Boolean false If true, include the list of Domains to which each Load Definition belongs in the response.
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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the load definition object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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 Message Templates

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

List All Domain Message Templates

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 4,
  "partial": true,
  "previous": null,
  "next": "WyJoYWlsIiwiMzdmMGY1MDAtMWJlMC0xMWU0LTkxODEtM2M5NzBlN2ZmNTYwIl0=",
  "data": [
    {
      "distributionListIdsCustomizable": true,
      "subject": "Lunch options for this Friday",
      "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
      "userIdsCustomizable": false,
      "notificationProfile": {
        "id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3",
        "name": "Default Profile",
        "settings": "... Object omitted for brevity ..."
      },
      "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
      "userIDs": ["685c2400-dd09-11e3-8c49-b8e856327746"],
      "confirmationRequestIdDisplay": "auto",
      "bodyDisplay": "auto",
      "audioDisplay": "auto",
      "name": "Friday Food Choices",
      "imageCustomizable": false,
      "subjectCustomizable": false,
      "confirmationRequestIdCustomizable": false,
      "image": 0,
      "imageDisplay": "auto",
      "audioCustomizable": false,
      "audio": 0,
      "alertTone": "default",
      "alertToneCustomizable": false,
      "alertToneDisplay": "auto",
      "confirmationRequestId": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-04T13:58:37.777Z",
      "expiration": null,
      "expirationCustomizable": false,
      "expirationDisplay": "auto",
      "permissions": ["delete", "put", "get"],
      "distributionListIdsDisplay": "auto",
      "userIdsDisplay": "auto",
      "collaborationGroupIdsDisplay": "auto",
      "collaborationGroupIdsCustomizable": false,
      "collaborationGroupIds": [],
      "deviceGroupIdsDisplay": "auto",
      "deviceGroupIdsCustomizable": false,
      "deviceGroupIds": [],
      "deviceGroups": [],
      "collaborationGroups": [],
      "areaOfInterestIds": null,
      "areaOfInterestIdsCustomizable": false,
      "areasOfInterest": [],
      "areaOfInterestIdsDisplay": "auto",
      "subjectDisplay": "auto",
      "optOut": false,
      "body": "Please take a second to select what you would like to eat this Friday. If you have any dietary restrictions, please let myself or a member of the culinary staff know.",
      "id": "6ec13410-1bdf-11e4-9181-3c970e7ff560",
      "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
      "distributionLists": [
        {
          "createdAt": "2014-08-06T18:51:33.590Z",
          "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
          "name": "Staff"
        }
      ],
      "users": [
        {
          "createdAt": "2014-05-16T14:50:22.656Z",
          "id": "685c2400-dd09-11e3-8c49-b8e856327746",
          "name": "Craig Smith"
        }
      ],
      "confirmationRequest": {
        "escalationRules": [ ],
        "createdAt": "2014-08-04T13:57:18.824Z",
        "id": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
        "options": ["Pizza", "Salad & Bread Sticks"],
        "name": "Food Options - Friday"
      },
      "bodyCustomizable": false,
      "metadataCustomizable": false,
      "followUp": false
    }
  ]
}

Retrieves the list of all Message Templates 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}/message-templates

Produces

application/json

Path Parameters

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

Query Parameters

There were a total of two Message Templates 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 Message Templates attached to any subdomains of the specified Domain, find out the entire set of Domains to which each returned Message Template belongs, and/or filter the results by matching on the Message Template name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each message template belongs.
name String Returns only Message Templates whose names exactly match the supplied value.
followUp Boolean Returns only Message Templates whose followUp attributes match the supplied value.
recursive Boolean If true, in addition to Message Templates that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Message Template response format is detailed here. Additionally, the id of the domain whose message templates were requested is returned under the key domainId inside each response.

Check if a Domain contains a Message Template

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    template = JSON.parse(HTTParty.get(url, headers: headers))
    puts(template)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    template = requests.get(url, headers=headers).json()
    print(template)
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListIdsCustomizable": true,
  "subject": "Lunch options for this Friday",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "userIdsCustomizable": false,
  "notificationProfile": {
    "id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3",
    "name": "Default Profile",
    "settings": "... Object omitted for brevity ..."
  },
  "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
  "userIDs": ["685c2400-dd09-11e3-8c49-b8e856327746"],
  "confirmationRequestIdDisplay": "auto",
  "bodyDisplay": "auto",
  "audioDisplay": "auto",
  "name": "Friday Food Choices",
  "imageCustomizable": false,
  "subjectCustomizable": false,
  "confirmationRequestIdCustomizable": false,
  "image": 0,
  "imageDisplay": "auto",
  "audioCustomizable": false,
  "audio": 0,
  "alertTone": "default",
  "alertToneCustomizable": false,
  "alertToneDisplay": "auto",
  "confirmationRequestId": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-04T13:58:37.777Z",
  "expiration": null,
  "expirationCustomizable": false,
  "expirationDisplay": "auto",
  "permissions": ["delete", "put", "get"],
  "distributionListIdsDisplay": "auto",
  "userIdsDisplay": "auto",
  "collaborationGroupIdsDisplay": "auto",
  "collaborationGroupIdsCustomizable": false,
  "collaborationGroupIds": [],
  "deviceGroupIdsDisplay": "auto",
  "deviceGroupIdsCustomizable": false,
  "deviceGroupIds": [],
  "deviceGroups": [],
  "collaborationGroups": [],
  "areaOfInterestIds": null,
  "areaOfInterestIdsCustomizable": false,
  "areasOfInterest": [],
  "areaOfInterestIdsDisplay": "auto",
  "subjectDisplay": "auto",
  "optOut": false,
  "body": "Please take a second to select what you would like to eat this Friday. If you have any dietary restrictions, please let myself or a member of the culinary staff know.",
  "id": "6ec13410-1bdf-11e4-9181-3c970e7ff560",
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "distributionLists": [
    {
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Staff"
    }
  ],
  "users": [
    {
      "createdAt": "2014-05-16T14:50:22.656Z",
      "id": "685c2400-dd09-11e3-8c49-b8e856327746",
      "name": "Craig Smith"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-04T13:57:18.824Z",
    "id": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
    "options": ["Pizza", "Salad & Bread Sticks"],
    "name": "Food Options - Friday"
  },
  "bodyCustomizable": false,
  "metadataCustomizable": false,
  "followUp": false
}

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

HTTP Request

GET /domains/{domainId}/message-templates/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Message Templates are of interest.
id The id of the Message Template whose membership in the Domain is being checked.

Query Parameters

Additionally, you can find out the exact set of domains to which the Message Template belongs, or check if the Message Template is attached to any subdomains of the specified Domain, using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the message template belongs.
recursive boolean If true, in addition to Message Templates that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '6ec13410-1bdf-11e4-9181-3c970e7ff560'

}

begin: 
    template = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(template)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "6ec13410-1bdf-11e4-9181-3c970e7ff560"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '6ec13410-1bdf-11e4-9181-3c970e7ff560'
}

try: 
    template = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(template)
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListIdsCustomizable": true,
  "subject": "Lunch options for this Friday",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "userIdsCustomizable": false,
  "notificationProfile": {
    "id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3",
    "name": "Default Profile",
    "settings": "... Object omitted for brevity ..."
  },
  "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
  "userIDs": ["685c2400-dd09-11e3-8c49-b8e856327746"],
  "confirmationRequestIdDisplay": "auto",
  "bodyDisplay": "auto",
  "audioDisplay": "auto",
  "name": "Friday Food Choices",
  "imageCustomizable": false,
  "subjectCustomizable": false,
  "confirmationRequestIdCustomizable": false,
  "image": 0,
  "imageDisplay": "auto",
  "audioCustomizable": false,
  "audio": 0,
  "alertTone": "default",
  "alertToneCustomizable": false,
  "alertToneDisplay": "auto",
  "confirmationRequestId": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-04T13:58:37.777Z",
  "expiration": null,
  "expirationCustomizable": false,
  "expirationDisplay": "auto",
  "permissions": ["delete", "put", "get"],
  "distributionListIdsDisplay": "auto",
  "userIdsDisplay": "auto",
  "collaborationGroupIdsDisplay": "auto",
  "collaborationGroupIdsCustomizable": false,
  "collaborationGroupIds": [],
  "deviceGroupIdsDisplay": "auto",
  "deviceGroupIdsCustomizable": false,
  "deviceGroupIds": [],
  "deviceGroups": [],
  "collaborationGroups": [],
  "areaOfInterestIds": null,
  "areaOfInterestIdsCustomizable": false,
  "areasOfInterest": [],
  "areaOfInterestIdsDisplay": "auto",
  "subjectDisplay": "auto",
  "optOut": false,
  "body": "Please take a second to select what you would like to eat this Friday. If you have any dietary restrictions, please let myself or a member of the culinary staff know.",
  "id": "6ec13410-1bdf-11e4-9181-3c970e7ff560",
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "distributionLists": [
    {
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Staff"
    }
  ],
  "users": [
    {
      "createdAt": "2014-05-16T14:50:22.656Z",
      "id": "685c2400-dd09-11e3-8c49-b8e856327746",
      "name": "Craig Smith"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-04T13:57:18.824Z",
    "id": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
    "options": ["Pizza", "Salad & Bread Sticks"],
    "name": "Food Options - Friday"
  },
  "bodyCustomizable": false,
  "metadataCustomizable": false,
  "followUp": false
}

Puts the Message Template 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}/message-templates

Produces

application/json

Path Parameters

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

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Message Template out of a parent Domain?
id String n/a The id of the Message Template to be added to the Domain.
include­Domains Boolean false If true, include the list of Domains to which each Message Template belongs in the response.
promote Boolean false Allow this request to proceed even if it will promote the Message Template out of one or more child Domains?

A Message Template 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 Message Template 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 Message Template

# Continuing with the message template object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the message template object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Message Template 6ec13410-1bdf-11e4-9181-3c970e7ff560"
}

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

HTTP Request

DELETE /domains/{domainId}/message-templates/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Message Template should be removed.
id String The id of the Message Template 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 Message Template in no Domain.

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

Response

The deletion response format is detailed here.

Domain Notifications

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Notifications are assigned to the acting domain of the sending user. This resource lets you see which Notifications were sent in which Domains.

List All Domain Notifications

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notifications?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 7,
  "partial": true,
  "previous": null,
  "next": "WyIyMTBmMGRmMC0xZDg4LTExZTQtYzk3MGU3ZmY1NjAiXQ==",
  "data": [
    {
      "subject": "An intruder has been spotted on campus",
      "distributionListIds": ["71ad1fe0-19af-11e4-9367-3c970e7ff560"],
      "initiatorId": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
      "initiator": {
        "createdAt": "2014-08-04T13:42:57.973Z",
        "id": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
        "email": "security@e.mail",
        "name": "Security Office"
      },
      "image": 0,
      "confirmationResults": { "Yes, I've seen the intruder": 0, "No, I haven't": 0 },
      "audio": 32292,
      "alertTone": "default",
      "followUpAllowed": true,
      "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-06T16:38:56.411Z",
      "messageTemplateId": "e5543bf0-1bde-11e4-9181-3c970e7ff560",
      "permissions": ["delete", "put", "get"],
      "recipientCount": 5,
      "progress": {
        "recipientCount": 5,
        "readCount": 4,
        "smsReceivedCount": 3,
        "callAnsweredCount": 1,
        "smsFailedCount": 0,
        "callPlacedCount": 2,
        "callFailedCount": 1,
        "smsSentCount": 4,
        "extensions": {
          "17c57b50-833d-11e5-b222-def38c5ff9e6": {
            "type": "device",
            "total": 4,
            "failed": 0,
            "completed": 3,
            "deviceType": "SMS"
          },
          "b6d90e60-2a40-11e5-8134-9a9e6c05013a": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "singlewire:email"
          },
          "5a181177-3f02-11e6-9617-6bb7c7eddc0e": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "Android"
          },
          "551de6ae-3d36-11e6-834a-3d1fcb19aadd": {
            "type": "fusion-endpoint",
            "total": 1,
            "failed": 1,
            "completed": 1,
            "deviceType": null
          },
          "e322d549-4e80-11e6-af2d-9baf604d14b0": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "singlewire:icop"
          },
          "1a172e36-3f02-11e6-9617-9fc8b50f4de1": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "apns-sandbox"
          },
          "1a172e36-3f02-11e6-9617-9fc8b50f4de2": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "apns-qa"
          },
          "839771a8-4915-11e6-8b2f-d310e58d9c03": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "apns"
          },
          "0a466b30-7670-11e5-ba6e-765ae9d26291": {
            "type": "device",
            "total": 2,
            "failed": 1,
            "completed": 1,
            "deviceType": "phone-call"
          }
        }
      },
      "messageTemplate": {
        "name": "Intruder Alert"
      },
      "body": "Warning: An intruder has been spotted on campus heading towards the recreation center. Please be advised and stay tuned for further updates. Have you seen the intruder?",
      "id": "28bbc6b0-1d88-11e4-a054-3c970e7ff560",
      "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
      "distributionLists": [null],
      "areasOfInterest": [ {
        "id": "9cf22563-01a7-11e6-91d9-c77df3a40a79",
        "name": "Clifton",
        "createdAt": "2016-04-13T18:43:28.566Z",
        "geometryType": "circle",
        "geometryValue": {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [ -84.0, 39.0 ]
          },
          "properties": { "radiusInM": 1221 }
        },
        "recipientCount": 2
      } ],
      "confirmationRequest": {
        "escalationRules": [ ],
        "createdAt": "2014-08-04T13:53:57.566Z",
        "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
        "options": ["Yes, I've seen the intruder", "No, I haven't"],
        "name": "Intruder?"
      }
    }
  ]
}

Retrieves the list of all Notifications 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}/notifications

Produces

application/json

Path Parameters

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

Query Parameters

There were seven notifications assigned to the specified Domain when the request was made, and we asked for only the first to be returned in order to save space. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can find out the entire set of Domains to which each returned Notification belongs, or request the Notifications attached to any subdomains of the specified Domain, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Notification belongs.
recursive boolean If true, in addition to Notifications that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Notification response format is detailed here. Additionally, the id of the domain whose notifications were requested is returned under the key domainId inside each response.

Check if a Domain contains a Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/notifications/28bbc6b0-1d88-11e4-a054-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/notifications/28bbc6b0-1d88-11e4-a054-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/notifications/28bbc6b0-1d88-11e4-a054-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "subject": "An intruder has been spotted on campus",
  "distributionListIds": ["71ad1fe0-19af-11e4-9367-3c970e7ff560"],
  "initiatorId": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
  "initiator": {
    "createdAt": "2014-08-04T13:42:57.973Z",
    "id": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
    "email": "security@e.mail",
    "name": "Security Office"
  },
  "image": 0,
  "confirmationResults": { "Yes, I've seen the intruder": 0, "No, I haven't": 0 },
  "audio": 32292,
  "alertTone": "default",
  "followUpAllowed": true,
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-06T16:38:56.411Z",
  "messageTemplateId": "e5543bf0-1bde-11e4-9181-3c970e7ff560",
  "permissions": ["delete", "put", "get"],
  "recipientCount": 5,
  "progress": {
    "recipientCount": 5,
    "readCount": 4,
    "smsReceivedCount": 3,
    "callAnsweredCount": 1,
    "smsFailedCount": 0,
    "callPlacedCount": 2,
    "callFailedCount": 1,
    "smsSentCount": 4,
    "extensions": {
      "17c57b50-833d-11e5-b222-def38c5ff9e6": {
        "type": "device",
        "total": 4,
        "failed": 0,
        "completed": 3,
        "deviceType": "SMS"
      },
      "b6d90e60-2a40-11e5-8134-9a9e6c05013a": {
        "type": "device",
        "total": 0,
        "failed": 0,
        "completed": 0,
        "deviceType": "singlewire:email"
      },
      "5a181177-3f02-11e6-9617-6bb7c7eddc0e": {
        "type": "device",
        "total": 0,
        "failed": 0,
        "completed": 0,
        "deviceType": "Android"
      },
      "551de6ae-3d36-11e6-834a-3d1fcb19aadd": {
        "type": "fusion-endpoint",
        "total": 1,
        "failed": 1,
        "completed": 1,
        "deviceType": null
      },
      "e322d549-4e80-11e6-af2d-9baf604d14b0": {
        "type": "device",
        "total": 0,
        "failed": 0,
        "completed": 0,
        "deviceType": "singlewire:icop"
      },
      "1a172e36-3f02-11e6-9617-9fc8b50f4de1": {
        "type": "device",
        "total": 0,
        "failed": 0,
        "completed": 0,
        "deviceType": "apns-sandbox"
      },
      "1a172e36-3f02-11e6-9617-9fc8b50f4de2": {
        "type": "device",
        "total": 0,
        "failed": 0,
        "completed": 0,
        "deviceType": "apns-qa"
      },
      "839771a8-4915-11e6-8b2f-d310e58d9c03": {
        "type": "device",
        "total": 0,
        "failed": 0,
        "completed": 0,
        "deviceType": "apns"
      },
      "0a466b30-7670-11e5-ba6e-765ae9d26291": {
        "type": "device",
        "total": 2,
        "failed": 1,
        "completed": 1,
        "deviceType": "phone-call"
      }
    }
  },
  "messageTemplate": {
    "name": "Intruder Alert",
  },
  "body": "Warning: An intruder has been spotted on campus heading towards the recreation center. Please be advised and stay tuned for further updates. Have you seen the intruder?",
  "domainId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
  "id": "28bbc6b0-1d88-11e4-a054-3c970e7ff560",
  "distributionLists": [null],
  "areasOfInterest": [ {
    "id": "9cf22563-01a7-11e6-91d9-c77df3a40a79",
    "name": "Clifton",
    "createdAt": "2016-04-13T18:43:28.566Z",
    "geometryType": "circle",
    "geometryValue": {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [ -84.0, 39.0 ]
      },
      "properties": { "radiusInM": 1221 }
    },
    "recipientCount": 2
  } ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-04T13:53:57.566Z",
    "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
    "options": ["Yes, I've seen the intruder", "No, I haven't"],
    "name": "Intruder?"
  }
}

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

HTTP Request

GET /domains/{domainId}/notifications/{id}

Produces

application/json

Path Parameters

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

Query Parameters

Additionally, you can find out the exact set of domains to which the Notification belongs, or check if the Notification is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Notification belongs.
recursive boolean If true, in addition to Notifications that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

Domain Notification Profiles

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

List All Domain Notification Profiles

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "previous": null,
  "next": 2,
  "partial": true,
  "data": [{
    "id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d",
    "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
    "name": "Default Profile",
    "settings": [{
      "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
      "name": "InformaCast Device",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
      "name": "Email",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {
          "headingText": "Notification From",
          "introText": "Custom intro",
          "primaryColor": "#3498db",
          "primaryTextColor": "#ffffff",
          "secondaryTextColor": "#205478",
          "subheadingText": "InformaCast Mobile"
        }
      },
      "attachments": []
    }, {
      "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
      "name": "Apple Production Push μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
      "name": "Google μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de2",
      "name": "Apple QA Push μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
      "name": "Apple Dev Push μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
      "name": "SMS",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {
          "introduction": "Main introduction",
          "includeBody": null
        }
      },
      "attachments": []
    }, {
      "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
      "name": "Phone Call",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {
          "introduction": "The following is an alert from the University of Wisconsin."
        }
      },
      "attachments": []
    }],
    "createdAt": "2017-07-26T12:50:58.048Z",
    "permissions": ["delete", "put", "get"]
  }]
}

Retrieves the list of all Notification Profiles 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}/notification-profiles

Produces

application/json

Path Parameters

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

Query Parameters

To make this example more manageable, only the first Notification Profile associated with the Domain 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.

Additionally, you can request the Notification Profiles attached to any subdomains of the specified Domain, find out the entire set of Domains to which each returned Notification Profile belongs, and/or filter the results by matching on the Notification Profile name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Notification Profile belongs.
name String Returns only Notification Profiles whose names exactly match the supplied value.
recursive Boolean If true, in addition to Notification Profiles that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Notification Profile response format is detailed here. Additionally, the id of the domain whose notification profiles were requested is returned under the key domainId inside each response.

Check if a Domain contains a Notification Profile

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles/11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    profile = JSON.parse(HTTParty.get(url, headers: headers))
    puts(profile)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles/11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles/11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    profile = requests.get(url, headers=headers).json()
    print(profile)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d",
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "name": "Default Profile",
  "settings": [{
    "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
    "name": "InformaCast Device",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
    "name": "Email",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "headingText": "Notification From",
        "introText": "Custom intro",
        "primaryColor": "#3498db",
        "primaryTextColor": "#ffffff",
        "secondaryTextColor": "#205478",
        "subheadingText": "InformaCast Mobile"
      }
    },
    "attachments": []
  }, {
    "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
    "name": "Apple Production Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
    "name": "Google μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de2",
    "name": "Apple QA Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
    "name": "Apple Dev Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
    "name": "SMS",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
    "name": "Phone Call",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }],
  "createdAt": "2017-07-26T12:50:58.048Z",
  "permissions": ["delete", "put", "get"]
}

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

HTTP Request

GET /domains/{domainId}/notification-profiles/{id}

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose Notification Profiles are of interest.
id The id of the Notification Profile whose membership in the Domain is being checked.

Query Parameters

Additionally, you can find out the exact set of domains to which the Notification Profile belongs, or check if the Notification Profile is attached to any subdomains of the specified Domain, using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the notification profile belongs.
recursive boolean If true, in addition to Notification Profiles that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d'

}

begin: 
    profile = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(profile)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d'
}

try: 
    profile = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(profile)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d",
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "name": "Default Profile",
  "settings": [{
    "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
    "name": "InformaCast Device",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
    "name": "Email",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "headingText": "Notification From",
        "introText": "Custom intro",
        "primaryColor": "#3498db",
        "primaryTextColor": "#ffffff",
        "secondaryTextColor": "#205478",
        "subheadingText": "InformaCast Mobile"
      }
    },
    "attachments": []
  }, {
    "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
    "name": "Apple Production Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
    "name": "Google μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de2",
    "name": "Apple QA Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
    "name": "Apple Dev Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
    "name": "SMS",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
    "name": "Phone Call",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }],
  "createdAt": "2017-07-26T12:50:58.048Z",
  "permissions": ["delete", "put", "get"]
}

Puts the Notification Profile 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}/notification-profiles

Produces

application/json

Path Parameters

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

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Notification Profile out of a parent Domain?
id String n/a The id of the Notification Profile to be added to the Domain.
include­Domains Boolean false If true, include the list of Domains to which each Bell Schedule belongs in the response.
promote Boolean false Allow this request to proceed even if it will promote the Notification Profile out of one or more child Domains?

A Notification Profile 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 Notification Profile 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 Notification Profile

# Continuing with the notification profile
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/notification-profiles/6ec13410-1bdf-11e4-9181-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the notification profile
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Notification Profile 6ec13410-1bdf-11e4-9181-3c970e7ff560"
}

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

HTTP Request

DELETE /domains/{domainId}/notification-profiles/{id}

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Notification Profile should be removed.
id String The id of the Notification Profile 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 Notification Profile in no Domain.

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

Response

The deletion response format is detailed here.

Domain Ring Lists

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

List All Domain Ring Lists

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
    "id": "95f5006b-7a3f-11e8-bcdc-798f6371a42a",
    "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
    "name": "Long Day",
    "description": "Schedule for Monday, Wednesday, and Friday",
    "entries": [
      {
        "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
        "time": "08:00:00",
        "deviceGroups": [
          {
            "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
            "name": "All Speakers"
          }
        ],
        "distributionLists": null,
        "messageTemplate": {
          "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "name": "School Bell"
        },
        "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
        "distributionListIds": []
      },
      {
        "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
        "time": "09:00:00",
        "deviceGroups": [
          {
            "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
            "name": "All Speakers"
          }
        ],
        "distributionLists": null,
        "messageTemplate": {
          "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "name": "School Bell"
        },
        "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
        "distributionListIds": []
      },
      {
        "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
        "time": "10:00:00",
        "deviceGroups": [
          {
            "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
            "name": "All Speakers"
          }
        ],
        "distributionLists": null,
        "messageTemplate": {
          "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "name": "School Bell"
        },
        "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
        "distributionListIds": []
      },
      {
        "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
        "time": "11:00:00",
        "deviceGroups": [
          {
            "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
            "name": "All Speakers"
          }
        ],
        "distributionLists": null,
        "messageTemplate": {
          "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "name": "School Bell"
        },
        "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
        "distributionListIds": []
      }
    ],
    "permissions": [
      "delete",
      "put",
      "get"
    ],
    "createdAt": "2018-06-27T19:23:35.219Z"
   }
 ]
}

Retrieves the list of all Ring 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}/ring-lists

Produces

application/json

Path Parameters

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

Query Parameters

There were a total of two ring 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 find out the entire set of Domains to which each returned Ring List belongs, request the Ring Lists attached to any subdomains of the specified Domain, and/or filter the results by matching on the Ring List name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Ring List belongs.
name String Returns only Ring Lists whose names exactly match the supplied value.
recursive boolean If true, in addition to Ring Lists that are directly attached to the specified Domain, any attached to its subdomains will be returned.

Response

The Ring List response format is detailed here. Additionally, the id of the domain whose ring lists were requested is returned under the key domainId inside each response.

Check if a Domain contains a Ring List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "95f5006b-7a3f-11e8-bcdc-798f6371a42a",
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "name": "Long Day",
  "description": "Schedule for Monday, Wednesday, and Friday",
  "entries": [
    {
      "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
      "time": "08:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
      "time": "09:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
      "time": "10:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
      "time": "11:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    }
  ],
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-06-27T19:23:35.219Z"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

Additionally, you can find out the exact set of domains to which the Ring List belongs, or check if the Ring List is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Ring List belongs.
recursive boolean If true, in addition to Ring Lists that are directly attached to the specified Domain, any attached to its subdomains will be considered.

Response

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '7030f7f4-4661-11e9-9372-ad3660dbb389'

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "7030f7f4-4661-11e9-9372-ad3660dbb389"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '7030f7f4-4661-11e9-9372-ad3660dbb389'
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
  "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "name": "Long Day",
  "description": "Schedule for Monday, Wednesday, and Friday",
  "entries": [
    {
      "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
      "time": "08:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
      "time": "09:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
      "time": "10:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
      "time": "11:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    }
  ],
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-06-27T19:23:35.219Z"
}

Puts the Ring 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}/ring-lists

Produces

application/json

Path Parameters

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

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Ring List out of a parent Domain?
id String n/a The id of the Ring List to be added to the Domain.
include­Domains Boolean false If true, include the list of Domains to which each Ring List belongs in the response.
promote Boolean false Allow this request to proceed even if it will promote the Ring List out of one or more child Domains?

A Ring 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 Ring 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 Ring List

# Continuing with the ring list object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/ring-lists/7030f7f4-4661-11e9-9372-ad3660dbb389" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the ring list object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Ring List 7030f7f4-4661-11e9-9372-ad3660dbb389"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

Parameter Type Description
domainId String The id of the Domain from which the Ring List should be removed.
id String The id of the Ring 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 Ring List in no Domain.

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

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/scenarios?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true,
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "id": "4d244d53-9450-11e9-8a98-29ad15a64fbc",
   "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "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.403Z",
   "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 find out the entire set of Domains to which each returned Scenario belongs, request the Scenarios attached to any subdomains of the specified Domain, and/or filter the results by matching on the Scenario name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Scenario belongs.
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. Additionally, the id of the domain whose scenarios were requested is returned under the key domainId inside each response.

Check if a Domain contains a Scenario

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/scenarios/4d244d53-9450-11e9-8a98-29ad15a64fbc"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/scenarios/4d244d53-9450-11e9-8a98-29ad15a64fbc?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/scenarios/4d244d53-9450-11e9-8a98-29ad15a64fbc"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true
}

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "4d244d53-9450-11e9-8a98-29ad15a64fbc",
 "domainId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
 "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.403Z",
 "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.

Query Parameters

Additionally, you can find out the exact set of domains to which the Scenario belongs, or check if the Scenario is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Scenario belongs.
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 Scenario 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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '4d244d53-9450-11e9-8a98-29ad15a64fbc'
,
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
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", \
       "includeDomains": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '4d244d53-9450-11e9-8a98-29ad15a64fbc',
    'includeDomains': true
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "4d244d53-9450-11e9-8a98-29ad15a64fbc",
 "domainId": "8b5ec352-6ce3-11e9-8128-731ed9098c36",
 "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.403Z",
 "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.
includeDomains Boolean false If true, include the list of Domains to which the Scenario belongs in the response.
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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the scenario object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJhZHJpYW4gYWRzaGVhZCIsImZiNTA3YTMwLTAxNTktMTFlNC1iYzNkLTY4NWIzNThlYTg0NyJd",
  "data": [
    {
      "id": "c54e4241-299b-11e8-94d3-2be9464da125",
      "domainId": "90de0f6a-28df-11e8-8c38-e9fe0f3683de",
      "name": "Custodial Staff",
      "superGroup": false,
      "permissions": [
          "delete",
          "put",
          "get"
      ],
      "createdAt": "2018-03-17T04:29:24.171Z"
    }
  ]
}

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 find out the entire set of Domains to which each returned Security Group belongs, request the Security Groups attached to any subdomains of the specified Domain, and/or filter the results by matching on the Security Group name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Security Group belongs.
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. Additionally, the id of the domain whose security groups were requested is returned under the key domainId inside each response.

Check if a Domain contains a Security Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups/c54e4241-299b-11e8-94d3-2be9464da125"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    group = JSON.parse(HTTParty.get(url, headers: headers))
    puts(group)
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/90de0f6a-28df-11e8-8c38-e9fe0f3683de/security-groups/c54e4241-299b-11e8-94d3-2be9464da125"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    group = requests.get(url, headers=headers).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "c54e4241-299b-11e8-94d3-2be9464da125",
  "domainId": "90de0f6a-28df-11e8-8c38-e9fe0f3683de",
  "name": "Custodial Staff",
  "superGroup": false,
  "permissions": [
      "delete",
      "put",
      "get"
  ],
  "createdAt": "2018-03-17T04:29:24.171Z"
}

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.

Query Parameters

Additionally, you can find out the exact set of domains to which the Security Group belongs, or check if the Security Group is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Security Group belongs.
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

require 'httparty'
require 'json'

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

}

begin: 
    group = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(group)
rescue StandardError => e
    puts e
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"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    group = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "c54e4241-299b-11e8-94d3-2be9464da125",
  "domainId": "90de0f6a-28df-11e8-8c38-e9fe0f3683de",
  "name": "Custodial Staff",
  "superGroup": false,
  "permissions": [
      "delete",
      "put",
      "get"
  ],
  "createdAt": "2018-03-17T04:29:24.171Z"
}

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.
include­Domains Boolean false If true, include the list of Domains to which each Security Group belongs in the response.
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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the security group object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/security-group-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/security-group-permissions?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/security-group-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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.773Z"
        },
        "permissions": [
          "delete",
          "put",
          "get"
        ],
        "createdAt": "2017-01-19T00:10:22.801Z"
    },
    {
      "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.773Z"
      },
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2017-01-19T00:10:22.802Z"
    }
  ]
}

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/security-group-permissions/ab9b0b88-dddb-11e6-a7a8-7b42f33ea4b7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    perm = JSON.parse(HTTParty.get(url, headers: headers))
    puts(perm)
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/security-group-permissions/ab9b0b88-dddb-11e6-a7a8-7b42f33ea4b7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    perm = requests.get(url, headers=headers).json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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.773Z"
  },
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2017-01-19T00:10:22.802Z"
}

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/7e71167b-4124-11ea-aa0d-5b75363e5d84/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/7e71167b-4124-11ea-aa0d-5b75363e5d84/sites?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/7e71167b-4124-11ea-aa0d-5b75363e5d84/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true,
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "total": 1,
    "previous": null,
    "next": null,
    "partial": false,
    "data": [
        {
            "id": "c10f88d8-0779-11eb-b543-6dea855a479f",
            "name": "South Campus",
            "domains": [
                {
                    "id": "7e71167b-4124-11ea-aa0d-5b75363e5d84",
                    "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
                    "name": "South Campus",
                    "path": "/7e71167b-4124-11ea-aa0d-5b75363e5d84/",
                    "namePath": "/South Campus/"
                }
            ],
            "createdAt": "2020-10-06T02:15:07.639Z",
            "recipients": [
                {
                    "siteId": "c10f88d8-0779-11eb-b543-6dea855a479f",
                    "collaborationGroups": [],
                    "createdAt": "2020-10-06T02:15:07.664Z",
                    "distributionListIds": [],
                    "deviceGroupIds": [],
                    "areasOfInterest": [],
                    "id": "c113596a-0779-11eb-b543-23dc51b8c4c4",
                    "siteRoleId": "14fdcf83-0778-11eb-b543-3da0d7f5f643",
                    "collaborationGroupIds": [],
                    "distributionLists": [],
                    "userIds": [],
                    "deviceGroups": [],
                    "areaOfInterestIds": [],
                    "users": []
                },
                {
                    "siteId": "c10f88d8-0779-11eb-b543-6dea855a479f",
                    "collaborationGroups": [],
                    "createdAt": "2020-10-06T02:15:07.664Z",
                    "distributionListIds": [
                        "b5578105-0779-11eb-b543-5f1e8986ac15"
                    ],
                    "deviceGroupIds": [],
                    "areasOfInterest": [],
                    "id": "c1135969-0779-11eb-b543-e98eebf336a0",
                    "siteRoleId": "19b00cf4-0778-11eb-b543-4735b006d8eb",
                    "collaborationGroupIds": [],
                    "distributionLists": [
                        {
                            "campaign": null,
                            "name": "South Admins",
                            "syncId": "b5578105-0779-11eb-b543-5f1e8986ac15:1601950487986",
                            "id": "b5578105-0779-11eb-b543-5f1e8986ac15",
                            "createdAt": "2020-10-06T02:14:47.978Z",
                            "isSubscribable": false
                        }
                    ],
                    "userIds": [],
                    "deviceGroups": [],
                    "areaOfInterestIds": [],
                    "users": []
                }
            ],
            "domainId": "7e71167b-4124-11ea-aa0d-5b75363e5d84",
            "permissions": [
                "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 find out the entire set of Domains to which each returned Site belongs, request the Sites attached to any subdomains of the specified Domain, and/or filter the results by matching on the Site name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Site belongs.
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. Additionally, the id of the domain whose sites were requested is returned under the key domainId inside each response.

Check if a Domain contains a Site

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/7e71167b-4124-11ea-aa0d-5b75363e5d84/sites/c10f88d8-0779-11eb-b543-6dea855a479f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/7e71167b-4124-11ea-aa0d-5b75363e5d84/sites/c10f88d8-0779-11eb-b543-6dea855a479f?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/7e71167b-4124-11ea-aa0d-5b75363e5d84/sites/c10f88d8-0779-11eb-b543-6dea855a479f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true
}

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "c10f88d8-0779-11eb-b543-6dea855a479f",
    "name": "South Campus",
    "domains": [
        {
            "id": "7e71167b-4124-11ea-aa0d-5b75363e5d84",
            "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
            "name": "South Campus",
            "path": "/7e71167b-4124-11ea-aa0d-5b75363e5d84/",
            "namePath": "/South Campus/"
        }
    ],
    "createdAt": "2020-10-06T02:15:07.639Z",
    "recipients": [
        {
            "siteId": "c10f88d8-0779-11eb-b543-6dea855a479f",
            "collaborationGroups": [],
            "createdAt": "2020-10-06T02:15:07.664Z",
            "distributionListIds": [],
            "deviceGroupIds": [],
            "areasOfInterest": [],
            "id": "c113596a-0779-11eb-b543-23dc51b8c4c4",
            "siteRoleId": "14fdcf83-0778-11eb-b543-3da0d7f5f643",
            "collaborationGroupIds": [],
            "distributionLists": [],
            "userIds": [],
            "deviceGroups": [],
            "areaOfInterestIds": [],
            "users": []
        },
        {
            "siteId": "c10f88d8-0779-11eb-b543-6dea855a479f",
            "collaborationGroups": [],
            "createdAt": "2020-10-06T02:15:07.664Z",
            "distributionListIds": [
                "b5578105-0779-11eb-b543-5f1e8986ac15"
            ],
            "deviceGroupIds": [],
            "areasOfInterest": [],
            "id": "c1135969-0779-11eb-b543-e98eebf336a0",
            "siteRoleId": "19b00cf4-0778-11eb-b543-4735b006d8eb",
            "collaborationGroupIds": [],
            "distributionLists": [
                {
                    "campaign": null,
                    "name": "South Admins",
                    "syncId": "b5578105-0779-11eb-b543-5f1e8986ac15:1601950487986",
                    "id": "b5578105-0779-11eb-b543-5f1e8986ac15",
                    "createdAt": "2020-10-06T02:14:47.978Z",
                    "isSubscribable": false
                }
            ],
            "userIds": [],
            "deviceGroups": [],
            "areaOfInterestIds": [],
            "users": []
        }
    ],
    "domainId": "7e71167b-4124-11ea-aa0d-5b75363e5d84",
    "permissions": [
        "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.

Query Parameters

Additionally, you can find out the exact set of domains to which the Site belongs, or check if the Site is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Site belongs.
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 Site 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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '896437cf-9458-11e9-bb63-07b12ce3e3e2'
,
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
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", \
       "includeDomains": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/8b5ec352-6ce3-11e9-8128-731ed9098c36/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '896437cf-9458-11e9-bb63-07b12ce3e3e2',
    'includeDomains': true
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "c10f88d8-0779-11eb-b543-6dea855a479f",
    "domainId": "896437cf-9458-11e9-bb63-07b12ce3e3e2",
    "name": "South Campus",
    "domains": [
        {
            "id": "7e71167b-4124-11ea-aa0d-5b75363e5d84",
            "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
            "name": "South Campus",
            "path": "/7e71167b-4124-11ea-aa0d-5b75363e5d84/",
            "namePath": "/South 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": "2020-10-06T02:15:07.639Z",
    "recipients": [
        {
            "siteId": "c10f88d8-0779-11eb-b543-6dea855a479f",
            "collaborationGroups": [],
            "createdAt": "2020-10-06T02:15:07.664Z",
            "distributionListIds": [],
            "deviceGroupIds": [],
            "areasOfInterest": [],
            "id": "c113596a-0779-11eb-b543-23dc51b8c4c4",
            "siteRoleId": "14fdcf83-0778-11eb-b543-3da0d7f5f643",
            "collaborationGroupIds": [],
            "distributionLists": [],
            "userIds": [],
            "deviceGroups": [],
            "areaOfInterestIds": [],
            "users": []
        },
        {
            "siteId": "c10f88d8-0779-11eb-b543-6dea855a479f",
            "collaborationGroups": [],
            "createdAt": "2020-10-06T02:15:07.664Z",
            "distributionListIds": [
                "b5578105-0779-11eb-b543-5f1e8986ac15"
            ],
            "deviceGroupIds": [],
            "areasOfInterest": [],
            "id": "c1135969-0779-11eb-b543-e98eebf336a0",
            "siteRoleId": "19b00cf4-0778-11eb-b543-4735b006d8eb",
            "collaborationGroupIds": [],
            "distributionLists": [
                {
                    "campaign": null,
                    "name": "South Admins",
                    "syncId": "b5578105-0779-11eb-b543-5f1e8986ac15:1601950487986",
                    "id": "b5578105-0779-11eb-b543-5f1e8986ac15",
                    "createdAt": "2020-10-06T02:14:47.978Z",
                    "isSubscribable": false
                }
            ],
            "userIds": [],
            "deviceGroups": [],
            "areaOfInterestIds": [],
            "users": []
        }
    ],
    "permissions": [
        "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.
includeDomains Boolean false If true, include the list of Domains to which the Site belongs in the response.
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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the site object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': true
,
    'limit': 2

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles?includeDomains=true&limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': true,
    'limit': 2
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "total": 2,
    "previous": null,
    "next": null,
    "partial": false,
    "data": [
        {
            "id": "19b00cf4-0778-11eb-b543-4735b006d8eb",
            "name": "Library",
            "domains": [
                {
                    "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
                    "parentId": null,
                    "name": "Root",
                    "path": "/",
                    "namePath": "/"
                }
            ],
            "createdAt": "2020-10-06T02:03:17.337Z",
            "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
            "permissions": [
                "delete",
                "get"
            ]
        },
        {
            "id": "14fdcf83-0778-11eb-b543-3da0d7f5f643",
            "name": "Site Role 1",
            "domains": [
                {
                    "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
                    "parentId": null,
                    "name": "Root",
                    "path": "/",
                    "namePath": "/"
                }
            ],
            "createdAt": "2020-10-06T02:03:09.458Z",
            "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
            "permissions": [
                "delete",
                "get"
            ]
        }
    ]
}

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 find out the entire set of Domains to which each returned Site Role belongs, request the Site Roles attached to any subdomains of the specified Domain, and/or filter the results by matching on the Site Role name, using query parameters:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each Site Role belongs.
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. Additionally, the id of the domain whose site roles were requested is returned under the key domainId inside each response.

Check if a Domain contains a Site Role

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/site-roles/19b00cf4-0778-11eb-b543-4735b006d8eb"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/site-roles/19b00cf4-0778-11eb-b543-4735b006d8eb" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/site-roles/19b00cf4-0778-11eb-b543-4735b006d8eb"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    list = requests.get(url, headers=headers).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "19b00cf4-0778-11eb-b543-4735b006d8eb",
    "name": "Library",
    "createdAt": "2020-10-06T02:03:17.337Z",
    "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
    "permissions": [
        "delete",
        "get"
    ]
}

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.

Query Parameters

Additionally, you can find out the exact set of domains to which the Site Role belongs, or check if the Site Role is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Site Role belongs.
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 Site Role 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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '7030f7f4-4661-11e9-9372-ad3660dbb389'
,
    'includeDomains': true

}

begin: 
    list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(list)
rescue StandardError => e
    puts e
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", \
       "includeDomains": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/d3651b0a-3357-11e8-98ef-81eb3ce85bec/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '7030f7f4-4661-11e9-9372-ad3660dbb389',
    'includeDomains': true
}

try: 
    list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
 "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.954Z",
 "id": "7030f7f4-4661-11e9-9372-ad3660dbb389",
 "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec"
}

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.
includeDomains Boolean false If true, include the list of Domains to which the Site Role belongs in the response.
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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the site role object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'transitive': true
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users?transitive=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'transitive': true,
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 4,
  "partial": true,
  "previous": null,
  "next": "WyJhZHJpYW4gYWRzaGVhZCIsImZiNTA3YTMwLTAxNTktMTFlNC1iYzNkLTY4NWIzNThlYTg0NyJd",
  "data": [
    {
      "lock": { "start": "2014-03-16T14:00:00.000Z", "end": "2014-09-16T14:00:00.000Z" },
      "name": "Al Smith",
      "securityGroups": [
        {
          "createdAt": "2014-05-16T14:50:23.126Z",
          "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.656Z",
      "email": "al.smith@acme.edu",
      "type": "regular",
      "idleTimeout": null,
      "permissions": ["delete", "put", "get"],
      "subscriptions": [
        {
          "createdAt": "2014-05-19T19:09:21.020Z",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
          "id": "152f93c0-df89-11e3-93bc-685b358ea847"
        },
        {
          "createdAt": "2014-07-22T19:15:42.057Z",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
          "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
        }
      ],
      "source": "direct",
      "securityGroupId": null,
      "domainId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "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, find out the entire set of Domains to which each returned User belongs, and/or filter the results by matching on the User name or type, using query parameters:

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.
includeDomains Boolean If true, include the list of Domains to which each user belongs.
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).
type String Option: regular, application, anonymous. Return only Users whose type match the supplied value. Application users are for non-interactive use with permanent API tokens, such as with the InformaCast plugin; anonymous users cannot be created via the API, but are created when users register a phone anonymously to participate in a campaign.

Response

The User response format is detailed here. Additionally, the id of the domain whose users were requested is returned under the key domainId inside each response.

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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users/685c2400-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    user = JSON.parse(HTTParty.get(url, headers: headers))
    puts(user)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users/685c2400-dd09-11e3-8c49-b8e856327746" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users/685c2400-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    user = requests.get(url, headers=headers).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
{
  "lock": { "start": "2014-03-16T14:00:00.000Z", "end": "2014-09-16T14:00:00.000Z" },
  "name": "Al Smith",
  "securityGroups": [
    {
      "createdAt": "2014-05-16T14:50:23.126Z",
      "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.656Z",
  "email": "al.smith@acme.edu",
  "type": "regular",
  "idleTimeout": null,
  "permissions": ["delete", "put", "get"],
  "subscriptions": [
    {
      "createdAt": "2014-05-19T19:09:21.020Z",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
      "id": "152f93c0-df89-11e3-93bc-685b358ea847"
    },
    {
      "createdAt": "2014-07-22T19:15:42.057Z",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
      "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
    }
  ],
  "id": "685c2400-dd09-11e3-8c49-b8e856327746",
  "domainId": "9ca35dab-28df-11e8-8c38-235a5737f6bb"
}

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.

Query Parameters

Additionally, you can find out the exact set of domains to which the user belongs, or 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
includeDomains Boolean If true, include the list of Domains to which the User belongs.
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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '685c2400-dd09-11e3-8c49-b8e856327746'

}

begin: 
    user = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(user)
rescue StandardError => e
    puts e
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"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/domains/9ca35dab-28df-11e8-8c38-235a5737f6bb/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '685c2400-dd09-11e3-8c49-b8e856327746'
}

try: 
    user = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
{
  "lock": { "start": "2014-03-16T14:00:00.000Z", "end": "2014-09-16T14:00:00.000Z" },
  "name": "Al Smith",
  "securityGroups": [
    {
      "createdAt": "2014-05-16T14:50:23.126Z",
      "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.656Z",
  "email": "al.smith@acme.edu",
  "type": "regular",
  "idleTimeout": null,
  "permissions": ["delete", "put", "get"],
  "subscriptions": [
    {
      "createdAt": "2014-05-19T19:09:21.020Z",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
      "id": "152f93c0-df89-11e3-93bc-685b358ea847"
    },
    {
      "createdAt": "2014-07-22T19:15:42.057Z",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
      "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
    }
  ],
  "domainId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "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.
include­Domains Boolean false If true, include the list of Domains to which each user belongs in the response.
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:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
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"

# Continuing with the user object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/user-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/user-permissions?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/user-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 260,
 "previous": null,
 "next": "2",
 "partial": true,
 "data": [
  {
   "id": "009882e7-cd3e-11e6-a0cc-c52b5ffa2c35",
   "userId": "42532c36-4478-11e6-9ba6-fb22bf89f89a",
   "verb": "post",
   "spec": "/users",
   "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "user": {
    "id": "42532c36-4478-11e6-9ba6-fb22bf89f89a",
    "name": "Dione Jones",
    "email": "dione.jones@acme.com",
    "type": "regular",
    "createdAt": "2016-07-07T19:23:18.089Z"
   },
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2016-12-28T20:41:26.304Z"
  },
  {
   "id": "049e19b9-4a09-11e6-bbed-95f38efd94db",
   "userId": "42532c36-4478-11e6-9ba6-fb22bf89f89a",
   "verb": "get",
   "spec": "/users/*",
   "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
   "user": {
    "id": "42532c36-4478-11e6-9ba6-fb22bf89f89a",
    "name": "Dione Jones",
    "email": "dione.jones@acme.com",
    "type": "regular",
    "createdAt": "2016-07-07T19:23:18.089Z"
   },
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2016-07-14T21:22:07.401Z"
  }
 ]
}

These permissions mean that user Dione Jones can create new users and list all users in the specified Domain. Since an unpredictable set of userId values might be present in results, the corresponding User information is returned.

Retrieves the list of all Domain User 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}/user-permissions

Produces

application/json

Path Parameters

Parameter Description
domainId The id of the Domain whose associated User 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 260 User 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 User Permissions that are directly attached to the specified Domain, any permissions attached to its subdomains will be returned.

Response

The Domains User 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 User Permission

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/user-permissions/049e19b9-4a09-11e6-bbed-95f38efd94db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    perm = JSON.parse(HTTParty.get(url, headers: headers))
    puts(perm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/user-permissions/049e19b9-4a09-11e6-bbed-95f38efd94db" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/domains/69dab71b-12b2-11e8-bfe3-41154f2b6534/user-permissions/049e19b9-4a09-11e6-bbed-95f38efd94db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    perm = requests.get(url, headers=headers).json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "049e19b9-4a09-11e6-bbed-95f38efd94db",
 "userId": "42532c36-4478-11e6-9ba6-fb22bf89f89a",
 "verb": "get",
 "spec": "/users/*",
 "domainId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
 "user": {
  "id": "42532c36-4478-11e6-9ba6-fb22bf89f89a",
  "name": "Dione Jones",
  "email": "dione.jones@acme.com",
  "type": "regular",
  "createdAt": "2016-07-07T19:23:18.089Z"
 },
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "createdAt": "2016-07-14T21:22:07.401Z"
}

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

HTTP Request

GET /domains/{domainId}/user-permissions/{id}

Produces

application/json

Path Parameters

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

Response

The Domains User Permissions response format is detailed here.

Domains User Permissions Response

The JSON document used to represent a Domain User 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 User Permission that is scoped to the Domain.
permissions Array[String] Options: get put delete. What operations are possible on this permission resource itself.
spec String Identifies the path to the resource(s) the user is being permitted to act on.
user Object For convenience, provides information (name, email, type, creation timestamp) about the user to whom the permsision applies.
userId String The id of the User to whom this permission applies.
verb String Options: get post put delete. The action (HTTP method) which is permitted on the resource(s) identified by spec.

Dynamic Replies

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

List All Dynamic Replies

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
     "createdAt": "2020-10-14T22:49:39.332Z",
     "quota": 5,
     "confirmationRequestId": "0a6b60a0-0e4a-11eb-986a-55883885ddfb",
     "id": "8a88ecd8-0e6f-11eb-986a-2707a9326e84",
     "optionLabel": "I need assistance",
     "first": "Help is on the way!",
     "rest": "Uh oh.",
     "every": null
    }
  ]
}

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The dynamic reply response format is detailed here.

Get a Dynamic Reply

require 'httparty'
require 'json'

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

begin: 
    reply = JSON.parse(HTTParty.get(url, headers: headers))
    puts(reply)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies/8a88ecd8-0e6f-11eb-986a-2707a9326e84" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    reply = requests.get(url, headers=headers).json()
    print(reply)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": ["put", "delete", "get"],
 "createdAt": "2020-10-14T22:49:39.332Z",
 "quota": 5,
 "confirmationRequestId": "0a6b60a0-0e4a-11eb-986a-55883885ddfb",
 "id": "8a88ecd8-0e6f-11eb-986a-2707a9326e84",
 "optionLabel": "I need assistance",
 "first": "Help is on the way!",
 "every": null,
 "rest": "Uh oh."
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

The dynamic reply response format is detailed here.

Create a Dynamic Reply

require 'httparty'
require 'json'

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

}

begin: 
    reply = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(reply)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"optionLabel": "I am safe: outside building", \
       "every": "Get inside!"}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    reply = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(reply)
except RequestException as e:
    print('Unexpected error!', e)
{
 "confirmationRequestId": "0a6b60a0-0e4a-11eb-986a-55883885ddfb",
 "id": "254ee0b1-12ec-11eb-b89c-b1714049c798",
 "optionLabel": "I am safe: outside building",
 "createdAt": "2020-10-20T15:51:41.244Z",
 "every": "Get inside!",
 "permissions": ["put", "delete", "get"]
}

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

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

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The dynamic reply response format is detailed here.

Update a Dynamic Reply

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

Modifies an existing dynamic reply.

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The dynamic reply response format is detailed here.

Delete a Dynamic Reply

# Continuing with the dynamic reply object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/0a6b60a0-0e4a-11eb-986a-55883885ddfb/dynamic-replies/254ee0b1-12ec-11eb-b89c-b1714049c798" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the dynamic reply object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"ConfirmationRequestDynamicReply\"} 254ee0b1-12ec-11eb-b89c-b1714049c798"
}

Removes a dynamic reply from a confirmation request.

HTTP Request

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

Produces

Path Parameters

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

Response

The deletion response format is detailed here.

Dynamic Reply Response

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

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

Escalation Rules

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

List All Escalation Rules

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "optionLabel": "Yes, I have seen the intruder",
      "subject": "The intruder has been spotted!",
      "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
      "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"],
      "comparison": "GT",
      "image": null,
      "audio": null,
      "delay": 600,
      "comparisonValue": 0,
      "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-11T14:03:45.434Z",
      "permissions": ["delete", "put", "get"],
      "body": "",
      "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
    }
  ]
}

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

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Query Parameters

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

Response

The escalation rule response format is detailed here.

Get an Escalation Rule

require 'httparty'
require 'json'

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

begin: 
    rule = JSON.parse(HTTParty.get(url, headers: headers))
    puts(rule)
rescue StandardError => e
    puts e
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=" \
import requests
from requests.exceptions import RequestException

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

try: 
    rule = requests.get(url, headers=headers).json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
{
  "optionLabel": "Yes, I have seen the intruder",
  "subject": "The intruder has been spotted!",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"],
  "comparison": "GT",
  "image": null,
  "audio": null,
  "delay": 600,
  "comparisonValue": 0,
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-11T14:03:45.434Z",
  "messageTemplateId": null,
  "permissions": ["delete", "put", "get"],
  "body": "",
  "id": "4f062fa0-2160-11e4-ba87-3c970e7ff560"
}

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

HTTP Request

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

Produces

application/json

Path Parameters

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

Response

The escalation rule response format is detailed here.

Create an Escalation Rule

require 'httparty'
require 'json'

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

}

begin: 
    rule = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(rule)
rescue StandardError => e
    puts e
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"]}'
import requests
from requests.exceptions import RequestException
import json

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

try: 
    rule = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
{
  "optionLabel": "Yes, I have seen the intruder",
  "subject": "Still no sightings",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "deviceGroupIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff561"],
  "comparison": "LT",
  "image": null,
  "audio": null,
  "delay": 3600,
  "comparisonValue": 1,
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-11T19:26:58.885Z",
  "permissions": ["delete", "put", "get"],
  "body": null,
  "id": "766bf750-218d-11e4-ba87-3c970e7ff560"
}

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

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

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The escalation rule response format is detailed here.

Update an Escalation Rule

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

Modifies an existing escalation rule.

HTTP Request

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

Consumes

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

Produces

application/json

Path Parameters

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

Request Parameters

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

Response

The escalation rule response format is detailed here.

Delete an Escalation Rule

# Continuing with the escalation rule object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/confirmation-requests/c7bc65e0-1bde-11e4-9181-3c970e7ff560/escalation-rules/766bf750-218d-11e4-ba87-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the escalation rule object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"ConfirmationRequestEscalationRules\"} 766bf750-218d-11e4-ba87-3c970e7ff560"
}

Removes an escalation rule from a confirmation request.

HTTP Request

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

Produces

Path Parameters

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

Response

The deletion response format is detailed here.

Escalation Rule Response

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

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

Extensions

Extensions allow new features to be added to InformaCast Mobile without changing the core API implementation. Eventually this ability may be extended to third-party developers, but for now only Singlewire can create Extensions. As such, the documentation of this resource is currently limited, but should hopefully be enough to let you understand what you see in the API.

There are currently four different kinds of extensions, distinguished by their type attribute.

List All Extensions

require 'httparty'
require 'json'

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

}

begin: 
    extensions = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(extensions)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions?limit=3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    extensions = requests.get(url, headers=headers, params=params).json()
    print(extensions)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "disabled": false,
   "name": "Do Not Disturb Notification Blocker",
   "type": "device-filter",
   "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
   "createdAt": "2015-07-21T19:28:51.225Z",
   "updatedAt": "2015-07-21T19:28:51.225Z",
   "permissions": [
    "put",
    "get"
   ]
  },
  {
   "permissions": [
    "put",
    "get"
   ],
   "deviceLimit": 3,
   "disabled": false,
   "config": {
    "secondaryTextColor": null,
    "introText": "Some test intro text",
    "subheadingText": "InformaCast Mobile Alert System",
    "replyToAddress": null,
    "replyToName": null,
    "primaryTextColor": null,
    "fromAddress": null,
    "fromName": null,
    "primaryColor": null,
    "headingText": "Important Alert From"
   },
   "name": "Email",
   "type": "device",
   "deviceType": "singlewire:email",
   "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
   "createdAt": "2015-07-14T15:55:13.862Z",
   "updatedAt": "2015-07-14T15:55:13.862Z",
   "requiresOptIn": true
  }
 ]
}

Retrieves a list of all extensions. (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 manipulate extensions.)

HTTP Request

GET /extensions

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 three extensions were requested, there were only two available. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The extension response format is detailed here.

Get an Extension

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    extension = JSON.parse(HTTParty.get(url, headers: headers))
    puts(extension)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    extension = requests.get(url, headers=headers).json()
    print(extension)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "put",
  "get"
 ],
 "disabled": false,
 "config": {
  "secondaryTextColor": null,
  "introText": "Some test intro text",
  "subheadingText": "InformaCast Mobile Alert System",
  "replyToAddress": null,
  "replyToName": null,
  "primaryTextColor": null,
  "fromAddress": null,
  "fromName": null,
  "primaryColor": null,
  "headingText": "Important Alert From"
 },
 "name": "Email",
 "type": "device",
 "deviceType": "singlewire:email",
 "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
 "createdAt": "2015-07-14T15:55:13.862Z",
 "updatedAt": "2015-07-14T15:55:13.862Z",
 "requiresOptIn": true
}

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

HTTP Request

GET /extensions/{extensionId}

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension of interest.

Response

The extension response format is detailed here.

Update an Extension

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'disabled': true

}

begin: 
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'disabled': true
}

try: 
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "put",
  "get"
 ],
 "disabled": true,
 "config": {
  "secondaryTextColor": null,
  "introText": "Some test intro text",
  "subheadingText": "InformaCast Mobile Alert System",
  "replyToAddress": null,
  "replyToName": null,
  "primaryTextColor": null,
  "fromAddress": null,
  "fromName": null,
  "primaryColor": null,
  "headingText": "Important Alert From"
 },
 "name": "Email",
 "type": "device",
 "deviceType": "singlewire:email",
 "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
 "createdAt": "2015-07-14T15:55:13.862Z",
 "updatedAt": "2015-08-11T13:52:11.831Z",
 "requiresOptIn": true
}

Updates an existing extension, changing its configuration, enabling, or disabling it (license filter limit: 200 per type).

Tied Extensions

There are two pairs of extensions which are now treated by the user interface as a single concept: the iOS and Android push extensions are jointly managed as InformaCast for iOS/Android, and the macOS and Windows push extensions are jointly managed as InformaCast for Mac/Windows. Because of this, enabling or disabling one of either pair will automatically enable or disable the other.

HTTP Request

PUT /extensions/{extensionId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension being altered.

Request Parameters

Parameter Type Description
config JSON The configuration parameters for the extension. These will be sent to the extension itself for validation; the details are up to the extension, and you will need to consult the extension documentation to learn about them.
disabled boolean When true, the extension will no longer be used, and InformaCast Mobile will act as if it simply did not exist.

Response

The extension response format is detailed here.

Extension Response

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

Attribute Type Description
createdAt ISO 8601 date/time When this extension was created.
updatedAt ISO 8601 date/time When this extension was last updated.
config JSON The configuration parameters for the extension. These will be sent to the extension itself for validation; its details are up to the extension, and you will need to consult the extension documentation to learn about them.
configExports Array[String] The configuration parameters that will be exposed to notification profiles/message templates so they can see pieces of the config. For example includeBody for the SMS extension is important so the clients can properly compute SMS count estimates.
globalDisabled Boolean Determines whether the extension has been disabled by Singlewire. Note, this can’t be changed by anyone other than Singlewire.
deviceLimit integer For extensions of type device, identifies how many devices of the type provided by this extension may be associated with a single user.
deviceType String For extensions of type device, identifies the new type of device supported by the extension.
failureCode String For extensions of type device, identifies what the notification activity type will be if we fail to reach the extension.
disabled boolean When true, the extension will no longer be used, and InformaCast Mobile will act as if it simply did not exist.
id String The id of this specific extension, allowing it to be manipulated or retrieved individually.
name String The name of the extension.
permissions Array[String] Options: get put. What operations are possible on this extension resource itself.
type String Options: device device-filter, collaboration, endpoint-proxy. The kind of extension this is (as described at the start of this section).
requiresOptIn boolean Determines whether this extension type requires users to verify ownership of devices before they can receive notifications.

Extension Config Options

Many extensions allow for some customization through their configuration settings. (This is the config block in the examples and responses above.) These configurable extensions and their associated options are listed below.

Fusion Extension

Device type: endpoint-proxy

Option Type Default Description
idnFilter JSON (none)                     Filter for devices of idn type in device filter format. If unspecified, the license filter will include all devices. The filters format is detailed here.
phoneFilter JSON (none) Filter for devices of phone type in device filter format. If unspecified, the license filter will include all devices. The filters format is detailed here.
phoneRebuildSchedule String (hourly) Cron string whose frequency denotes how often the phone cache is rebuilt. By default, a hash of the provider-id is used, setting this job to an deterministic but unspecified minute every hour.
phoneRebuildTz String UTC Time zone for phoneRebuildSchedule
phoneRefreshInterval Integer 0 Interval (in minutes) after which partial phone information will be updated. If 0, these updates are not done at all.
phoneResetSchedule String 0 0 7 * * ? * If phoneResetStrategy is periodically, this cron schedule indicates when phones that need to be reset will be reset.
phoneResetTz String UTC Time zone for phoneResetSchedule
phoneResetStrategy String never Option: never, immediately, or periodically. Specifies when affected phones should be reset when configuration has changed or activation groups are changed. never: phones are never reset. immediately: phones are reset immediately. periodically: phones will be reset on a cron schedule, which you may also specify on this object. Phones must be reset once initially, and also when their authentication url changes as a result of an activation group pointing to a new endpoint.
speakerFilter JSON (none) Filter for devices of speaker type in device filter format. If unspecified, the license filter will include all devices. The filters format is detailed here.

Email Extension

Device type: singlewire:email

The configuration options for the email extension are broken down into three groups for readability. They are all part of the actual configuration and may be combined when setting or updating.

Basic Option Type Default Description
introText String (none) A short message to prepend to the content of all notifications sent via email.
headingText String Notification From Title text appearing at the top of the email.
subheadingText String InformaCast Mobile Subtitle text appearing just below headingText.
primaryColor String #3498db Background color of the heading.
primaryTextColor String #ffffff Color of any text appearing in the heading section.
secondaryTextColor String #205478 Color of any text appearing in the body of the notification.
Advanced Option Type Default Description
fromName String InformaCast Mobile The display name to use for the sender of the email. Should be verified with Singlewire before use.
fromAddress String do-not-reply@singlewire-informacast.com The email address to use for the sender of the email. Should be verified with Singlewire before use.
replyToName String InformaCast Mobile The display name to use when replying to the email. Should be verified with Singlewire before use.
replyToAddress String do-not-reply@singlewire-informacast.com The email address to use when replying to the email. Should be verified with Singlewire before use.
SMTP Option Type Default Description
smtpEnabled String false Whether or not custom SMTP settings will be used to deliver email messages through your own servers.
host String (none) The fully qualified domain name of the SMTP host.
port Int (none) The port to use for connecting. Must be one of the standard outbound email ports: 25, 465, or 587.
user String (none) The username for use during authentication.
password String (none) The password for use during authentication.*
disableUnsubscribe Boolean false Whether or not to remove the unsubscribe link in emails. Use with care, removal can make your messages appear more like spam.
ssl Boolean false Whether or not the SMTP server expects secure connections using SSL.
starttls Boolean false Whether or not the SMTP server will attempt to establish a secure connection using StartTLS.
sasl Boolean false Whether or not to use SASL authentication mechanisms.
saslMechanism String DIGEST-MD5,PLAIN Comma-separated list of authentication mechanisms supported by your server. Currently CRAM-MD5 is also accepted.
saslRealm String (none) Realm for use with DIGEST-MD5.

SMS Extension

Device type: SMS

Option Type Default Description
includeBody Boolean false Whether or not SMS messages should include the body in addition to the subject of the notification.
introduction String (none) Introductory text to prepend to all notification text delivered via SMS.

Telephony Extension

Device type: phone-call

Option Type Default Description
voice String man, en The particular voice and language to use when reading the notification during a phone call. *
introduction String (none) Introductory verbiage to be read before all notification text delivered via phone call.
conferenceCall­Introduction String (none) Introductory verbiage to be read before the user is added to a conference call.

Outbound CAP Extension

Device type: outbound-cap

{
  "configName1": {
    "url": "http://cap-system/etc",
    "profile": "standard"
  },
  "configName2": {
    "url": "https://cap-system/with/basic-auth",
    "profile": "standard",
    "username": "admin",
    "password": "1Z3456u8DtYz3"
  }
}

The configuration for the Outbound CAP extension consists of a map of connection configuration names to connection info. A connection configuration contains everything necessary for InformaCast to communicate with the external CAP system.

The JSON configuration object contains a name key for each connection configuration, and the value is a JSON object with the following options:

Option Type Default Description
url String (none) The URL of the external system to POST the CAP message to.
profile String standard Which CAP profile to support. Currently the only supported value is standard.
username String (none) If the external system supports HTTP Basic Auth, the username used to authenticate when connecting to the system. (Optional)
password String (none) If the external system supports HTTP Basic Auth, the password used to authenticate when connecting to the system. (Optional)

Extension Endpoints

An extension endpoint is a way of indicating an extension can have multiple targets. Currently, the only extension supporting endpoints is the Fusion extension. There are sub-routes that allow communication with specific endpoints, viewing their current resource mappings, current state, uploads/backups, and devices. Fusion endpoints can’t be created manually, but instead, they must be created following the on-screen instructions on the Fusion server itself.

List All Extension Endpoints

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    endpoints = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(endpoints)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    endpoints = requests.get(url, headers=headers, params=params).json()
    print(endpoints)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [{
    "id": "28a92caf-3d37-11e6-834a-431f5104df9d",
    "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
    "name": "Headquarters",
    "buildInfo": {
      "apiVersion": 1,
      "app": "Fusion",
      "version": "3.0.1",
      "buildSet": "95",
      "hostUuid": "ba76dc8a-34e5-11e7-a216-0242ac110002",
      "buildNumber": "95",
      "ipAddresses": {
        "en0": ["2001:470:c3e0:146:60f2:30d7:2e36:ae6d", "2001:470:c3e0:146:e0b9:fff9:8b0e:2b03", "2001:470:c3e0:146:bf:90aa:970a:bdd4", "fe80:0:0:0:1c8a:9d24:2cc9:d849%en0", "172.20.146.63"],
        "en9": ["2001:470:c3e0:128:f84d:150:4bcd:14c8", "2001:470:c3e0:128:a9c8:b5e2:5fca:d2be", "2001:470:c3e0:128:c3a:ab29:87eb:7aff", "fe80:0:0:0:46:1b10:adf4:2aa9%en9", "172.20.128.15"],
        "lo0": ["fe80:0:0:0:0:0:0:1%lo0", "0:0:0:0:0:0:0:1", "127.0.0.1"],
        "awdl0": ["fe80:0:0:0:a4ff:eff:fe10:2bdc%awdl0"],
        "utun0": ["fe80:0:0:0:850:440a:83d8:2704%utun0"]
      }
    },
    "config": {
      "timeZone": null,
      "backupSchedule": "0 0 0 1/1 * ? *"
    },
    "status": "GREEN",
    "redReasons": null,
    "yellowReason": null,
    "statusLastUpdated": "2016-06-28T13:49:39.605Z",
    "healthy": true,
    "syncErrors": [],
    "createdAt": "2016-06-28T13:49:39.605Z",
    "updatedAt": "2016-06-28T13:49:39.605Z",
    "permissions": ["delete", "put", "get"]
  }]
}

Retrieves a list of all extension endpoints. (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/{extensionId}/endpoints

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 three extensions were requested, there were only two available. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includePending Boolean If true, will include endpoints that do not have their build information set.

Response

The extension endpoints response format is detailed here.

Get an Extension Endpoint

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    endpoint = JSON.parse(HTTParty.get(url, headers: headers))
    puts(endpoint)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    endpoint = requests.get(url, headers=headers).json()
    print(endpoint)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "28a92caf-3d37-11e6-834a-431f5104df9d",
  "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
  "name": "Headquarters",
  "buildInfo": {
    "apiVersion": 1,
    "app": "Fusion",
    "version": "3.0.1",
    "buildSet": "95",
    "hostUuid": "ba76dc8a-34e5-11e7-a216-0242ac110002",
    "buildNumber": "95",
    "ipAddresses": {
      "en0": ["2001:470:c3e0:146:60f2:30d7:2e36:ae6d", "2001:470:c3e0:146:e0b9:fff9:8b0e:2b03", "2001:470:c3e0:146:bf:90aa:970a:bdd4", "fe80:0:0:0:1c8a:9d24:2cc9:d849%en0", "172.20.146.63"],
      "en9": ["2001:470:c3e0:128:f84d:150:4bcd:14c8", "2001:470:c3e0:128:a9c8:b5e2:5fca:d2be", "2001:470:c3e0:128:c3a:ab29:87eb:7aff", "fe80:0:0:0:46:1b10:adf4:2aa9%en9", "172.20.128.15"],
      "lo0": ["fe80:0:0:0:0:0:0:1%lo0", "0:0:0:0:0:0:0:1", "127.0.0.1"],
      "awdl0": ["fe80:0:0:0:a4ff:eff:fe10:2bdc%awdl0"],
      "utun0": ["fe80:0:0:0:850:440a:83d8:2704%utun0"]
    }
  },
  "config": {
    "timeZone": null,
    "backupSchedule": "0 0 0 1/1 * ? *",
    "description": "Our Main Headquarters"
  },
  "status": "GREEN",
  "redReasons": null,
  "yellowReason": null,
  "statusLastUpdated": "2016-06-28T13:49:39.605Z",
  "healthy": true,
  "syncErrors": [],
  "createdAt": "2016-06-28T13:49:39.605Z",
  "updatedAt": "2016-06-28T13:49:39.605Z",
  "permissions": ["delete", "put", "get"]
}

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

HTTP Request

GET /extensions/{extensionId}/endpoints/{endpointId}

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension.
endpointId The id of the Extension.

Response

The extension endpoint response format is detailed here.

Update an Extension Endpoint’s Config

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Headquarters'
,
    'config': {
        'description': 'Our Main Headquarters'

}


}

begin: 
    endpoint = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(endpoint)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Headquarters", \
       "config": {"description": "Our Main Headquarters"}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Headquarters',
    'config': {
        'description': 'Our Main Headquarters'
}

}

try: 
    endpoint = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(endpoint)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "28a92caf-3d37-11e6-834a-431f5104df9d",
  "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
  "name": "Headquarters",
  "buildInfo": {
    "apiVersion": 1,
    "app": "Fusion",
    "version": "3.0.1",
    "buildSet": "95",
    "hostUuid": "ba76dc8a-34e5-11e7-a216-0242ac110002",
    "buildNumber": "95",
    "ipAddresses": {
      "en0": ["2001:470:c3e0:146:60f2:30d7:2e36:ae6d", "2001:470:c3e0:146:e0b9:fff9:8b0e:2b03", "2001:470:c3e0:146:bf:90aa:970a:bdd4", "fe80:0:0:0:1c8a:9d24:2cc9:d849%en0", "172.20.146.63"],
      "en9": ["2001:470:c3e0:128:f84d:150:4bcd:14c8", "2001:470:c3e0:128:a9c8:b5e2:5fca:d2be", "2001:470:c3e0:128:c3a:ab29:87eb:7aff", "fe80:0:0:0:46:1b10:adf4:2aa9%en9", "172.20.128.15"],
      "lo0": ["fe80:0:0:0:0:0:0:1%lo0", "0:0:0:0:0:0:0:1", "127.0.0.1"],
      "awdl0": ["fe80:0:0:0:a4ff:eff:fe10:2bdc%awdl0"],
      "utun0": ["fe80:0:0:0:850:440a:83d8:2704%utun0"]
    }
  },
  "config": {
    "timeZone": null,
    "backupSchedule": "0 0 0 1/1 * ? *",
    "description": "Our Main Headquarters"
  },
  "status": "GREEN",
  "redReasons": null,
  "yellowReason": null,
  "statusLastUpdated": "2016-06-28T13:49:39.605Z",
  "healthy": true,
  "syncErrors": [],
  "createdAt": "2016-06-28T13:49:39.605Z",
  "updatedAt": "2016-07-20T11:41:23.587Z",
  "permissions": ["delete", "put", "get"]
}

Update the extension’s config and name.

HTTP Request

PUT /extensions/{extensionId}/endpoints/{endpointId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension.
endpointId The id of the Endpoint.

Request Parameters

Parameter Type Default Description
name String N/A The name of the endpoint.
config.timeZone String N/A The timezone the server should operate in.
config.backup­Schedule String N/A A Quartz cron schedule representing when the server should back up. The format is described in detail here.
config.desc­ription String N/A An expanded description to provide more details than the name.

Response

The extension endpoint response format is detailed here.

Extension Endpoint Response

The JSON document used to represent an extension endpoint resource has the following content:

Attribute | Type | Description ——— | | ———– id | String | The id of the extension endpoint. extensionId | String | The extension id of the extension endpoint. name | String | The name of the endpoint. healthy | Boolean | Whether or not the server has recently responded to a health check. syncErrors | Array[object] | An collection of errors encountered during synchronization with on-prem InformaCast. status | String | The status of the server, one of RED and YELLOW and GREEN, where RED or YELLOW indicates a problem with your server has been detected. Not writable. redReasons | Array[String] | A list of reasons as to why your server is in a RED status. Not writable. yellowReasons | Array[String] | A list of reasons as to why your server is in a YELLOW status. Not writable. statusLastUpdated | ISO 8601 date/time | The last time that the status of the server was updated at. Not writable. createdAt | ISO 8601 date/time | When this endpoint was created. updatedAt | ISO 8601 date/time | When this endpoint was last updated. permissions | Array[String] | Options: get put. What operations are possible on this endpoint resource itself. buildInfo.api­Version | Integer | The API version the endpoint is running. buildInfo.app | String | The mode the server is in. buildInfo.version | String | The version of the server. buildInfo.host­Uuid | String | The unique identifer of the Fusion server. buildInfo.build­Number | String | The server’s build. buildInfo.ip­Addresses | Object | The server’s IP addresses, represented as an Object whose keys are String (adapter name) -> Array[String] (IP addresses). config.time­Zone | String | The timezone the server should operate in. config.backup­Schedule | String | A Quartz cron schedule representing when the server should back up. The format is described in detail here. config.description | String | An expanded description from the name to provide more details

Extension Endpoint Activities

Provides a log of interactions between extension endpoints (currently these are only Fusion servers) and InformaCast Mobile. For the most part this is read-only, but you can also ask an endpoint to create a backup or to restart itself by POSTing a special activity to it.

List All Endpoint Activities

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 3

}

begin: 
    activities = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(activities)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities?limit=3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 3
}

try: 
    activities = requests.get(url, headers=headers, params=params).json()
    print(activities)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [{
    "permissions": ["delete", "put", "get"],
    "value": null,
    "createdAt": "2017-07-26T18:30:25.060Z",
    "type": "recipient-group-update",
    "state": "complete",
    "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
    "endpointId": "28a92caf-3d37-11e6-834a-431f5104df9d",
    "id": "7dad5e6f-7230-11e7-a5a3-fd11e045be24",
    "referenceType": "device-group",
    "severity": "info",
    "referenceId": "f7f6353f-3654-11e7-a84b-8fdfa583129f"
  }]
}

Retrieves a list of all endpoint activities. (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/{extensionId}/endpoints/{endpointId}/activities

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 three extensions were requested, there were only two available. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The activity response format is detailed here.

Get an Extension Endpoint Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities/7dad5e6f-7230-11e7-a5a3-fd11e045be24"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities/7dad5e6f-7230-11e7-a5a3-fd11e045be24" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities/7dad5e6f-7230-11e7-a5a3-fd11e045be24"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    activity = requests.get(url, headers=headers).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "value": null,
  "createdAt": "2017-07-26T18:30:25.060Z",
  "type": "recipient-group-update",
  "state": "complete",
  "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
  "endpointId": "28a92caf-3d37-11e6-834a-431f5104df9d",
  "id": "7dad5e6f-7230-11e7-a5a3-fd11e045be24",
  "referenceType": "device-group",
  "severity": "info",
  "referenceId": "f7f6353f-3654-11e7-a84b-8fdfa583129f"
}

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

HTTP Request

GET /extensions/{extensionId}/endpoints/{endpointId}/activitites/{activityId}

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension of interest.
endpointId The id of the Endpoint of interest.
activityId The id endpoint activity.

Response

The extension endpoint activity response format is detailed here.

Create an Extension Endpoint Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'severity': 'info'
,
    'state': 'pending'
,
    'type': 'backup'

}

begin: 
    activity = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"severity": "info", \
       "state": "pending", \
       "type": "backup"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'severity': 'info',
    'state': 'pending',
    'type': 'backup'
}

try: 
    activity = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "value": null,
  "createdAt": "2017-07-26T19:58:53.982Z",
  "type": "backup",
  "state": "pending",
  "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
  "endpointId": "28a92caf-3d37-11e6-834a-431f5104df9d",
  "id": "da0a9443-723c-11e7-a5a3-c16694f3a822",
  "referenceType": null,
  "severity": "info",
  "referenceId": null
}

Add a new endpoint activity. Only certain types (backup and reboot requests) may be created. The severity must always be set to info, and the state must always be set to pending. The type can either be restart or backup, which request that the specified Fusion server restart itself or perform a backup, respectively.

HTTP Request

POST /extensions/{extensionId}/endpoints/{endpointId}/activities

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension of interest.
endpointId The id of the Endpoint of interest.

Request Parameters

Parameter Type Default Description
severity String N/A Options: info.
state String N/A Options: pending.
type String N/A Options: restart, backup. If you want to back up or restart a Fusion server, use these activity types.

Response

The extension endpoint activity response format is detailed here.

Endpoint Activity Response

The JSON document used to represent an endpoint activity resource has the following content:

Attribute Type Description
permissions Array[String] Options: get put. What operations are possible on this activity resource itself.
createdAt ISO 8601 date/time When this activity was created.
value Object A value describing the result of the activity. Can be any object, but usually describes a failure.
type String Options: recipient-group-delete, recipient-group-create, recipient-group-update, recipient-group-sync, recipient-group-dependency-sync, message-delete, message-skipped, message-create, message-update, message-sync, message-dependency-sync, scheduled-broadcast-create, scheduled-broadcast-update, scheduled-broadcast-delete, scheduled-broadcast-sync, scheduled-broadcast-skipped, broadcast-pending, broadcast-complete, broadcast-failed, syncer-startup, log-message, phone-cache-update, restart, backup. The activity type.
state String Options: pending, fail, success. Primarily of interest in determining whether the activity is still in progress or has completed.
reference­Type String Options: message-template, distribution-list, scheduled-notifications. What type of resource the activity is for.
severity String Options: debug, info, warn, error. How severe the log entry should be considered.
extensionId String The extension id.
endpointId String The extension endpoint id.
id String The id of the extension endpoint activity.

Extension Endpoint Mappings

Currently, fusion server dependency mappings are only generated by Singlewire to describe relationships between cloud and fusion server entities. You can request the list of mappings with GET /extensions/{extensionId}/mappings and you can get a specific one via a GET /extensions/{extensionId}/mappings/{mappingId}. At the moment, this is no real value to calling these APIs so the documentation is limited.

Extension Endpoint Proxy

Extensions endpoints may choose to expose their own, custom APIs. Currently, only the Fusion extension exposes an API. The example to the right shows how one may communicate directly with a Fusion server by requesting to list the CUCM Clusters.

Making an Endpoint Request

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/proxy/proxy/V1/Admin/Telephony/cucmClusters"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'sync': true
,
    'limit': 1

}

begin: 
    clusters = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(clusters)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/proxy/proxy/V1/Admin/Telephony/cucmClusters?sync=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/proxy/proxy/V1/Admin/Telephony/cucmClusters"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'sync': true,
    'limit': 1
}

try: 
    clusters = requests.get(url, headers=headers, params=params).json()
    print(clusters)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "next": null,
  "previous": null,
  "data": [{
    "id": 55,
    "clusterName": "Default configuration",
    "cmAddress": "172.30.228.98",
    "primary": true,
    "index": 0,
    "permissions": ["get", "put", "delete"]
  }, {
    "id": 388382,
    "clusterName": "BulkPhones",
    "cmAddress": "172.30.228.110",
    "primary": false,
    "index": 1,
    "permissions": ["get", "put", "delete"]
  }]
}

HTTP Request

ANY /extensions/{extensionId}/endpoints/{endpointId}/proxy/{path}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension being altered.
endpointId The id of the extension endpoint being altered.
path The api path of the resource you wish to request

Request Parameters

Response

Extension Endpoint Uploads

Currently, Fusion server backups are uploaded to this resource. The upload can only be performed by the Fusion server itself. You can request the list of uploads with GET /extensions/{extensionId}/uploads and you can download a specific one via a GET /extensions/{extensionId}/uploads/{uploadId}. At the moment, there is no need for anything other than a Fusion server to call these APIs so the documentation is limited.

Extension Endpoint Devices

Lists the devices managed by a particular endpoint. Currently only Fusion servers can manage devices, so this resource can only be queried.

List All Endpoint Devices

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 3

}

begin: 
    devices = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(devices)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/devices?limit=3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 3
}

try: 
    devices = requests.get(url, headers=headers, params=params).json()
    print(devices)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [{
    "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
    "deviceIdentifier": "CiscoPhone-388382:SEP001D45E95D12",
    "permissions": ["delete", "put", "get"],
    "createdAt": "2017-06-07T16:13:18.053Z",
    "type": "phones",
    "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
    "endpointId": "28a92caf-3d37-11e6-834a-431f5104df9d",
    "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
    "attributes": {
      "EndUserIdentifier": "jim.bob@acme.com",
      "CallManagerDevicePool": "Default",
      "CallManagerClusterName": "BulkPhones",
      "DirectoryNumbers": "[]",
      "Name": "SEP001D45E95D12",
      "CallManagerDeviceType": "336",
      "InformaCastDeviceType": "CiscoIPPhone",
      "Description": "12002",
      "IPAddress": "172.20.127.86",
      "InformaCast4StyleRegExTarget": "name=SEP001D45E95D12\ndesc=12002\ncss=pnp system test\npool=Default\naddr=172.20.127.86\ntype=336",
      "Location": "Hub_None",
      "CallManagerCSS": "pnp system test",
      "PartitionNames": "[]",
      "HasDisplay": "true"
    },
    "defunct": false
  }]
}

Retrieves a list of all endpoint 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 /extensions/{extensionId}/endpoints/{endpointId}/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 three extensions 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 an Extension Endpoint Device

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    device = JSON.parse(HTTParty.get(url, headers: headers))
    puts(device)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/28a92caf-3d37-11e6-834a-431f5104df9d/devices/37c1fe0a-4b9c-11e7-8148-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    device = requests.get(url, headers=headers).json()
    print(device)
except RequestException as e:
    print('Unexpected error!', e)
{
  "description": "Cisco IP Phone: 12002; DNs: ; SEP001D45E95D12",
  "deviceIdentifier": "CiscoPhone-388382:SEP001D45E95D12",
  "permissions": ["delete", "put", "get"],
  "createdAt": "2017-06-07T16:13:18.053Z",
  "type": "phones",
  "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
  "endpointId": "28a92caf-3d37-11e6-834a-431f5104df9d",
  "id": "37c1fe0a-4b9c-11e7-8148-0242ac110002",
  "attributes": {
    "EndUserIdentifier": "jim.bob@acme.com",
    "CallManagerDevicePool": "Default",
    "CallManagerClusterName": "BulkPhones",
    "DirectoryNumbers": "[]",
    "Name": "SEP001D45E95D12",
    "CallManagerDeviceType": "336",
    "InformaCastDeviceType": "CiscoIPPhone",
    "Description": "12002",
    "IPAddress": "172.20.127.86",
    "InformaCast4StyleRegExTarget": "name=SEP001D45E95D12\ndesc=12002\ncss=pnp system test\npool=Default\naddr=172.20.127.86\ntype=336",
    "Location": "Hub_None",
    "CallManagerCSS": "pnp system test",
    "PartitionNames": "[]",
    "HasDisplay": "true"
  },
  "defunct": false
}

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

HTTP Request

GET /extensions/{extensionId}/endpoints/{endpointId}/devices/{deviceId}

Produces

application/json

Path Parameters

Parameter Description
extensionId The id of the Extension of interest.
endpointId The id of the Extension of interest.
deviceId The id endpoint device.

Response

The extension endpoint device response format is detailed here.

Endpoint Device Response

The JSON document used to represent an endpoint 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.
extensionId String The id of the extension.
endpointId String The id of the extension endpoint.
createdAt ISO 8601 date/time When this activity was created.
type String Options: phones, speakers, plugins, idns
device­Identifier String The identifier 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).
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.

Failover Pairs

Allows a fusion server to failover to another server when it goes down.

Get all Failover Pairs

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/failover-pairs?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "previous" : null,
  "next" : null,
  "partial" : false,
  "data" : [ {
    "backupEndpointId" : "0f6a540d-f036-11ed-9aaf-c1a3f1a9f26a",
    "updatedAt" : "2023-05-11T19:57:29.718Z",
    "permissions" : [ "put", "delete", "get" ],
    "name" : "Test",
    "backupEndpoint" : {
      "id" : "0f6a540d-f036-11ed-9aaf-c1a3f1a9f26a",
      "name" : "endpoint-2"
    },
    "createdAt" : "2023-05-11T19:57:29.707Z",
    "primaryEndpoint" : {
      "id" : "0f6068fa-f036-11ed-9aaf-171ef9ba8bfb",
      "name" : "endpoint"
    },
    "id" : "0f7c7c83-f036-11ed-9aaf-73cbd35ad87b",
    "primaryEndpointId" : "0f6068fa-f036-11ed-9aaf-171ef9ba8bfb",
    "timeout" : 30
  } ],
  "total" : 1
}

Gets a list of all failover pairs 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 /failover-pairs

Produces

application/json

Query Parameters

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

Response

The Failover pair response format is detailed here

Get One Failover Pair

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs/df611894-474f-4920-9d0e-8420a6004a26"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    failover_pair = JSON.parse(HTTParty.get(url, headers: headers))
    puts(failover_pair)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/failover-pairs/df611894-474f-4920-9d0e-8420a6004a26" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs/df611894-474f-4920-9d0e-8420a6004a26"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    failover_pair = requests.get(url, headers=headers).json()
    print(failover_pair)
except RequestException as e:
    print('Unexpected error!', e)
{
  "backupEndpointId" : "6d0445fd-f036-11ed-9aaf-e33b624157ca",
  "updatedAt" : "2023-05-11T20:00:06.741Z",
  "permissions" : [ "put", "delete", "get" ],
  "name" : "Test",
  "backupEndpoint" : {
    "id" : "6d0445fd-f036-11ed-9aaf-e33b624157ca",
    "name" : "endpoint-2"
  },
  "createdAt" : "2023-05-11T20:00:06.729Z",
  "primaryEndpoint" : {
    "id" : "6cfa33da-f036-11ed-9aaf-c54d5f604a8b",
    "name" : "endpoint"
  },
  "id" : "6d142483-f036-11ed-9aaf-db8aaf45bf4b",
  "primaryEndpointId" : "6cfa33da-f036-11ed-9aaf-c54d5f604a8b",
  "timeout" : 30
}

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

HTTP Request

GET /failover-pairs/{failoverPairId}

Produces

application/json

Path Parameters

Parameter Description
failoverPairId The id of the failover pair to retrieve.

Response

The Failover pair response format is detailed here

Create a Failover Pair

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Example Failover Pair'
,
    'primaryEndpointid': '01e68454-1cd1-477b-b612-37bf210e889b'
,
    'backupEndpointId': '4e30e10c-4c2c-4ee5-a0ad-e82eb4576d52'
,
    'timeout': 100

}

begin: 
    failover_pair = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(failover_pair)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/failover-pairs" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Failover Pair", \
       "primaryEndpointid": "01e68454-1cd1-477b-b612-37bf210e889b", \
       "backupEndpointId": "4e30e10c-4c2c-4ee5-a0ad-e82eb4576d52", \
       "timeout": 100}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Example Failover Pair',
    'primaryEndpointid': '01e68454-1cd1-477b-b612-37bf210e889b',
    'backupEndpointId': '4e30e10c-4c2c-4ee5-a0ad-e82eb4576d52',
    'timeout': 100
}

try: 
    failover_pair = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(failover_pair)
except RequestException as e:
    print('Unexpected error!', e)
{
  "backupEndpointId" : "6d0445fd-f036-11ed-9aaf-e33b624157ca",
  "updatedAt" : "2023-05-11T20:00:06.741Z",
  "permissions" : [ "put", "delete", "get" ],
  "name" : "Test",
  "backupEndpoint" : {
    "id" : "6d0445fd-f036-11ed-9aaf-e33b624157ca",
    "name" : "endpoint-2"
  },
  "createdAt" : "2023-05-11T20:00:06.729Z",
  "primaryEndpoint" : {
    "id" : "6cfa33da-f036-11ed-9aaf-c54d5f604a8b",
    "name" : "endpoint"
  },
  "id" : "6d142483-f036-11ed-9aaf-db8aaf45bf4b",
  "primaryEndpointId" : "6cfa33da-f036-11ed-9aaf-c54d5f604a8b",
  "timeout" : 30
}

Creates a new Failover Pair

HTTP Request

POST /failover-pairs

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 to new failover pair. May be up to 140 characters long
priamryEndpointId String N/A The id of the endpoint that will be the primary
backupendpointid String N/A The id of the endpoint that will be the backup
timeout Number 30 How long in seconds the backup endpoint should wait before coming active after primary endpoint disconnect

Response

The Failover pair response format is detailed here

Update a Failover Pair

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs/05cc87fe-e02a-4fd2-a4fe-72e872cd2ac6"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Example Failover Pair'
,
    'primaryEndpointid': '01e68454-1cd1-477b-b612-37bf210e889b'
,
    'backupEndpointId': '4e30e10c-4c2c-4ee5-a0ad-e82eb4576d52'
,
    'timeout': 100

}

begin: 
    failover_pair = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(failover_pair)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/failover-pairs/05cc87fe-e02a-4fd2-a4fe-72e872cd2ac6" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Failover Pair", \
       "primaryEndpointid": "01e68454-1cd1-477b-b612-37bf210e889b", \
       "backupEndpointId": "4e30e10c-4c2c-4ee5-a0ad-e82eb4576d52", \
       "timeout": 100}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs/05cc87fe-e02a-4fd2-a4fe-72e872cd2ac6"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Example Failover Pair',
    'primaryEndpointid': '01e68454-1cd1-477b-b612-37bf210e889b',
    'backupEndpointId': '4e30e10c-4c2c-4ee5-a0ad-e82eb4576d52',
    'timeout': 100
}

try: 
    failover_pair = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(failover_pair)
except RequestException as e:
    print('Unexpected error!', e)
{
  "backupEndpointId" : "b9480b10-f036-11ed-9aaf-0395ef82ec2f",
  "updatedAt" : "2023-05-11T20:02:14.731Z",
  "permissions" : [ "put", "delete", "get" ],
  "name" : "Best",
  "backupEndpoint" : {
    "id" : "b9480b10-f036-11ed-9aaf-0395ef82ec2f",
    "name" : "endpoint-3"
  },
  "createdAt" : "2023-05-11T20:02:14.627Z",
  "primaryEndpoint" : {
    "id" : "b936a5ea-f036-11ed-9aaf-67d6fd2d5b9c",
    "name" : "endpoint"
  },
  "id" : "b94fd343-f036-11ed-9aaf-f9c6798deaa4",
  "primaryEndpointId" : "b936a5ea-f036-11ed-9aaf-67d6fd2d5b9c",
  "timeout" : 45
}

Updates an existing Failover Pair. Note: If the backup endpoint of the failover pair is changed, the previous backup endpoint will undergo a factory reset when the failover pair is updated. This is done to avoid unexpected behavior that may occur when a failover backup becomes a standalone or failover primary server

HTTP Request

PUT /failover-pairs/{failoverPairId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
failoverPairId The id of the failover pair to update.

Request Parameters

Parameter Type Default Description
name String N/A The name to give to new failover pair. May be up to 140 characters long
priamryEndpointId String N/A The id of the endpoint that will be the primary
backupendpointid String N/A The id of the endpoint that will be the backup
timeout Number 30 How long in seconds the backup endpoint should wait before coming active after primary endpoint disconnect

Response

The Failover pair response format is detailed here

Delete a Failover Pair

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs/05cc87fe-e02a-4fd2-a4fe-72e872cd2ac6"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/failover-pairs/05cc87fe-e02a-4fd2-a4fe-72e872cd2ac6" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/failover-pairs/05cc87fe-e02a-4fd2-a4fe-72e872cd2ac6"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status" : 200,
  "message" : "success",
  "resources" : [ {
    "id" : "de17df33-f036-11ed-9aaf-dd562849fbdd",
    "name" : "Test"
  } ]
}

Delete an existing Failover Pair. Note: The backup endpoint of the failover pair will undergo a factory reset when the failover pair is deleted. This is done to avoid unexpected behavior that may occur when a failover backup becomes a standalone or failover primary server

HTTP Request

DELETE /failover-pairs/{failoverPairId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
failoverPairId The id of the failover pair to update.

Response

The Failover pair response format is detailed here

Failover Pair Response Format

Attribute Type Description
createdAt ISO 8601 date/time When this failover pair was created
updatedAt ISO 8601 date/time When this failover pair was last updated
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
id String The id of this specific failover pair, allowing it to be manipulated or retrieved individually
name String Name of the failover pair
primaryEndpointId String Id of the primary endpoint
backupPrimaryEndpointId String Id of the backup endpoint
timeout Number How long in seconds the backup endpoint should wait before coming active after primary endpoint disconnect
primaryEndpoint Object Additional info about the endpoint configured as the primary
backupEndpoint Object Additional info about the endpoint configured as the backup

Endpoint Object

JSON document representing additional details about the primary and backup endpoints

Attribute Type Description
id String Id of this endpoint
name String Name of this endpoint

Features

Provides information about the current available feature set for the logged in user.

Get available features

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/features" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "features": [
    {
      "name": "feature-a",
      "enabled": false
    },
    {
      "name": "feature-b",
      "enabled": true,
      "variant": 5
    },
    {
      "name": "feature-c",
      "enabled": true,
      "variant": {
        "json": "variant"
      }
    }
  ]
}

Retrieves the available features list.

HTTP Request

GET /features

Produces

application/json

Response

Attribute Type Description
features Array A list of features that are enabled.

Features object

Attribute Type Description
name String The name of the feature
enabled Boolean Whether the feature is enabled for this user
variant JSON Optional; The variant value of the feature if one exists

Fusion Resources

Fusion Only

To use the Mobile REST API (also referred to simply as the RestAPI) to access Fusion Server configuration information or to call Fusion Server API targets from the the Mobile REST API, there are several pieces of information we need to use to construct those calls.

Bearer Token

As the Fusion Server itself is not accessible externally (except through the Fusion Syncer mechanism), we must use the Fusion proxy extension to pass those requests through to the Fusion Server API.

An API call to a Fusion Server’s API is similar to calling endpoints in the Mobile API, in that it also requires a bearer token authentication header (as do other Mobile API calls), but in addition, we must specify the extensionId, endpointId, and API path to the Fusion Server API target.

Here’s an example request URL: https://api.icmobile.singlewire.com/api/v1/extensions/{endpoint-proxy extensionId}/endpoints/{Fusion Server endpointId}/proxy/proxy/{Fusion Server API target path}

Endpoint-Proxy Extension ID

To find the endpoint-proxy extension id, call the following endpoint: GETextensions?type=endpoint-proxy&name=InformaCast, the response should look contain the information in the right column:

 "name": "InformaCast",
 "deviceLimit": 3,
 "createdAt": "2016-06-28T13:43:44.693Z",
 "type": "endpoint-proxy",
 "failureCode": null,
 "proxyUrl": "http://localhost:8080/fusion/{provider-id}/{endpoint-id}",
 "id": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
 "deviceType": null

Note the id field, which will always be the endpoint-proxy extensionId (551de6ae-3d36-11e6-834a-3d1fcb19aadd) in our fusion-specific proxy requests.

Finding the Fusion Server EndpointId

The next step is to determine the endpointId for the Fusion Server we want to access. You can see a list of which endpoints are available using the following call, where NameOfFusionServer is the name you assigned to your Fusion Server when it was added on the Admin -> Servers/List Servers page:

GET extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/?name={NameOfFusionServer}

The response will then include the endpointId of the Fusion Server (see response info at right):

{
  ...
  "config": null,
  "name": "ICOP Server",
  "createdAt": "2018-05-14T18:47:30.748Z",
  "extensionId": "551de6ae-3d36-11e6-834a-3d1fcb19aadd",
  ...
  "healthy": true,
  "id": "41a7f094-57a7-11e8-b511-1b4b03640c60"
}

Note, the id listed is unique to every Fusion Server, so it is important to check the name field to ensure this is the Fusion Server you intend to interact with.

Construct the Full Request

Now, by replacing {Fusion Server endpointId}, with the appropriate value, we can make API proxy requests to the Fusion Server, such as the following:

GET https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/overview?sync=true

The rest of the URL after proxy/proxy (that is not a typo) is the same as those endpoints listed in the InformaCast Advanced API Documentation, though not all endpoints are available via Mobile proxy calls.

Fusion Server Configuration Resources

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialCast/dialingConfigurations"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'dialingPatternRegEx': '1357'
,
    'authType': 0
,
    'messageId': 867
,
    'messageDescription': null
,
    'recipientGroups': [961
, 6678
]
,
    'recipientGroupName': ''
,
    'dialcodes': ['123'
]
,
    'dns': ['12'
, '13'
]
,
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialCast/dialingConfigurations?sync=true" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"dialingPatternRegEx": "1357", \
       "authType": 0, \
       "messageId": 867, \
       "messageDescription": null, \
       "recipientGroups": [961, 6678], \
       "recipientGroupName": "", \
       "dialcodes": ["123"], \
       "dns": ["12", "13"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Admin/DialCast/dialingConfigurations"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'dialingPatternRegEx': '1357',
    'authType': 0,
    'messageId': 867,
    'messageDescription': null,
    'recipientGroups': [961, 6678],
    'recipientGroupName': '',
    'dialcodes': ['123'],
    'dns': ['12', '13'],
    'sync': true
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": 14267,
  "dialingPatternRegEx": "1357",
  "authType": 0,
  "messageId": 867,
  "messageJson": {
    "description": "Example Humoctopus Alert",
    "id": 867
  },
  "messageDescription": null,
  "recipientGroups": [6678,961],
  "recipientGroupsJson": [
    {
      "name": "Recipient Group 1",
      "id": 6678
    },
    {
      "name": "Recipient Group 2",
      "id": 961
    }
  ],
  "recipientGroupName": "",
  "dialcodes": ["123"],
  "dns": ["13","12"]
}

All fusion server configuration resources can be found in the InformaCast Advanced API Documentation. If a resources listed in the documentation is not available to Fusion via Mobile proxy calls, a “resource not available” response will be returned.

Each resource will follow the general URL structure listed in the sections above, using the appropriate extensions and endpoints parameters.

An example configuration resource request here is the Dialcast Dialing Configuration. To create a Dialcast dialing configuration, use the 'POST /V1/Admin/DialCast/dialingConfigurations’ resource, making an API proxy request to the Fusion Server shown here on the right.

Generic Multicast Streaming

Fusion Only

Generic Multicast Streaming allows endpoints to be created that broadcast audio over a multicast IP and port so that Cloud/Other IP Phones can receive audio broadcasts. Formats currently supported include Generic multicast and Polycom-formatted multicast.

List Generic Multicast Streams

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast?sync=true&limit=10" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "next": null,
  "previous": null,
  "total": 2,
  "data": [
    {
      "index": 0,
      "id": "d4e7e88b-f05a-46d8-abd1-e04f6377578d",
      "name": "Polycom Devices",
      "address": "224.0.1.116",
      "port": 5000,
      "channel": 1,
      "type": "polycom",
      "conflicts": [],
      "permissions": [
        "get",
        "put",
        "delete"
      ]
    },
    {
      "index": 1,
      "id": "14971fea-b042-49f7-9332-246ecfde7268",
      "name": "Yealink, Algo, Cisco MPP devices",
      "address": "224.0.1.117",
      "port": 5002,
      "type": "generic",
      "conflicts": [],
      "permissions": [
        "get",
        "put",
        "delete"
      ]
    }
  ],
  "partial": false
}

Retrieves the list of all configured Multicast Streams.

The listed resources are available in the data attribute of the response. For more information, click here

HTTP Request

GET /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Plugins/GenericMulticast

Produces

application/json

Query Parameters

Results can be retrieved in groups using the API’s pagination parameters. There were a total of 2 multicast streams when the request was made. The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can filter requests using the Multicast Stream name as a query parameters:

Parameter Type Description
name String Returns only multicast streams whose names exactly match the supplied value

Response

The Generic/Polycom Multicast Stream response formats are detailed here and here.

Get a Multicast Stream

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/d4e7e88b-f05a-46d8-abd1-e04f6377578d?sync=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "d4e7e88b-f05a-46d8-abd1-e04f6377578d",
  "name": "Polycom Devices",
  "address": "224.0.1.116",
  "port": 5000,
  "channel": 1,
  "type": "polycom",
  "conflicts": [],
  "permissions": [
      "get",
      "put",
      "delete"
  ]
}

Retrieves a single Multicast Stream by id (either generic or polycom types). 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/Plugins/GenericMulticast/{id}

Produces

application/json

Path Parameters

Parameter Description
id The id of the Multicast Stream to retrieve.

Response

The Generic/Polycom Multicast Stream response formats are detailed here and here, respectively.

Create a Generic Multicast Stream

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/generic"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Yealink, Algo, Cisco MPP devices'
,
    'address': '224.0.1.117'
,
    'port': 5002
,
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/generic?sync=true" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Yealink, Algo, Cisco MPP devices", \
       "address": "224.0.1.117", \
       "port": 5002}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/generic"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Yealink, Algo, Cisco MPP devices',
    'address': '224.0.1.117',
    'port': 5002,
    'sync': true
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "14971fea-b042-49f7-9332-246ecfde7268",
  "name": "Yealink, Algo, Cisco MPP devices",
  "address": "224.0.1.117",
  "port": 5002,
  "conflicts": [],
  "link": "https://172.20.146.37:8444/InformaCast/RESTServices/V1/Plugins/GenericMulticast/14971fea-b042-49f7-9332-246ecfde7268",
  "type": "generic"
}

Create a new Generic Multicast Stream.

HTTP Request

POST /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Plugins/GenericMulticast/generic

Consumes

application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A Name of the Generic Multicast Stream
address String N/A Multicast address over which to send audio (multicast range 224.0.0.0-239.255.255.255)
port int N/A Multicast port over which to send audio (1-65535)

Response

The Generic Multicast Stream response format is detailed here.

Create a Polycom Multicast Stream

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/polycom"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Polycom Devices'
,
    'address': '224.0.1.116'
,
    'port': 5000
,
    'channel': 1
,
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/polycom?sync=true" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Polycom Devices", \
       "address": "224.0.1.116", \
       "port": 5000, \
       "channel": 1}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/polycom"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Polycom Devices',
    'address': '224.0.1.116',
    'port': 5000,
    'channel': 1,
    'sync': true
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "d4e7e88b-f05a-46d8-abd1-e04f6377578d",
    "name": "Polycom Devices",
    "address": "224.0.1.116",
    "port": 5000,
    "conflicts": [],
    "channel": 1,
    "type": "polycom"
}

Create a new Polycom Multicast Stream.

HTTP Request

POST /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Plugins/GenericMulticast/polycom

Consumes

application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A Name of the Generic Multicast Stream
address String N/A Multicast address over which to send audio (multicast range 224.0.0.0-239.255.255.255)
port int N/A Multicast port over which to send audio (1-65535)
channel int 1 Polycom PTT/paging channel (1-50)

Response

The Polycom Multicast Stream response format is detailed here.

Update a Generic Multicast Stream

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/generic//14971fea-b042-49f7-9332-246ecfde7268"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Weyland-Yutani'
,
    'address': '224.0.0.121'
,
    'port': 2
,
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/generic//14971fea-b042-49f7-9332-246ecfde7268?sync=true" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weyland-Yutani", \
       "address": "224.0.0.121", \
       "port": 2}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/generic//14971fea-b042-49f7-9332-246ecfde7268"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Weyland-Yutani',
    'address': '224.0.0.121',
    'port': 2,
    'sync': true
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "14971fea-b042-49f7-9332-246ecfde7268",
  "name": "Weyland-Yutani",
  "address": "224.0.0.121",
  "port": 2,
  "conflicts": [],
  "type": "generic"
}

Updates an existing Generic Multicast Stream

For polycom type streams, the Edit Polycom target must be used.

HTTP Request

PUT /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Plugins/GenericMulticast/generic/{id}

Consumes

application/json

Produces

application/json

Path Parameters

Parameter Description
id The id Generic Multicast Stream to update.

Request Parameters

Parameter Type Description
name String Name of the Generic Multicast Stream
address String Multicast address over which to send audio (multicast range 224.0.0.0-239.255.255.255)
port int Multicast port over which to send audio (1-65535)

Response

The Generic Multicast Stream response format is detailed here.

Update a Polycom Multicast Stream

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/polycom//d4e7e88b-f05a-46d8-abd1-e04f6377578d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Nakatomi'
,
    'address': '224.12.19.88'
,
    'channel': 35
,
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/polycom//d4e7e88b-f05a-46d8-abd1-e04f6377578d?sync=true" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nakatomi", \
       "address": "224.12.19.88", \
       "channel": 35}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/polycom//d4e7e88b-f05a-46d8-abd1-e04f6377578d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Nakatomi',
    'address': '224.12.19.88',
    'channel': 35,
    'sync': true
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "d4e7e88b-f05a-46d8-abd1-e04f6377578d",
  "name": "Nakatomi",
  "address": "224.12.19.88",
  "port": 5000,
  "channel": 35,
  "conflicts": [],
  "link": "https://172.20.146.37:8444/InformaCast/RESTServices/V1/Plugins/GenericMulticast/d4e7e88b-f05a-46d8-abd1-e04f6377578d",
  "type": "polycom"
}

Updates an existing Polycom Multicast Stream

For generic type streams, the Edit Generic target must be used.

HTTP Request

PUT /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Plugins/GenericMulticast/polycom/{id}

Consumes

application/json

Produces

application/json

Path Parameters

Parameter Description
id The id Polycom Multicast Stream to update.

Request Parameters

Parameter Type Description
name String Name of the Polycom Multicast Stream
address String Multicast address over which to send audio (multicast range 224.0.0.0-239.255.255.255)
port int Multicast port over which to send audio (1-65535)
channel int Polycom PTT/paging channel (1-50)

Response

The Polycom Multicast Stream response format is detailed here.

Remove a Multicast Stream

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast//14971fea-b042-49f7-9332-246ecfde7268"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'sync': true

}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast//14971fea-b042-49f7-9332-246ecfde7268?sync=true" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast//14971fea-b042-49f7-9332-246ecfde7268"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'sync': true
}

try: 
    print(requests.delete(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted  14971fea-b042-49f7-9332-246ecfde7268"
}

Deletes an existing Multicast Stream.

HTTP Request

DELETE /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Plugins/GenericMulticast/{id}

Produces

application/json

Path Parameters

Parameter Description
id The id of the Multicast Stream to delete

Response

The deletion response format is detailed here.

List Active Streams

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/41a7f094-57a7-11e8-b511-1b4b03640c60/proxy/proxy/V1/Plugins/GenericMulticast/activeStreams?sync=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
[
  {
    "address": {
      "value": "224.0.1.116"
    },
    "port": {
      "value": 5000
    },
    "name": {
      "value": "Polycom Devices"
    },
    "conflicts": [],
    "broadcasts": [
      {
        "serialNumber": 2,
        "audioFile": "/web/WEB-INF/uploads/pfx6821225162089750812sfx",
        "audioFormat": "ULAW 8000.0 Hz, 8 bit, mono, 1 bytes/frame, ",
        "isNonUrgent": true,
        "messagePriority": 2,
        "messageVolume": "As-Is",
        "interrupt": true,
        "preTone": null,
        "postTone": null,
        "remoteAddress": "239.0.1.2",
        "remotePort": 20482,
        "timeInitiated": "2018-11-08T23:09:09.049Z"
      }
    ]
  }
]

Retrieves the list of all (currently) active streams.

HTTP Request

GET /extensions/551de6ae-3d36-11e6-834a-3d1fcb19aadd/endpoints/{endpointId}/proxy/proxy/V1/Plugins/GenericMulticast/activeStreams

Produces

application/json

Response

Attribute Type Description
name String The name of the Generic Multicast Stream
address String Multicast address over which to send audio
port int Multicast port over which to send audio
conflicts Array[String] Any conflicts that exist for the multicast address assigned to this stream
broadcasts Array[(#broadcast-object-response)] A list of broadcasts being sent over that Multicast Stream

Broadcast Object Response

The JSON document used to represent an ongoing audio stream

Attribute Type Description
serialNumber int A unique id to index this broadcast
audioFile String If this is a pre-recorded audio, the filename that is the audio source
audioFormat String Description of audio source parameters
isNonUrgent boolean Synchronized (true) or As-Available (false)
messagePriority int Numerical message priority setting
messageVolume String Volume setting (Low, Medium, Maximum, As-Is)
interrupt boolean Skip Phones in Use (false) or not (true)
preTone String File name of Pre-Tone Audio
postTone String File name of Post-Tone Audio
remoteAddress Network multicast address in use
remotePort int Network multicast port in use
timeInitiated Time broadcast was started

Generic Multicast Stream Response

The JSON document used to represent a Generic Multicast Stream has the following content:

Attribute Type Description
id String The id assigned to this Generic Multicast Stream
name String The name of the Generic Multicast Stream
address String Multicast address over which to send audio
port int Multicast port over which to send audio
type String generic (always generic for generic Multicast Streams)
conflicts Array[String] Any conflicts that exist for the multicast address assigned to this stream

Polycom Multicast Stream Response

The JSON document used to represent a Polycom Multicast Stream has the following content:

Attribute Type Description
id String The id assigned to this Polycom Multicast Stream
name String The name of the Polycom Multicast Stream
address String Multicast address over which to send audio
port int Multicast port over which to send audio
channel int Polycom PTT/paging channel (1-50)
type String polycom (always polycom for Polycom Multicast Streams)
conflicts Array[String] Any conflicts that exist for the multicast address assigned to this stream

Activation Groups

Fusion Only

Activation Groups are named groups of Devices, and are the method of distributing these devices across Fusion servers.

Activation Groups are commonly composed of a set of filters that will match certain Devices, a target endpoint for those devices, and a priority of evaluation

Get All Activation Groups

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/activation-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "exclusionIds": [],
      "filterType": "AND",
      "additionIds": [],
      "additions": [],
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "filters": [
        {
          "value": "",
          "attribute": "Description",
          "comparison": "CONTAINS",
          "complement": false,
          "caseSensitive": false
        }
      ],
      "name": "Primary",
      "exclusions": [],
      "createdAt": "2019-07-16T19:03:56.287Z",
      "updatedAt": "2019-07-16T19:03:56.287Z",
      "deviceSummary": null,
      "endpoints": [
        {
          "name": "Headquarters",
          "id": "28a92caf-3d37-11e6-834a-431f5104df9d"
        }
      ],
      "priority": 1,
      "id": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0",
      "endpointIds": [
        "28a92caf-3d37-11e6-834a-431f5104df9d"
      ]
    }
  ]
}

Gets a list of all Activation 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 activation groups allows administrators to decide who may configure devices for fusion endpoints)

HTTP Request

GET /activation-groups

Produces

application/json

Query Parameters

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

Response

The Activation Group response format is detailed here.

Get One Activation Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/activation-groups/75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    group = JSON.parse(HTTParty.get(url, headers: headers))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/activation-groups/75e24102-a7fc-11e9-ad0a-6d25be5fdfe0" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/activation-groups/75e24102-a7fc-11e9-ad0a-6d25be5fdfe0"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    group = requests.get(url, headers=headers).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "exclusionIds": [],
  "filterType": "AND",
  "additionIds": [],
  "additions": [],
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "filters": [
    {
      "value": "",
      "attribute": "Description",
      "comparison": "CONTAINS",
      "complement": false,
      "caseSensitive": false
    }
  ],
  "name": "Primary",
  "exclusions": [],
  "createdAt": "2019-07-16T19:03:56.287Z",
  "updatedAt": "2019-07-16T19:03:56.287Z",
  "deviceSummary": null,
  "endpoints": [
    {
      "name": "Headquarters",
      "id": "28a92caf-3d37-11e6-834a-431f5104df9d"
    }
  ],
  "priority": 1,
  "id": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0",
  "endpointIds": [
    "28a92caf-3d37-11e6-834a-431f5104df9d"
  ]
}

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

HTTP Request

GET /activation-groups/{activationGroupId}

Produces

application/json

Path Parameters

Parameter Description
activationGroupId The id of the Activation Group to retrieve.

Response

The Activation Group response format is detailed here.

Create an Activation Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/activation-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'exclusionIds': []
,
    'filterType': 'OR'
,
    'additionIds': []
,
    'filters': [{
        'value': ''
,
        'attribute': 'Description'
,
        'comparison': 'CONTAINS'
,
        'complement': false
,
        'caseSensitive': false

}

]
,
    'name': 'Primary'
,
    'multicastPort': 2345
,
    'priority': 1
,
    'endpointIds': ['28a92caf-3d37-11e6-834a-431f5104df9d'
]
,
    'multicastAddress': '224.0.0.1'
,
    'multicastType': 'poly-ucs'

}

begin: 
    group = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/activation-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"exclusionIds": [], \
       "filterType": "OR", \
       "additionIds": [], \
       "filters": [{"value": "", \
         "attribute": "Description", \
         "comparison": "CONTAINS", \
         "complement": false, \
         "caseSensitive": false}], \
       "name": "Primary", \
       "multicastPort": 2345, \
       "priority": 1, \
       "endpointIds": ["28a92caf-3d37-11e6-834a-431f5104df9d"], \
       "multicastAddress": "224.0.0.1", \
       "multicastType": "poly-ucs"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/activation-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'exclusionIds': [],
    'filterType': 'OR',
    'additionIds': [],
    'filters': [{
        'value': '',
        'attribute': 'Description',
        'comparison': 'CONTAINS',
        'complement': false,
        'caseSensitive': false
}
],
    'name': 'Primary',
    'multicastPort': 2345,
    'priority': 1,
    'endpointIds': ['28a92caf-3d37-11e6-834a-431f5104df9d'],
    'multicastAddress': '224.0.0.1',
    'multicastType': 'poly-ucs'
}

try: 
    group = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "exclusionIds": [],
  "filterType": "AND",
  "additionIds": [],
  "additions": [],
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "filters": [
    {
      "value": "",
      "attribute": "Description",
      "comparison": "CONTAINS",
      "complement": false,
      "caseSensitive": false
    }
  ],
  "name": "Primary",
  "exclusions": [],
  "createdAt": "2019-07-16T19:03:56.287Z",
  "updatedAt": "2019-07-16T19:03:56.287Z",
  "deviceSummary": null,
  "endpoints": [
    {
      "name": "Headquarters",
      "id": "28a92caf-3d37-11e6-834a-431f5104df9d"
    }
  ],
  "priority": 1,
  "id": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0",
  "endpointIds": [
    "28a92caf-3d37-11e6-834a-431f5104df9d"
  ],
  "multicastType": "poly-ucs",
  "multicastAddress": "224.0.0.1",
  "multicastPort": 2345
}

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

HTTP Request

POST /activation-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 Activation Group. May be up to 140 characters long.
exclusionIds Array[String] N/A The specific device icop_ids that are excluded from the Activation Group regardless of filters and other Activation Groups. This is either a MAC Address (for speakers and idns) or the device identifier (for all other devices).
filterType String N/A Controls how the filters that define rules for dynamically determining the Devices in this Activation Group are combined (i.e. AND or OR, REJECT, ACCEPT, or LOGICAL_EXPRESSION).
additionIds Array[String] N/A The specific Device icop_ids that are in the Group regardless of filters and other Activation Groups. This is either a MAC Address (for speakers and idns) or the device identifier (for all other devices).
filters Array[Object] N/A Defines rules to dynamically determine the Devices in this Activation Group, combined as specified by filterType. The filters format is detailed here.
priority Integer N/A Unique ranking specifies the order in which activation groups are evaluated (lower number = higher priority). If a device falls in more than one group, the lower numbered priority wins.
endpointIds Array[UUID] N/A The endpoint(s) to which devices in this activation group should get sent.
multicastType String none Determines the type of multicast streaming the members of the group are expected to support. Valid types are:
none - for groups without multicast capable members.
poly-ucs - for grouping Poly© phones with UCS firmware.
gms - for grouping other multicast capable devices. The grouping of Poly® phones in activation groups is only available to customers who have linked their accounts to Polycom Device Management Service for Service Providers (PDMS-SP).
multicastAddress String N/A When multicastType is set to poly-ucs or gms, specifies the multicast address at which the multicast capable group members will be receiving audio notifications.
multicastPort String N/A When multicastType is set to poly-ucs or gms, specifies the port at which the multicast capable group members will be receiving audio notifications.

Response

The Activation Group response format is detailed here.

Update an Activation Group

# Continuing with the activation group object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/activation-groups/75e24102-a7fc-11e9-ad0a-6d25be5fdfe0" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"exclusionIds": [], \
       "filterType": "OR", \
       "additionIds": [], \
       "filters": [{"value": "", \
         "attribute": "Description", \
         "comparison": "CONTAINS", \
         "complement": false, \
         "caseSensitive": false}], \
       "name": "Primary", \
       "priority": 1, \
       "endpointIds": ["28a92caf-3d37-11e6-834a-431f5104df9d"]}'
# Continuing with the activation group object
# from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "exclusionIds": [],
  "filterType": "AND",
  "additionIds": [],
  "additions": [],
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "filters": [
    {
      "value": "",
      "attribute": "Description",
      "comparison": "CONTAINS",
      "complement": false,
      "caseSensitive": false
    }
  ],
  "name": "Primary",
  "exclusions": [],
  "createdAt": "2019-07-16T19:03:56.287Z",
  "updatedAt": "2020-08-17T20:01:23.834Z",
  "deviceSummary": null,
  "endpoints": [
    {
      "name": "Headquarters",
      "id": "28a92caf-3d37-11e6-834a-431f5104df9d"
    }
  ],
  "priority": 1,
  "id": "75e24102-a7fc-11e9-ad0a-6d25be5fdfe0",
  "endpointIds": [
    "28a92caf-3d37-11e6-834a-431f5104df9d"
  ],
  "multicastType": "poly-ucs",
  "multicastAddress": "224.0.0.1",
  "multicastPort": 2345
}

Modifies the details of the Activation Group.

HTTP Request

PUT /activation-groups/{activationGroupId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
activationGroupId The id of the activation group to update.

Request Parameters

Parameter Type Default Description
name String N/A The new name to give the Activation Group. May be up to 140 characters long.
exclusionIds Array[String] N/A The specific device icop_ids that are excluded from the Activation Group regardless of filters and other Activation Groups. This is either a MAC Address (for speakers and idns) or the device identifier (for all other devices).
filterType String N/A Controls how the filters that define rules for dynamically determining the Devices in this Activation Group are combined (i.e. AND or OR, REJECT, ACCEPT, or LOGICAL_EXPRESSION).
additionIds Array[String] N/A The specific Device icop_ids that are in the Group regardless of filters and other Activation Groups. This is either a MAC Address (for speakers and idns) or the device identifier (for all other devices).
filters Array[Object] N/A Defines rules to dynamically determine the Devices in this Activation Group, combined as specified by filterType. The filters format is detailed here.
priority Integer N/A Unique ranking specifies the order in which activation groups are evaluated (lower number = higher priority). If a device falls in more than one group, the lower numbered priority wins.
endpointIds Array[UUID] N/A The endpoint(s) to which devices in this activation group should get sent.
multicastType String none Determines the type of multicast streaming the members of the group are expected to support. Valid types are:
none - for groups without multicast capable members.
poly-ucs - for grouping Poly© phones with UCS firmware.
gms - for grouping other multicast capable devices.
multicastAddress String N/A When multicastType is set to poly-ucs or gms, specifies the multicast address at which the multicast capable group members will be receiving audio notifications.
multicastPort String N/A When multicastType is set to poly-ucs or gms, specifies the port at which the multicast capable group members will be receiving audio notifications.

Response

The Activation Group response format is detailed here.

Remove an Activation group

# Continuing with the activation group object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/activation-groups/3cf58710-2305-11e4-b544-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the activation group object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"ActivationGroups\"} 3cf58710-2305-11e4-b544-3c970e7ff560"
}

Removes an Activation Group, discarding its Device information.

HTTP Request

DELETE /activation-groups/{activationGroupId}

Produces

application/json

Path Parameters

Parameter Description
activationGroupId The id of the Activation Group to delete.

Response

The deletion response format is detailed here.

Activation Group Response

The JSON document used to represent an Activation Group resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this activation group was created.
updatedAt ISO 8601 date/time When this activation group was last updated.
id String The id of this specific activation group, allowing it to be manipulated or retrieved individually.
name String The activation 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.
exclusionIds Array[String] The specific device icop_ids that are excluded from this activation group regardless of filters and other activation groups. This is either a MAC Address (for speakers and idns) or the device identifier (for all other devices).
exclusions Array[Object] The specific devices that are excluded from this activation group regardless of filters and other activation groups.
filterType String Controls how the filters that define rules for dynamically determining the Devices in this activation group are combined (i.e. AND or OR, REJECT, ACCEPT, or LOGICAL_EXPRESSION).
additionIds Array[String] The specific device icop_ids that are in the Group regardless of filters and other Activation Groups. This is either a MAC Address (for speakers and idns) or the device identifier (for all other devices).
additions Array[Object] The specific devices that are in the group regardless of filters and other activation groups.
filters Array[Object] Defines rules to dynamically determine the Devices in this Activation Group, combined as specified by filterType. The filters format is detailed here.
priority Integer Unique ranking specifies the order in which activation groups are evaluated (lower number = higher priority). If a device falls in more than one group, the lower numbered priority wins.
endpointIds Array[UUID] The endpoint(s) to which devices in this activation group should get sent.
deviceSummary Object The current device counts. Only applicable query param include-device-counts is true.
multicastType String The type of multicast streaming that the group’s members are expected to support. Supported types are:
none - for groups without multicast capable members.
poly-ucs - for grouping Poly© phones with UCS firmware.
gms - for grouping other multicast capable devices.
multicastAddress String When multicastType is set to poly-ucs or gms, specifies the multicast address at which the multicast capable group members will be receiving audio notifications.
multicastPort String When multicastType is set to poly-ucs or gms, specifies the port at which the multicast capable group members will be receiving audio notifications.
usedChannels Array[Object] When multicastType is set to poly-ucs, contains the Group Paging Channels that have been allocated for this activation group. One channel is allocated when a device group gets associated with the activation group. The format of the elements of usedChannels is detailed here.

Activation Group Filters Format

The JSON document used to represent an Activation 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.

Used Channels Format

The elements of the usedChannels attribute of an Activation Group describe the Activation Group’s associations with existing Device Groups. Each Device Group associated with an Activation Group whose multicastType is set to poly-ucs also gets assigned a Polycom Group Paging Channel. This channel will be used for delivering audio notifications to the Device Group’s Poly© phones with UCS firmware.

Attribute Type Description
deviceGroupId String The ID of the device group
activationGroupId String The ID of the activation group
channel Number The Polycom Group Paging Channel assigned to the device group

Identity Providers

Identity Providers are used for User authentication when logging in to an InformaCast Mobile Provider. Each Provider can have one or more Identity Providers.

List All Identity Providers

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/idps?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "id": "7e6f92b7-1ac6-11eb-9cb3-e3cdd7e88402",
      "name": "Google IDP",
      "isDefault": true,
      "selfRegistrationEnabled": false,
      "type": "google",
      "enabled": true,
      "createdAt": "2020-10-30T15:42:19.202Z",
      "permissions": [
        "put",
        "delete",
        "get"
      ]
    },
  ]
}

Retrieves the list of Identity Providers.

HTTP Request

GET /idps

Produces

application/json

Query Parameters

As usual, the number of responses can be controlled using the API’s pagination parameters. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The Identity Provider response format is detailed here.

Get an Identity Provider

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/idps/7e6f92b7-1ac6-11eb-9cb3-e3cdd7e88402"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    idp = JSON.parse(HTTParty.get(url, headers: headers))
    puts(idp)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/idps/7e6f92b7-1ac6-11eb-9cb3-e3cdd7e88402" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/idps/7e6f92b7-1ac6-11eb-9cb3-e3cdd7e88402"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    idp = requests.get(url, headers=headers).json()
    print(idp)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "7e6f92b7-1ac6-11eb-9cb3-e3cdd7e88402",
  "name": "Google IDP",
  "isDefault": true,
  "selfRegistrationEnabled": false,
  "type": "google",
  "enabled": true,
  "createdAt": "2020-10-30T15:42:19.202Z",
  "permissions": [
    "put",
    "delete",
    "get"
  ]
},

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

HTTP Request

GET /idps/{idpId}

Produces

application/json

Path Parameters

Parameter Description
idpId The id of the Identity Provider of interest.

Response

The Identity Provider response format is detailed here.

Update an Identity Provider

# Continuing with the idp object from the previous
# example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/7e6f92b7-1ac6-11eb-9cb3-e3cdd7e88402" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Google IDP"}'
# Continuing with the idp object from the previous
# example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "7e6f92b7-1ac6-11eb-9cb3-e3cdd7e88402",
  "name": "My Google IDP",
  "isDefault": true,
  "selfRegistrationEnabled": false,
  "type": "google",
  "enabled": true,
  "createdAt": "2020-10-30T15:42:19.202Z",
  "permissions": [
    "put",
    "delete",
    "get"
  ]
},

Updates an existing Identity Provider.

HTTP Request

PUT /idps/{idpId}

Produces

application/json

Path Parameters

Parameter Description
idpId The id of the Identity Provider of interest.

Request Parameters

Parameter Type Default Description
name String Capitalized value of type The name of the Identity Provider.
isDefault Boolean false Whether this is the “default” Identity Provider. This means that Users with a providerIdpId value of NULL will use this Identity Provider for authentication.
selfRegistrationEnabled Boolean false Whether this Identity Provider can be used for user self-registration. Only a Cirrus IDP can have this value set to true.
type String N/A The Identity Provider type (e.g. "google", "azure", "cirrus-idp", "saml2", "google").
enabled Boolean true Whether this Identity Provider is currently enabled.

Response

The Identity Provider response format is detailed here.

Identity Provider Response

The JSON document used to represent an Identity Provider resource has the following content:

Attribute Type Description
id String The id of the Identity Provider.
name String The name of the Identity Provider.
isDefault Boolean Whether this is the “default” Identity Provider. This means that Users with a providerIdpId value of NULL will use this Identity Provider for authentication.
selfRegistrationEnabled Boolean Whether this Identity Provider can be used for user self-registration. Only a Cirrus IDP can have this value set to true.
type String The Identity Provider type (e.g. "google", "azure", "cirrus-idp", "saml2", "google").
enabled Boolean Whether this Identity Provider is currently enabled.
createdAt ISO 8601 date/time When this Identity Provider was created.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Inbound CAP

Inbound CAP rules (the CAP message trigger for Inbound Events) allow you to specify a Message Template used to create a Notification when a CAP message matches an expression.

List All Inbound CAP Rules

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "id": "15433821-2096-11e8-8d4d-532f6fd5bb3d",
   "name": "Amber Alert",
   "expression": "(\nareaContainsLatLon(43.0798, -89.5353)\n|| areaGeocodeUgcContains(\"WIZ063\")\n|| areaGeocodeFips6SAMEContains(\"55025\")\n)\n&&\n(\nalertTextContains(\"Amber Alert\")\n)\n&&\n(\ncategoryIsRescue()\n|| categoryIsSecurity()\n|| categoryIsSafety()\n)",
   "messageTemplateId": "937fb4a2-034b-11e7-8ab4-63081f5d59f0",
   "disabled": true,
   "createdAt": "2018-03-05T16:56:05.158Z",
   "languageCode": "EN",
   "permissions": [ "delete", "put", "get" ]
  },
  {
   "id": "73d183bf-2090-11e8-8d4d-89d85e85e1c0",
   "name": "Severe Weather",
   "expression": "(\nareaContainsLatLon(43.111, -89.3463)\n|| areaGeocodeUgcContains(\"WIZ063\")\n|| areaGeocodeFips6SAMEContains(\"55025\")\n)\n&&\n(\nalertTextContains(\"Severe Weather\")\n)\n&&\n(\ncategoryIsMet()\n)",
   "messageTemplateId": "939dc3f7-034b-11e7-8ab4-1b0e0c25b88e",
   "disabled": false,
   "createdAt": "2018-03-05T16:15:47.592Z",
   "languageCode": null,
   "permissions": [ "delete", "put", "get" ]
  }
 ]
}

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

HTTP Request

GET /inbound-cap-rules

Produces

application/json

Query Parameters

Results can be retrieved in groups using the API’s pagination parameters. There were a total of 2 rules available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Inbound CAP rules whose names exactly match the supplied value

Response

The Inbound CAP response format is detailed here.

Get an Inbound CAP Rule

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules/73d183bf-2090-11e8-8d4d-89d85e85e1c0"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    inbound = JSON.parse(HTTParty.get(url, headers: headers))
    puts(inbound)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules/73d183bf-2090-11e8-8d4d-89d85e85e1c0" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules/73d183bf-2090-11e8-8d4d-89d85e85e1c0"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    inbound = requests.get(url, headers=headers).json()
    print(inbound)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "73d183bf-2090-11e8-8d4d-89d85e85e1c0",
 "name": "Severe Weather",
 "expression": "(\nareaContainsLatLon(43.111, -89.3463)\n|| areaGeocodeUgcContains(\"WIZ063\")\n|| areaGeocodeFips6SAMEContains(\"55025\")\n)\n&&\n(\nalertTextContains(\"Severe Weather\")\n)\n&&\n(\ncategoryIsMet()\n)",
 "messageTemplateId": "939dc3f7-034b-11e7-8ab4-1b0e0c25b88e",
 "disabled": false,
 "createdAt": "2018-03-05T16:15:47.592Z",
 "languageCode": null,
 "permissions": [ "delete", "put", "get" ],
}

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

HTTP Request

GET /inbound-cap-rules/{icapRuleId}

Produces

application/json

Path Parameters

Parameter Description
icapRuleId The id of the Inbound Email rule to retrieve.

Response

The Inbound CAP rule format is detailed here.

Create an Inbound CAP Rule

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Severe Weather'
,
    'expression': '(
areaContainsLatLon(43.111, -89.3463)
|| areaGeocodeUgcContains("WIZ063")
|| areaGeocodeFips6SAMEContains("55025")
)
&&
(
alertTextContains("Severe Weather")
)
&&
(
categoryIsMet()
)'
,
    'messageTemplateId': '939dc3f7-034b-11e7-8ab4-1b0e0c25b88e'
,
    'languageCode': 'EN'
,
    'disabled': false

}

begin: 
    inbound = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(inbound)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Severe Weather", \
       "expression": "(
areaContainsLatLon(43.111, -89.3463)
|| areaGeocodeUgcContains(\"WIZ063\")
|| areaGeocodeFips6SAMEContains(\"55025\")
)
&&
(
alertTextContains(\"Severe Weather\")
)
&&
(
categoryIsMet()
)", \
       "messageTemplateId": "939dc3f7-034b-11e7-8ab4-1b0e0c25b88e", \
       "languageCode": "EN", \
       "disabled": false}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Severe Weather',
    'expression': '(
areaContainsLatLon(43.111, -89.3463)
|| areaGeocodeUgcContains("WIZ063")
|| areaGeocodeFips6SAMEContains("55025")
)
&&
(
alertTextContains("Severe Weather")
)
&&
(
categoryIsMet()
)',
    'messageTemplateId': '939dc3f7-034b-11e7-8ab4-1b0e0c25b88e',
    'languageCode': 'EN',
    'disabled': false
}

try: 
    inbound = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(inbound)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "73d183bf-2090-11e8-8d4d-89d85e85e1c0",
 "name": "Severe Weather",
 "expression": "(\nareaContainsLatLon(43.111, -89.3463)\n|| areaGeocodeUgcContains(\"WIZ063\")\n|| areaGeocodeFips6SAMEContains(\"55025\")\n)\n&&\n(\nalertTextContains(\"Severe Weather\")\n)\n&&\n(\ncategoryIsMet()\n)",
 "messageTemplateId": "939dc3f7-034b-11e7-8ab4-1b0e0c25b88e",
 "disabled": false,
 "createdAt": "2018-03-05T16:15:47.592Z",
 "languageCode": null,
 "permissions": [ "delete", "put", "get" ],
}

Create a new Inbound CAP rule.

HTTP Request

POST /inbound-cap-rules

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 Inbound CAP rule’s display name
expression String N/A The expression evaluated to determine if a CAP message triggers a notification
messageTemplateId UUID N/A The Message Template to use when creating a notification
disabled Boolean false Whether or not CAP messages matching this rule triggers a notification
languageCode String N/A The language code to match against in an incoming CAP message

The expression in the expression field may contain the boolean operators && and || in addition to calls to the functions listed here. Expressions containing syntax errors or those referencing unsupported functions/operators will be considered invalid.

Response

The Inbound CAP rule response format is detailed here.

Update an Inbound CAP Rule

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules/73d183bf-2090-11e8-8d4d-89d85e85e1c0"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'languageCode': 'EN'
,
    'disabled': true

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules/73d183bf-2090-11e8-8d4d-89d85e85e1c0" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"languageCode": "EN", \
       "disabled": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules/73d183bf-2090-11e8-8d4d-89d85e85e1c0"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'languageCode': 'EN',
    'disabled': true
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "73d183bf-2090-11e8-8d4d-89d85e85e1c0",
 "name": "Severe Weather",
 "expression": "(\nareaContainsLatLon(43.111, -89.3463)\n|| areaGeocodeUgcContains(\"WIZ063\")\n|| areaGeocodeFips6SAMEContains(\"55025\")\n)\n&&\n(\nalertTextContains(\"Severe Weather\")\n)\n&&\n(\ncategoryIsMet()\n)",
 "messageTemplateId": "939dc3f7-034b-11e7-8ab4-1b0e0c25b88e",
 "disabled": true,
 "createdAt": "2018-03-05T16:15:47.592Z",
 "languageCode": "EN",
 "permissions": [ "delete", "put", "get" ],
}

Updates an existing Inbound CAP rule.

HTTP Request

PUT /inbound-cap-rules/{inboundCapRuleId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
inboundCapRuleId The id of the Inbound Email configuration to update.

Request Parameters

Parameter Type Default Description
name String N/A The Inbound CAP rule’s display name
expression String N/A The expression evaluated to determine if a CAP message triggers a notification
messageTemplateId UUID N/A The Message Template to use when creating a notification
disabled Boolean false Whether or not CAP messages matching this rule triggers a notification
languageCode String N/A The language code to match against in an incoming CAP message

Disabling an Inbound CAP rule will not remove it from the system, but no notifications will be created.

Response

The Inbound CAP rule response format is detailed here.

Remove an Inbound CAP Rule

# Continuing with the inbound cap rule object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-cap-rules/73d183bf-2090-11e8-8d4d-89d85e85e1c0" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the inbound cap rule object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted  73d183bf-2090-11e8-8d4d-89d85e85e1c0"
}

Deletes an existing Inbound CAP rule.

HTTP Request

DELETE /inbound-cap-rules/{inboundCapRuleId}

Produces

application/json

Path Parameters

Parameter Description
inboundCapRuleId The id of the Inbound CAP rule to delete

Response

The deletion response format is detailed here.

Inbound CAP Rule Response

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

Attribute Type Description
createdAt ISO 8601 date/time When this configuration was created.
id String The id of the Inbound CAP rule
name String The Inbound CAP rule’s display name
expression String The expression evaluated to determine if a CAP message triggers a notification
messageTemplateId UUID The Message Template to use when creating a notification
disabled boolean Whether or not this rule is disabled. When disabled, a rule will not be evaluated to determine a match
languageCode String The language code to match against in an incoming CAP message

Publish a CAP Event

This endpoint allows you to send a CAP XML payload to InformaCast Mobile so it can process the inbound CAP rules against that payload.

The following restrictions exist:

  1. The payload must be valid XML format and valid CAP payload.
  2. The <identifier> tag is required and must be globally unique. If you submit two CAP messages, for the same provider, with the same value for <identifier> the second one will not be processed.
  3. The <info> <headline> and <area> tags are required.
  4. One or more of the following tags must be included: <geocode> <polygon> <circle>.
  5. The <expires> tag, if included, must reference a time in the future.
  6. The API access token provided must be associated with an application user with permissions to send notifications and Inbound CAP Create Event.
curl "https://api.icmobile.singlewire.com/api/v1/extensions/e1b2db4b-626a-11e7-a3f9-0de43455e890/proxy/cap/event"
     -H "Authorization: Bearer S35QCVBN6S6TUQKHOND="
     -X POST 
     -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alert xmlns="urn:oasis:names:tc:emergency:cap:1.2">
    <identifier>Example-001</identifier>
    <sender>singlewiredoc</sender>
    <sent>2020-10-02T15:02:00-04:00</sent>
    <status>Actual</status>
    <msgType>Alert</msgType>
    <scope>Public</scope>
    <info>
        <language>en-US</language>
        <category>Safety</category>
        <event>Civil Danger Warning</event>
        <urgency>Expected</urgency>
        <severity>Severe</severity>
        <certainty>Likely</certainty>
        <eventCode>
            <valueName>SAME</valueName>
            <value>CDW</value>
        </eventCode>
        <expires>2060-10-12T23:15:00-04:00</expires>
        <senderName>Mr. CAP</senderName>
        <headline>This is a sample headline</headline>
        <description>This is a sample description</description>
        <instruction>This is a sample instruction</instruction>
        <area>
            <areaDesc>Dane County</areaDesc>
            <geocode>
                <valueName>SAME</valueName>
                <value>055025</value>
            </geocode>
        </area>
    </info>
</alert>'
<?xml version="1.0" encoding="UTF-8"?>
<notificationEvents>
    <ruleset rulesetId="6f4e3e85-fd49-11ea-9a37-3f53b6365c06" expression="categoryIsSafety()">
        <alerts>
            <alert>
                <identifier>Example-001</identifier>
            </alert>
        </alerts>
    </ruleset>
</notificationEvents>

HTTP Request

POST /extensions/e1b2db4b-626a-11e7-a3f9-0de43455e890/proxy/cap/event

HTTP Response

  1. HTTP status 201 will be generatd if the CAP message was processed successfully and lead to notifications being sent out.
  2. HTTP status 204 will be generated if the CAP message didn’t create any notifications. This would happen if there were no ruleset matches or the alert has already been processed.
  3. HTTP status 204 will be generated if the CAP message has a tag which references a date in the past.
  4. HTTP status 400 indicates there was some sort of validation error.

The 201 response can have several instances of <ruleset> if the CAP alert matches the expression in more than one ruleset. Each <ruleset> can have more than one <alert> tag if the source CAP message actually contained several blocks with different tags.

If the request has the header ‘Accept: application/json’ in it, the response payload will be in JSON format.

Inbound Email

Inbound Email configurations (the email trigger for Inbound Events) allow you to specify the basic elements of a Notification to be created when an email matching specific critera including a whitelist and Outbound Rules.

List All Inbound Emails

require 'httparty'
require 'json'

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

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "permissions": [ "delete", "put", "get" ],
   "disabled": false,
   "sourceWhitelist": [
    "marc.loy@singlewire.com",
    "gabe.johnson@singlewire.com"
   ],
   "name": "Bad Weather",
   "createdAt": "2017-11-29T13:50:19.331Z",
   "outboundRules": [
    {
     "name": "Weather Subject",
     "id": "6a76e59f-d50c-11e7-8536-0ff1b8ecefa1",
     "messageTemplateId": "257d474f-b367-11e7-b291-a315426b49c6",
     "subjectCriteria": [ "weather", "storm" ],
     "bodyCriteria": [],
     "disabled": false,
     "userIds": [ "1f133539-d829-11e6-a35f-89d404f9ed0c" ],
     "distributionListIds": []
    }
   ],
   "id": "3cb8b11e-d50c-11e7-8536-0707cdb26a90",
   "securityLevel": "low",
   "tag": "6101703d-d50b-11e7-8536-ad37ed31a41d"
  },
  {
   "permissions": [ "delete", "put", "get" ],
   "disabled": false,
   "sourceWhitelist": [ "marc.loy@singlewire.com" ],
   "name": "General Update",
   "createdAt": "2017-11-29T17:10:18.424Z",
   "outboundRules": [],
   "id": "2cbea871-d528-11e7-81b3-a5ff55816643",
   "securityLevel": "high",
   "tag": "fa413554-d51b-11e7-81b3-0996f74f9670"
  }
 ]
}

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

HTTP Request

GET /inbound-email

Produces

application/json

Query Parameters

Results can be retrieved in groups using the API’s pagination parameters. There were a total of 2 configurations available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

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

Parameter Type Description
name String Returns only Inbound Email configurations whose names exactly match the supplied value

Response

The Inbound Email response format is detailed here.

Get an Inbound Email

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/2cbea871-d528-11e7-81b3-a5ff55816643"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    inbound = JSON.parse(HTTParty.get(url, headers: headers))
    puts(inbound)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email/2cbea871-d528-11e7-81b3-a5ff55816643" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/2cbea871-d528-11e7-81b3-a5ff55816643"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    inbound = requests.get(url, headers=headers).json()
    print(inbound)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "2cbea871-d528-11e7-81b3-a5ff55816643",
 "name": "General Update",
 "tag": "fa413554-d51b-11e7-81b3-0996f74f9670",
 "disabled": false,
 "sourceWhitelist": [ "marc.loy@singlewire.com" ],
 "createdAt": "2017-11-29T17:10:18.424Z",
 "outboundRules": [],
 "securityLevel": "high",
 "permissions": [ "delete", "put", "get" ]
}

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

HTTP Request

GET /inbound-email/{inboundId}

Produces

application/json

Path Parameters

Parameter Description
inboundId The id of the Inbound Email configuration to retrieve.

Response

The Inbound Email response format is detailed here.

Create an Inbound Email

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Fire Door Closed'
,
    'sourceWhitelist': 'firedoor-*@company.com'
,
    'securityLevel': 'high'

}

begin: 
    inbound = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(inbound)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fire Door Closed", \
       "sourceWhitelist": "firedoor-*@company.com", \
       "securityLevel": "high"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Fire Door Closed',
    'sourceWhitelist': 'firedoor-*@company.com',
    'securityLevel': 'high'
}

try: 
    inbound = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(inbound)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "bd263f53-1d66-11e8-b54a-d7bec9371d33",
 "name": "Fire Door Closed",
 "tag": "bd263f54-1d66-11e8-b54a-715064f51c99",
 "sourceWhitelist": [ "firedoor-*@company.com" ],
 "securityLevel": "high",
 "outboundRules": [],
 "createdAt": "2018-03-01T15:39:33.207Z",
 "permissions": [ "delete", "put", "get" ]
}

Create a new Inbound Email.

HTTP Request

POST /inbound-email

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 Inbound Email configuration’s display name
disabled Boolean false Whether or not emails sent to this configuration should be evaluated for creating notifications
securityLevel String N/A Options: high, medium, low, off; determines how elements in the email metadata such as SPF and spam score are used in evaluating a received email
sourceWhitelist Array[String] N/A The (required) list of emails allowed to send to this configuration

The email addresses in the sourceWhitelist field may contain simple wildcard characters (*) to match common prefixes and suffixes. The wildcards can appear in both the name and the domain portion e.g. firedoor-*@company.com or admin@*.company.com.

Please note that a security level of off is discouraged. The other settings guard against egregious spam practices but still accept email from most legacy systems.

Also note that after creating an Inbound Email configuration, you need to attach at least one Outbound Rule to complete the required setup and specify the Message Template to be used for creating notifications.

Response

The Inbound Email response format is detailed here.

Update an Inbound Email

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/52640b89-13b0-11e8-a40a-6553f9413d68"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'sourceWhitelist': 'security@company.com'
,
    'securityLevel': 'medium'

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email/52640b89-13b0-11e8-a40a-6553f9413d68" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"sourceWhitelist": "security@company.com", \
       "securityLevel": "medium"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/52640b89-13b0-11e8-a40a-6553f9413d68"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'sourceWhitelist': 'security@company.com',
    'securityLevel': 'medium'
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "bd263f53-1d66-11e8-b54a-d7bec9371d33",
 "name": "Fire Door Closed",
 "tag": "bd263f54-1d66-11e8-b54a-715064f51c99",
 "sourceWhitelist": [ "security@company.com" ],
 "securityLevel": "medium",
 "outboundRules": [],
 "createdAt": "2018-03-01T15:39:33.207Z",
 "permissions": [ "delete", "put", "get" ]
}

Updates an existing Inbound Email configuration.

HTTP Request

PUT /inbound-email/{inboundId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
inboundId The id of the Inbound Email configuration to update.

Request Parameters

Parameter Type Default Description
name String N/A The Inbound Email configuration’s display name
disabled Boolean false Whether or not emails sent to this configuration should be evaluated for creating notifications
securityLevel String N/A Options: high, medium, low, off; determines how elements in the email metadata such as SPF and spam score are used in evaluating a received email
sourceWhitelist Array[String] N/A The (required) list of emails allowed to send to this configuration
outboundRuleIds Array[UUID] N/A The list of associated outbound rules for further validation of received emails

Disabling an Inbound Email configuration will not remove it from the system, but no notifications will be created.

While not required for creating or updating, you must attach an Outbound Rule before an Inbound Email configuration can be used to generate notifications based on receipt of an email.

Response

The Inbound Email response format is detailed here.

Remove an Inbound Email

# Continuing with the inbound email object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-mail/bd263f53-1d66-11e8-b54a-d7bec9371d33" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the inbound email object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted  bd263f53-1d66-11e8-b54a-d7bec9371d33"
}

Deletes an existing Inbound Email configuration.

HTTP Request

DELETE /inbound-email/{inboundId}

Produces

application/json

Path Parameters

Parameter Description
inboundId The id of the Inbound Email configuration to delete

Any associated Outbound Rules will be deleted along with the Inbound Email configuration.

Response

The deletion response format is detailed here.

Inbound Email Response

The JSON document used to represent an Inbound Email resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this configuration was created.
id String The id of the Inbound Email configuration
name String The Inbound Email configuration’s display name
disabled boolean Whether or not this configuration is disabled. When disabled, a configuration will not accept inbound emails
outboundRules Array[Object] A list of zero or more Outbound Rules associated with this configuration. No rules implies any email from a member of the whitelist will be used to generate a notification
securityLevel String Options: high, medium, low, off; determines how elements in the email metadata such as SPF and spam score are used in evaluating a received email
sourceWhitelist Array[String] A required list of email addresses (which may contain wildcards) that are allowed to initiate a notification through this configuration
tag String The suffix to use in the email address so that a received email can trigger this configuration

Inbound RSS Feeds

Define RSS feeds to monitor and send notifications to IcMobile.

This service can monitor either RSS or ATOM syndicated feeds. When a new entry is found in a feed a notification will be sent out to recipients in the message template or overridden with the entries in the distribution_list_ids.

If a new RSS <item> is acquired the <title> section of an <item> will become the subject of the notification and the <description> will become the body.

If a new ATOM <entry> is acquired the <title> becomes the subject of the notification and the <summary> will become the body.

List All Inbound RSS Feeds

# 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.rss_feeds().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 rss in icm_client.rss_feeds().LIST():
        print(rss)
# 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.rss_feeds.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.rss_feeds.list.each do |rss|
    puts JSON.pretty_generate(rss)
  end
curl "https://api.icmobile.singlewire.com/api/v1/rss-feeds?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "messageTemplateId": "8c568e22-a04c-11e6-880c-cffa0fd0a676",
   "disabled": false,
   "name": "CNN Top Stories",
   "createdAt": "2016-11-03T19:32:48.196Z",
   "distributionListIds": [
    "9309cb65-a04c-11e6-b2ca-d3981c7949ac"
   ],
   "id": "4d4ad917-a1fc-11e6-b473-83bca009511b",
   "url": "http://rss.cnn.com/rss/cnn_topstories.rss"
   ]
  }
 ]
}

Retrieves the list of all rss feeds to monitor.

HTTP Request

GET /rss-feeds

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 RSS Feeds available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The rss-feeds response format is detailed here.

Get an RSS Feed

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    rss = icm_client.rss_feeds("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").GET().json()
    print(rss)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  rss = JSON.parse(
    icm_client.rss_feeds("cd2ec764-01a7-11e6-91d9-339e9d3d9df4").get)
  puts JSON.pretty_generate(rss)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/rss-feeds/cd2ec764-01a7-11e6-91d9-339e9d3d9df4" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"


{
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "messageTemplateId": "8c568e22-a04c-11e6-880c-cffa0fd0a676",
 "disabled": false,
 "name": "CNN Top Stories",
 "createdAt": "2016-11-03T19:32:48.196Z",
 "distributionListIds": [
  "9309cb65-a04c-11e6-b2ca-d3981c7949ac"
 ],
 "id": "4d4ad917-a1fc-11e6-b473-83bca009511b",
 "url": "http://rss.cnn.com/rss/cnn_topstories.rss"
 ]
}

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

HTTP Request

GET /rss-feeds/{rssFeedId}

Produces

application/json

Path Parameters

Parameter Description
rssFeedId The id of the RSS feed data to retrieve.

Response

The RSS response format is detailed here.

Create an RSS Feed

from icm_python_client.icm_client import ICMClient
from requests.exceptions import RequestException
token = 'S35QCVBN6S6TUQKHOND='
try:
    icm_client = ICMClient.create(token)
    rss = icm_client.rss_feeds().POST(data={
        "name": "NY Times Home Page",
        "url": "http://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml",
        "messageTemplateId": "8c568e22-a04c-11e6-880c-cffa0fd0a676",
        "distributionListIds": ["9309cb65-a04c-11e6-b2ca-d3981c7949ac"],
        "disabled": false
        }).json()
    print(rss)
except RequestException as e:
    print('Unexpected error!', e)
require 'json'
require 'icm_client'
token = 'S35QCVBN6S6TUQKHOND='
begin
  icm_client = ICMClient::Client.new(token)
  rss = JSON.parse(
    icm_client.rss_feeds.post(data={
        :name => 'NY Times Home Page',
        :url => 'http://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml',
        :messageTemplateId =>'8c568e22-a04c-11e6-880c-cffa0fd0a676',
        :distributionListIds => ['9309cb65-a04c-11e6-b2ca-d3981c7949ac'],
        :disabled => false
        })
  puts JSON.pretty_generate(rss)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/rss-feeds" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{ \
        "name": 'NY Times Home Page', \
        "url": "http://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml", \
        "messageTemplateId": "8c568e22-a04c-11e6-880c-cffa0fd0a676", \
        "distributionListIds": ["9309cb65-a04c-11e6-b2ca-d3981c7949ac"], \
        "disabled": false \
        }'
{
   "id": "4d4ad917-a1fc-11e6-b473-83bca009511b",
   "name": "NY Times Home Page",
   "url": "http://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml",
   "messageTemplateId": "8c568e22-a04c-11e6-880c-cffa0fd0a676",
   "distributionListIds": ["9309cb65-a04c-11e6-b2ca-d3981c7949ac"],
   "disabled": false
}

Create a new RSS feed

HTTP Request

POST /rss-feeds

Consumes

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

Produces

application/json

Request Parameters

Parameter Type Default Description
name String none The RSS feed’s display name
url String none The RSS feed’s url to monitor. It will be polled every 60 seconds.
messageTemplateId String none The message template to use when building a notification for an RSS feed entry. (Must have subject and body customizable)
distributionListIds Array none List of distribution lists to send notifications to.
disabled boolean false When set to true the feed will be monitored, but no notifications will be sent out.

Response

The RSS response format is detailed here.

Update an RSS Feed

# Continuing with the RSS feed object
# from the previous example:
try:
    print(icm_client.rss_feeds(rss['id']).PUT(data={
        'name': 'MSN'}).json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the rss feed object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.rss_feeds(rss['id']).put(
      :name => 'MSN'))
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/rss-feeds/e83d84e6-2281-11e6-a729-83a644c48766" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "MSN"}'
{
   "name": "MSN",
   "id": "e83d84e6-2281-11e6-a729-83a644c48766",
   "url": "http://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml",
   "messageTemplateId": "8c568e22-a04c-11e6-880c-cffa0fd0a676",
   "distributionListIds": ["9309cb65-a04c-11e6-b2ca-d3981c7949ac"],
   "disabled": false
}

Updates an existing RSS feed.

HTTP Request

PUT /rss-feeds/{rssFeedId}

Consumes

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

Produces

application/json

Path Parameters

Parameter Description
rssFeedId The id of the RSS feed to update.

Request Parameters

Parameter Type Default Description
name String none The RSS feed’s display name
url String none The RSS feed’s url to monitor. It will be polled every 60 seconds.
messageTemplateId String none The message template to use when building a notification for an RSS feed entry. (Must have subject and body customizable)
distributionListIds Array none List of distribution lists to send notifications to.
disabled boolean false When set to true the feed will be monitored, but no notifications will be sent out.

Response

The RSS feed response format is detailed here.

Remove an RSS Feed

# Continuing with the RSS feed object
# from the previous example:
try:
    print(icm_client.rss_feeds(rss['id']).DELETE().json())
except RequestException as e:
    print('Unexpected error!', e)
# Continuing with the RSS feed object
# from the previous example:
begin
  puts JSON.parse(
    icm_client.rss_feeds(rss['id']).delete)
rescue => e
  p e
end
curl "https://api.icmobile.singlewire.com/api/v1/rss-feeds/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 RSS feed.

HTTP Request

DELETE /rss-feeds/{rssFeedId}

Produces

application/json

Path Parameters

Parameter Description
rssFeedId The id of the RSS feed to delete.

Response

The deletion response format is detailed here.

RSS Feed Response

The JSON document used to represent an RSS Feed resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this RSS Feed was created.
id String The id of the RSS feed, for efficient retrieval, manipulation, or looking up sub-resources attached to the RSS Feed
name String The RSS Feed’s display name
url String The URL of the RSS feed being monitored.
messageTemplateId String The message template to use when sending a notification from this RSS feed source.
distributionListIds Array List of distribution list IDs to include when sending out an RSS feed notification.
disabled Boolean If set to true, the feed will continue to be processed, but it will not send out notifications.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Incident Plans

Incident Plans are agendas to follow when there are ongoing Incidents in your organization. Each Incident Plan has a name, description (optional), a list of Message Templates and Scenarios available for quick access, a list of hyperlink or file Incident Plan Resources for managing the Incident, and optional configuration for Roll Call.

When configuring a Message Template or Scenario, you may also specify an Incident Plan ID so that when you send the notification, an Incident will spawn from the associated Incident Plan.

List All Incident Plans

require 'httparty'
require 'json'

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

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

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

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
      "name": "IT Outage",
      "description": "Network connections interrupted - Updates will follow",
      "createdAt": "2021-05-27T15:03:50.605Z",
      "permissions": [
          "put",
          "delete",
          "get"
      ]
    },
  ]
}

Retrieves the list of Incident Plans.

HTTP Request

GET /incident-plans

Produces

application/json

Query Parameters

As usual, the number of responses can be controlled using the API’s pagination parameters. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeMessageTemplates Boolean If true, include the list of quick access Message Templates specified for this Incident Plan.
includeScenarios Boolean If true, include the list of quick access Scenarios specified for this Incident Plan.
includeResources Boolean If true, include the list of Incident Plan Resources for this Incident Plan.
includeRostering Boolean If true, include the Roll Call configuration for this Incident Plan.
includeDomains Boolean If true, include the list of Domains to which each Incident Plan belongs.

Response

The Incident Plan response format is detailed here.

Get an Incident Plan

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    ip = JSON.parse(HTTParty.get(url, headers: headers))
    puts(ip)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    ip = requests.get(url, headers=headers).json()
    print(ip)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "name": "IT Outage",
  "description": "Network connections interrupted - Updates will follow",
  "createdAt": "2021-05-27T15:03:50.605Z",
  "permissions": [
      "put",
      "delete",
      "get"
  ]
}

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

HTTP Request

GET /incident-plans/{incidentPlanId}

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan to retrieve.

Query Parameters

Parameter Type Description
includeMessageTemplates Boolean If true, include the list of quick access Message Templates specified for this Incident Plan.
includeScenarios Boolean If true, include the list of quick access Scenarios specified for this Incident Plan.
includeResources Boolean If true, include the list of Incident Plan Resources for this Incident Plan.
includeRostering Boolean If true, include the Roll Call configuration for this Incident Plan.
includeDomains Boolean If true, include the list of Domains to which each Incident Plan belongs.

Response

The Incident Plan response format is detailed here.

Create an Incident Plan

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'IT Outage'
,
    'description': 'Network connections interrupted - Updates will follow'

}

begin: 
    ip = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(ip)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "IT Outage", \
       "description": "Network connections interrupted - Updates will follow"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'IT Outage',
    'description': 'Network connections interrupted - Updates will follow'
}

try: 
    ip = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(ip)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "name": "IT Outage",
  "description": "Network connections interrupted - Updates will follow",
  "createdAt": "2021-05-27T15:03:50.605Z",
  "permissions": [
      "put",
      "delete",
      "get"
  ]
}

Create a new Incident Plan.

HTTP Request

POST /incident-plans

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 Incident Plan.
description String N/A An optional description for the Incident Plan.

Response

The Incident Plan response format is detailed here.

Update an Incident Plan

# Continuing with the incident plan object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "IT Problem"}'
# Continuing with the incident plan object
# from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "name": "IT Problem",
  "description": "Network connections interrupted - Updates will follow",
  "createdAt": "2021-05-27T15:03:50.605Z",
  "permissions": [
      "put",
      "delete",
      "get"
  ]
}

Update an existing Incident Plan.

HTTP Request

PUT /incidentPlans/{incidentPlanId}

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan to update.

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the Incident Plan.
description String N/A An optional description for the Incident Plan.
scenarioIds Array[UUID] N/A The ids of the Scenarios to use for quick access. If set to null, it will remove any scenarios from this Incident Plan.
messageTemplateIds Array[UUID] N/A The ids of the Message Templates to use for quick access. If set to null, it will remove any message templates from this Incident Plan.
rostering Incident Plan Roll Call Configuration N/A The Roll Call configuration. If set to null, it will remove Roll Call configuration from this Incident Plan
resources Empty array N/A If passed an empty array ([]), it will remove any resources from this Incident Plan.

Response

The Incident Plan response format is detailed here.

Remove an Incident Plan

# Continuing with the incident plan object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the incident plan object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"IncidentPlans\"} bebd604d-befc-11eb-9006-654fb6bb8702"
}

Deletes an existing Incident Plan.

HTTP Request

DELETE /incident-plans/{incidentPlanId}

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan to update.

Response

The deletion response format is detailed here.

Incident Plan Response

Attribute Type Description
createdAt ISO 8601 date/time When this Incident Plan was created.
description String The optional description for the Incident Plan.
domains Array[Domain] When Domains are in use and includeDomains was true in your request, this response will list the Domains to which the Incident Plan belongs.
id String The id of this specific Incident Plan, allowing it to be manipulated or retrieved individually.
messageTemplates Array[Object] When includeMessageTemplates is set to true in your request, this response will list the name and id of the specified quick access Message Templates.
name String The name of the Incident Plan.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
resources Array[Incident Plan Resource] When includeResources is set to true in your request, this response will list the specified Incident Plan Resources.
scenarios Array[Object] When includeScenarios is set to true in your request, this response will list the name and id of the specified quick access Scenarios.
rostering Incident Plan Roll Call Config When includeRostering is set to true in your request, this response will contain the Incident Plan Roll Call configuration.
visitorAwareBaseUrl String URL for base Visitor Aware domain. Only included if user has Visitor Aware license.

Incident Plan Roll Call Request Parameters

The structure of the Incident Plan Roll Call object in the Incident Plan request.

Attribute Type Default Description
locations Array[string] N/A The list of locations available to use during a Roll Call event
statuses Array[string] N/A The list of statuses available to use during a Roll Call event
rosterManagerSiteRoleIds Array[UUID] N/A The ids of site roles that determine the Roll Call administrators for a Roll Call event
rosterMemberSiteRoleIds Array[UUID] N/A The ids of of site roles that determine which users populate the Roll Call list for a Roll Call event
type String ‘informacast’ A string representing the type of Roll Call service to be used, either informacast which indicates Roll Call or visitor-aware which indicates Visitor Aware Reunification.

Incident Plan Roll Call Response

The structure of the Incident Plan Roll Call object in Incident Plan response.

Attribute Type Description
incidentPlanRosteringId UUID The id of the Incident Plan Roll Call configuration.
locations Array[string] The list of locations available to use during a Roll Call event.
statuses Array[string] The list of statuses available to use during a Roll Call event.
rosterManagerSiteRoleIds Array[UUID] The ids of site roles that determine the Roll Call administrators for a Roll Call event.
rosterManagerSiteRoles Array[Site Role] The list of site roles that determine the Roll Call administrators for a Roll Call event.
rosterMemberSiteRoleIds Array[UUID] The ids of of site roles that determine which users populate the Roll Call list for a Roll Call event.
rosterMemberSiteRoles Array[Site Role] The list of site roles that determine the users that populate the Roll Call list in a Roll Call event.
type String A string representing the type of Roll Call service to be used, either informacast which indicates Roll Call or visitor-aware which indicates Visitor Aware Reunification.

Incident Plan Domains

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

List All Incident Plan Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "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/",
      "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

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

HTTP Request

GET /incident-plans/{incidentPlanId}/domains

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan whose associated Domains are listed.

Query Parameters

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

Response

The Domain response format is detailed here. Additionally, the id of the Incident Plan whose domains were requested is returned under the key incidentPlanId inside each domain response.

Check if an Incident Plan contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Incident Plan Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /incident-plans/{incidentPlanId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan whose Domains are of interest.
id The id of the Domain you want to know whether the Incident Plan belongs to.

Additionally, you can check if the Incident Plan 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 Incident Plan, any of their subdomains will be considered.

Response

If the Incident Plan is part of the Domain (or its subdomains, if recursive is true), a response will be returned. The Incident Plan 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 an Incident Plan Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Incident Plan 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 /incident-plans/{incidentPlanId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
incidentPlanId UUID The id of the Incident Plan 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 Incident Plan out of a parent Domain?
id String n/a The id of the Domain to which the Incident Plan should be added.
promote Boolean false Allow this request to proceed even if it will promote the Incident Plan out of one or more child Domains?

A Incident Plan 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 Incident Plan 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 an Incident Plan Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Incident Plan c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Incident Plan from the specified Domain. As described below, if this is the only Domain that the Incident Plan currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Incident Plan itself.

HTTP Request

DELETE /incident-plans/{incidentPlanId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
incidentPlanId The id of the Incident Plan whose Domain should be removed.
id The id of the Domain to be removed from the Incident Plan.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Incident Plan in no Domain.

A Incident Plan must always belong to at least one Domain, so if you try to remove the Incident Plan from the only Domain that it belongs to, the request must either fail, or delete the Incident Plan. 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 Incident Plan out of its last Domain will delete the Incident Plan.

Response

The deletion response format is detailed here.

Incident Plan Resources

Incident Plan Resources are the collection of hyperlinks and files that belong to a specific Incident Plan. When an Incident is created from this Incident Plan, the associated resources become immediately available to your Incident Management team.

List All Incident Plan Resources

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "permissions": [
       "delete",
       "get"
      ],
      "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
      "name": "IT Outage Protocol",
      "fileName": "it_outage_protocol.txt",
      "createdAt": "2021-06-02T19:08:50.920Z",
      "type": "file",
      "size": 9,
      "id": "f749eefc-c3d5-11eb-b004-a963ffc8cb9f",
      "hyperlink": null,
      "contentType": "text/plain",
      "metadata": {}
    },
    {
      "permissions": [
       "delete",
       "get"
      ],
      "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
      "name": "Helpdesk Website",
      "fileName": null,
      "createdAt": "2021-06-02T19:09:50.920Z",
      "type": "hyperlink",
      "size": null,
      "id": "d2f58733-b8f0-11eb-a15c-ad35ea737d26",
      "hyperlink": "https://www.helpdesk.com",
      "contentType": null,
      "metadata": null
    }
  ]
}

Retrieves the list of Incident Plan Resources.

HTTP Request

GET /incident-plans/{incidentPlanId}/resources

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan for which this resource belongs.

Query Parameters

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

The Incident Plan Resource response format is detailed here.

Get a Specific Incident Plan Resource

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources/f749eefc-c3d5-11eb-b004-a963ffc8cb9f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    ipr = JSON.parse(HTTParty.get(url, headers: headers))
    puts(ipr)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources/f749eefc-c3d5-11eb-b004-a963ffc8cb9f" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources/f749eefc-c3d5-11eb-b004-a963ffc8cb9f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    ipr = requests.get(url, headers=headers).json()
    print(ipr)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
   "delete",
   "get"
  ],
  "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "name": "IT Outage Protocol",
  "fileName": "it_outage_protocol.txt",
  "createdAt": "2021-06-02T19:08:50.920Z",
  "type": "file",
  "size": 9,
  "id": "f749eefc-c3d5-11eb-b004-a963ffc8cb9f",
  "hyperlink": null,
  "contentType": "text/plain",
  "metadata": {}
}

Retrieves resource information based on the id values of the Incident Plan and Incident Plan Resource. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /incident-plans/{incidentPlanId}/resources/{resourceId}

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan for which resource information is desired.
resourceId The id of the Incident Plan Resource.

Response

The Incident Plan Resource response format is detailed here.

Create an Incident Plan Resource

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Helpdesk Website'
,
    'type': 'hyperlink'
,
    'hyperlink': 'https://www.helpdesk.com'

}

begin: 
    ipr = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(ipr)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Helpdesk Website", \
       "type": "hyperlink", \
       "hyperlink": "https://www.helpdesk.com"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Helpdesk Website',
    'type': 'hyperlink',
    'hyperlink': 'https://www.helpdesk.com'
}

try: 
    ipr = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(ipr)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
   "delete",
   "get"
  ],
  "incidentPlanId": "bebd604d-befc-11eb-9006-654fb6bb8702",
  "name": "Helpdesk Website",
  "fileName": null,
  "createdAt": "2021-06-02T19:09:50.920Z",
  "type": "hyperlink",
  "size": null,
  "id": "d2f58733-b8f0-11eb-a15c-ad35ea737d26",
  "hyperlink": "https://www.helpdesk.com",
  "contentType": null,
  "metadata": null
}

Create a new Incident Plan Resource.

HTTP Request

POST /incident-plans/{incidentPlanId}/resources

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 Incident Plan Resource.
type String N/A The resource type. Must be “hyperlink” or “file”.
hyperlink String N/A The hyperlink for the Incident Plan Resource. Must be specified for hyperlink resources.
file Blob N/A The binary stream of a the file data. The size of the image must not exceed 20 MiB. Must be specified for file resources.

Response

The Incident Plan Resource response format is detailed here.

Remove an Incident Plan Resource

# Continuing with the incident plan and resource
# objects from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources/f749eefc-c3d5-11eb-b004-a963ffc8cb9f" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the incident plan and resource
# objects from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"IncidentPlanResources\"} f749eefc-c3d5-11eb-b004-a963ffc8cb9f"
}

Deletes an existing Incident Plan Resource.

HTTP Request

DELETE /incident-plans/{incidentPlanId}/resources/{resourceId}

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan to which the Incident Plan Resource belongs.
resourceId The id of the Incident Plan Resource to delete.

Response

The deletion response format is detailed here.

Get an Incident Plan File Resource’s Data

# Continuing with the incident plan and resource
# objects from the previous example:
begin:
    pic = HTTParty.get(url, headers: headers)
    puts(pic.headers['content-type'])   # e.g., image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/resources/f749eefc-c3d5-11eb-b004-a963ffc8cb9f/file" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the incident plan and resource
# objects from the previous example:
try:
    pic = requests.get(url, headers=headers)
    print(pic.headers['content-type'])   # e.g., image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Produces a binary stream of the file data, with the specific MIME type identified in the response header. Will likely involve redirection to a content distribution network server closer to where the request originated.

Retrieves the file data for an Incident Plan Resource, if any, as a binary stream. For improved performance, this will likely involve redirection (via an HTTP 302 Redirect response) to an AWS CloudFront content distribution network node which has cached the content closer geographically to where the request originated than the Singlewire REST API servers.

HTTP Request

GET /incident-plans/{incidentPlanId}/resources/{resourceId}/file

Produces

image/png

image/jpeg

image/svg+xml

image/bmp

application/pdf

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

application/vnd.ms-excel

application/msword

application/vnd.openxmlformats-officedocument.wordprocessingml.document

application/vnd.ms-powerpoint

application/vnd.openxmlformats-officedocument.presentationml.presentation

text/plain

Path Parameters

Parameter Description
incidentPlanId The id of the Incident Plan with an Incident Plan File Resource.
resourceId The id of the Incident Plan File Resource to get the file data.

Incident Plan Resource Response

Attribute Type Description
contentType String The content type of the Incident Plan Resource. Only applies for file resources.
createdAt ISO 8601 date/time When this Incident Plan Resource was created.
fileName String The name of the uploaded file. Only applies for file resources.
hyperlink String The hyperlink resource. Only applies for hyperlink Incident Plan Resources.
id UUID The id of this specific Incident Plan Resource, allowing it to be manipulated or retrieved individually.
incidentPlanId UUID The id of the Incident Plan for which this resource belongs.
metadata JSON Any specific metadata about the file resource. Only applies for file resources.
name String The name of the Incident Plan Resource.
permissions Array[String] Options: get delete. Which operations are possible on this resource, given the authentication token being used to access the API.
size Integer The size in bytes of file. Only applies for file resources.
type String The type of the Incident Plan Resource. Must be either “hyperlink” or “file”.

Incident Plan Visitor Aware Mappings Status

Incident Plan Visitor Aware Mappings status is a resource reflecting whether or not all InformaCast sites have mappings to ‘Locations’ in Visitor Aware. This endpoint is only accessible to users licensed to use Visitor Aware Features.

Get Incident Plan Visitor Aware Mappings Status

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/visitor-aware-mapping-status"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/visitor-aware-mapping-status" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incident-plans/bebd604d-befc-11eb-9006-654fb6bb8702/visitor-aware-mapping-status"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{"areMappingsMissing":true}

Retrieves the Mappings Completed status

HTTP Request

GET /incident-plans/{incidentPlanId}/visitor-aware-mapping-status

Produces

application/json

Path Parameters

Parameter Description
incidentPlanId The id of an Incident Plan for this provider.

Response

Attribute Type Description
areMappingsMissing Boolean False if all sites have location mappings in Visitor Aware, true otherwise.

Incidents

Incidents are the instantiation of Incident Plans. When a Notification is sent via a Message Template or Scenario with an attached Incident Plan, an Ongoing Incident begins. All quick-access notifications and Incident Plan Resources become available to your Incident Management team.

During an Ongoing Incident, Incident Resources may be added and removed. Once the incident ends, no additional changes may be made to the Incident or its subresources.

List All Incidents

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
    {
      "permissions": [
          "delete",
          "get"
      ],
      "messageTemplateId": "9c260d34-b72e-11eb-ba2e-53e6a3f416c2",
      "messageTemplate": {
          "name": "IT Outage Incident"
      },
      "notificationId": "918bcd71-c3d9-11eb-9f49-eb0999116a25",
      "createdAt": "2021-06-02T19:34:38.210Z",
      "notificationCreatedAt": "2021-06-02T19:34:38.211Z",
      "id": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
      "incidentPlan": {
          "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
          "name": "IT Outage",
          "description": "Network connections interrupted - Updates will follow"
      },
      "scenario": null,
      "emergencyCallingStatus": null,
      "endedAt": null
    }
  ]
}

Retrieves a list of all Incidents.

HTTP Request

GET /incidents

Produces

application/json

Query Parameters

As usual, the number of responses can be controlled using the API’s pagination parameters. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
ongoingOnly Boolean If true, only include Ongoing Incidents. This is denoted by Incident’s whose endedAt value is null.
includeNotificationCount Boolean If true, include the total number of Notifications sent during this Incident.
includeResources Boolean If true, include the list of Incident Resources in the response.
includeDomains Boolean If true, include the list of Domains to which each Incident belongs.

Response

The Incident response format is detailed here.

Get an Incident

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incident/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    i = JSON.parse(HTTParty.get(url, headers: headers))
    puts(i)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incident/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incident/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    i = requests.get(url, headers=headers).json()
    print(i)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
      "delete",
      "get"
  ],
  "messageTemplateId": "9c260d34-b72e-11eb-ba2e-53e6a3f416c2",
  "messageTemplate": {
      "name": "IT Outage Incident"
  },
  "notificationId": "918bcd71-c3d9-11eb-9f49-eb0999116a25",
  "createdAt": "2021-06-02T19:34:38.210Z",
  "notificationCreatedAt": "2021-06-02T19:34:38.211Z",
  "id": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
  "incidentPlan": {
      "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
      "name": "IT Outage",
      "description": "Network connections interrupted - Updates will follow"
  },
  "scenario": null,
  "emergencyCallingStatus": null,
  "endedAt": null
}

Retrieves a single Incident by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /incidents/{incidentId}

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident to retrieve.

Query Parameters

Parameter Type Description
ongoingOnly Boolean If true, only include Ongoing Incidents. This is denoted by Incident’s whose endedAt value is null.
includeNotificationCount Boolean If true, include the total number of Notifications sent during this Incident.
includeResources Boolean If true, include the list of Incident Resources in the response.
includeDomains Boolean If true, include the list of Domains to which each Incident belongs.

Response

The Incident response format is detailed here.

Create an Incident

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'incidentPlanId': '335ae2c1-7226-11eb-9d92-cb1d1a168b9b'

}

begin: 
    i = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(i)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"incidentPlanId": "335ae2c1-7226-11eb-9d92-cb1d1a168b9b"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incidents"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'incidentPlanId': '335ae2c1-7226-11eb-9d92-cb1d1a168b9b'
}

try: 
    i = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(i)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
      "delete",
      "get"
  ],
  "messageTemplateId": "9c260d34-b72e-11eb-ba2e-53e6a3f416c2",
  "messageTemplate": {
      "name": "IT Outage Incident"
  },
  "notificationId": "918bcd71-c3d9-11eb-9f49-eb0999116a25",
  "createdAt": "2021-06-02T19:34:38.210Z",
  "notificationCreatedAt": "2021-06-02T19:34:38.211Z",
  "id": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
  "incidentPlan": {
      "id": "bebd604d-befc-11eb-9006-654fb6bb8702",
      "name": "IT Outage",
      "description": "Network connections interrupted - Updates will follow"
  },
  "scenario": null,
  "rostering": null,
  "site": null,
  "emergencyCallingStatus": null,
  "endedAt": null
}

Create a new Incident. Although Incidents may be triggered by specifying an Incident Plan on a Message Template or Scenario, You may also start an Incident using the /incidents API directly.

HTTP Request

POST /incidents

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
incidentPlanId UUID N/A The ID of the Incident Plan to use for this Incident.

Response

The Incident response format is detailed here.

Remove an Incident

# Continuing with the incident object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the incident object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"Incidents\"} 918ba620-c3d9-11eb-9f49-b9d2cf5b3e40"
}

Removes an Incident from the record. Generally only administrative users will have permission to do this.

HTTP Request

DELETE /incidents/{incidentId}

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident to delete.

Response

The deletion response format is detailed here.

Incident Response

Attribute Type Description
createdAt ISO 8601 date/time When this Incident 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 Incident belongs.
emergency­CallingStatus Emergency Calling Status object If this is an emergency scenario, will hold information from the most recent Incident Activity that reported an update about the emergency calling flow. Will be null if none has been recevied yet, or if this is not an emergency scenario.
endedAt String When the Incident was completed. null indicates that the Incident is ongoing.
id String The id of this specific Incident, allowing it to be manipulated or retrieved individually.
incidentPlan Incident Plan The Incident Plan used to start the Incident.
message­Template Object An object containing the name of the Message Template used to trigger the Incident. null if triggered some other way.
message­TemplateId String The ID of the Message Template used to trigger the Incident. null if triggered some other way.
notificationId String The ID of the Notification that triggered this Incident. null if triggered manually via the /incidents API.
notification­Count Integer When includeNotificationCount is true in the request, the number of notifications sent during this Incident. Otherwise omitted from the response.
notification­CreatedAt ISO 8601 date/time The createdAt value of the Notification that triggered this Incident. null if triggered manually via the /incidents API.
permissions Array[String] Options: get delete. Which operations are possible on this resource, given the authentication token being used to access the API.
resources Array[Incident Resource] When includeResources is set to true in the request, list the Incident Resources that belong to this Incident.
rostering Incident Roll Call object If this Incident has Roll Call configured, contains Incident Roll Call data.
scenario Scenario The Scenario used to trigger the Incident. null if triggered some other way.
site Site The site assigned to the incident. Used for Roll Call when assigning Roll Call members and administrators. Will be null if no site is assigned.

Emergency Calling Status Response

When a status update about the progress of emergency calling has been received it will have the following format:

Attribute Type Description
type String One of rapid-sos-initiated, rapid-sos-no-response, rapid-sos-confirmed, rapid-sos-declined rapid-sos-contacting-monitoring, rapid-sos-cancelled, or rapid-sos-completed.
createdAt ISO 8601 date/time The createdAt value of the Incident Activity that reported this status.
details Object Any additional information that was supplied by the emergency services integration provider.

Incident Roll Call Response

The response data for Roll Call when it is enabled on an Incident has the following format:

Attribute Type Description
locations Array[string] List of locations that can be used in this Roll Call event
statuses Array[string] List of statuses that can be used in this Roll Call event
type String A string representing the type of Roll Call service to be used, either informacast which indicates Roll Call or visitor-aware which indicates Visitor Aware Reunification.
visitorAwareUrl String A URL pointing at the Visitor Aware Reunification Event initiated by this incident.
visitorAwareError String An error message recieved when trying to initiate a Visitor Aware Reunification Event.
visitorAwareBaseUrl String URL for base Visitor Aware domain.

Incident Activities

Incident Activities are the mechanism for tracking and reviewing certain interactions that Users have had with a particular Incident. At this time, the activity types end-incident, rapid-sos-initiated, rapid-sos-no-response, rapid-sos-confirmed, rapid-sos-declined, rapid-sos-contacting-monitoring, rapid-sos-cancelled, and rapid-sos-completed are supported. end-incident reflects the fact that an incident has ended and can be posted to the incident when a user wants to end it. The other activities are informational in nature, and are added by the system when certain events occur, such as progress in contacting emergency responders for emergency scenarios.

Get All Incident Activities

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "id": "e2ada148-bd82-11eb-a95c-0d6c5fd6888c",
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "userId": "b2fddd62-1ece-11eb-81a7-7b383da79abc",
      "createdAt": "2021-05-25T17:59:01.136Z",
      "type": "end-incident",
      "details": {
          "user": {
              "id": "b2fddd62-1ece-11eb-81a7-7b383da79abc",
              "name": "John Smith",
              "email": "john.smith@acmecompany.com"
          }
      },
      "permissions": [
          "get"
      ]
    }
  ]
}

Retrieves the list of all activities recorded for the specified Incident.

HTTP Request

GET /incidents/{incidentId}/activities

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which activity information is desired.

Query Parameters

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

The Incident Activity response format is detailed here.

Get a Specific Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities/e2ada148-bd82-11eb-a95c-0d6c5fd6888c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities/e2ada148-bd82-11eb-a95c-0d6c5fd6888c" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities/e2ada148-bd82-11eb-a95c-0d6c5fd6888c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    activity = requests.get(url, headers=headers).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "e2ada148-bd82-11eb-a95c-0d6c5fd6888c",
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "userId": "b2fddd62-1ece-11eb-81a7-7b383da79abc",
  "createdAt": "2021-05-25T17:59:01.136Z",
  "type": "end-incident",
  "details": {
      "user": {
          "id": "b2fddd62-1ece-11eb-81a7-7b383da79abc",
          "name": "John Smith",
          "email": "john.smith@acmecompany.com"
      }
  },
  "permissions": [
      "get"
  ]
}

Retrieves a specific activity based the id values of the Incident and Activity. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /incidents/{incidentId}/activities/{activityId}

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which activity information is desired.
activityId The id of the specific Incident Activity of interest.

Response

The Incident Activity response format is detailed here.

Create an Activity To End an Incident

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'type': 'end-incident'

}

begin: 
    activity = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"type": "end-incident"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'type': 'end-incident'
}

try: 
    activity = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "e2ada148-bd82-11eb-a95c-0d6c5fd6888c",
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "userId": "b2fddd62-1ece-11eb-81a7-7b383da79abc",
  "createdAt": "2021-05-25T17:59:01.136Z",
  "type": "end-incident",
  "details": {
      "user": {
          "id": "b2fddd62-1ece-11eb-81a7-7b383da79abc",
          "name": "John Smith",
          "email": "john.smith@acmecompany.com"
      }
  },
  "permissions": [
      "get"
  ]
}

Creates a new end-incident Activity to end the specified Incident. Since this is not a list request, there is no pagination wrapper around the result.

Although incidents can have other types of activities added by the system, the only type that you can post yourself is end-incident.

HTTP Request

POST /incidents/{incidentId}/activities

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Required Description
incidentId UUID Yes The id of the Incident for which activity information is desired.
type String Yes Options: end-incident. Ends an Ongoing Incident by setting the endedAt value on the Incident.

Response

The Incident Activity response format is detailed here.

Incident Activity Response

Attribute Type Description
createdAt ISO 8601 date/time When this Incident Activity was created.
details Object A JSON object containing additional information about the Activity when it was created, such as the User email.
id String The id of this specific Incident Activity.
incidentId UUID The Incident to which this Activity belongs.
permissions Array[String] Options: get. Which operations are possible on this resource, given the authentication token being used to access the API.
type String Options: end-incident, rapid-sos-initiated, rapid-sos-no-response, rapid-sos-confirmed, rapid-sos-declined, rapid-sos-contacting-monitoring, rapid-sos-cancelled, and rapid-sos-completed.
userId String The id of the User that created the activity.

Incident Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Incidents are assigned to the acting domain of the User that triggers the Incident. This resource lets you see which Incidents occurred in which Domains.

List All Incident Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "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/",
      "incidentId": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
      "permissions": [
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Incident belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /incidents/{incidentId}/domains

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident whose associated Domains are to be listed.

Query Parameters

There will always only be one Domain associated with an Incident, reflecting the Domain in which the User that triggered it was acting at the time it was sent, so the standard pagination mechanism is not needed for this resource.

Additionally, you can request the subdomains of the Domain attached to the specified Incident 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 the Domain that is directly attached to the specified Incident, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the Incident whose domains were requested is returned under the key incidentId inside each domain response.

Check if an Incident contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "incidentId": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Incident Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /incidents/{incidentId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident whose Domains are of interest.
id The id of the Domain you want to know whether the Incident belongs to.

Additionally, you can check if the Incident is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
recursive boolean If true, in addition to the Domain that is directly attached to the specified Incident, any of its subdomains will be considered.

Response

If the Incident 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.

Incident Resources

Incident Resources are the collection of hyperlinks and files that belong to a specific Incident. When an Incident is created from an Incident Plan, all of the Plan’s resources are copied over to the Incident. You may then continue to add and remove Incident Resources until the Incident is completed.

List All Incident Resources

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "permissions": [
       "delete",
       "get"
      ],
      "name": "IT Outage Protocol",
      "fileName": "it_outage_protocol.txt",
      "createdAt": "2021-06-02T19:08:50.920Z",
      "type": "file",
      "size": 9,
      "id": "8aaadc98-c490-11eb-9f49-2137e0f117ec",
      "hyperlink": null,
      "contentType": "text/plain",
      "incidentId": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
      "metadata": {}
    },
    {
      "permissions": [
       "delete",
       "get"
      ],
      "name": "Helpdesk Website",
      "fileName": null,
      "createdAt": "2021-06-02T19:09:50.920Z",
      "type": "hyperlink",
      "size": null,
      "id": "8aaa8e77-c490-11eb-9f49-ad61e93bfa2c",
      "hyperlink": "https://www.helpdesk.com",
      "contentType": null,
      "incidentId": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
      "metadata": null
    }
  ]
}

Retrieves the list of Incident Resources.

HTTP Request

GET /incidents/{incidentId}/resources

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which this resource belongs.

Query Parameters

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

The Incident Resource response format is detailed here.

Get a Specific Incident Resource

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources/8aaadc98-c490-11eb-9f49-2137e0f117ec"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    ir = JSON.parse(HTTParty.get(url, headers: headers))
    puts(ir)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources/8aaadc98-c490-11eb-9f49-2137e0f117ec" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources/8aaadc98-c490-11eb-9f49-2137e0f117ec"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    ir = requests.get(url, headers=headers).json()
    print(ir)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
   "delete",
   "get"
  ],
  "incidentId": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
  "name": "IT Outage Protocol",
  "fileName": "it_outage_protocol.txt",
  "createdAt": "2021-06-02T19:08:50.920Z",
  "type": "file",
  "size": 9,
  "id": "8aaadc98-c490-11eb-9f49-2137e0f117ec",
  "hyperlink": null,
  "contentType": "text/plain",
  "metadata": {}
}

Retrieves resource information based on the id values of the Incident and Incident Resource. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /incidents/{incidentId}/resources/{resourceId}

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which resource information is desired.
resourceId The id of the Incident Resource.

Response

The Incident Resource response format is detailed here.

Create an Incident Resource

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Helpdesk Website'
,
    'type': 'hyperlink'
,
    'hyperlink': 'https://www.helpdesk.com'

}

begin: 
    ir = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(ir)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Helpdesk Website", \
       "type": "hyperlink", \
       "hyperlink": "https://www.helpdesk.com"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Helpdesk Website',
    'type': 'hyperlink',
    'hyperlink': 'https://www.helpdesk.com'
}

try: 
    ir = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(ir)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
   "delete",
   "get"
  ],
  "incidentId": "918ba620-c3d9-11eb-9f49-b9d2cf5b3e40",
  "name": "Helpdesk Website",
  "fileName": null,
  "createdAt": "2021-06-02T19:09:50.920Z",
  "type": "hyperlink",
  "size": null,
  "id": "8aaa8e77-c490-11eb-9f49-ad61e93bfa2c",
  "hyperlink": "https://www.helpdesk.com",
  "contentType": null,
  "metadata": null
}

Create a new Incident Resource.

HTTP Request

POST /incidents/{incidentId}/resources

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 Incident Resource.
type String N/A The resource type. Must be “hyperlink” or “file”.
hyperlink String N/A The hyperlink for the Incident Resource. Must be specified for hyperlink resources.
file Blob N/A The binary stream of a the file data. The size of the image must not exceed 20 MiB. Must be specified for file resources.

Response

The Incident Resource response format is detailed here.

Remove an Incident Resource

# Continuing with the incident and resource
# objects from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/bebd604d-befc-11eb-9006-654fb6bb8702/resources/f749eefc-c3d5-11eb-b004-a963ffc8cb9f" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the incident and resource
# objects from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"IncidentPlanResources\"} f749eefc-c3d5-11eb-b004-a963ffc8cb9f"
}

Deletes an existing Incident Resource. This may only be done for Ongoing Incidents.

HTTP Request

DELETE /incidents/{incidentId}/resources/{resourceId}

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident to which the Incident Resource belongs.
resourceId The id of the Incident Resource to delete.

Response

The deletion response format is detailed here.

Get an Incident File Resource’s Data

# Continuing with the incident and resource
# objects from the previous example:
begin:
    pic = HTTParty.get(url, headers: headers)
    puts(pic.headers['content-type'])   # e.g., image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/918ba620-c3d9-11eb-9f49-b9d2cf5b3e40/resources/8aaadc98-c490-11eb-9f49-2137e0f117ec/file" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the incident and resource
# objects from the previous example:
try:
    pic = requests.get(url, headers=headers)
    print(pic.headers['content-type'])   # e.g., image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Produces a binary stream of the file data, with the specific MIME type identified in the response header. Will likely involve redirection to a content distribution network server closer to where the request originated.

Retrieves the file data for an Incident Resource, if any, as a binary stream. For improved performance, this will likely involve redirection (via an HTTP 302 Redirect response) to an AWS CloudFront content distribution network node which has cached the content closer geographically to where the request originated than the Singlewire REST API servers.

HTTP Request

GET /incidents/{incidentId}/resources/{resourceId}/file

Produces

image/png

image/jpeg

image/svg+xml

image/bmp

application/pdf

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

application/vnd.ms-excel

application/msword

application/vnd.openxmlformats-officedocument.wordprocessingml.document

application/vnd.ms-powerpoint

application/vnd.openxmlformats-officedocument.presentationml.presentation

text/plain

Path Parameters

Parameter Description
incidentId The id of the Incident with an Incident File Resource.
resourceId The id of the Incident File Resource to get the file data.

Incident Resource Response

Attribute Type Description
contentType String The content type of the Incident Resource. Only applies for file resources.
createdAt ISO 8601 date/time When this Incident Resource was created.
fileName String The name of the uploaded file. Only applies for file resources.
hyperlink String The hyperlink resource. Only applies for hyperlink Incident Resources.
id String The id of this specific Incident Resource, allowing it to be manipulated or retrieved individually.
incidentId UUID The id of the Incident for which this resource belongs.
metadata JSON Any specific metadata about the file resource. Only applies for file resources.
name String The name of the Incident Resource.
permissions Array[String] Options: get delete. Which operations are possible on this resource, given the authentication token being used to access the API.
size Integer The size in bytes of file. Only applies for file resources.
type String The type of the Incident Resource. Must be either “hyperlink” or “file”.

Incident Roll Call Members

Incident Roll Call members are the users who are in the list for a particular Roll Call event. The Roll Call members will have a status and location assigned, which will be updated by Roll Call administrators during the event.

Get All Incident Roll Call Members

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
        "name": "John Doe",
        "email": "john.doe@domain.com"
      },
      "status": "Safe",
      "location": "Classroom",
      "permissions": [
          "get", "put"
      ]
    },
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
        "name": "Jane Doe",
        "email": "jane.doe@domain.com"
      },
      "status": "Safe",
      "location": "Reunification Zone",
      "permissions": [
        "get", "put"
      ]
    }
  ]
}

Retrieves all members of the Incident’s Roll Call list.

HTTP Request

GET /incidents/{incidentId}/rostering-members

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which Roll Call member information is desired.

Query Parameters

Parameter Type Description
filterStatuses Array[string] A JSON-encoded array of statuses on which to filter Roll Call members. To filter on ‘Unknown’, include a status of null.
filterLocations Array[string] A JSON-encoded array of locations on which to filter Roll Call members. To filter on 'Unknown’, include a location of null.

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

The Roll Call member response format is detailed here.

Get a Specific Roll Call Member

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    rcm = JSON.parse(HTTParty.get(url, headers: headers))
    puts(rcm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    rcm = requests.get(url, headers=headers).json()
    print(rcm)
except RequestException as e:
    print('Unexpected error!', e)
 {
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "memberUser": {
    "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
    "name": "Jane Doe",
    "email": "jane.doe@domain.com"
  },
  "status": "Safe",
  "location": "Reunification Zone",
  "permissions": [
    "get", "put"
  ]
}

Retrieves a specific Roll Call member based on the id values of the Incident and Roll Call member. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /incidents/{incidentId}/rostering-members/{userId}

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which Roll Call information is desired.
userId The id of the specific user who is a member of the Roll Call list.

Response

The Incident Roll Call member response format is detailed here.

Bulk Update Roll Call Member Statuses and Locations

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'rosterMemberUserIds': ['0a8f4841-11d2-11ed-87c6-11f85dd7497d'
, '7676808b-d5fa-11eb-aea1-a17da050c75a'
]
,
    'status': 'Safe'
,
    'location': 'Reunification Zone'

}

begin: 
    rcm = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(rcm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"rosterMemberUserIds": ["0a8f4841-11d2-11ed-87c6-11f85dd7497d", "7676808b-d5fa-11eb-aea1-a17da050c75a"], \
       "status": "Safe", \
       "location": "Reunification Zone"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'rosterMemberUserIds': ['0a8f4841-11d2-11ed-87c6-11f85dd7497d', '7676808b-d5fa-11eb-aea1-a17da050c75a'],
    'status': 'Safe',
    'location': 'Reunification Zone'
}

try: 
    rcm = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(rcm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "rosterMemberUsers": [
    {
      "memberUser": {
        "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
        "name": "John Doe",
        "email": "john.doe@domain.com"
      },
      "status": "Safe",
      "location": "Reunification Zone"
    },
    {
      "memberUser": {
        "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
        "name": "Jane Doe",
        "email": "jane.doe@domain.com"
      },
      "status": "Safe",
      "location": "Reunification Zone"
    }
  ],
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "permissions": ["put", "get"],
}

Updates the status and/or location of all specified Roll Call members. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

POST /incidents/{incidentId}/rostering-members

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which to update Roll Call member data.

Request Parameters

Parameter Type Required Description
rosterMemberUserIds Array[UUID] Yes List of ids of users in the Roll Call list to be updated.
location String One or both of status or location required The new location to be set for the specified roll call members. To set location to 'Unknown’, pass null.
status String One or both ofstatus or location required The new status to be set for the specified Roll Call members. To set status to 'Unknown’, pass null.

Response

The Incident Roll Call Member response format is detailed here.

Update One Roll Call Member Status and Location

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'status': 'Safe'
,
    'location': 'Reunification Zone'

}

begin: 
    rcm = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(rcm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"status": "Safe", \
       "location": "Reunification Zone"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'status': 'Safe',
    'location': 'Reunification Zone'
}

try: 
    rcm = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(rcm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "memberUser": {
    "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
    "name": "John Doe",
    "email": "john.doe@domain.com"
  },
  "status": "Safe",
  "location": "Classroom",
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "permissions": ["put", "get"]
}

Updates the status and/or location of the specified Roll Call member. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

PUT /incidents/{incidentId}/rostering-members

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which to update Roll Call member data.
userId The user id of the Roll Call member for which to update status and/or location

Request Parameters

Parameter Type Required Description
location String No The new location to be set for the specified roll call member. To set location to 'Unknown’, pass null.
status String No The new status to be set for the specified Roll Call member. To set status to 'Unknown’, pass null.

Response

The Roll Call member response format is detailed here.

Incident Roll Call Member Response

Attribute Type Description
incidentId UUID The Incident to which the Roll Call member belongs.
memberUser Array[Object] A JSON object containing the user name, email and ID for the Roll Call list member
status String The status of the Roll Call member. null indicates status of 'Unknown’.
location String The location of the Roll Call member. null indicates location of 'Unknown’.

Incident Roll Call My List

Roll Call My List is specific to each individual Roll Call administrator. It is the list of all Roll Call members whose status and/or location have been updated by that particular Roll Call administrator. The user making the request determines the list of Roll Call members returned.

Get Roll Call My List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-my-list"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-my-list" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-my-list"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
        "name": "John Doe",
        "email": "john.doe@domain.com"
      },
      "status": "Safe",
      "location": "Classroom",
      "permissions": [
          "get"
      ]
    },
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
        "name": "Jane Doe",
        "email": "jane.doe@domain.com"
      },
      "status": "Safe",
      "location": "Reunification Zone",
      "permissions": [
        "get"
      ]
    }
  ]
}

Retrieves the list of all Roll Call members whose status and/or location the requesting user has updated. If the requesting user has not updated any status or location of any Roll Call members, then an empty list will be returned. The requesting user can only get their own Roll Call My List, and will be unable to access any other user’s My List.

HTTP Request

GET /incidents/{incidentId}/rostering-my-list

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which Roll Call My List information is desired.

Query Parameters

Parameter Type Description
filterStatuses Array[string] A JSON-encoded array of statuses on which to filter Roll Call members. To filter on ‘Unknown’, include a status of null.
filterLocations Array[string] A JSON-encoded array of locations on which to filter Roll Call members. To filter on 'Unknown’, include a location of null.

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

Attribute Type Description
incidentId UUID The Incident to which the Roll Call member belongs.
memberUser Array[Object] A JSON object containing the user name, email, and ID for the Roll Call list member.
status String The status of the Roll Call member. null indicates status of 'Unknown’.
location String The location of the Roll Call member. null indicates location of 'Unknown’.

Incident Roll Call Report

The Incident Roll Call report contains the number of users currently assigned to each status in the Roll Call event. This is used to help incident administrators with directing the incident response.

Get Roll Call Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-report"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-report" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/rostering-report"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "statusCounts": [
    {"status":  "Safe", "count":  370},
    {"status":  "Injured", "count":  3},
    {"status":  null, "count":  23}
  ]
}

Retrieves the user counts for each status in the Roll Call event.

HTTP Request

GET /incidents/{incidentId}/rostering-report

Produces

application/json

Path Parameters

Parameter Description
incidentId The id of the Incident for which Roll Call information is desired.

Query Parameters

N/A

Response

Attribute Type Description
statusCounts Array[Object] A list of JSON objects that contain the status label and assigned user count for each status in the Roll Call incident. A status of null means ‘Unknown’

Incident Site

For Roll Call, the administrators and list of participants are determined by the Site assigned to the Incident, combined with the Site Roles configured in the Incident Plan. If an Incident is configured with Roll Call, the Roll Call event begins once a Site is assigned to the Incident.

Assign Incident Site

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/site"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'siteId': 'f4fb6922-18f3-11ed-adcc-d78288dc4cbe'

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/site" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"siteId": "f4fb6922-18f3-11ed-adcc-d78288dc4cbe"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/incidents/da757132-bd82-11eb-a95c-75282fb7d651/site"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'siteId': 'f4fb6922-18f3-11ed-adcc-d78288dc4cbe'
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
204 No Content

Assigns a Site to the specified Incident.

HTTP Request

POST /incidents/{incidentId}/site

Produces

204 No Content

Path Parameters

Parameter Description
incidentId The id of the Incident for which to assign the site.

Request Parameters

Parameter Type Required Description
siteId UUID Yes The id of the site to assign to the incident

Response

The response will be 204 No Content if successful, or a validation error if unsuccessful (e.g. the site was already assigned to another incident from the same incident plan).

License Acceptances

Future releases will include capabilities which must be licensed separately. This resource will allow the acceptance of such licenses to be recorded and reviewed.

List All License Acceptances

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/license-acceptances"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 3

}

begin: 
    acceptances = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(acceptances)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/license-acceptances?limit=3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/license-acceptances"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 3
}

try: 
    acceptances = requests.get(url, headers=headers, params=params).json()
    print(acceptances)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "type": "rapid-sos",
   "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
   "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
   "historicalUser": {
     "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
     "name": "Craig Smith",
     "email": "craig.smith@acme.com"
   },
   "acceptedAt": "2023-07-21T19:28:51.225Z",
   "createdAt": "2023-07-21T19:28:51.225Z",
   "permissions": [
    "get"
   ]
  }
 ]
}

Retrieves a list of all license acceptances.

HTTP Request

GET /license-acceptances

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 three acceptances were requested, there was only one available. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The license acceptance response format is detailed here.

Get a License Acceptance

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/license-acceptances/b77bb090-2fde-11e5-80c4-56847afe9799"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    acc = JSON.parse(HTTParty.get(url, headers: headers))
    puts(acc)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/license-acceptances/b77bb090-2fde-11e5-80c4-56847afe9799" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/license-acceptances/b77bb090-2fde-11e5-80c4-56847afe9799"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    acc = requests.get(url, headers=headers).json()
    print(acc)
except RequestException as e:
    print('Unexpected error!', e)
{
 "type": "rapid-sos",
 "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
 "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
 "historicalUser": {
   "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
   "name": "Craig Smith",
   "email": "craig.smith@acme.com"
 },
 "acceptedAt": "2023-07-21T19:28:51.225Z",
 "createdAt": "2023-07-21T19:28:51.225Z",
 "permissions": [
  "get"
 ]
}

Retrieves a single license acceptance by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /license-acceptances/{acceptanceId}

Produces

application/json

Path Parameters

Parameter Description
accepanceId The id of the License Acceptance of interest.

Response

The license acceptance response format is detailed here.

License Acceptance Response

The JSON document used to represent a license acceptance resource has the following content:

Attribute Type Description
acceptedAt ISO 8601 date/time When the license was accepted.
createdAt ISO 8601 date/time When this acceptance was created.
historicalUser Object Tracks the id, name, and email of the user who accepted the license, as they existed when the license was accepted.
id String The id of this specific license acceptance, allowing it to be retrieved individually.
licenseType String Identifies what kind of license was accepted. As licensed features are released, the list of valid options will be expanded.
userId String The id of the user who accepted the license.
permissions Array[String] Options: get. What operations are possible on this license acceptance resource itself.

Load Definitions

While a handful of user accounts can easily be set up individually through the InformaCast Mobile front end, using normal REST operations on the User resource, there is also a bulk-load mechanism which makes it easier to create and synchronize a larger number of users and assign them to Security Groups and Distribution Lists.

This is done by creating a Load Definition, which sets up basic parameters about how to deal with existing users during the loading process, and also enables the assignment of loaded users to security groups and distribution lists through Security Group Mappings, Distribution List Mappings, and Domain Mappings (if Domains are in use).

Once the load definition is set up appropriately, the bulk load operation is performed by posting a Load Request referencing the load definition, with the user data in a very simple CSV text format.

List All Load Definitions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "WyJzcGFyZSByZXRhaW5pbmcgbG9hZGVyIiwiNTk5ODhmNDAtMjNlOS0xMWU0LWI3ZWMtM2M5NzBlN2ZmNTYwIl0=",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "id": "17d02180-23e0-11e4-b7ec-3c970e7ff560",
      "createdAt": "2014-08-14T18:23:30.712Z",
      "name": "Primary Loader",
      "loadType": "csv",
      "deviceUpdatePolicy": "update",
      "domainUpdatePolicy": "update",
      "deletePolicy": "retain",
      "distributionListUpdatePolicy": "update",
      "securityGroupUpdatePolicy": "update",
      "sisAuthUrl": null,
      "sisBaseUrl: null,
      "sisClientId": null,
      "sisIncludeUserTypes": null
    }
  ]
}

Gets a list of all load definitions. (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 manipulate load definitions.)

HTTP Request

GET /load-definitions/

Produces

application/json

Query Parameters

To make this example more manageable, only the first load definition was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each load definition belongs.

Response

The load definition response format is detailed here.

Get a Load Definition

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    ld = JSON.parse(HTTParty.get(url, headers: headers))
    puts(ld)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    ld = requests.get(url, headers=headers).json()
    print(ld)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "id": "17d02180-23e0-11e4-b7ec-3c970e7ff560",
  "createdAt": "2014-08-14T18:23:30.712Z",
  "name": "Primary Loader",
  "loadType": "csv",
  "deviceUpdatePolicy": "update",
  "domainUpdatePolicy": "update",
  "deletePolicy": "retain",
  "distributionListUpdatePolicy": "update",
  "securityGroupUpdatePolicy": "update",
  "sisAuthUrl": null,
  "sisBaseUrl: null,
  "sisClientId": null,
  "sisIncludeUserTypes": null
}

Retrieves a single load definition by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /load-definitions/{loadDefinitionId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this load definition belongs.

Response

The load definition response format is detailed here.

Create a Load Definition

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Retaining User Loader'
,
    'deletePolicy': 'retain'

}

begin: 
    ld = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(ld)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Retaining User Loader", \
       "deletePolicy": "retain"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Retaining User Loader',
    'deletePolicy': 'retain'
}

try: 
    ld = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(ld)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-14T18:23:30.712Z",
  "id": "17d02180-23e0-11e4-b7ec-3c970e7ff560",
  "loadType": "csv",
  "deviceUpdatePolicy": "update",
  "domainUpdatePolicy": "update",
  "deletePolicy": "retain",
  "distributionListUpdatePolicy": "update",
  "securityGroupUpdatePolicy": "update",
  "name": "Retaining User Loader",
  "sisAuthUrl": null,
  "sisBaseUrl: null,
  "sisClientId": null,
  "sisIncludeUserTypes": null
}

Creates a new load definition. Once the load definition is created, Security Group Mappings, Distribution List Mappings, and Domain Mappings can be assigned to it, and then it can be used to bulk-load user accounts by posting a Load Request referencing it, with the user data in a very simple CSV text format.

HTTP Request

POST /load-definitions/

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
delete­Policy String retain Options: retain delete. Determines what should happen to user accounts that exist in the system which are not present in the uploaded data of a subsequent Load Request. The value delete causes unmatched users to be deleted from the system, while retain leaves them alone.
device­Update­Policy String update Options: update skip. Determines how to handle user devices when updating an existing user while processing a Load Request. The value skip causes devices to be left as-is, while update will change the user to reflect the values in the Load Request.
distribution­List­Update­Policy String update Options: update skip. Determines how to handle distribution list subscriptions when updating an existing user while processing a Load Request. The value skip causes subscriptions to be left as-is, while update will change the user to reflect the values in the Load Request.
domain­Update­Policy String update Options: update skip. Determines how to handle domains (if they are in use) when updating an existing user while processing a Load Request. The value skip causes the user’s domains to be left as-is, while update will move the user into the Domains tagged in the Load Request.
name String N/A A unique name for the load definition.
security­group­Update­Policy String update Options: update skip. Determines how to handle security group membership when updating an existing user while processing a Load Request. The value skip causes membership to be left as-is, while update will change the user to reflect the values in the Load Request.
loadType String csv Options: csv azure. This distinguishes between a loader that’s associated with a cloud IDP or loads CSV files. Currently the only IDP supported is Azure AD. This cannot be changed after loader creation.
sisAuthUrl String N/A Authentication URL for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisBaseUrl String N/A Base URL for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisClientId String N/A Client ID for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisClient­Secret N/A String Client Secret for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis on creation only.
sisInclude­UserTypes Object N/A List of types of users that should be imported from OneRoster, format detailed here

If there are no tags associated with

Response

The load definition response format is detailed here.

Update a Load Definition

# Continuing with the load definition object
# from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Non-retaining User Loader", \
       "deletePolicy": "delete"}'
# Continuing with the load definition object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "id": "17d02180-23e0-11e4-b7ec-3c970e7ff560",
  "createdAt": "2014-08-14T18:23:30.712Z",
  "name": "Non-retaining User Loader",
  "loadType": "csv",
  "deviceUpdatePolicy": "update",
  "domainUpdatePolicy": "update",
  "deletePolicy": "delete",
  "distributionListUpdatePolicy": "update",
  "securityGroupUpdatePolicy": "update"
}

Changes an existing load definition’s name or one of its policy entries.

HTTP Request

PUT /load-definitions/{loadDefinitionId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition to modify.

Request Parameters

Parameter Type Default Description
delete­Policy String retain Options: retain delete. Determines what should happen to user accounts that exist in the system which are not present in the uploaded data of a subsequent Load Request. The value delete causes unmatched users to be deleted from the system, while retain leaves them alone.
device­Update­Policy String update Options: update skip. Determines how to handle user devices when updating an existing user while processing a Load Request. The value skip causes devices to be left as-is, while update will change the user to reflect the values in the Load Request.
domain­Update­Policy String update Options: update skip. Determines how to handle domains (if they are in use) when updating an existing user while processing a Load Request. The value skip causes the user’s domains to be left as-is, while update will move the user into the Domains tagged in the Load Request.
distribution­List­Update­Policy String update Options: update skip. Determines how to handle distribution list subscriptions when updating an existing user while processing a Load Request. The value skip causes subscriptions to be left as-is, while update will change the user to reflect the values in the Load Request.
name String N/A A unique name for the load definition.
security­group­Update­Policy String update Options: update skip. Determines how to handle security group membership when updating an existing user while processing a Load Request. The value skip causes membership to be left as-is, while update will change the user to reflect the values in the Load Request.
sisAuthUrl String N/A Authentication URL for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisBaseUrl String N/A Base URL for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisClientId String N/A Client ID for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisClient­Secret N/A String Client Secret for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis on creation only.
sisInclude­UserTypes Object N/A List of types of users that should be imported from OneRoster, format detailed here

Response

The load definition response format is detailed here.

Remove a Load Definition

# Continuing with the load definition object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the load definition object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"LoadDefinitions\"} 17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Deletes an existing load definition.

HTTP Request

DELETE /load-definitions/{loadDefinitionId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition to delete.

Response

The deletion response format is detailed here.

Load Definition Response

Attribute Type Description
createdAt ISO 8601 date/time When this load definition was created.
delete­Policy String Options: retain delete. Determines what should happen to user accounts that exist in the system which are not present in the uploaded data of a subsequent Load Request. The value delete causes unmatched users to be deleted from the system, while retain leaves them alone.
device­Update­Policy String Options: update skip. Determines how to handle user devices when updating an existing user while processing a Load Request. The value skip causes devices to be left as-is, while update will change the user to reflect the values in the Load Request.
distribution­List­Update­Policy String Options: update skip. Determines how to handle distribution list subscriptions when updating an existing user while processing a Load Request. The value skip causes subscriptions to be left as-is, while update will change the user to reflect the values in the Load Request.
domains Array[Domain] When Domains are in use and includeDomains was true in your request, this response will list the Domains to which the load definition belongs.
domain­Update­Policy String Options: update skip. Determines how to handle domains (if they are in use) when updating an existing user while processing a Load Request. The value skip causes the user’s domains to be left as-is, while update will move the user into the Domains tagged in the Load Request.
name String The name of the load definition.
id String The id of this specific load definition, allowing it to be manipulated or retrieved individually, and to attach Security Group Mappings and Distribution List Mappings to it.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
security­group­Update­Policy String Options: update skip. Determines how to handle security group membership when updating an existing user while processing a Load Request. The value skip causes membership to be left as-is, while update will change the user to reflect the values in the Load Request.
loadType String Options: csv azure sis. This distinguishes between a loader that’s associated with a cloud IDP, a OneRoster endpoint, or loads CSV files. Currently the only IDP supported is Azure AD. This cannot be changed after loader creation.
applicationId UUID The application associated with the loader; only returned if the loader is not of type csv.
applicationToken String A token associated with the application user specified by the id above. Used to interface with cloud IDPs. Only returned if the loader is not of type csv, and only returned on a POST.
sisAuthUrl String Authentication URL for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisBaseUrl String Base URL for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisClientId String Client ID for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis.
sisClient­Secret String Client Secret for a OneRoster endpoint. Used to load users from a SIS. Required for loaders with loadType sis on creation only.
sisInclude­UserTypes Object List of types of users that should be imported from OneRoster, format detailed here

SIS User Types

Attribute Type Description
student boolean Whether to import students.
teachers boolean Whether to import teachers.
parentsGuardians boolean Whether to import parents/guardians.

Get a Load Definition Excel Template

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/31ace430-1f26-11e4-a54f-3c970e7ff560/template"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {

}

begin: 
    template = HTTParty.get(url, headers: headers, query: query)
    puts(template.headers['content-type'])   # application/xlsx
    f = open('Users.xlsx', 'w')
    f.write(template.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/31ace430-1f26-11e4-a54f-3c970e7ff560/template?" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/31ace430-1f26-11e4-a54f-3c970e7ff560/template"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {

}

try: 
    template = requests.get(url, headers=headers, params=params)
    print(template.headers['content-type'])   # application/xlsx
    f = open('Users.xlsx', 'w')
    f.write(template.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Retrieves a generated Excel spreadsheet template that a user can populate and then upload as a load request.

Produces a binary Excel spreadsheet file.

HTTP Request

GET /load-definitions/{loadDefinitionId}/template

Produces

application/xlsx

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition.

Load Definition Distribution List Mappings

Distribution list mappings provide a way to assign Users to Distribution Lists when processing a bulk user upload. They are attached to Load Definitions, and define a text tag, which when found in a user’s tags field in the bulk-load data, causes the user to be a member of the specified distribution list.

List All Distribution List Mappings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "distributionList": {
        "createdAt": "2014-08-06T18:51:33.590Z",
        "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
        "name": "Everyone"
      },
      "createdAt": "2014-08-14T19:45:21.024Z",
      "tagName": "Everyone",
      "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "id": "86964800-23eb-11e4-b7ec-3c970e7ff560",
      "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
    }
  ]
}

Gets a list of all distribution list mappings associated with a particular load definition. (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 manipulate load definitions.)

HTTP Request

GET /load-definitions/{loadDefinitionId}/distribution-list-mappings

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition whose distribution list mappings are being examined.

Query Parameters

To make this example more manageable, only the first distribution list mapping was requested using the API’s pagination parameters. The response shows that this was unnecessary, as there was only one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The distribution list mapping response format is detailed here.

Get a Distribution List Mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings/86964800-23eb-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    mapping = JSON.parse(HTTParty.get(url, headers: headers))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings/86964800-23eb-11e4-b7ec-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings/86964800-23eb-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    mapping = requests.get(url, headers=headers).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590Z",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-14T19:45:21.024Z",
  "tagName": "Everyone",
  "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
  "id": "86964800-23eb-11e4-b7ec-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Retrieves a single distribution list mapping by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /load-definitions/{loadDefinitionId}/distribution-list-mappings/{distributionListMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose distribution list mappings are being examined.
distributionListMappingId The id of the specific distribution list mapping to retrieve.

Response

The distribution list mapping response format is detailed here.

Create a Distribution List Mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'tagName': 'Faculty'
,
    'distributionListId': 'af94ef60-1d9a-11e4-a054-3c970e7ff560'

}

begin: 
    mapping = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "Faculty", \
       "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'tagName': 'Faculty',
    'distributionListId': 'af94ef60-1d9a-11e4-a054-3c970e7ff560'
}

try: 
    mapping = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590Z",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-15T15:41:19.228Z",
  "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
  "tagName": "Faculty",
  "id": "99cf43c0-2492-11e4-90ec-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Adds a distribution list mapping to a load definition.

HTTP Request

POST /load-definitions/{loadDefinitionId}/distribution-list-mappings

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition to which a distribution list mapping is to be added.

Request Parameters

Parameter Type Description
distribution­ListId String The id of a Distribution List to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this distribution list.

Response

The distribution list mapping response format is detailed here.

Update a Distribution List Mapping

# Continuing with the distribution list mapping
# object from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings/99cf43c0-2492-11e4-90ec-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "Staff", \
       "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560"}'
# Continuing with the distribution list mapping
# object from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "distributionList": {
    "createdAt": "2014-08-06T18:51:33.590Z",
    "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
    "name": "Everyone"
  },
  "createdAt": "2014-08-15T15:41:19.228Z",
  "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
  "tagName": "Staff",
  "id": "99cf43c0-2492-11e4-90ec-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Change the distributionListId and/or tagName of an existing distribution list mapping .

HTTP Request

PUT /load-definitions/{loadDefinitionId}/distribution-list-mappings/{distributionListMappingId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose distribution list mapping is to be updated.
distributionListMappingId The id of the specific distribution list mapping to update.

Request Parameters

Parameter Type Description
distribution­ListId String The id of a Distribution List to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this distribution list.

Response

The distribution list mapping response format is detailed here.

Remove a Distribution List Mapping

# Continuing with the distribution list mapping
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/distribution-list-mappings/99cf43c0-2492-11e4-90ec-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the distribution list mapping
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"LoadDefinitionDistributionListMappings\"} 99cf43c0-2492-11e4-90ec-3c970e7ff560"
}

Deletes a distribution list mapping.

HTTP Request

DELETE /load-definitions/{loadDefinitionId}/distribution-list-mappings/{distributionListMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose distribution list mapping is to be deleted.
distributionListMappingId The id of the specific distribution list mapping to delete.

Response

The deletion response format is detailed here.

Distribution List Mapping Response

Attribute Type Description
createdAt ISO 8601 date/time When this distribution list mapping was created.
load­DefinitionId String The id of the load definition to which this distribution list mapping belongs.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
id String The id of this specific distribution list mapping, allowing it to be manipulated or retrieved individually.
distribution­List DistributionList The Distribution List to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
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.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this distribution list.

Load Definition Domains

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 Load Definition Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "loadDefinitionId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "loadDefinitionId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Load Definition belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /load-definitions/{loadDefinitionId}/domains

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Load Definition 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 Load Definition 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 Load Definition, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the load definition whose domains were requested is returned under the key loadDefinitionId inside each domain response.

Check if a Load Definition contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "loadDefinitionId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Load Definition Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /load-definitions/{loadDefinitionId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition whose Domains are of interest.
id The id of the Domain you want to know whether the Load Definition belongs to.

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 Domains that are directly attached to the specified Load Definition, any of their subdomains will be considered.

Response

If the Load Definition is part of the Domain (or its subdomains, 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 Load Definition Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "loadDefinitionId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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 /load-definitions/{loadDefinitionId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
loadDefinitionId String The id of the Load Definition 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 Load Definition out of a parent Domain?
id String n/a The id of the Domain to which the Load Definition should be added.
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 Load Definition Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Load Definition c54e4241-299b-11e8-94d3-2be9464da125"
}

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 /load-definitions/{loadDefinitionId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
loadDefinitionId The id of the Load Definition whose Domain should be removed.
id The id of the Domain to be removed from the Load Definition.

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.

Load Definition Domain Mappings

Domain mappings provide a way to assign Users to Domains when processing a bulk user upload. They are attached to Load Definitions, and define a text tag, which when found in a user’s tags field in the bulk-load data, causes the user to be a member of the specified Domain.

If there are no Domain tags assigned to a user in the bulk-load data, the user will be created in the acting Domain in which the Load Request was posted.

List All Domain mappings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "id": "c9e7ad72-45a3-11e9-9372-d330df227886",
   "loadDefinitionId": "8bf05eaf-6be8-11e7-925b-49f9effcdeab",
   "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
   "tagName": "library",
   "domain": {
    "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
    "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
    "name": "Library",
    "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
    "namePath": "/Library/"
   },
   "createdAt": "2019-03-13T15:22:18.090Z",
   "permissions": [ "delete", "put", "get" ]
  }
 ]
}

Gets a list of all Domain mappings associated with a particular load definition. (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 manipulate load definitions.)

HTTP Request

GET /load-definitions/{loadDefinitionId}/domain-mappings

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition whose load definition mappings are being examined.

Query Parameters

To make this example more manageable, only the first Domain mapping was requested using the API’s pagination parameters. The response shows that this was unnecessary, as there was only one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The Domain mapping response format is detailed here.

Get a Domain mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings/c9e7ad72-45a3-11e9-9372-d330df227886"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    mapping = JSON.parse(HTTParty.get(url, headers: headers))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings/c9e7ad72-45a3-11e9-9372-d330df227886" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings/c9e7ad72-45a3-11e9-9372-d330df227886"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    mapping = requests.get(url, headers=headers).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "c9e7ad72-45a3-11e9-9372-d330df227886",
 "loadDefinitionId": "8bf05eaf-6be8-11e7-925b-49f9effcdeab",
 "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
 "tagName": "library",
 "domain": {
  "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
  "name": "Library",
  "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
  "namePath": "/Library/"
 },
 "createdAt": "2019-03-13T15:22:18.090Z",
 "permissions": [ "delete", "put", "get" ]
}

Retrieves a single Domain mapping by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /load-definitions/{loadDefinitionId}/domain-mappings/{domainMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose Domain mappings are being examined.
domainMappingId The id of the specific Domain mapping to retrieve.

Response

The Domain mapping response format is detailed here.

Create a Domain Mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'tagName': 'library'
,
    'domainId': 'd3651b0a-3357-11e8-98ef-81eb3ce85bec'

}

begin: 
    mapping = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "library", \
       "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'tagName': 'library',
    'domainId': 'd3651b0a-3357-11e8-98ef-81eb3ce85bec'
}

try: 
    mapping = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "c9e7ad72-45a3-11e9-9372-d330df227886",
 "loadDefinitionId": "8bf05eaf-6be8-11e7-925b-49f9effcdeab",
 "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
 "tagName": "library",
 "domain": {
  "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
  "name": "Library",
  "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
  "namePath": "/Library/"
 },
 "createdAt": "2019-03-13T15:22:18.090Z",
 "permissions": [ "delete", "put", "get" ]
}

Adds a Domain mapping to a load definition.

HTTP Request

POST /load-definitions/{loadDefinitionId}/domain-mappings

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition to which a Domain mapping is to be added.

Request Parameters

Parameter Type Description
domainId String The id of a Domain to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this Domain.

Response

The Domain mapping response format is detailed here.

Update a Domain Mapping

# Continuing with the domain mapping object
# from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings/d3651b0a-3357-11e8-98ef-81eb3ce85bec" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "EastLibrary", \
       "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec"}'
# Continuing with the domain mapping object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "c9e7ad72-45a3-11e9-9372-d330df227886",
 "loadDefinitionId": "8bf05eaf-6be8-11e7-925b-49f9effcdeab",
 "domainId": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
 "tagName": "EastLibrary",
 "domain": {
  "id": "d3651b0a-3357-11e8-98ef-81eb3ce85bec",
  "parentId": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
  "name": "Library",
  "path": "/d3651b0a-3357-11e8-98ef-81eb3ce85bec/",
  "namePath": "/Library/"
 },
 "createdAt": "2019-03-13T15:22:18.090Z",
 "permissions": [ "delete", "put", "get" ]
}

Change the domainId and/or tagName of an existing Domain mapping. The tagName was changed in the above example while leaving the associated domainId the same.

HTTP Request

PUT /load-definitions/{loadDefinitionId}/domain-mappings/{domainMappingId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose Domain mapping is to be updated.
domainMappingId The id of the specific Domain mapping to update.

Request Parameters

Parameter Type Description
domainId String The id of a Domain to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this Domain.

Response

The Domain mapping response format is detailed here.

Remove a Domain Mapping

# Continuing with the domain mapping object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/8bf05eaf-6be8-11e7-925b-49f9effcdeab/domain-mappings/c9e7ad72-45a3-11e9-9372-d330df227886" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain mapping object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted c9e7ad72-45a3-11e9-9372-d330df227886"
}

Deletes a Domain mapping.

HTTP Request

DELETE /load-definitions/{loadDefinitionId}/domain-mappings/{domainMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose Domain mapping is to be deleted.
domainMappingId The id of the specific Domain mapping to delete.

Response

The deletion response format is detailed here.

Domain Mapping Response

Attribute Type Description
createdAt ISO 8601 date/time When this Domain mapping was created.
load­DefinitionId String The id of the load definition to which this Domain mapping belongs.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
id String The id of this specific Domain mapping, allowing it to be manipulated or retrieved individually.
domain Domain The Domain to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
domainId String The id of the Domain above. This is what is actually stored; the expanded details about the Domain are returned as a convenience, to save clients from having to issue a separate request to look them up.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this Domain.

Load Definition Security Group Mappings

Security group mappings provide a way to assign Users to Security Groups when processing a bulk user upload. They are attached to Load Definitions, and define a text tag, which when found in a user’s tags field in the bulk-load data, causes the user to be a member of the specified security group.

List All Security Group Mappings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "securityGroup": {
        "createdAt": "2014-08-12T14:44:52.170Z",
        "id": "37b9faa0-222f-11e4-8f54-3c970e7ff560",
        "name": "Student Council Member"
      },
      "createdAt": "2014-08-14T19:45:11.204Z",
      "tagName": "Students",
      "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560",
      "id": "80bbde40-23eb-11e4-b7ec-3c970e7ff560",
      "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
    }
  ]
}

Gets a list of all security group mappings associated with a particular load definition. (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 manipulate load definitions.)

HTTP Request

GET /load-definitions/{loadDefinitionId}/security-group-mappings

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition whose security group mappings are being examined..

Query Parameters

To make this example more manageable, only the first security group mapping was requested using the API’s pagination parameters. The response shows that this was unnecessary, as there was only one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The security group mapping response format is detailed here.

Get a Security Group Mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings/80bbde40-23eb-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    mapping = JSON.parse(HTTParty.get(url, headers: headers))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings/80bbde40-23eb-11e4-b7ec-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings/80bbde40-23eb-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    mapping = requests.get(url, headers=headers).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "securityGroup": {
    "createdAt": "2014-08-12T14:44:52.170Z",
    "id": "37b9faa0-222f-11e4-8f54-3c970e7ff560",
    "name": "Student Council Member"
  },
  "createdAt": "2014-08-14T19:45:11.204Z",
  "tagName": "Students",
  "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560",
  "id": "80bbde40-23eb-11e4-b7ec-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Retrieves a single security group mapping by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /load-definitions/{loadDefinitionId}/security-group-mappings/{securityGroupMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose security group mappings are being examined.
securityGroupMappingId The id of the specific security group mapping to retrieve.

Response

The security group mapping response format is detailed here.

Create a Security Group Mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'tagName': 'Everyone'
,
    'securityGroupId': '5a218e70-19ae-11e4-9195-3c970e7ff560'

}

begin: 
    mapping = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "Everyone", \
       "securityGroupId": "5a218e70-19ae-11e4-9195-3c970e7ff560"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'tagName': 'Everyone',
    'securityGroupId': '5a218e70-19ae-11e4-9195-3c970e7ff560'
}

try: 
    mapping = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "securityGroup": {
    "createdAt": "2014-08-01T19:02:15.511Z",
    "id": "5a218e70-19ae-11e4-9195-3c970e7ff560",
    "name": "Administrators"
  },
  "createdAt": "2014-08-15T14:11:15.046Z",
  "securityGroupId": "5a218e70-19ae-11e4-9195-3c970e7ff560",
  "tagName": "Everyone",
  "id": "04aa8860-2486-11e4-90ec-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Adds a security group mapping to a load definition.

HTTP Request

POST /load-definitions/{loadDefinitionId}/security-group-mappings

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition to which a security group mapping is to be added.

Request Parameters

Parameter Type Description
security­GroupId String The id of a Security Group to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this security group.

Response

The security group mapping response format is detailed here.

Update a Security Group Mapping

# Continuing with the security group mapping
# object from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings/04aa8860-2486-11e4-90ec-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "Faculty", \
       "securityGroupId": "03f9a7f0-1d80-11e4-a054-3c970e7ff560"}'
# Continuing with the security group mapping
# object from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "securityGroup": {
    "createdAt": "2014-08-01T19:02:15.511Z",
    "id": "03f9a7f0-1d80-11e4-a054-3c970e7ff560",
    "name": "Faculty"
  },
  "createdAt": "2014-08-15T14:11:15.046Z",
  "securityGroupId": "03f9a7f0-1d80-11e4-a054-3c970e7ff560",
  "tagName": "Faculty",
  "id": "04aa8860-2486-11e4-90ec-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Change the securityGroupId and/or tagName of an existing security group mapping.

HTTP Request

PUT /load-definitions/{loadDefinitionId}/security-group-mappings/{securityGroupMappingId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose security group mapping is to be updated.
securityGroupMappingId The id of the specific security group mapping to modify.

Request Parameters

Parameter Type Description
security­GroupId String The id of a Security Group to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this security group.

Response

The security group mapping response format is detailed here.

Remove a Security Group Mapping

# Continuing with the security group mapping
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/security-group-mappings/04aa8860-2486-11e4-90ec-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the security group mapping
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"LoadDefinitionSecurityGroupMappings\"} 04aa8860-2486-11e4-90ec-3c970e7ff560"
}

Deletes a security group mapping.

HTTP Request

DELETE /load-definitions/{loadDefinitionId}/security-group-mappings/{securityGroupMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition containing the security group mapping to delete.
securityGroupMappingId The id of the specific security group mapping to delete.

Response

The deletion response format is detailed here.

Security Group Mapping Response

Attribute Type Description
createdAt ISO 8601 date/time When this security group mapping was created.
load­DefinitionId String The id of the load definition to which this security group mapping belongs.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
id String The id of this specific security group mapping, allowing it to be manipulated or retrieved individually.
security­Group SecurityGroup The Security Group to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
security­GroupId String The id of the Security Group above. This is what is actually stored; the expanded details about the Security Group are returned as a convenience, to save clients from having to issue a separate request to look them up.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned to this security group.

Load Definition User Type Mappings

User type mappings provide a way to assign user types to Users when processing a bulk user upload. They are attached to Load Definitions, and define a text tag, which when found in a user’s tags field in the bulk-load data, causes the user to be assigned the specified type.

The available types are regular (which corresponds to Individual) and rostered (which corresponds to Roll Call). A type of regular is a standard user who can log into the system, receive notifications, and be assigned permissions within the system. A user of type rostered is a user who cannot receive notifications or log into the system, but who can be used in the Roll Call feature.

The default user type when not specified is regular, so it is only necessary to define user type mappings if you are defining some of your users as rostered.

List All User Type Mappings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "id": "ab2e6d1e-434e-11ed-9833-c993f0e1ac8d",
      "loadDefinitionId": "9615277f-3b4e-11ed-8ed2-37d5bbca65fa",
      "userType": "rostered",
      "tagName": "rollCall",
      "createdAt": "2022-10-03T19:07:47.681Z",
      "permissions": [
        "get",
        "delete",
        "put"
      ]
    }
  ]
}

Gets a list of all user type mappings associated with a particular load definition. (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 manipulate load definitions.)

HTTP Request

GET /load-definitions/{loadDefinitionId}/user-type-mappings

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition user type mappings are being examined.

Query Parameters

To make this example more manageable, only the first user type mapping was requested using the API’s pagination parameters. The response shows that this was unnecessary, as there was only one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The user type mapping response format is detailed here.

Get a User Type Mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings/274ddef1-b979-11ee-ab2e-81a6c4d17ee7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    mapping = JSON.parse(HTTParty.get(url, headers: headers))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings/274ddef1-b979-11ee-ab2e-81a6c4d17ee7" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings/274ddef1-b979-11ee-ab2e-81a6c4d17ee7"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    mapping = requests.get(url, headers=headers).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "274ddef1-b979-11ee-ab2e-81a6c4d17ee7",
  "loadDefinitionId": "9615277f-3b4e-11ed-8ed2-37d5bbca65fa",
  "userType": "rostered",
  "tagName": "rollCall",
  "createdAt": "2024-01-22T22:54:09.666Z",
  "permissions": [
    "get",
    "delete",
    "put"
  ]
}

Retrieves a single user type mapping by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /load-definitions/{loadDefinitionId}/user-type-mappings/{userTypeMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose user type mappings are being examined.
userTypeMappingId The id of the specific user type mapping to retrieve.

Response

The user type mapping response format is detailed here.

Create a User Type Mapping

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'tagName': 'rollCall'
,
    'userType': 'rostered'

}

begin: 
    mapping = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(mapping)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "rollCall", \
       "userType": "rostered"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'tagName': 'rollCall',
    'userType': 'rostered'
}

try: 
    mapping = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(mapping)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "0281a215-b97b-11ee-ab2e-c7bf0482f07d",
  "loadDefinitionId": "9615277f-3b4e-11ed-8ed2-37d5bbca65fa",
  "userType": "rostered",
  "tagName": "rollCall",
  "createdAt": "2024-01-22T23:07:26.923Z",
  "permissions": [
    "get",
    "delete",
    "put"
  ]
}

Adds a user type mapping to a load definition. Note: the default user type is regular, so it is only necessary to define user type mappings if you are making use of the rostered user type.

HTTP Request

POST /load-definitions/{loadDefinitionId}/user-type-mappings

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition to which a type mapping mapping is to be added.

Request Parameters

Parameter Type Description
userType String The user type to assign to the user, either regular or rostered
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned this user type.

Response

The user type mapping response format is detailed here.

Update a User Type Mapping

# Continuing with the user type mapping object
# from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings/1c551d35-b97b-11ee-ab2e-011c7efa8554" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"tagName": "rollCall", \
       "userType": "rostered"}'
# Continuing with the user type mapping object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "1c551d35-b97b-11ee-ab2e-011c7efa8554",
  "loadDefinitionId": "9615277f-3b4e-11ed-8ed2-37d5bbca65fa",
  "userType": "rostered",
  "tagName": "rollCall",
  "createdAt": "2024-01-22T23:08:10.252Z",
  "permissions": [
    "get",
    "delete",
    "put"
  ]
}

Change the userType and/or tagName of an existing user type mapping .

HTTP Request

PUT /load-definitions/{loadDefinitionId}/user-type-mappings/{userTypeMappingId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose user type mapping is to be updated.
userTypeMappingId The id of the specific user type mapping mapping to update.

Request Parameters

Parameter Type Description
userType String The user type, either regular or rostered. This will be assigned to users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned user type.

Response

The user type mapping response format is detailed here.

Remove a User Type Mapping

# Continuing with the user type mapping object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/9615277f-3b4e-11ed-8ed2-37d5bbca65fa/user-type-mappings/1c551d35-b97b-11ee-ab2e-011c7efa8554" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the user type mapping object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "success",
  "resources": [
    {
      "id": "1c551d35-b97b-11ee-ab2e-011c7efa8554"
    }
  ]
}

Deletes a user type mapping.

HTTP Request

DELETE /load-definitions/{loadDefinitionId}/user-type-mappings/{userTypeMappingId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose user type mapping is to be deleted.
userTypeMappingId The id of the specific user type mapping to delete.

Response

The deletion response format is detailed here.

User Type Mapping Response

Attribute Type Description
createdAt ISO 8601 date/time When this user type mapping was created.
loadDefinitionId String The id of the load definition to which this user type mapping belongs.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
id String The id of this specific user type mapping, allowing it to be manipulated or retrieved individually.
userType String Options are regular or rostered. The user type to assign Users being uploaded to the system, if the corresponding tag is found on their line in the CSV upload.
tagName String A text label (containing no whitespace) which, when found in the tags field of a line in the CSV data being processed in a Load Request, will cause the user to be assigned this user type.

Load Requests

Example CSV file contents:

name, email, tags
Butch Cassidy, ridingdirty@yoyodyne.com, student
Jesse James, bushwhackersforever@outwest.us, student
Billy the Kid, wm.bonney@horse.com, student admin

Assuming this file is posted in a load request using a Load Definition which has one or more Security Group Mappings, Distribution List Mappings, and Domain Mappings associated with the tags student and admin, all three Users created or updated will be placed in the groups, lists, and/or domains assigned the student tag, and Billy the Kid will also be placed in the groups, lists, and/or domains assigned the admin tag. More details on the format can be found in the online help.

Posting a load request is how a Load Definition can be used to actually create or update a batch of Users in InformaCast Mobile. User information in a simple comma-separated-value text format or Excel spreadsheet (see the example on the right) is uploaded in the post request, and the rules and mappings that make up the load definition are used to appropriately adjust the Users resource.

The deletePolicy of the Load Definition controls what happens to users that existed in the system before the load request was posted, and which are not present in the uploaded data. They can either be deleted, or left alone.

If domains are in use, and there are no Domain Mapping tags present for a user that is being created, that user will be created in the acting Domain in which the Load Request was submitted. Similarly, if the user is being updated and there are no Domain Mapping tags present, their Domain memberships will be left alone even if the domainUpdatePolicy is set to update.

Once posted, the load request resource can be examined to see the status and results of the bulk load process.

List All Load Requests

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 8,
  "partial": true,
  "next": "ImU1MjhiMTQwLTI0YjQtMTFlNC05YWYzLTNjOTcwZTdmZjU2MCI=",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "containsLogs": true,
      "tagsSeen": ["student", "admin" ],
      "loadState": "finished",
      "createdAt": "2014-08-15T19:50:28.284Z",
      "id": "68242fc0-24b5-11e4-9af3-3c970e7ff560",
      "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
    }
  ]
}

Retrieves a list of all load requests that have been submitted for a particular load definition. (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 manipulate load requests.)

HTTP Request

GET /load-definitions/{loadDefinitionId}/load-requests

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the load definition whose load requests are to be examined.

Query Parameters

To make this example more manageable, only the first load request was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of eight available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The load request response format is detailed here.

Get a Load Request

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests/68242fc0-24b5-11e4-9af3-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    lr = JSON.parse(HTTParty.get(url, headers: headers))
    puts(lr)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests/68242fc0-24b5-11e4-9af3-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests/68242fc0-24b5-11e4-9af3-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    lr = requests.get(url, headers=headers).json()
    print(lr)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "containsLogs": true,
  "tagsSeen": ["student", "admin"],
  "loadState": "finished",
  "createdAt": "2014-08-15T19:50:28.284Z",
  "id": "68242fc0-24b5-11e4-9af3-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

Retrieves a single load request by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /load-definitions/{loadDefinitionId}/load-requests/{loadRequestId}

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition whose load requests are to be examined.
loadRequestId The id of the specific load request to retrieve.

Response

The load request response format is detailed here.

Batch Load Users

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
body = {'data': File.open('user_data.csv', 'rb')}

begin: 
    lr = JSON.parse(HTTParty.post(url, headers: headers, body: body))
    puts(lr)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -F "data=@user_data.csv;type=text/csv" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/load-definitions/17d02180-23e0-11e4-b7ec-3c970e7ff560/load-requests"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
files = {'data': ('data', open('user_data.csv', 'rb'), 'text/csv')}

try: 
    lr = requests.post(url, headers=headers, files=files).json()
    print(lr)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "containsLogs": false,
  "tagsSeen": [ ],
  "loadState": "queued",
  "createdAt": "2014-08-15T19:32:38.453Z",
  "id": "ea78ee50-24b2-11e4-bcfc-3c970e7ff560",
  "loadDefinitionId": "17d02180-23e0-11e4-b7ec-3c970e7ff560"
}

To kick off the process of batch loading users into the environment, a POST request is made to the Load Requests resource, and the CSV or Excel spreadsheet data describing the users to be loaded and their security group and distribution list tags is submitted in the post data. The load request is queued, and will be processed when the server has an opportunity. The current processing stage is reflected by the loadState attribute in the load request response.

HTTP Request

POST /load-definitions/{loadDefinitionId}/load-requests

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition that will be used to interpret the uploaded user data.

Request Parameters

Parameter Type Default Description
data File N/A The CSV formatted text or Excel spreadsheet describing the users to be created or updated according to the rules in the Load Definition.

Response

The load request response format is detailed here.

Load Request Response

Attribute Type Description
createdAt ISO 8601 date/time When this load request was submitted.
containsLogs Boolean A true or false flag that shows if the load request has associated logs.
id String The id of this specific load request, allowing it to be retrieved individually.
load­DefinitionId String The id of the Load Definition used to interpret the uploaded user data.
loadState String Options: queued running failed finished. The current processing state of this load request. Until it begins to be processed it is in the queued state. Once the server begins to process the request it enters the running state, from which it will eventually reach either the failed or finished state.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
tagsSeen Array[String] The set of tags that were matched in the uploaded user data.

Get Load Request Logs

HTTP Request

GET /load-definitions/{loadDefinitionId}/load-requests/{loadRequestId}/log

Produces

text/plain

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition that will be used to interpret the uploaded user data.
loadRequestId The id of the specific load request to retrieve.

Response

Returns the text content of the logs associated with this load request.

Get Load Request Content

HTTP Request

GET /load-definitions/{loadDefinitionId}/load-requests/{loadRequestId}/content

Produces

text/csv

Path Parameters

Parameter Description
loadDefinitionId The id of the Load Definition that will be used to interpret the uploaded user data.
loadRequestId The id of the specific load request to retrieve.

Response

Returns the text content of the csv associated with this load request.

Message Templates

As their name suggests, message templates form the basis of Notifications. The process of sending a notification begins when a User selects a message template to which they have been granted access. The template can provide a default subject, content, recipients, and confirmation request for the notification, and controls which fields the user is allowed to see and change in the process of sending the notification. Templates can range from fully locked down notifications which can only be sent as-is, to a blank slate with no default content, from which the sender can decide everything. Of course, the more that is pre-populated (and even hidden), the more quickly and efficiently a notification can be composed and sent when in a stressful situation, on a mobile client.

In order to control the visibility and changeability of notification features, the template attributes come in groups of three. For example, the subject attribute in the message template provides a default notification subject, while subjectCustomizable controls whether the sender is able to change the subject when sending a notification based on the template, and subjectDisplay specifies whether the subject should be visible at all during the sending process. The same pattern of related attribute names is used for other notification features. The ttsType attribute is considered part of the message audio, and so it can only be changed at send time when audioCustomizable is true.

The display-control attributes are an instruction to client applications working with the API, telling them when the corresponding notification features should be displayed to users who are using the template to send a notification. They have two possible values:

In order to support easy sending of follow-up notifications, a single message template can be marked for this kind of use by setting its followUp attribute to true, as described in the Response section. Because there can only be one such follow-up message template, even when domains are in use, the follow-up template can only be created and edited in the Root domain, but unlike other message templates, it will be visible and usable from all domains.

List All Message Templates

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 4,
  "partial": true,
  "previous": null,
  "next": "WyJoYWlsIiwiMzdmMGY1MDAtMWJlMC0xMWU0LTkxODEtM2M5NzBlN2ZmNTYwIl0=",
  "data": [
    {
      "distributionListIdsCustomizable": true,
      "subject": "Lunch options for this Friday",
      "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
      "userIdsCustomizable": false,
      "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
      "userIDs": ["685c2400-dd09-11e3-8c49-b8e856327746"],
      "confirmationRequestIdDisplay": "show",
      "bodyDisplay": "show",
      "ttsType": "none",
      "ttsSpeed": null,
      "audioDisplay": "show",
      "name": "Friday Food Choices",
      "imageCustomizable": false,
      "subjectCustomizable": false,
      "confirmationRequestIdCustomizable": false,
      "image": 0,
      "imageDisplay": "show",
      "audioCustomizable": false,
      "audio": 0,
      "alertTone": "default",
      "alertToneCustomizable": false,
      "alertToneDisplay": "show",
      "cancelNotificationsType": "none",
      "cancelNotificationsTypeDisplay": "hide",
      "confirmationRequestId": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-04T13:58:37.777Z",
      "updatedAt": "2014-08-04T13:58:37.777Z",
      "expiration": null,
      "incidentPlanId": null,
      "incidentPlanIdCustomizable": false,
      "incidentPlanIdDisplay": "show",
      "expirationCustomizable": false,
      "expirationDisplay": "show",
      "permissions": ["delete", "put", "get"],
      "distributionListIdsDisplay": "show",
      "userIdsDisplay": "show",
      "collaborationGroupIdsDisplay": "show",
      "collaborationGroupIdsCustomizable": false,
      "collaborationGroupIds": [],
      "deviceGroupIdsDisplay": "show",
      "deviceGroupIdsCustomizable": false,
      "deviceGroupIds": [],
      "deviceGroups": [],
      "collaborationGroups": [],
      "areaOfInterestIds": null,
      "areaOfInterestIdsCustomizable": false,
      "areasOfInterest": [],
      "areaOfInterestIdsDisplay": "show",
      "subjectDisplay": "show",
      "body": "Please take a second to select what you would like to eat this Friday. If you have any dietary restrictions, please let myself or a member of the culinary staff know.",
      "id": "6ec13410-1bdf-11e4-9181-3c970e7ff560",
      "distributionLists": [
        {
          "createdAt": "2014-08-06T18:51:33.590Z",
          "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
          "name": "Staff"
        }
      ],
      "users": [
        {
          "createdAt": "2014-05-16T14:50:22.656Z",
          "id": "685c2400-dd09-11e3-8c49-b8e856327746",
          "name": "Craig Smith"
        }
      ],
      "confirmationRequest": {
        "escalationRules": [ ],
        "createdAt": "2014-08-04T13:57:18.824Z",
        "id": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
        "options": ["Pizza", "Salad & Bread Sticks"],
        "name": "Food Options - Friday"
      },
      "bodyCustomizable": false,
      "followUp": false
    }
  ]
}

Retrieves a list of all message templates 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 message templates allows administrators to decide which users can send what content.)

HTTP Request

GET /message-templates

Produces

application/json

Query Parameters

To make this example more concise, only the first message template 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.
assoc-sync-state-for-endpoint String Include the current synchronization state for a specific fusion endpoint.
followUp Boolean Returns only Message Templates whose followUp attributes match the supplied value.
include­BinaryUrls Boolean If true, include signed CloudFront URLs for image/audio in the response when available.
include­ConfirmationRequest Boolean If false, omit an embedded Confirmation Request from the response.
includeDomains Boolean If true, include the list of Domains to which the message template belongs.
include­NotificationProfile Boolean If true, include an embedded Notification Profile in the response.
name String Returns only message templates whose names exactly match the supplied value

Response

The message template response format is detailed here.

Get a Message Template

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    mt = JSON.parse(HTTParty.get(url, headers: headers))
    puts(mt)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    mt = requests.get(url, headers=headers).json()
    print(mt)
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListIdsCustomizable": true,
  "subject": "Lunch options for this Friday",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "userIdsCustomizable": false,
  "userIDs": ["685c2400-dd09-11e3-8c49-b8e856327746"],
  "confirmationRequestIdDisplay": "show",
  "bodyDisplay": "show",
  "ttsType": "none",
  "ttsSpeed": null,
  "audioDisplay": "show",
  "name": "Friday Food Choices",
  "imageCustomizable": false,
  "subjectCustomizable": false,
  "confirmationRequestIdCustomizable": false,
  "image": 0,
  "imageDisplay": "show",
  "audioCustomizable": false,
  "audio": 0,
  "alertTone": "default",
  "alertToneCustomizable": false,
  "alertToneDisplay": "show",
  "cancelNotificationsType": "none",
  "cancelNotificationsTypeDisplay": "hide",
  "confirmationRequestId": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-04T13:58:37.777Z",
  "updatedAt": "2014-08-04T13:58:37.777Z",
  "expiration": null,
  "expirationCustomizable": false,
  "expirationDisplay": "show",
  "incidentPlanId": null,
  "incidentPlanIdCustomizable": false,
  "incidentPlanIdDisplay": "show",
  "permissions": ["delete", "put", "get"],
  "distributionListIdsDisplay": "show",
  "userIdsDisplay": "show",
  "subjectDisplay": "show",
  "collaborationGroupIdsDisplay": "show",
  "collaborationGroupIdsCustomizable": false,
  "collaborationGroupIds": [],
  "collaborationGroups": [],
  "deviceGroupIdsDisplay": "show",
  "deviceGroupIdsCustomizable": false,
  "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
  "deviceGroupIds": [],
  "deviceGroups": [],
  "areaOfInterestIds": null,
  "areaOfInterestIdsCustomizable": false,
  "areasOfInterest": [],
  "areaOfInterestIdsDisplay": "show",
  "body": "Please take a second to select what you would like to eat this Friday. If you have any dietary restrictions, please let myself or a member of the culinary staff know.",
  "id": "6ec13410-1bdf-11e4-9181-3c970e7ff560",
  "distributionLists": [
    {
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Staff"
    }
  ],
  "users": [
    {
      "createdAt": "2014-05-16T14:50:22.656Z",
      "id": "685c2400-dd09-11e3-8c49-b8e856327746",
      "name": "Craig Smith"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-04T13:57:18.824Z",
    "id": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
    "options": ["Pizza", "Salad & Bread Sticks"],
    "name": "Food Options - Friday"
  },
  "bodyCustomizable": false,
  "followUp": false
}

Retrieves a single message template based on its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /message-templates/{messageTemplateId}

Produces

application/json

Path Parameters

Parameter Description
messageTemplateId The id of the specific message template to retrieve.

Query Parameters

Parameter Type Description
followUp Boolean Returns only Message Templates whose followUp attributes match the supplied value.
include­BinaryUrls Boolean If true, include signed CloudFront URLs for image/audio in the response when available.
include­ConfirmationRequest Boolean If false, omit an embedded Confirmation Request from the response.
includeDomains Boolean If true, include the list of Domains to which the message template belongs.
include­NotificationProfile Boolean If true, include an embedded Notification Profile in the response.

Response

The message template response format is detailed here.

Create a Message Template

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Intruder Alert'
,
    'subject': 'An intruder has been spotted on campus'
,
    'body': '<To be customized at send time>'
,
    'bodyCustomizable': true
,
    'bodyDisplay': 'show'
,
    'confirmationRequestId': 'c7bc65e0-1bde-11e4-9181-3c970e7ff560'
,
    'distributionListIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff560'
]

}

begin: 
    mt = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(mt)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Intruder Alert", \
       "subject": "An intruder has been spotted on campus", \
       "body": "<To be customized at send time>", \
       "bodyCustomizable": true, \
       "bodyDisplay": "show", \
       "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560", \
       "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Intruder Alert',
    'subject': 'An intruder has been spotted on campus',
    'body': '<To be customized at send time>',
    'bodyCustomizable': true,
    'bodyDisplay': 'show',
    'confirmationRequestId': 'c7bc65e0-1bde-11e4-9181-3c970e7ff560',
    'distributionListIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff560']
}

try: 
    mt = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(mt)
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListIdsCustomizable": false,
  "subject": "An intruder has been spotted on campus",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "confirmationRequestIdDisplay": "show",
  "bodyDisplay": "show",
  "ttsType": "none",
  "ttsSpeed": null,
  "audioDisplay": "show",
  "name": "Intruder Alert",
  "imageCustomizable": false,
  "subjectCustomizable": false,
  "confirmationRequestIdCustomizable": false,
  "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
  "image": 0,
  "imageDisplay": "show",
  "audioCustomizable": false,
  "audio": 0,
  "alertTone": "default",
  "alertToneCustomizable": false,
  "alertToneDisplay": "show",
  "cancelNotificationsType": "none",
  "cancelNotificationsTypeDisplay": "hide",
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-04T13:58:37.777Z",
  "updatedAt": "2014-08-04T13:58:37.777Z",
  "expiration": null,
  "expirationCustomizable": false,
  "expirationDisplay": "show",
  "incidentPlanId": null,
  "incidentPlanIdCustomizable": false,
  "incidentPlanIdDisplay": "show",
  "permissions": ["delete", "put", "get"],
  "distributionListIdsDisplay": "show",
  "subjectDisplay": "show",
  "body": "<To be customized at send time>",
  "id": "31ace430-1f26-11e4-a54f-3c970e7ff560",
  "collaborationGroupIdsDisplay": "show",
  "collaborationGroupIdsCustomizable": false,
  "collaborationGroupIds": [],
  "collaborationGroups": [],
  "deviceGroupIdsDisplay": "show",
  "deviceGroupIdsCustomizable": false,
  "deviceGroupIds": [],
  "deviceGroups": [],
  "areaOfInterestIds": null,
  "areaOfInterestIdsCustomizable": false,
  "areasOfInterest": [],
  "areaOfInterestIdsDisplay": "show",
  "distributionLists": [
    {
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Staff"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-04T13:53:57.566Z",
    "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
    "options": ["Yes, I've seen the intruder", "No, I haven't"],
    "name": "Have you seen the intruder?"
  },
  "bodyCustomizable": true,
  "followUp": false
}

Creates a new message template (limit: 3500).

HTTP Request

POST /message-templates

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
alertTone String default Option: default, 911-dialed, accent, all-clear1, all-clear2, bell, bright, chime, chirp, class-change1, class-change2, class-change3, class-change4, class-change5, class-change6, code-blue, code-call, crystal, eas, eas-intro, evacuate1, evacuate2, evacuate3, evacuate4, fire-alarm, industrial-alarm, internal-emergency1, internal-emergency2, internal-emergency3, klaxon, location-closing, lockdown-1-pulse, lockdown-2-pulses, lockdown-3-pulses, lockdown, room-turn, severe-weather-advisory, shift-change1, shift-change2, shift-change3, shift-change4, silent, take-shelter, tone, tornado-siren. Controls the sound played by a mobile phone or other compatible InformaCast Fusion Devices (i.e. desktops) when this message template is sent. default means to play the standard alert tone chosen by the device’s owner, silent means to play no tone, and the others choose specific named sounds.
alertTone­Customizable Boolean false Whether the mobile push alert tone can be changed when sending notifications based on this template.
alertTone­Display String hide Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the alert tone section should be displayed to senders when composing a notification based on this template. Can no longer be set independently.
areaOf­Interest­Ids Array[UUID] N/A The ids of the Areas of Interest to which notifications based on this template should be sent.
areaOf­InterestIds­Customizable Boolean false Whether the areas of interest can be changed when sending notifications based on this template.
areaOf­InterestIds­Display String hide* Option: hide, show. Informs client applications whether the area of interest section should be displayed to senders when composing a notification based on this template. *Defaults to show when areaOfInterestIds are supplied.
audio Blob N/A Default audio content. Binary stream of audio. The audio formats accepted include μ-law, Opus, MP3, Vorbis, or some other common WAV formats. Non μ-law files will be converted to μ-law and the size of the converted audio must not exceed 10 MiB.
audio­Customizable Boolean false Whether the attached audio can be changed when sending notifications based on this template.
audio­Display String hide* Option: hide, show. Informs client applications whether the audio section should be displayed to senders when composing a notification based on this template. *Defaults to show when audio is present.
body String N/A Default optional detailed body text. This may be up to 10,000 characters long.
body­Customizable Boolean false Whether the body text can be changed when sending notifications based on this template.
bodyDisplay String show Deprecated (body is now always shown). Option: show. This attribute can no longer change and will be removed in a future release.
cancel­NotificationsType String none Option: none, all, specific. When a notification sent with this message template, determines what other notifications should be canceled, none, all, or some based on the message templates used for those other notification sends.
cancel­NotificationsType­Display String hide Option: hide, show. Informs client applications whether the cancellation section should be displayed to senders when composing a notification based on this template.
collaboration­GroupIds Array[String] N/A The ids of Collaboration Groups who should, by default, receive notifications based on this template.
collaboration­GroupIds­Customizable Boolean false Whether the collaboration groups can be changed when sending notifications based on this template.
collaboration­GroupIds­Display String hide* Option: hide, show. Informs client applications whether the collaboration groups section should be displayed to senders when composing a notification based on this template. *Defaults to show when collaborationGroupIds are supplied.
confirmation­RequestId String N/A The id of the Confirmation Request to send with the notification, if any.
confirmation­RequestId­Customizable Boolean false Whether the confirmation request can be changed when sending notifications based on this template.
confirmation­RequestId­Display String hide* Option: hide, show. Informs client applications whether the confirmation request section should be displayed to senders when composing a notification based on this template. *Defaults to show when confirmationRequestId is present.
device­GroupIds Array[String] N/A The ids of Device Groups who should, by default, receive notifications based on this template.
device­GroupIds­Customizable Boolean false Whether the device groups can be changed when sending notifications based on this template.
device­GroupIds­Display String hide* Option: hide, show. Informs client applications whether the device groups section should be displayed to senders when composing a notification based on this template. *Defaults to show when deviceGroupIds are supplied.
distribution­ListIds Array[String] N/A A list of ids of Distribution Lists which should, by default, receive notifications based on this template.
distribution­ListIds­Customizable Boolean false Whether the recipient distribution lists can be changed when sending notifications based on this template.
distribution­ListIds­Display String hide* Option: hide, show. Informs client applications whether the distribution lists section should be displayed to senders when composing a notification based on this template. *Defaults to show when distributionListIds are supplied.
expiration Integer null The time in seconds the notification should expire from the time it is sent. (A null value indicates the notification does not expire.)
expiration­Customizable Boolean false Whether the expiration can be changed when sending notifications based on this template.
expiration­Display String hide* Option: hide, show. Informs client applications whether the expiration section should be displayed to senders when composing a notification based on this template. *Defaults to show when expiration is present.
image Blob N/A Binary stream of the default image to send with the notification. The size of the image must not exceed 10 MiB.
image­Customizable Boolean false Whether the attached image can be changed when sending notifications based on this template.
image­Display String hide* Option: hide, show. Informs client applications whether the image section should be displayed to senders when composing a notification based on this template. *Defaults to show when image is present.
incident­PlanId UUID N/A The Incident Plan to use for the incident created from this message template, if any.
incident­PlanId­Customizable Boolean false Whether the attached incident plan can be changed when sending notifications based on this template.
incident­PlanId­Display String hide* Option: hide, show. Informs client applications whether the incident plan section should be displayed to senders when composing a notification based on this template. *Defaults to show when incidentPlanId is present.
include­BinaryUrls Boolean false Whether to include signed CloudFront URLs for image/audio in the response when available.
include­ConfirmationRequest Boolean true Include an embedded Confirmation Request in the response.
include­NotificationProfile Boolean false Include an embedded Notification Profile in the response.
include­MessageTemplate­CancellationIds Boolean false Include the list of cancellation ids for the message template in the response.
messageTemplate­CancellationIds Array[String] N/A A list of ids of Message Templates. Notifications sent by these message templates will be canceled by any sends of the message template described in the response.
name String N/A The name of the message template. This may be up to 140 characters long.
notification­ProfileId String N/A The id of the Notification Profile to configure the notification with. Omitting this value will default it to the Default Notification Profile.
subject­Customizable Boolean false Whether the subject can be changed when sending notifications based on this template.
subject­Display String show Deprecated (subject is always shown). Option: show. This attribute can no longer be changed and will be removed in a future release.
ttsCustom­Content String N/A Custom text used for synthesized speech when ttsType is custom-text or custom-ssml.
ttsCustom­Content­Customizable Boolean false Whether the custom text-to-speech content can be changed when sending notifications based on this template.
ttsCustom­Content­Display String hide Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the custom text-to-speech content section should be displayed to senders when composing a notification based on this template. Can no longer be set independently.
ttsSpeed String normal Option: very-slow, slow, normal, fast, very-fast. The rate at which the text will be spoken.
ttsType String none Option: none, subject, body, subject-and-body, custom-text, custom-ssml. Controls which attributes are transformed into speech audio, and how. This is considered part of the message audio, so it can only be overridden at send time when audioCustomizable is true.
ttsVoiceId UUID N/A Specifies the Text-to-Speech Voice to be used when synthesizing audio for this message template.
ttsVoiceId­Customizable Boolean false Whether the Text-to-Speech Voice can be changed when sending notifications based on this template.
ttsVoiceId­Display String hide Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the Text-to-Speech Voice section should be displayed to senders when composing a notification based on this template. Can no longer be set independently.
user­Ids Array[String] N/A The ids of individual Users who should, by default, receive notifications based on this template, regardless of their distribution list memberships.
userIds­Customizable Boolean false Whether the individual recipient users can be changed when sending notifications based on this template.
userIds­Display String hide* Option: hide, show. Informs client applications whether the individual user section should be displayed to senders when composing a notification based on this template. *Defaults to show when userIds are supplied.

Response

The message template response format is detailed here.

Update a Message Template

Updates an existing message template.

# Continuing with the message template object
# from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/31ace430-1f26-11e4-a54f-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Intruder Alert", \
       "subject": "An intruder matching the description <description here> has been spotted!", \
       "body": "The intruder was last seen <insert location here>.", \
       "subjectCustomizable": true, \
       "subjectDisplay": "show"}'
# Continuing with the message template object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListIdsCustomizable": false,
  "subject": "An intruder matching the description <description here> has been spotted!",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "confirmationRequestIdDisplay": "hide",
  "bodyDisplay": "show",
  "ttsType": "none",
  "ttsSpeed": null,
  "audioDisplay": "show",
  "name": "Intruder Alert",
  "imageCustomizable": false,
  "subjectCustomizable": true,
  "confirmationRequestIdCustomizable": false,
  "image": 0,
  "imageDisplay": "show",
  "audioCustomizable": false,
  "audio": 0,
  "alertTone": "default",
  "alertToneCustomizable": false,
  "alertToneDisplay": "show",
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-08T18:02:43.059Z",
  "updatedAt": "2014-08-10T13:58:37.777Z",
  "incidentPlanId": null,
  "incidentPlanIdCustomizable": false,
  "incidentPlanIdDisplay": "show",
  "permissions": ["delete", "put", "get"],
  "distributionListIdsDisplay": "show",
  "subjectDisplay": "show",
  "body": "The intruder was last seen <insert location here>.",
  "id": "31ace430-1f26-11e4-a54f-3c970e7ff560",
  "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
  "collaborationGroupIdsDisplay": "show",
  "collaborationGroupIdsCustomizable": false,
  "collaborationGroupIds": [],
  "collaborationGroups": [],
  "deviceGroupIdsDisplay": "show",
  "deviceGroupIdsCustomizable": false,
  "deviceGroupIds": [],
  "deviceGroups": [],
  "distributionLists": [
    {
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Staff"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-04T13:53:57.566Z",
    "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
    "options": ["Yes, I've seen the intruder", "No, I haven't"],
    "name": "Have you seen the intruder?"
  },
  "bodyCustomizable": false,
  "followUp": false
}

HTTP Request

PUT /message-templates/{messageTemplateId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
messageTemplateId The id of the message template to update.

Request Parameters

Parameter Required Default Description
alertTone String default Controls the sound played by a mobile phone or other compatible InformaCast Fusion Devices (i.e. desktops) when this message template is sent. Possible values match those listed for alertTone in Create a Message Template.
alertTone­Customizable Boolean false Whether the mobile push alert tone can be changed when sending notifications based on this template.
alertTone­Display String hide Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the alert tone section should be displayed to senders when composing a notification based on this template. Can no longer be set independently.
areaOf­Interest­Ids Array[UUID] N/A The ids of the Areas of Interest to which notifications based on this template should be sent.
areaOf­InterestIds­Customizable Boolean false Whether the areas of interest can be changed when sending notifications based on this template.
areaOf­InterestIds­Display String hide* Option: hide, show. Informs client applications whether the area of interest section should be displayed to senders when composing a notification based on this template. *Defaults to show when areaOfInterestIds are supplied.
audio Blob N/A Default audio content. Binary stream of audio. The audio formats accepted include μ-law, Opus, MP3, Vorbis, or some other common WAV formats. Non μ-law files will be converted to μ-law and the size of the converted audio must not exceed 10 MiB.
audio­Customizable Boolean false Whether the attached audio can be changed when sending notifications based on this template.
audio­Display String hide* Option: hide, show. Informs client applications whether the audio section should be displayed to senders when composing a notification based on this template. *Defaults to show when audio is present.
body String N/A Default optional detailed body text. This may be up to 10,000 characters long.
body­Customizable Boolean false Whether the body text can be changed when sending notifications based on this template.
body­Display String show Deprecated (body is always shown). Option: show. This attribute can no longer be changed and will be removed in a future release.
collaboration­GroupIds Array[String] N/A The ids of Collaboration Groups who should, by default, receive notifications based on this template.
collaboration­GroupIds­Customizable Boolean false Whether the collaboration groups can be changed when sending notifications based on this template.
collaboration­GroupIds­Display String hide* Option: hide, show. Informs client applications whether the collaboration groups section should be displayed to senders when composing a notification based on this template. *Defaults to show when collaborationGroupIds are supplied.
confirmation­RequestId String N/A The id of the Confirmation Request to send with the notification, if any.
confirmation­RequestId­Customizable Boolean false Whether the confirmation request can be changed when sending notifications based on this template.
confirmation­RequestId­Display String hide* Option: hide, show. Informs client applications whether the confirmation request section should be displayed to senders when composing a notification based on this template. *Defaults to show when confirmationRequestId is present.
device­GroupIds Array[String] N/A The ids of Device Groups who should, by default, receive notifications based on this template.
device­GroupIds­Customizable Boolean false Whether the device groups can be changed when sending notifications based on this template.
device­GroupIds­Display String hide* Option: hide, show. Informs client applications whether the device groups section should be displayed to senders when composing a notification based on this template. *Defaults to show when deviceGroupIds are supplied.
distribution­ListIds Array[String] N/A A list of ids of Distribution Lists which should, by default, receive notifications based on this template.
distribution­ListIds­Customizable Boolean false Whether the recipient distribution lists can be changed when sending notifications based on this template.
distribution­ListIds­Display String hide* Option: hide, show. Informs client applications whether the distribution lists section should be displayed to senders when composing a notification based on this template. *Defaults to show when distributionListIds are supplied.
image Blob N/A Binary stream of the default image to send with the notification. The size of the image must not exceed 10 MiB.
image­Customizable Boolean false Whether the attached image can be changed when sending notifications based on this template.
image­Display String hide* Option: hide, show. Informs client applications whether the image section should be displayed to senders when composing a notification based on this template. *Defaults to show when image is present.
incident­PlanId UUID N/A The Incident Plan to use for the incident created from this message template, if any.
incident­PlanId­Customizable Boolean false Whether the attached incident plan can be changed when sending notifications based on this template.
incident­PlanId­Display String hide* Option: hide, show. Informs client applications whether the incident plan section should be displayed to senders when composing a notification based on this template. *Defaults to show when incidentPlanId is present.
include­BinaryUrls Boolean false Whether to include signed CloudFront URLs for image/audio in the response when available.
include­ConfirmationRequest Boolean true Include an embedded Confirmation Request in the response.
include­NotificationProfile Boolean false Include an embedded Notification Profile in the response.
name String N/A The name of the message template. This may be up to 140 characters long.
notification­ProfileId String N/A The id of the Notification Profile to configure the notification with. Omitting this value will default it to the Default Notification Profile.
subject String N/A Default subject for notifications based on the message template. This may be up to 256 characters long.
subject­Customizable Boolean false Whether the subject can be changed when sending notifications based on this template.
subject­Display String show Deprecated (subject is always shown). Option: show. This attribute can no longer be changed and will be removed in a future release.
ttsCustom­Content String N/A Custom text used for synthesized speech when ttsType is custom-text or custom-ssml.
ttsCustom­Content­Customizable Boolean false Whether the custom text-to-speech content can be changed when sending notifications based on this template.
ttsCustom­Content­Display String hide Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the custom text-to-speech content section should be displayed to senders when composing a notification based on this template. Can no longer be set independently.
ttsSpeed String normal Option: very-slow, slow, normal, fast, very-fast. The rate at which the text will be spoken.
ttsType String none Option: none, subject, body, subject-and-body, custom-text, custom-ssml. Controls which attributes are transformed into speech audio, and how.
ttsVoiceId UUID N/A Specifies the Text-to-Speech Voice to be used when synthesizing audio for this message template.
ttsVoiceId­Customizable Boolean false Whether the Text-to-Speech Voice can be changed when sending notifications based on this template.
ttsVoiceId­Display String hide Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the Text-to-Speech Voice section should be displayed to senders when composing a notification based on this template. Can no longer be set independently.
user­Ids Array[String] N/A The ids of individual Users who should, by default, receive notifications based on this template, regardless of their distribution list memberships.
userIds­Customizable Boolean false Whether the individual recipient users can be changed when sending notifications based on this template.
userIds­Display String hide* Option: hide, show. Informs client applications whether the individual user section should be displayed to senders when composing a notification based on this template. *Defaults to show when userIds are supplied.

Response

The message template response format is detailed here.

Remove a Message Template

# Continuing with the message template object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/31ace430-1f26-11e4-a54f-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the message template object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"MessageTemplates\"} 31ace430-1f26-11e4-a54f-3c970e7ff560"
}

Deletes a message template by id.

HTTP REQUEST

DELETE /message-templates/{messageTemplateId}

Produces

application/json

Path Parameters

Parameter Description
messageTemplateId The id of the message template to delete.

Response

The deletion response format is detailed here.

Get a Template’s Audio

# Continuing with the message template object
# from the previous example:
begin:
    sound = HTTParty.get(url, headers: headers)
    puts(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/31ace430-1f26-11e4-a54f-3c970e7ff560/audio" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the message template object
# from the previous example:
try:
    sound = requests.get(url, headers=headers)
    print(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Retrieves the audio, if any, that is attached to the template, as a binary stream. Typically this is μ-law encoded compressed audio. For improved performance, this will likely involve redirection (via an HTTP 302 Redirect response) to an AWS CloudFront content distribution network node which has cached the content closer geographically to where the request originated than the Singlewire REST API servers.

Produces a binary stream of audio data, with the specific MIME type identified in the response header. Will likely involve redirection to a content distribution network server closer to where the request originated.

HTTP Request

GET /message-templates/{messageTemplateId}/audio

Produces

audio/wav, audio/u-law

Path Parameters

Parameter Description
messageTemplateId The id of the message template for which the audio data is desired.

Request Parameters

Parameter Type Default Description
convert String null Deprecated: Specify a value of pcm to request that the server convert the audio to PCM (WAV) format from μ-law. This takes more network bandwidth, so should only be done if the client cannot handle μ-law compression.

Get a Template’s Image

# Continuing with the message template object
# from the previous example:
begin:
    pic = HTTParty.get(url, headers: headers)
    puts(pic.headers['content-type'])   # e.g. image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/31ace430-1f26-11e4-a54f-3c970e7ff560/image" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the message template object
# from the previous example:
try:
    pic = requests.get(url, headers=headers)
    print(pic.headers['content-type'])   # e.g. image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Retrieves the image, if any, attached to the message template, as a binary stream. For improved performance, this will likely involve redirection (via an HTTP 302 Redirect response) to an AWS CloudFront content distribution network node which has cached the content closer geographically to where the request originated than the Singlewire REST API servers.

Produces a binary stream of the image data, with the specific MIME type identified in the response header. Will likely involve redirection to a content distribution network server closer to where the request originated.

HTTP Request

GET /message-templates/{messageTemplateId}/image

Produces

image/png image/jpeg image/gif

Path Parameters

Parameter Description
messageTemplateId The id of the message template for which the image data is desired.

Message Template Response

The JSON document used to represent a message template resource has the following content:

Attribute Type Description
alertTone String Controls the sound played by a mobile phone or other compatible InformaCast Fusion Devices (i.e. desktops) when this message template is sent. Possible values match those listed for alertTone in Create a Message Template.
alertTone­Customizable Boolean Whether the mobile push alert tone can be changed when sending notifications based on this template.
alertTone­Display String Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the alert tone section should be displayed to senders when composing a notification based on this template.
areaOf­Interest­Ids Array[String] The ids of the Areas of Interest to which notifications based on this template should be sent.
areaOf­InterestIds­Customizable Boolean Whether the areas of interest can be changed when sending notifications based on this template.
areaOf­InterestIds­Display String Option: hide, show. Informs client applications whether the area of intererst section should be displayed to senders when composing a notification based on this template.
audio Integer The size of the default audio attached to the message template, in bytes. Zero if there is no audio. (This is now redundant with the audioFiles attribute, and will likely be deprecated and removed in a future release.)
audio­Customizable Boolean Whether the attached audio can be changed when sending notifications based on this template.
audio­Display String Option: hide, show. Informs client applications whether the audio section should be displayed to senders when composing a notification based on this template.
audioFiles Array[Object] Lists information about the default audio files attached to the message template. Currently there will only be one, but future releases may support multiple audio streams with different purposes or quality. Each entry in the array is a file description object.
body String Default optional detailed body text. This may be up to 10,000 characters long.
body­Customizable Boolean Whether the body text can be changed when sending notifications based on this template.
body­Display String Deprecated (body is always shown). Option: show. This attribute can no longer be changed and will be removed in a future release.
collaboration­GroupIds Array[String] The ids of Collaboration Groups who should, by default, receive notifications based on this template.
collaboration­GroupIds­Customizable Boolean Whether the collaboration groups can be changed when sending notifications based on this template.
collaboration­GroupIds­Display String Option: hide, show. Informs client applications whether the collaboration groups section should be displayed to senders when composing a notification based on this template.
confirmation­Request Confirmation­Request The default Confirmation Request to send with the notification, if any. This can be omitted by passing a false value for the query parameter includeConfirmationRequest.
confirmation­RequestId String The id of the Confirmation Request, above. This is what is actually stored; the expanded details about the Confirmation Request are returned as a convenience, to save clients from having to issue a separate request to look them up.
confirmation­RequestId­Customizable Boolean Whether the confirmation request can be changed when sending notifications based on this template.
confirmation­RequestId­Display String Option: hide, show. Informs client applications whether the confirmation request section should be displayed to senders when composing a notification based on this template.
createdAt ISO 8601 date/time When this message template was created.
updatedAt ISO 8601 date/time When this message template was last updated.
device­GroupIds­Customizable Boolean Whether the device groups can be changed when sending notifications based on this template.
device­GroupIds Array[String] The ids of Device Groups who should, by default, receive notifications based on this template.
device­GroupIds­Display String Option: hide, show. Informs client applications whether the device groups section should be displayed to senders when composing a notification based on this template.
distribution­Lists Array[Dist­ributionList] The list of Distribution Lists which should, by default, receive notifications based on this template.
distribution­ListIds Array[String] The ids of the distribution lists, above. This is what is actually stored; the expanded details about the Distribution Lists are returned as a convenience, to save clients from having to issue a separate request to look them up.
distribution­ListIds­Customizable Boolean Whether the recipient distribution lists can be changed when sending notifications based on this template.
distribution­ListIds­Display String Option: hide, show. Informs client applications whether the distribution lists section should be displayed to senders when composing a notification based on this template.
domains Array[Domain] When Domains are in use and includeDomains was true in your request, this response will list the Domains to which the Message Template belongs.
follow­Up Boolean Denotes whether this template is usable for a follow-up. If set true, this template can be used as the messageTemplateId when sending a new notification based on an existing notification in history. If set false and attempting to use this template in the same manner, an error will occur. Message templates that support a follow-up are subject to different validation rules (i.e. all recipient fields can be set non-customizable in addition to specifying no recipients when saving the template).
id String The id of this specific message template, allowing it to be manipulated or retrieved individually, used to send a Notification, and providing access to its audio and image.
image Integer The size of the default image attached to the message template, in bytes. Zero if there is no image. (This is now redundant with the imageFiles attribute, and will likely be deprecated and removed in a future release.)
image­Customizable Boolean Whether the attached image can be changed when sending notifications based on this template.
image­Display String Option: hide, show. Informs client applications whether the image section should be displayed to senders when composing a notification based on this template.
imageFiles Array[Object] Lists information about the default image files attached to the message template. Currently there will only be one, but future releases may support multiple audio streams with different purposes or quality. Each entry in the array is a file description object.
image­MimeType String Options: image/png image/jpeg image/gif. The content type of the default image attached to the message template, if there is one. (This is now redundant with the imageFiles attribute, and will likely be deprecated and removed in a future release.)
incident­PlanId UUID The Incident Plan to use for the incident created from this message template, if any.
incident­PlanId­Customizable Boolean Whether the attached incident plan can be changed when sending notifications based on this template.
incident­PlanId­Display String Option: hide, show. Informs client applications whether the incident plan section should be displayed to senders when composing a notification based on this template.
name String The name of the message template. This may be up to 140 characters long.
notification­Profile Notification Profile The Notification Profile to configure the notification with. This will only be included if you pass a true value for the query parameter includeNotificationProfile.
notification­ProfileId String The id of the Notification Profile, above. This is what is actually stored; the expanded details about the Notification Profile are returned as a convenience, to save clients from having to issue a separate request to look them up.
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 Default subject for notifications based on the message template. This may be up to 256 characters long.
subject­Customizable Boolean Whether the subject can be changed when sending notifications based on this template.
subject­Display String Deprecated (subject is always shown). Option: show. This attribute can no longer be changed and will be removed in a future release.
syncState Array[Object] The endpoints’ sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
endpointSyncState Object The specific endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state-for-endpoint is true.
ttsCustom­Content String Custom text used for synthesized speech when ttsType is custom-text or custom-ssml.
ttsCustom­Content­Customizable Boolean Whether the custom text-to-speech content can be changed when sending notifications based on this template.
ttsCustom­Content­Display String Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the custom text-to-speech content section should be displayed to senders when composing a notification based on this template.
ttsSpeed String Option: very-slow, slow, normal, fast, very-fast. The rate at which the text will be spoken.
ttsType String Option: none, subject, body, subject-and-body, custom-text, custom-ssml. Controls which attributes are transformed into speech audio, and how.
ttsVoiceId UUID Specifies the Text-to-Speech Voice to be used when synthesizing audio for this message template.
ttsVoiceId­Customizable Boolean Whether the Text-to-Speech Voice can be changed when sending notifications based on this template.
ttsVoiceId­Display String Deprecated (controlled by audioDisplay). Option: hide, show. Informs client applications whether the Text-to-Speech Voice section should be displayed to senders when composing a notification based on this template.
user­Ids Array[String] The ids of individual Users who should, by default, receive notifications based on this template, regardless of their distribution list memberships.
userIds­Customizable Boolean Whether the individual recipient users can be changed when sending notifications based on this template.
userIds­Display String Option: hide, show. Informs client applications whether the individual user section should be displayed to senders when composing a notification based on this template.

Message Template Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Message Templates are assigned to at least one Domain, and can be associated with more than one. This resource lets you see and adjust which Message Templates are assigned to which Domains.

List All Message Template Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "messageTemplateId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "messageTemplateId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Message Template belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /message-templates/{messageTemplateId}/domains

Produces

application/json

Path Parameters

Parameter Description
messageTemplateId The id of the Message Template whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Message Template 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 Message Template 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 Message Template, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the message template whose domains were requested is returned under the key messageTemplateId inside each domain response.

Check if a Message Template contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "messageTemplateId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Message Template Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /message-templates/{messageTemplateId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
messageTemplateId The id of the Message Template whose Domains are of interest.
id The id of the Domain you want to know whether the Message Template belongs to.

Additionally, you can check if the Message Template 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 Message Template, any of their subdomains will be considered.

Response

If the Message Template 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 Message Template Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "messageTemplateId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Message Template 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 /message-templates/{messageTemplateId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
messageTemplateId String The id of the Message Template 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 Message Template out of a parent Domain?
id String n/a The id of the Domain to which the Message Template should be added.
promote Boolean false Allow this request to proceed even if it will promote the Message Template out of one or more child Domains?

A Message Template 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 Message Template 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 Message Template Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Message Template c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Message Template from the specified Domain. As described below, if this is the only Domain that the Message Template currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Message Template itself.

HTTP Request

DELETE /message-templates/{messageTemplateId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
messageTemplateId The id of the Message Template whose Domain should be removed.
id The id of the Domain to be removed from the Message Template.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Message Template in no Domain.

A Message Template must always belong to at least one Domain, so if you try to remove the Message Template from the only Domain that it belongs to, the request must either fail, or delete the Message Template. 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 Message Template out of its last Domain will delete the Message Template.

Response

The deletion response format is detailed here.

Message Template Cloning

This resource is used to make a copy of the Message Template specified by id in the request path.

The only operation supported is POST.

Clone a Message Template

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/message-templates/6ec13410-1bdf-11e4-9181-3c970e7ff560/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListIdsCustomizable": true,
  "subject": "Lunch options for this Friday",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "userIdsCustomizable": false,
  "notificationProfile": {
    "id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3",
    "name": "Default Profile",
    "settings": "... Object omitted for brevity ..."
  },
  "notificationProfileId": {"id": "7026aa0b-720e-11e7-a5a3-696d40dec0a3"},
  "userIDs": ["685c2400-dd09-11e3-8c49-b8e856327746"],
  "confirmationRequestIdDisplay": "auto",
  "bodyDisplay": "auto",
  "ttsType": "none",
  "audioDisplay": "auto",
  "name": "Friday Food Choices (Copy)",
  "imageCustomizable": false,
  "subjectCustomizable": false,
  "confirmationRequestIdCustomizable": false,
  "image": 0,
  "imageDisplay": "auto",
  "audioCustomizable": false,
  "audio": 0,
  "alertTone": "default",
  "alertToneCustomizable": false,
  "alertToneDisplay": "auto",
  "confirmationRequestId": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-04T13:58:57.777Z",
  "expiration": null,
  "expirationCustomizable": false,
  "expirationDisplay": "auto",
  "permissions": ["delete", "put", "get"],
  "distributionListIdsDisplay": "auto",
  "userIdsDisplay": "auto",
  "collaborationGroupIdsDisplay": "auto",
  "collaborationGroupIdsCustomizable": false,
  "collaborationGroupIds": [],
  "deviceGroupIdsDisplay": "auto",
  "deviceGroupIdsCustomizable": false,
  "deviceGroupIds": [],
  "deviceGroups": [],
  "collaborationGroups": [],
  "areaOfInterestIds": null,
  "areaOfInterestIdsCustomizable": false,
  "areasOfInterest": [],
  "areaOfInterestIdsDisplay": "auto",
  "subjectDisplay": "auto",
  "optOut": false,
  "body": "Please take a second to select what you would like to eat this Friday. If you have any dietary restrictions, please let myself or a member of the culinary staff know.",
  "id": "6e41df90-ddc9-4d3f-83db-7fe6b95b0277",
  "distributionLists": [
    {
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Staff"
    }
  ],
  "users": [
    {
      "createdAt": "2014-05-16T14:50:22.656Z",
      "id": "685c2400-dd09-11e3-8c49-b8e856327746",
      "name": "Craig Smith"
    }
  ],
  "confirmationRequest": {
    "escalationRules": [],
    "createdAt": "2014-08-04T13:57:18.824Z",
    "id": "3fb1ee80-1bdf-11e4-9181-3c970e7ff560",
    "options": ["Pizza", "Salad & Bread Sticks"],
    "name": "Food Options - Friday"
  },
  "bodyCustomizable": false,
  "metadataCustomizable": false,
  "followUp": false
}

Creates a copy of the specified Message Template. The name of the new copy is simply the original Message Template’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /message-templates resource and GET permission to the Message Template they wish to copy.

Note that the follow-up template cannot be copied.

HTTP Request

POST /message-templates/{messageTemplateId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
messageTemplateId String The id of the Message Template to copy.

Response

The Message Template response format is detailed here.

Notification Profiles

Fusion Only

A notification profile is a convenient way of grouping common message settings and applying it to multiple message templates. As an example, you may have a group of emergency related message templates which have the same notification profile so they can share settings such as the same icon, repetition settings, introductory text, etc.

A notification profile is composed of a name and settings. Each setting maps directly to a device extension and if a non-null object is provided for the setting’s value, it will then override settings defined globally in the extension’s config.

List All Notification Profiles

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    profile = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(profile)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    profile = requests.get(url, headers=headers, params=params).json()
    print(profile)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "previous": null,
  "next": 2,
  "partial": true,
  "data": [{
    "id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d",
    "name": "Default Profile",
    "default": true,
    "settings": [{
      "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
      "name": "InformaCast Device",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
      "name": "Email",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {
          "headingText": "Notification From",
          "introText": "Custom intro",
          "primaryColor": "#3498db",
          "primaryTextColor": "#ffffff",
          "secondaryTextColor": "#205478",
          "subheadingText": "InformaCast Mobile"
        }
      },
      "attachments": []
    }, {
      "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
      "name": "Apple Production Push μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
      "name": "Google μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de2",
      "name": "Apple QA Push μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
      "name": "Apple Dev Push μ",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {}
      },
      "attachments": []
    }, {
      "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
      "name": "SMS",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {
          "introduction": "Main introduction",
          "includeBody": null
        }
      },
      "attachments": []
    }, {
      "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
      "name": "Phone Call",
      "disabled": false,
      "value": null,
      "extension": {
        "disabled": false,
        "globalDisabled": false,
        "effectiveConfig": {
          "introduction": "The following is an alert from the University of Wisconsin."
        }
      },
      "attachments": []
    }],
    "createdAt": "2017-07-26T12:50:58.048Z",
    "permissions": ["delete", "put", "get"]
  }]
}

Retrieves the list of all Notification Profiles. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

Controlling access to Notification Profiles allows administrators to decide who can modify a message template’s overall configuration.)

HTTP Request

GET /notification-profiles

Produces

application/json

Query Parameters

To make this example more manageable, only the first notification profile was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the Notification Profile belongs.
includeMessageTemplates Boolean If true, include the list of Message Templates that use this Notification Profile.

Response

The notification profile response format is detailed here.

Get a Notification Profile

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    profile = JSON.parse(HTTParty.get(url, headers: headers))
    puts(profile)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    profile = requests.get(url, headers=headers).json()
    print(profile)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d",
  "name": "Default Profile",
  "default": true,
  "settings": [{
    "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
    "name": "InformaCast Device",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
    "name": "Email",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "headingText": "Notification From",
        "introText": "Custom intro",
        "primaryColor": "#3498db",
        "primaryTextColor": "#ffffff",
        "secondaryTextColor": "#205478",
        "subheadingText": "InformaCast Mobile"
      }
    },
    "attachments": []
  }, {
    "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
    "name": "Apple Production Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
    "name": "Google μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de2",
    "name": "Apple QA Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
    "name": "Apple Dev Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
    "name": "SMS",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
    "name": "Phone Call",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }],
  "createdAt": "2017-07-26T12:50:58.048Z",
  "permissions": ["delete", "put", "get"]
}

Retrieves a single notification profile by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /notification-profiles/{notificationProfileId}

Produces

application/json

Path Parameters

Parameter Description
notificationProfileId The id of the notification profile to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the notification profile belongs.
includeMessageTemplates Boolean If true, include the list of Message Templates that use this Notification Profile.

Response

The notification profile response format is detailed here.

Create a Notification Profile

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Default Profile'

}

begin: 
    profile = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(profile)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Default Profile"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Default Profile'
}

try: 
    profile = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(profile)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d",
  "name": "Default Profile",
  "default": true,
  "settings": [{
    "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
    "name": "InformaCast Device",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
    "name": "Email",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "headingText": "Notification From",
        "introText": "Custom intro",
        "primaryColor": "#3498db",
        "primaryTextColor": "#ffffff",
        "secondaryTextColor": "#205478",
        "subheadingText": "InformaCast Mobile"
      }
    },
    "attachments": []
  }, {
    "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
    "name": "Apple Production Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
    "name": "Google μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de2",
    "name": "Apple QA Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
    "name": "Apple Dev Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
    "name": "SMS",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "introduction": "Main introduction",
        "includeBody": null
      }
    },
    "attachments": []
  }, {
    "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
    "name": "Phone Call",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "introduction": "The following is an alert from the University of Wisconsin."
      }
    },
    "attachments": []
  }],
  "createdAt": "2017-07-26T12:50:58.048Z",
  "permissions": ["delete", "put", "get"]
}

Creates a new notification profile. You can optionally define settings in this request as well.

HTTP Request

POST /notification-profiles

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 notification profile.
settings Array[Notification Profile Settings] N/A An array of Notification Profile Settings.
includeMessageTemplates Boolean false If true, include the list of Message Templates that use this Notification Profile in the response.

Response

The notification profile response format is detailed here.

Update a Notification Profile

# Continuing with the notification profile
# object from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Emergency Profile"}'
# Continuing with the notification profile
# object from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "11fdf8a2-7201-11e7-a5a3-bbfbabf08c3d",
  "name": "Emergency Profile",
  "default": false,
  "settings": [{
    "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
    "name": "InformaCast Device",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
    "name": "Email",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "headingText": "Notification From",
        "introText": "Custom intro",
        "primaryColor": "#3498db",
        "primaryTextColor": "#ffffff",
        "secondaryTextColor": "#205478",
        "subheadingText": "InformaCast Mobile"
      }
    },
    "attachments": []
  }, {
    "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
    "name": "Apple Production Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
    "name": "Google μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de2",
    "name": "Apple QA Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
    "name": "Apple Dev Push μ",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {}
    },
    "attachments": []
  }, {
    "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
    "name": "SMS",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "introduction": "Main introduction",
        "includeBody": null
      }
    },
    "attachments": []
  }, {
    "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
    "name": "Phone Call",
    "disabled": false,
    "value": null,
    "extension": {
      "disabled": false,
      "globalDisabled": false,
      "effectiveConfig": {
        "introduction": "The following is an alert from the University of Wisconsin."
      }
    },
    "attachments": []
  }],
  "createdAt": "2017-07-26T12:50:58.048Z",
  "permissions": ["delete", "put", "get"]
}

Updates an existing notification profile’s name and settings.

HTTP Request

PUT /notification-profiles/{notificationProfileId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
notificationProfileId The id of the notification profile to update.

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the notification profile.
settings Array[Notification Profile Settings] N/A An array of Notification Profile Settings
includeMessageTemplates Boolean false If true, include the list of Message Templates that use this Notification Profile in the response.

Response

The notification profile response format is detailed here.

Remove a Notification Profile

# Continuing with the notification profile
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/789c2810-222d-11e4-8f54-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the notification profile
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"NotificationProfiles\"} 789c2810-222d-11e4-8f54-3c970e7ff560"
}

Deletes an existing notification profile.

HTTP Request

DELETE /notification-profiles/{notificationProfileId}

Produces

application/json

Path Parameters

Parameter Description
notificationProfileId The id of the notification profile to delete.

Response

The deletion response format is detailed here.

Notification Profile Response

The JSON document used to represent a notification profile resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this notification profile 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 Notification Profile belongs.
default Boolean Will be true if this notification profile is the system default, which means it will be used by any message template that does not specify to use another, and therefore it cannot be deleted.
id String The id of this specific notification profile, allowing it to be manipulated or retrieved individually.
messageTemplates Array[id, name] If includeMessageTemplates was set to true in the request, this will be present, and list the IDs and names of all Message Templates that use this notification profile.
name String The notification profile 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.
settings Array[Notification Profile Settings] An array of Notification Profile Settings

Notification Profile Settings

Currently, the API supports settings for the following extension IDs:

Name ID
InformaCast Device e322d549-4e80-11e6-af2d-9baf604d14b0
Email b6d90e60-2a40-11e5-8134-9a9e6c05013a
iOS 839771a8-4915-11e6-8b2f-d310e58d9c03
Android 5a181177-3f02-11e6-9617-6bb7c7eddc0e
SMS 17c57b50-833d-11e5-b222-def38c5ff9e6
Phone Call 0a466b30-7670-11e5-ba6e-765ae9d26291
Outbound CAP e1b2db4b-626a-11e7-a3f9-0de43455e893
Desktop Notifier 56d6e006-542e-11e6-ae77-e3b4cf41fce9

Notification Profile Settings Structure

To the right is the structure of a notification profile setting (specifically the SMS device extension).

{
  "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
  "name": "SMS",
  "disabled": false,
  "value": {
    "introduction": "Overridden Main introduction",
    "includeBody": false
  },
  "extension": {
    "disabled": false,
    "globalDisabled": false,
    "effectiveConfig": {
      "introduction": "Main introduction",
      "includeBody": null
    }
  },
  "attachments": []
}

Below is a description of the general structure of a setting.

Attribute Type Description
id String The id of the specific device extension.
name String The device extension’s name.
disabled Boolean Whether or not this channel will be enabled at send time. For example, if disable is set to true for the SMS extension, SMS devices will NOT receive a text notification.
value Object The global extension config override values. In the example to the right, the introduction and includeBody properties shown will be used during the actual send. If a property value is null, the send uses whatever is in extension.effectiveConfig.
extension.­disabled Boolean Whether an administrator has disabled this extension globally. When this is set to true, this notification channel will not be used during a notification.
extension.­globalDisabled Boolean Similar to extension.disabled, but only Singlewire may set this value (in case of abuse for example).
extension.­effectiveConfig Object Similar to value, but is the current config reported by the extension itself, and its values will be used in the send if the corresponding value entry is null.
attachments Array[Attachment] An array of attachments. Currently only the Fusion device extension supports/honors attachments.

InformaCast Device

The following InformaCast device settings may be provided:

{
  "disabled": false,
  "value": {
    "messageType": "Text and Pre-Recorded Audio",
    "repetitionPause": null,
    "scrollSpeed": 5,
    "repeatIndefinitely": false,
    "synchronizedDelivery": true,
    "duration": 5,
    "volume": "As-Is",
    "concatenateText": false,
    "skipPhonesInUse": false,
    "priority": 1,
    "ringtone": false,
    "scrollDuration": null,
    "repetitions": null,
    "persistentText": true
  }
}
Parameter Type Default Description
disabled Boolean false Whether or not this channel will be enabled at send time. For example, if disabled is set to true InformaCast devices will not receive the notification.
value.message­Type String N/A The message’s type, e.g. Text, Text and Pre-Recorded Audio, Text and Live Audio, Text and Ad-Hoc Audio, Pre-Recorded Audio, Live Audio, Ad-Hoc Audio.
value.concatenate­Text Boolean false Controls whether the short and long text will be concatenated together on the recipient’s display, the message icon will not be displayed, and no Details button will be offered.
value.duration Integer 5 Either the maximum time (in seconds) InformaCast will wait for recipient activation before beginning to play a message (when synchronizedDelivery is true), or the length of time for which InformaCast will play the message (default value 5) when synchronizedDelivery is false.
value.persistent­Text Boolean true Controls whether the text will persist on a phone’s display when the user exits a notification which arrives later.
value.priority Integer 1 Set the message priority. The highest priority is 1 (which is also the default value). The lowest priority can be configured in InformaCast’s Broadcast Parameters.
value.repeat­Indefinitely Boolean false Controls whether the message will be repeated until manually stopped. Must be consistent with repetitions if both are present.
value.repetition­Pause Integer 1 The number of seconds to wait between repetitions of the message.
value.repetitions Integer 1 The number of times the message will repeat (setting repetitions to 0 means the message will repeat indefinitely). Must be consistent with repeatIndefinitely if both are present.
value.ringtone Boolean false Sets whether a message will be available as a ring tone.
value.scroll­Duration Integer null The number of seconds for which scrolling recipients will repeatedly move through a message. (Set either scrollDuration or scrollRepetitions but not both.)
value.scroll­Repetitions Integer null The number of repetitions for which scrolling recipients will repeatedly move through a message (the value 0 means unlimited repetitions). Set either scrollDuration or scrollRepetitions, but not both; if both are null, three repetitions will be performed by scrolling recipients.
value.scroll­Speed Integer 5 The speed at which scrolling recipients will move through the message, a value ranging from 1 to 10.
value.skip­PhonesInUse Boolean false Sets whether audio will be sent to phones on active calls (provided this can be determined).
value.skip­Unresponsive­Recipients Boolean false Sets whether the message will be delivered only to recipients that are able to respond to it, i.e. phones and computers running the InformaCast Desktop Notifier.
value.synch­ronized­Delivery Boolean true Controls whether InformaCast will wait until all devices are ready before starting to send the audio of the message.
value.volume String As-Is The volume at which to play the message. Options: As-Is, Maximum Medium Low.
value.queueing­Allowed Boolean false Allows ad-hoc messages to be broadcast in the order they were initiated, but without overlapping.
value.queued­SendThreshold Integer N/A The smallest percentage of available broadcast devices that will permit a queued broadcast to be sent.
value.queued­Failure­RecipientGroup Integer N/A Recipient group id to be notified when a queued broadcast is not sent.
value.queued­FailureText String N/A Notification text to be sent when a queued broadcast is not sent.
attachments.main­Audio File N/A Either the audio file to play to recipients during a pre-recorded audio message, or an activation alert that plays while devices are activating for a live audio message.
attachments.display­Icon File A default warning icon The image file to use as an icon (displays on compatible devices; cropped to 38x64 and positioned at the top left corner of a message’s display).
attachments.postTone File N/A Audio that plays to recipients to designate an ending message.
attachments.preTone File N/A Audio that plays to recipients to announce an impending message.

Email

The following email settings may be provided:

{
  "disabled": false,
  "value": {
    "introText": "This is an alert from Singlewire Software"
  }
}
Parameter Type Default Description
disabled Boolean false Whether or not this channel will be enabled at send time. For example, if disabled is set to true, Email devices will not receive the notification.
value.introText String N/A The email introduction text.

iOS

The following iOS settings may be provided:

{
  "disabled": false,
  "value": {}
}
Parameter Type Default Description
disabled Boolean false Whether or not this channel will be enabled at send time. For example, if disabled is set to true iOS devices will not receive the notification.
value Object N/A No settings are currently accepted/honored at this time.

Android

The following Android settings may be provided:

{
  "disabled": false,
  "value": {}
}
Parameter Type Default Description
disabled Boolean false Whether or not this channel will be enabled at send time. For example, if disabled is set to true Android devices will not receive the notification.
value Object N/A No settings are currently accepted/honored at this time.

SMS

The following SMS settings may be provided:

{
  "disabled": false,
  "value": {
    "includeBody": true,
    "introduction": "This is an alert from Singlewire Software."
  }
}
Parameter Type Default Description
disabled Boolean false Whether or not this channel will be enabled at send time. For example, if disabled is set to true SMS devices will not receive the notification.
value.introduction String N/A This introductory text will be displayed before each notification sent to SMS-enabled devices. Use it to indicate the notification’s sender, e.g. “The following is an alert from campus security.”
value.includeBody Boolean N/A This will include up to 512 characters of the notification body in the delivered SMS message. Note: large notification bodies may impact SMS delivery times.

Phone Call

The following calling settings may be provided:

{
  "disabled": false,
  "value": {
    "introduction": "This is an alert from Singlewire Software."
  }
}
Parameter Type Default Description
disabled Boolean false Whether or not this channel will be enabled at send time. For example, if disabled is set to true Phone Call devices will not receive the notification.
value.introduction String N/A Using text-to-speech functionality, this introductory text will be spoken before each notification sent to phone call devices. Use it to indicate the notification’s sender, e.g. “The following is an alert from campus security.”

Outbound CAP

The following Outbound CAP settings may be provided:

{
  "disabled": false,
  "value": {
    "msgType": "Alert",
    "urgency": "Unknown",
    "severity": "Unknown",
    "certainty": "Unknown",
    "categories": ["Met"],
    "parameters": [{
      "paramName": "param1",
      "paramValue": "val1"}
      ],
    "eventDescription": "Fire!"
  }
}
Parameter Type Default Description
msgType String Alert CAP message type. Currently, only Alert is supported.
urgency String Unknown One of the following CAP urgency levels: Immediate, Expected, Future, Past, Unknown
severity String Unknown One of the following CAP severities: Extreme, Severe, Moderate, Minor, Unknown
certainty String Unknown One of the following CAP certainties: Observed, Likely, Possible, Unlikely, Unknown
categories Array of Strings (all categories selected) At least one of the following CAP categories: Geo,Met,Safety,Security,Rescue,Fire,Health,Env,Transport,Infra,CBRNE,Other
parameters Array of Strings (none) Array of parameter objects
paramName String (none) Custom parameter name
paramValue String (none) Custom parameter value
eventDescription String InformaCast Alert CAP event description

Desktop Notifier

The following Desktop Notifier settings may be provided: (values that also apply to Cisco IP Phones are denoted with a ☎ in the description)

{
  "disabled": false,
  "value": {
    "style": "Custom",
    "ticker": {
     "bold": false,
     "font": "Arial",
     "size": 12,
     "color": "#000000",
     "italic": false,
     "backgroundColor": "#FFFFFF"
    },
    "mainWindow": {
      "body": {
        "bold": false,
        "font": "Arial",
        "size": 12,
        "color": "#000000",
        "italic": false
      },
      "subject": {
        "bold": false,
        "font": "Arial",
        "size": 12,
        "color": "#000000",
        "italic": false
      },
      "linkColor": "#0000ee",
      "backgroundColor": "#FFFFFF"
    },
    "displaySize": "Medium",
    "initialDisplay": "Ticker"
  },
}
Parameter Type Default Description
disabled Boolean false ☎ If true, no settings on this extension are applied and default values are used. Controlling whether notifications are sent is based on the disabled parameter value from the InformaCast Device settings.
value.­style String Normal ☎ Affects the general display characteristics of the notification to include default fonts and colors: Normal, Emergency, Warning, Custom. If Custom is set, related dependent parameters are required.
value.­ticker.­bold Boolean false With a Custom style and Ticker initialDisplay, this determines if the ticker text is bold.
value.­ticker.­font String N/A With a Custom style and Ticker initialDisplay, this sets the font of the ticker text: Arial, ArialBlack, ComicSansMS, Courier, CourierNew, Georgia, Helvetica, Impact, TrebuchetMS, Times, TimesNewRoman, Verdana.
value.­ticker.­size String N/A With a Custom style and Ticker initialDisplay, this sets the size of the ticker text in points: 8, 9, 10, 11, 12, 14, 16, 18, 20, 24, 30.
value.­ticker.­color String N/A With a Custom style and Ticker initialDisplay, this sets the RGB hex encoded ticker text color.
value.­ticker.­italic Boolean false With a Custom style and Ticker initialDisplay, this determines if the ticker text is italicized.
value.­ticker.­backgroundColor String N/A With a Custom style and Ticker initialDisplay, this sets the RGB hex encoded color for the background.
value.­mainWindow.­body.­bold Boolean false With a Custom style, this determines if the body text is bold.
value.­mainWindow.­body.­font String N/A With a Custom style, this sets the font of the body text: Arial, ArialBlack, ComicSansMS, Courier, CourierNew, Georgia, Helvetica, Impact, TrebuchetMS, Times, TimesNewRoman, Verdana.
value.­mainWindow.­body.­size String N/A With a Custom style, this sets the size of the body text in points: 8, 9, 10, 11, 12, 14, 16, 18, 20, 24, 30.
value.­mainWindow.­body.­color String N/A With a Custom style, this sets the RGB hex encoded body text color.
value.­mainWindow.­body.­italic Boolean false With a Custom style, this determines if the subject text is italicized.
value.­mainWindow.­subject.­bold Boolean false With a Custom style, this determines if the subject text is bold.
value.­mainWindow.­subject.­font String N/A With a Custom style, this sets the font of the subject text: Arial, ArialBlack, ComicSansMS, Courier, CourierNew, Georgia, Helvetica, Impact, TrebuchetMS, Times, TimesNewRoman, Verdana.
value.­mainWindow.­subject.­size String N/A With a Custom style, this sets the size of the subject text in points: 8, 9, 10, 11, 12, 14, 16, 18, 20, 24, 30.
value.­mainWindow.­subject.­color String N/A ☎ With a Custom style, this sets the RGB hex encoded subject text color.
value.­mainWindow.­subject.­italic Boolean false With a Custom style, this determines if the subject text is italicized.
value.­mainWindow.­linkColor String N/A With a Custom style, this sets the RGB hex color for links (email addresses and URLs).
value.­mainWindow.­backgroundColor String N/A ☎ With a Custom style, this sets the RGB hex encoded color for the background.
value.­displaySize String Medium The size of the main window that is displayed: Small, Medium, Large, Max.
value.­initialDisplay String Immediate The initial window display behavior of the notification: Immediate, Ticker, Toast, Badge. If Ticker is set, related dependent parameters are required.

Notification Profile Attachments

Attachments may only be uploaded via multipart/form-data requests. They take the following structure:

Attribute Type Description
id String The id of the attachment.
name String The name of the attachment.
contentType String The content type of the attachment, such as image/png, image/jpeg, audio/wav, etc.
metadata Object Any specific metadata about the attachment such as audio length, format, etc.
url String The url that can be used to fetch the binary data of the attachment.

Notification Profiles Cloning

This resource is used to make a copy of the Notification Profile specified by id in the request path.

The only operation supported is POST.

Clone a Notification Profile

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/215bf5cd-c2eb-11eb-9318-c7bbd06be497/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/215bf5cd-c2eb-11eb-9318-c7bbd06be497/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/215bf5cd-c2eb-11eb-9318-c7bbd06be497/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "936eb45a-ebd1-11eb-81b3-230ff64c69ca",
    "name": "Bell Tone (Copy)",
    "settings": [
        {
            "id": "acb4e1a4-d029-11ea-b857-a730b507a69c",
            "name": "WNS μ",
            "disabled": false,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
            "name": "SMS",
            "disabled": true,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
            "name": "Phone Call",
            "disabled": true,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "e1b2db4b-626a-11e7-a3f9-0de43455e893",
            "name": "Outbound CAP Push",
            "disabled": false,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "f0e5d932-c31f-11e8-b4c1-7831c1bab3f6",
            "name": "Microsoft Teams Chat",
            "disabled": false,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": true,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
            "name": "Google μ",
            "disabled": true,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "6ff812ad-18e7-11e7-9f96-1d559a8159e8",
            "name": "Google QA μ",
            "disabled": false,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
            "name": "Fusion Device",
            "disabled": false,
            "value": {
                "volume": "As-Is",
                "duration": 10,
                "messageType": "Pre-Recorded Audio"
            },
            "extension": {
                "disabled": false,
                "globalDisabled": true,
                "effectiveConfig": {
                    "volume": "As-Is",
                    "duration": 10,
                    "messageType": "Pre-Recorded Audio"
                }
            },
            "attachments": [
                {
                    "id": "93703afb-ebd1-11eb-81b3-730c342d91f3",
                    "name": "mainAudio",
                    "fileName": "mainAudio.wav",
                    "contentType": "audio/wav",
                    "size": 24238,
                    "url": "",
                    "metadata": {
                        "codecTimeBase": "1/8000",
                        "encoding": "ulaw",
                        "bitRate": 64000,
                        "channels": 1,
                        "frameRate": 8000,
                        "seconds": 3.0225,
                        "sampleFmt": "s16",
                        "frameLength": 24180,
                        "timeBase": "1/8000",
                        "codecLongName": "PCM mu-law / G.711 mu-law",
                        "codecName": "pcm_mulaw",
                        "bitsPerSample": 8
                    }
                }
            ]
        },
        {
            "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
            "name": "Email",
            "disabled": true,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "56d6e006-542e-11e6-ae77-e3b4cf41fce9",
            "name": "Desktop Notifier - Fusion",
            "disabled": false,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": true,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "5fdb030c-18e7-11e7-9f96-273f619cf339",
            "name": "Apple QA Push μ",
            "disabled": false,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
            "name": "Apple Production Push μ",
            "disabled": true,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        },
        {
            "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
            "name": "Apple Dev Push μ",
            "disabled": false,
            "value": null,
            "extension": {
                "disabled": false,
                "globalDisabled": false,
                "effectiveConfig": null
            },
            "attachments": []
        }
    ],
    "createdAt": "2021-07-23T16:18:11.913Z",
    "permissions": []
}

Creates a copy of the specified Notification Profile. The name of the new copy is simply the original Notification Profile’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /notification-profiles resource and GET permission to the Notification Profile they wish to copy.

HTTP Request

POST /notification-profiles/{notificationProfileId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
notificationProfileId String The id of the Notification Profile to copy.

Response

The notification profile response format is detailed here.

Notification Profile Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Notification Profiles are assigned to at least one Domain, and can be associated with more than one. This resource lets you see and adjust which Notification Profiles are assigned to which Domains.

List All Notification Profile Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "notificationProfileId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "notificationProfileId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Notification Profile belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /notification-profiles/{notificationProfileId}/domains

Produces

application/json

Path Parameters

Parameter Description
notificationProfileId The id of the Notification Profile whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Notification Profile 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 Notification Profile 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 Notification Profile, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the notification profile whose domains were requested is returned under the key notificationProfileId inside each domain response.

Check if a Notification Profile contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "notificationProfileId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Notification Profile Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /notification-profiles/{notificationProfileId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
notificationProfileId The id of the Notification Profile whose Domains are of interest.
id The id of the Domain you want to know whether the Notification Profile belongs to.

Additionally, you can check if the Notification Profile 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 Notification Profile, any of their subdomains will be considered.

Response

If the Notification Profile 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 Notification Profile Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "notificationProfileId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Notification Profile 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 /notification-profiles/{notificationProfileId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
notificationProfileId String The id of the Notification Profile 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 Notification Profile out of a parent Domain?
id String n/a The id of the Domain to which the Notification Profile should be added.
promote Boolean false Allow this request to proceed even if it will promote the Notification Profile out of one or more child Domains?

A Notification Profile 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 Notification Profile 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 Notification Profile Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notification-profiles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Notification Profile c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Notification Profile from the specified Domain. As described below, if this is the only Domain that the Notification Profile currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Notification Profile itself.

HTTP Request

DELETE /notification-profiles/{notificationProfileId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
notificationProfileId The id of the Notification Profile whose Domain should be removed.
id The id of the Domain to be removed from the Notification Profile.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Notification Profile in no Domain.

A Notification Profile must always belong to at least one Domain, so if you try to remove the Notification Profile from the only Domain that it belongs to, the request must either fail, or delete the Notification Profile. 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 Notification Profile out of its last Domain will delete the Notification Profile.

Response

The deletion response format is detailed here.

Notifications

Posting a notification is how a notification is sent. Once sent, a record of the notification details remains for future reference. Administrators can access all sent notifications through this resource, or examine notifications sent to individual Users through the User Notifications resource. Ordinary users generally only have access to their own User Notifications resource, and to notifications they sent.

A Notification resource may include sub-resources which contain audio, an image, and Activities. Activities track how users have interacted with the Notification, such as marking it read, responding to a Confirmation Request, etc.

List All Notifications

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 42,
  "partial": true,
  "previous": null,
  "next": "WyIyMTBmMGRmMC0xZDg4LTExZTQtYzk3MGU3ZmY1NjAiXQ==",
  "data": [
    {
      "subject": "An intruder has been spotted on campus",
      "initiationSourceType": "api",
      "initiationSourceClientId": "IcMobile Web",
      "initiationSourceDescription": null,
      "initiationSourceId": "654adaf1-b76f-11ec-854e-ebe51cfb1261",
      "initiatingEndpointId": "71fab043-b76f-11ec-854e-bfded50f4b1b",
      "parentNotificationId": "6adf8922-b76f-11ec-854e-6d5e76ffc6aa",
      "initiationBroadcast": null,
      "initiationDetails": null,
      "initiatorId": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
      "initiator": {
        "createdAt": "2014-08-04T13:42:57.973Z",
        "id": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
        "email": "security@e.mail",
        "name": "Security Office"
      },
      "image": 0,
      "confirmationResults": { "Yes, I've seen the intruder": 0, "No, I haven't": 0 },
      "audioFiles": [
        {
          "fileName": "audio.wav",
          "size": 32292,
          "contentType": "audio/wav",
          "metadata": {
            "codecTimeBase": "1/8000",
            "encoding": "ulaw",
            "bitRate": 64000,
            "channels": 1,
            "frameRate": 8000,
            "seconds": 11.0759,
            "sampleFmt": "s16",
            "frameLength": 88607,
            "timeBase": "1/8000",
            "codecLongName": "PCM mu-law / G.711 mu-law",
            "codecName": "pcm_mulaw",
            "bitsPerSample": 8
          }
        }
      ],
      "audio": 32292,
      "alertTone": "default",
      "followUpAllowed": true,
      "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
      "createdAt": "2014-08-06T16:38:56.411Z",
      "draft": false,
      "messageTemplateId": "e5543bf0-1bde-11e4-9181-3c970e7ff560",
      "permissions": ["delete", "put", "get"],
      "recipientCount": 5,
      "progress": {
        "recipientCount": 5,
        "readCount": 4,
        "smsReceivedCount": 3,
        "callAnsweredCount": 1,
        "smsFailedCount": 0,
        "callPlacedCount": 2,
        "callFailedCount": 1,
        "smsSentCount": 4,
        "extensions": {
          "17c57b50-833d-11e5-b222-def38c5ff9e6": {
            "type": "device",
            "total": 4,
            "failed": 0,
            "completed": 3,
            "deviceType": "SMS"
          },
          "b6d90e60-2a40-11e5-8134-9a9e6c05013a": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "singlewire:email"
          },
          "5a181177-3f02-11e6-9617-6bb7c7eddc0e": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "Android"
          },
          "551de6ae-3d36-11e6-834a-3d1fcb19aadd": {
            "type": "fusion-endpoint",
            "total": 1,
            "failed": 1,
            "completed": 1,
            "deviceType": null
          },
          "e322d549-4e80-11e6-af2d-9baf604d14b0": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "singlewire:icop"
          },
          "1a172e36-3f02-11e6-9617-9fc8b50f4de1": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "apns-sandbox"
          },
          "1a172e36-3f02-11e6-9617-9fc8b50f4de2": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "apns-qa"
          },
          "839771a8-4915-11e6-8b2f-d310e58d9c03": {
            "type": "device",
            "total": 0,
            "failed": 0,
            "completed": 0,
            "deviceType": "apns"
          },
          "0a466b30-7670-11e5-ba6e-765ae9d26291": {
            "type": "device",
            "total": 2,
            "failed": 1,
            "completed": 1,
            "deviceType": "phone-call"
          }
        }
      },
      "messageTemplate": {
        "name": "Intruder Alert"
      },
      "body": "Warning: An intruder has been spotted on campus heading towards the recreation center. Please be advised and stay tuned for further updates. Have you seen the intruder?",
      "id": "28bbc6b0-1d88-11e4-a054-3c970e7ff560",
      "confirmationRequest": {
        "escalationRules": [ ],
        "createdAt": "2014-08-04T13:53:57.566Z",
        "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
        "options": ["Yes, I've seen the intruder", "No, I haven't"],
        "name": "Intruder?"
      }
    },
    {
        "abortedAt": null,
        "alertTone": "chime",
        "audio": 0,
        "audioFiles": [],
        "audioHash": null,
        "body": "Body user TestUser 1651001298715. email 1651001298717@aol.com device TestDevice 1651001298717",
        "confirmableCount": 1,
        "confirmationRequest": null,
        "confirmationRequestId": null,
        "confirmationResponseCounts": {},
        "createdAt": "2022-04-26T19:28:19.203Z",
        "expiresAt": null,
        "followUpAllowed": true,
        "id": "0721c553-c597-11ec-806a-c538cfbb3424",
        "image": 0,
        "imageFiles": [],
        "imageHash": null,
        "imageMimeType": null,
        "incidentId": null,
        "initiatingEndpointId": null,
        "initiationBroadcast": null,
        "initiationDetails": {
            "areaOfInterestBoundaryTrigger": {
                "action": "entered",
                "id": "070ba540-c597-11ec-806a-f1e55eb9921f",
                "triggeringUserId": "06deefea-c597-11ec-806a-fd5d620c7325"
            }
        },
        "initiationSourceClientId": null,
        "initiationSourceDescription": "TesteAoI 1651001298717",
        "initiationSourceId": "06f1185c-c597-11ec-806a-55a9526b1776",
        "initiationSourceType": "area-of-interest-boundary-trigger",
        "initiator": null,
        "initiatorId": null,
        "messageTemplate": {
            "name": "1651001298912"
        },
        "messageTemplateId": "06f7a80e-c597-11ec-806a-77c9233a634f",
        "metadata": null,
        "notificationProfile": {
            "createdAt": "2022-04-26T19:28:18.499Z",
            "default": true,
            "id": "06b65944-c597-11ec-806a-eb4a72240733",
            "name": "Default",
            "settings": [
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "0a466b30-7670-11e5-ba6e-765ae9d26291",
                    "name": "Test phone call extension",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "17c57b50-833d-11e5-b222-def38c5ff9e6",
                    "name": "Test SMS extension",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "1a172e36-3f02-11e6-9617-9fc8b50f4de1",
                    "name": "Test APNS sandbox extension",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "5a181177-3f02-11e6-9617-6bb7c7eddc0e",
                    "name": "Test GCM extension",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "5fdb030c-18e7-11e7-9f96-273f619cf339",
                    "name": "Apple QA Push μ",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "6ff812ad-18e7-11e7-9f96-1d559a8159e8",
                    "name": "Google QA μ",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "839771a8-4915-11e6-8b2f-d310e58d9c03",
                    "name": "Test APNS production extension",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "acb4e1a4-d029-11ea-b857-a730b507a69c",
                    "name": "Test WNS extension",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "b6d90e60-2a40-11e5-8134-9a9e6c05013a",
                    "name": "Email",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": false
                    },
                    "id": "e1b2db4b-626a-11e7-a3f9-0de43455e893",
                    "name": "Outbound CAP Push",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": true
                    },
                    "id": "56d6e006-542e-11e6-ae77-e3b4cf41fce9",
                    "name": "Desktop Notifier - Fusion",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": true
                    },
                    "id": "be227b70-d2af-11eb-9747-5d78afe13d0b",
                    "name": "Apple Dev Push μ for desktops",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": true
                    },
                    "id": "ddca87d8-d2af-11eb-9747-5d78afe13d0b",
                    "name": "Apple Production Push μ for desktops",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": true
                    },
                    "id": "e322d549-4e80-11e6-af2d-9baf604d14b0",
                    "name": "Fusion Device",
                    "value": null
                },
                {
                    "attachments": [],
                    "disabled": false,
                    "extension": {
                        "disabled": false,
                        "effectiveConfig": null,
                        "globalDisabled": true
                    },
                    "id": "f0e5d932-c31f-11e8-b4c1-7831c1bab3f6",
                    "name": "Microsoft Teams Chat",
                    "value": null
                }
            ]
        },
        "parentNotificationId": null,
        "permissions": [
            "delete",
            "get"
        ],
        "progress": {
            "percentComplete": 0
        },
        "recipientCount": 1,
        "scenarioNotificationCreatedAt": null,
        "scenarioNotificationId": null,
        "subject": "Test BT:1651001298717 User entered TestAoI 1651001298717.",
        "ttsCustomContent": null,
        "ttsType": "none",
        "ttsSpeed": null,
        "ttsVoiceId": null
    }
  ]
}

Retrieves a list of all notifications which have been sent. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. A user will generally be able to see all notifications sent to them, but ordinary users will not be able to see notifications sent to other users, unless they were the sender.)

HTTP Request

GET /notifications

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 42 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each notification belongs.
include­AreasOfInterest Boolean If true, include the list of Areas of Interest and a list of their ids on the notification. Defaults false on notification lists.
include­CollaborationGroups Boolean If true, include the list of Outbound Systems and a list of their ids on the notification. Defaults false on notification lists.
include­DeviceGroups Boolean If true, include the list of Device Groups and a list of their ids on the notification. Defaults false on notification lists.
include­DistributionLists Boolean If true, include the list of Distribution Lists and a list of their ids on the notification. Defaults false on notification lists.
include­Users Boolean If true, include the list of Users and a list of their ids on the notification. Defaults false on notification lists.
raw Boolean If true, the subject and body will be returned in their original, uninterpolated form.
draft Boolean Unless supplied, with the value true, only actual notifications are returned; if present and true, only preview (draft) notifications recently created by the requesting user will be returned.
includeBinaryUrls Boolean If true, include signed CloudFront URL for image, audio, or floor plan images in the response when available.
includeFloorPlan Boolean If true, floor plan image files will be added to the initiationDetails location object.
include­NotificationTypes String If supplied, will filter to include only notifications based on the comma-delimited list of notification types.
exclude­NotificationTypes String If supplied, will filter to exclude notifications based on the comma-delimited list of notification types.
filter­Notification­Statuses String If supplied, will filter to include only notifications based on the comma-delimited list of notification statuses, out of active, canceled, expired, completed, or unknown.
includeBy­MessageTemplateIds String If supplied, will filter to include only notifications sent using Message Templates associated with the comma-delimited list of ids.

Response

The notification response format is detailed here.

Get a Single Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/28bbc6b0-1d88-11e4-a054-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    n = JSON.parse(HTTParty.get(url, headers: headers))
    puts(n)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/28bbc6b0-1d88-11e4-a054-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/28bbc6b0-1d88-11e4-a054-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    n = requests.get(url, headers=headers).json()
    print(n)
except RequestException as e:
    print('Unexpected error!', e)
{
  "subject": "An intruder has been spotted on campus",
  "distributionListIds": ["71ad1fe0-19af-11e4-9367-3c970e7ff560"],
  "initiationSourceType": "api",
  "initiationSourceClientId": "iOS Device Secure",
  "initiationSourceDescription": null,
  "initiationSourceId": "a81fecd8-b76f-11ec-854e-8751f0432754",
  "initiatingEndpointId": "c7d7207c-b76f-11ec-854e-09a0c21abdc3",
  "parentNotificationId": "ae56a769-b76f-11ec-854e-81d582c5cb41",
  "initiationBroadcast": null,
  "initiationDetails": null,
  "initiatorId": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
  "initiator": {
    "createdAt": "2014-08-04T13:42:57.973Z",
    "id": "3e967e50-1bdd-11e4-9181-3c970e7ff560",
    "email": "security@e.mail",
    "name": "Security Office"
  },
  "image": 0,
  "confirmationResults": { "Yes, I've seen the intruder": 0, "No, I haven't": 0 },
  "audioFiles": [
    {
      "fileName": "audio.wav",
      "size": 32292,
      "contentType": "audio/wav",
      "metadata": {
        "codecTimeBase": "1/8000",
        "encoding": "ulaw",
        "bitRate": 64000,
        "channels": 1,
        "frameRate": 8000,
        "seconds": 11.0759,
        "sampleFmt": "s16",
        "frameLength": 88607,
        "timeBase": "1/8000",
        "codecLongName": "PCM mu-law / G.711 mu-law",
        "codecName": "pcm_mulaw",
        "bitsPerSample": 8
      }
    }
  ],
  "audio": 32292,
  "alertTone": "default",
  "followUpAllowed": false,
  "confirmationRequestId": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
  "createdAt": "2014-08-06T16:38:56.411Z",
  "draft": false,
  "messageTemplateId": "e5543bf0-1bde-11e4-9181-3c970e7ff560",
  "permissions": ["delete", "put", "get"],
  "recipientCount": 5,
  "progress": {
    "recipientCount": 5,
    "readCount": 4,
    "smsReceivedCount": 3,
    "callAnsweredCount": 1,
    "smsFailedCount": 0,
    "callPlacedCount": 2,
    "callFailedCount": 1,
    "smsSentCount": 4
  },
  "messageTemplate": {
    "name": "intruder"
  },
  "body": "Warning: An intruder has been spotted on campus heading towards the recreation center. Please be advised and stay tuned for further updates. Have you seen the intruder?",
  "id": "28bbc6b0-1d88-11e4-a054-3c970e7ff560",
  "distributionLists": [ ],
  "areasOfInterest": [ ],
  "confirmationRequest": {
    "escalationRules": [ ],
    "createdAt": "2014-08-04T13:53:57.566Z",
    "id": "c7bc65e0-1bde-11e4-9181-3c970e7ff560",
    "options": ["Yes, I've seen the intruder", "No, I haven't"],
    "name": "Intruder?"
  }
}

Retrieves a single notification based on its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /notifications/{notificationId}

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the specific notification to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this notification belongs.
include­AreasOfInterest Boolean If true, include the list of Areas of Interest and a list of their ids on the notification. Defaults true on individual notification reads.
include­CollaborationGroups Boolean If true, include the list of Outbound Systems and a list of their ids on the notification. Defaults true on individual notification reads.
include­DeviceGroups Boolean If true, include the list of Device Groups and a list of their ids on the notification. Defaults true on individual notification reads.
include­DistributionLists Boolean If true, include the list of Distribution Lists and a list of their ids on the notification. Defaults true on individual notification reads.
includeUsers Boolean If true, include the list of Users and a list of their ids on the notification. Defaults true on individual notification reads.
raw Boolean If true, the subject and body will be returned in their original, uninterpolated form.
draft Boolean Unless supplied, with the value true, only actual notifications are returned; if present and true, only preview (draft) notifications recently created by the requesting user will be returned.
includeBinaryUrls Boolean If true, include signed CloudFront URL for image, audio, or floor plan images in the response when available.
includeFloorPlan Boolean If true, floor plan image files will be added to the initiationDetails location object.
include­NotificationTypes String If supplied, will filter to include only notifications based on the comma-delimited list of notification types.
exclude­NotificationTypes String If supplied, will filter to exclude notifications based on the comma-delimited list of notification types.
filter­Notification­Statuses String If supplied, will filter to include only notifications based on the comma-delimited list of notification statuses, out of active, canceled, expired, completed, or unknown.
includeBy­MessageTemplateIds String If supplied, will filter to include only notifications sent using Message Templates associated with the comma-delimited list of ids.

Response

The notification response format is detailed here.

Send a Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'subject': 'Hail warning until 8PM'
,
    'distributionListIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff560'
]
,
    'messageTemplateId': '37f0f500-1be0-11e4-9181-3c970e7ff560'
,
    'metadata': {
        'weatherSeverity': 5

}

,
    'customVars': {
        'affectedCounty': 'Dane'
,
        'affectedState': 'Wisconsin'

}


}

begin: 
    n = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(n)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Hail warning until 8PM", \
       "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"], \
       "messageTemplateId": "37f0f500-1be0-11e4-9181-3c970e7ff560", \
       "metadata": {"weatherSeverity": 5}, \
       "customVars": {"affectedCounty": "Dane", \
         "affectedState": "Wisconsin"}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'subject': 'Hail warning until 8PM',
    'distributionListIds': ['af94ef60-1d9a-11e4-a054-3c970e7ff560'],
    'messageTemplateId': '37f0f500-1be0-11e4-9181-3c970e7ff560',
    'metadata': {
        'weatherSeverity': 5
}
,
    'customVars': {
        'affectedCounty': 'Dane',
        'affectedState': 'Wisconsin'
}

}

try: 
    n = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(n)
except RequestException as e:
    print('Unexpected error!', e)
{
  "subject": "Hail warning until 8PM",
  "distributionListIds": ["af94ef60-1d9a-11e4-a054-3c970e7ff560"],
  "metadata": "{\“weatherSeverity\”: 5}",
  "initiationSourceType": "api",
  "initiationSourceClientId": "IcMobile Web",
  "initiationSourceDescription": null,
  "initiationSourceId": "d2440aad-b76f-11ec-854e-f3a6f323e4c1",
  "initiatingEndpointId": "c250f13b-b76f-11ec-854e-e92ab677617c",
  "parentNotificationId": "bbfaeeda-b76f-11ec-854e-a3773c1accf5",
  "initiationBroadcast": null,
  "initiationDetails": null,
  "initiatorId": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
  "initiator": {
    "createdAt": "2014-08-01T19:02:15.595Z",
    "id": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "lock": { "start": null, "end": null }
  },
  "image": 0,
  "audio": 0,
  "alertTone": "default",
  "followUpAllowed": false,
  "createdAt": "2014-08-14T14:02:40.174Z",
  "messageTemplateId": "37f0f500-1be0-11e4-9181-3c970e7ff560",
  "permissions": ["delete", "put", "get"],
  "recipientCount": 612,
  "progress": {
    "recipientCount": 612,
    "readCount": 457,
    "smsReceivedCount": 391,
    "callAnsweredCount": 47,
    "smsFailedCount": 4,
    "callPlacedCount": 60,
    "callFailedCount": 5,
    "smsSentCount": 518
  },
  "messageTemplate": {
    "name": "Hail Alert"
  },
  "body": "THE NATIONAL WEATHER SERVICE IN MADISON HAS ISSUED A *HAIL WARNING TO THE DOWNTOWN WEST PHILADELPHIA AREA. PLEASE MOVE ANY VEHICLES AND PERSONS INTO SHELTERED POSITIONS UNTIL 8PM OR THE ALL CLEAR SIGNAL IS GIVEN",
  "metadata": "{\“weatherSeverity\”: 5}",
  "id": "a75d8ce0-23bb-11e4-b7ec-3c970e7ff560",
  "distributionLists": [
    {
      "createdAt": "2014-08-06T18:51:33.590Z",
      "id": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
      "name": "Everyone"
    }
  ],
  "areasOfInterest": [ ]
}

Creates a notification to be sent to one or more specified recipients. These may be individual Users or a group of recipients specified by Distribution Lists, Collaboration Groups, Areas of Interest, or Device Groups (for Fusion customers). Notifications are always based on a Message Template, but values from the template may be overridden at send time (as long as the template allows this). Any attributes in the template which are required but not marked as customizable must be present, with values matching those in the template. At least one recipient must be specified (whether in the Message Template or the request parameters), or the POST will fail validation.

HTTP Request

POST /notifications

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
alertTone String default Controls the sound played by a mobile phone or other compatible InformaCast Fusion Devices (i.e. desktops) when this notification is sent. Possible values match those listed for alertTone in Create a Message Template.
areaOf­Interest­Ids Array[UUID] N/A The ids of the Areas of Interest to which this notification should be sent.
audio Blob N/A Default audio content. Binary stream of audio. The audio formats accepted include μ-law, Opus, MP3, Vorbis, or some other common WAV formats. Non μ-law files will be converted to μ-law and the size of the converted audio must not exceed 10 MiB.
body String N/A Optional detailed body text for the notification. This may be up to 10,000 characters long.
collaboration­GroupIds Array[UUID] N/A The ids of the Collaboration Groups to which this notification should be sent.
device­GroupIds Array[UUID] N/A The ids of the Device Groups to which this notification should be sent.
confirmation­RequestId UUID N/A The id of the Confirmation Request to send with the notification, if any.
custom­Vars JSON N/A Key/value pairs which can replace placeholders in the message template when the notification is created. The placeholder syntax in message templates will be of the form {{varName}}.
distribution­ListIds Array[UUID] N/A The ids of the Distribution Lists to which this notification should be sent.
draft Boolean false If omitted, an actual notification is sent. If supplied with the value true, a notificaiton preview is created, showing who would have received it if it were actually sent, but no actual sending will occur.
extension­Settings­Overrides json N/A Allows device extensions which were enabled in the notification profile to be disabled at send time. A map whose keys are device extension IDs, and values are {"disabled": true}.
follow­Up­For­NotificationId UUID N/A The id of the source notification a follow-up message is being sent based on for recipients. The value for followUpAllowed must be true on that notification response. This value can be any notification in history and if supplied, the followUpForNotificationQuery must also be used for recipient selection. In addition, the messageTemplateId provided must support follow-up (i.e. followUp must be true on the Message Template).
follow­Up­For­Notification­Query String N/A The query used at send time to create the list of recipients based on the followUpForNotificationId also supplied. The value for this parameter conforms to the search query syntax used for queries (i.e. read:true would extract all recipients that read the source notification). Recipients determined from this query are merged with any configured on the message template.
image Blob N/A Binary stream of an image to send with the notification. The size of the image must not exceed 10 MiB.
message­TemplateId UUID N/A The id of the Message Template that serves as the basis for this notification. This will provide default values for the notification attributes and control whether they can be overridden at send time.
metadata JSON N/A Optional values to be attached to the notification, for use by client software.
subject String N/A The subject of the notification. This may be up to 256 characters long.
ttsCustom­Content String N/A Custom text used for synthesized speech when ttsType is custom-text or custom-ssml.
ttsSpeed String normal Option: very-slow, slow, normal, fast, very-fast. The rate at which the text will be spoken.
ttsType String none Option: none, subject, body, subject-and-body, custom-text, custom-ssml. Controls which attributes are transformed into speech audio, and how. This is considered part of the message audio, so it can only be overridden at send time when audioCustomizable is true.
ttsVoiceId UUID N/A Specifies the Text-to-Speech Voice to be used when synthesizing audio for this notification.
user­Ids Array[UUID] N/A The ids of individual Users to which this notification should be sent, regardless of their distribution list memberships.
initiationDetails JSON N/A Metadata about the initiation of the notification. If the notification comes from a location-enabled scenario, this will include site, building, floor, and zone information including any uploaded floor plans, floor boundaries, or zone boundaries.

Response

The notification response format is detailed here. Because so much already needs to happen during the creation of a notification, the includeDomains request parameter is ignored. If you need a version of the response that includes embedded domain information, you will have to send a separate GET request for the notification ID returned in the POST response, and specifying includeDomains=true in the GET request.

Remove a Notification

# Continuing with the notification object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/a75d8ce0-23bb-11e4-b7ec-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the notification object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"Notifications\"} a75d8ce0-23bb-11e4-b7ec-3c970e7ff560"
}

Removes a sent notification from the record. Generally only administrative users will have permission to do this.

HTTP Request

DELETE /notifications/{notificationId}

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the notification to delete.

Response

The deletion response format is detailed here.

Get a Notification’s Audio

# Continuing with the notification object from
# the previous example:
begin:
    sound = HTTParty.get(url, headers: headers)
    puts(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/audio" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the notification object from
# the previous example:
try:
    sound = requests.get(url, headers=headers)
    print(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Produces a binary stream of audio data, with the specific MIME type identified in the response header. Will likely involve redirection to a content distribution network server closer to where the request originated.

Retrieves the audio, if any, that was sent with the notification, as a binary stream. For improved performance, this will likely involve redirection (via an HTTP 302 Redirect response) to an AWS CloudFront content distribution network node which has cached the content closer geographically to where the request originated than the Singlewire REST API servers.

Deprecation warning: Requesting conversion of the audio format by specifying a value of pcm for the convert request parameter is no longer necessary, because the content-type header returned now allows the audio to be used as-is. This query parameter will no longer cause the audio format to be converted in a future release.

HTTP Request

GET /notifications/{notificationId}/audio

Produces

audio/wav, audio/u-law

Path Parameters

Parameter Description
notificationId The id of the notification for which the audio data is desired.

Request Parameters

Parameter Type Default Description
convert String null Deprecated: Specify a value of pcm to request that the server convert the audio to PCM (WAV) format from μ-law. This takes more network bandwidth, so should only be done if the client cannot handle μ-law compression.

Get a Notification’s Image

# Continuing with the notification object from
# the previous example:
begin:
    pic = HTTParty.get(url, headers: headers)
    puts(pic.headers['content-type'])   # e.g., image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/image" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the notification object from
# the previous example:
try:
    pic = requests.get(url, headers=headers)
    print(pic.headers['content-type'])   # e.g., image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Produces a binary stream of the image data, with the specific MIME type identified in the response header. Will likely involve redirection to a content distribution network server closer to where the request originated.

Retrieves the image, if any, that was sent with the notification, as a binary stream. For improved performance, this will likely involve redirection (via an HTTP 302 Redirect response) to an AWS CloudFront content distribution network node which has cached the content closer geographically to where the request originated than the Singlewire REST API servers.

HTTP Request

GET /notifications/{notificationId}/image

Produces

image/png image/jpeg image/gif

Path Parameters

Parameter Description
notificationId The id of the notification for which the image data is desired.

Notification Response

The JSON document used to represent a notification resource has the following content:

Attribute Type Description
abortedAt ISO 8601 date/time When this notification was canceled. Will be null if the notification has not been canceled.
alertTone String Controls the sound played by a mobile phone or other compatible InformaCast Fusion Devices (i.e. desktops) when this notification is sent. Possible values match those listed for alertTone in Create a Message Template.
areaOf­Interest­Ids Array[UUID] The ids of the Areas of Interest to which this notification should be sent.
audio Integer The size in bytes of the audio sent with this notification, or zero if there is none. (This is now redundant with the audioFiles attribute, and will likely be deprecated and removed in a future release.)
audioFiles Array[Object] Lists information about the audio files sent with this notification. Currently there will only be one, but future releases may support multiple audio streams with different purposes or quality. Each entry in the array is a file description object.
body String The body of text of the notification.
confirmation­Request ConfirmationRequest The Confirmation Request attached to the notification, if there was one.
confirmation­RequestId UUID The id of the Confirmation Request, above. This is what is actually stored; the expanded details about the Confirmation Request are returned as a convenience, to save clients from having to issue a separate request to look them up.
confirmation­Results ConfirmationResults A map collecting the counts of how many times each of the Confirmation Request options have been chosen by different users responding to the Notification.
createdAt ISO 8601 date/time When this notification was sent.
collaboration­GroupIds Array[UUID] A list of the ids of all collaboration groups to which this notification was sent.
device­GroupIds Array[UUID] A list of the ids of all device groups to which this notification was sent.
distribution­ListIds Array[UUID] A list of the ids of all distribution lists to which this notification was sent.
domains Array[Domain] When Domains are in use and includeDomains was true in your request, this response will list the Domains to which the notification belongs.
draft Boolean Indicates whether this is a notification preview, or an actual sent notification. Only drafts recently created by the same user can be seen, and only when they are explicitly requested using the draft query parameter.
expiresAt ISO 8601 date/time When this notification will (or did) expire. Can be null for non-expiring notifications.
id UUID The id of this specific notification, allowing it to be manipulated or retrieved individually, and providing access to its audio, image, and Activities.
follow­Up­Allowed Boolean Denotes whether this notification can have a follow-up sent using it as a source id for followUpForNotificationId. If set false and a follow-up is attempted using this notification, an error will occur. Client applications should use this flag as a way to enable buttons in a User Interface.
image Integer The size in bytes of the image sent with this notification, or zero if there is none. (This is now redundant with the imageFiles attribute, and will likely be deprecated and removed in a future release.)
imageFiles Array[Object] Lists information about the image files sent with this notification. Currently there will only be one, but future releases may support multiple images with different purposes or quality. Each entry in the array is a file description object.
image­MimeType String Options: image/png image/jpeg image/gif. The format in which the image data will be delivered, if there is an image associated with this notification. (This is now redundant with the imageFiles attribute, and will likely be deprecated and removed in a future release.)
initiationSourceType String Source type of the notification, unique to each type.
initiation­SourceClientId String The client type for vanilla notifications: iOS Device Secure, Android Device Secure, IcMobile Web, or Windows.
initiation­Source­Description String The name or description of the resource that triggered this notification.
initiation­SourceId String The id of the resource that initiated the notification, if not a user.
initiating­EndpointId UUID The id of the fusion server the broadcast came from, if applicable.
parent­NotificationId UUID The id of the notification from which this notification was sourced, such as in the case of follow-up notifications.
initiation­Broadcast JSON The json representation of the on-prem broadcast from which this notification is sourced.
initiation­Details JSON Details about why and how a notification was initiated. If the notification comes from a location-enabled scenario, this will include site, building, floor, and zone information including any uploaded floor plans, floor boundaries, or zone boundaries.
initiator JSON Embeds information from the User or device that sent the notification.
initiatorId UUID The id of the sender of the notification, above.
message­TemplateId UUID The id of the Message Template on which this Notification was based.
metadata JSON Optional values to be attached to the notification, for use by client software.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
progress JSON Provides an update on the process of sending the notification, as an object containing several counters with keys such as recipientCount, readCount, smsReceivedCount, etc. (See details below.) Some of these are also present in the main response, but these older copies are only present for backwards compatibility, and new code should look for them in the progress object.
read Boolean An indication of whether this user has seen this notification. Initially set to false, will become true if a readStatus activity with value true is posted (until a later one with value false is posted to mark it as unread again).
read­Timestamp ISO 8601 date/time The most recent time at which this notification was marked as read by this user. No value is returned if read is currently false.
subject String The subject text of this notification.
ttsCustom­Content String Custom text used for synthesized speech when ttsType is custom-text or custom-ssml.
ttsSpeed String Option: very-slow, slow, normal, fast, very-fast. The rate at which the text will be spoken.
ttsType String Option: none, subject, body, subject-and-body, custom-text, custom-ssml. Controls which attributes are transformed into speech audio, and how.
ttsVoiceId UUID Records the Text-to-Speech Voice, if any, used when synthesizing audio for this notification.
user­Ids Array[UUID] The ids of individual Users to which this notification was sent, regardless of their distribution list memberships.

Confirmation Results Response

{
  "Option A": 12,
  "Option B": 34
}

A map whose keys are all the options present in the Confirmation Request attached to the notification, and whose values are the count of how many users chose that option when responding to the notification.

File Description Objects

An example audio file description:

{
  "fileName": "audio.wav",
  "size": 32292,
  "contentType": "audio/wav",
  "metadata": {
    "codecTimeBase": "1/8000",
    "encoding": "ulaw",
    "bitRate": 64000,
    "channels": 1,
    "frameRate": 8000,
    "seconds": 11.0759,
    "sampleFmt": "s16",
    "frameLength": 88607,
    "timeBase": "1/8000",
    "codecLongName": "PCM mu-law / G.711 mu-law",
    "codecName": "pcm_mulaw",
    "bitsPerSample": 8
  }
}

For resources which include binary attachments, these provide details about the attachment, including the file name, size, content type, and more detailed metadata, the specifics of which depend on the content type.

An example image file description:

{
 "fileName": "image.png",
 "size": 25079,
 "contentType": "image/png",
 "metadata": {
  "data": {
   "sampleFormat": "UnsignedIntegral",
   "bitsPerSample": "8 8 8 8",
   "planarConfiguration": "PixelInterleaved"
  },
  "width": 960,
  "chroma": {
   "blackIsZero": true,
   "numChannels": 4,
   "colorSpaceType": "RGB"
  },
  "height": 720,
  "dimension": {
   "imageOrientation": "Normal",
   "pixelAspectRatio": 1,
   "verticalPixelSize": 0.35285816,
   "horizontalPixelSize": 0.35285816
  },
  "compression": {
   "lossless": true,
   "compressionTypeName": "deflate",
   "numProgressiveScans": 1
  },
  "transparency": {
   "alpha": "nonpremultipled"
  }
 }
}

In the section on the right you can find examples of what a file description object might look like for an audio attachment and an image attachment.

Initiation Details Response Object

An example of initiationDetails containing a location and floor plan data.

{
  "event": null,
  "fields": [
    {
      "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
      "name": "where",
      "rank": 1,
      "type": "site",
      "answer": "200183dc-e5d8-11ed-b219-f3947b41b855",
      "answerSiteName": "a 121"
    }
  ],
  "location": {
    "site": {
      "id": "200183dc-e5d8-11ed-b219-f3947b41b855",
      "name": "a 121"
    },
    "zone": {
      "id": "3acfa610-4c22-11ee-baa8-21a3f3c72fcd",
      "name": "lobby",
      "boundary": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -89.384013924,
              43.074699671
            ],
            [
              -89.38511363,
              43.074762371
            ],
            [
              -89.384574506,
              43.074962213
            ],
            [
              -89.384013924,
              43.074699671
            ]
          ]
        ]
      }
    },
    "floor": {
      "id": "fde6124c-4c1d-11ee-baa8-f97038af4341",
      "name": "capitol",
      "boundary": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -89.382946405,
              43.074609545
            ],
            [
              -89.384311649,
              43.073745507
            ],
            [
              -89.385548148,
              43.074723186
            ],
            [
              -89.38430092,
              43.075830154
            ],
            [
              -89.382946405,
              43.074609545
            ]
          ]
        ]
      },
      "imageOrigins": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -89.382141742,
            43.074601708
          ],
          [
            -89.386384997,
            43.074731023
          ]
        ]
      }
    },
    "building": {
      "id": "d42dd737-3e00-11ee-8e9d-1724c5724af0",
      "name": "another test b1"
    },
    "description": "a 121 (Building: another test b1, Floor: capitol, Room/Zone: lobby)",
    "floorPlanImageFiles": [
      {
        "fileName": "randomfloorplan.jpeg",
        "size": 89528,
        "contentType": "image/jpeg",
        "metadata": {
          "width": 900,
          "chroma": {
            "numChannels": 3,
            "colorSpaceType": "YCbCr"
          },
          "height": 900,
          "dimension": {
            "imageOrientation": "Normal",
            "pixelAspectRatio": 1.0,
            "verticalPixelSize": 0.26458332,
            "horizontalPixelSize": 0.26458332
          },
          "compression": {
            "lossless": false,
            "compressionTypeName": "JPEG",
            "numProgressiveScans": 1
          }
        },
        "url": "https://d18rjpan9mmbi8.cloudfront.net/c243138a-2fc2-11ed-9e01-f37bac8b8053/floor-plan-images/2ad74a79b2eb1bc7fb16ba479e05fa53fdc6f1ec7bfc01f3fa78eedb2c23776f?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIA5MKLDIOZ3IR2EWWX%2F20230906%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230906T000000Z&X-Amz-Expires=172800&X-Amz-Signature=a321a87dfe91a85213dc5ce4b2d1f75ddd89c4aa97d701eff86c64a0c556e276"
      }
    ]
}

When a notification is sent containing location data, such as from a sites-enabled scenario, the initiationDetails object will contain a location object. This location object will contain data about the site, building, floor, and zone associated with the notification. The floor’s imageOrigins and boundary, and the zone’s boundary data will always be present if available. The floor plan image files metadata will only be present if the query param includeFloorPlan is true, and this object will only contain the signed CloudFront URL if the query param includeBinaryUrls is also true. See Site Building Floors or Site Building Floor Zones for more details.

Progress Response Field

An example progress response:

 {
   "abortCount": 1,
   "broadcastFailedCount": 0,
   "broadcastFinishedCount": 0,
   "broadcastStartedCount": 0,
   "callAnsweredCount": 0,
   "callCompletedCount": 0,
   "callFailedCount": 0,
   "callQueuedCount": 0,
   "callPlacedCount": 0,
   "callSkippedCount": 0,
   "ciscoSparkCount": 0,
   "ciscoSparkFailedCount": 0,
   "conferenceCallFailedCount": 0,
   "conferenceCallLeftCount": 0,
   "conferenceCallJoinedCount": 0,
   "confirmableCount": 1,
   "displayTextAndStartAudioCount": 0,
   "displayTextCount": 0,
   "emailFailedCount": 0,
   "emailQueuedCount": 0,
   "emailSentCount": 1,
   "escalationRuleSkippedCount": 0,
   "expireCount": 0,
   "facebookFailedCount": 0,
   "facebookSentCount": 0,
   "infoCount": 0,
   "initServicesCount": 0,
   "percentComplete": 80,
   "pushFailedCount": 0,
   "pushQueuedCount": 0,
   "pushSentCount": 3,
   "readCount": 0,
   "recipientCount": 1,
   "recipientSkippedCount": 0,
   "sendingFinishedCount": 0,
   "sendingStartedCount": 0,
   "skipCount": 0,
   "smsFailedCount": 0,
   "smsQueuedCount": 0,
   "smsReceivedCount": 0,
   "smsSentCount": 0,
   "startAudioCount": 0,
   "stopAudioCount": 0,
   "trackingCompletedCount": 0,
   "trackingStartedCount": 0,
   "trackingTerminatedCount": 0,
   "extensions": {
     "5a181177-3f02-11e6-9617-6bb7c7eddc0e": {
      "type": "device",
      "deviceType": "Android",
      "total": 2,
      "failed": 0,
      "completed": 2
     },
     "d99d7d85-b02e-11e6-9fe5-27a42c0b5758": {
      "type": "device",
      "deviceType": "Android-qa",
      "total": 0,
      "failed": 0,
      "completed": 0
     },
     "839771a8-4915-11e6-8b2f-d310e58d9c03": {
      "type": "device",
      "deviceType": "apns",
      "total": 1,
      "failed": 0,
      "completed": 1
     },
     "1a172e36-3f02-11e6-9617-9fc8b50f4de1": {
      "type": "device",
      "deviceType": "apns-sandbox",
      "total": 0,
      "failed": 0,
      "completed": 0
     },
     "551de6ae-3d36-11e6-834a-3d1fcb19aadd": {
      "type": "fusion-endpoint",
      "deviceType": null,
      "total": 1,
      "failed": 0,
      "completed": 0
     },
     "0a466b30-7670-11e5-ba6e-765ae9d26291": {
      "type": "device",
      "deviceType": "phone-call",
      "total": 0,
      "failed": 0,
      "completed": 0
     },
    "b6d90e60-2a40-11e5-8134-9a9e6c05013a": {
     "type": "device",
     "deviceType": "singlewire:email",
     "total": 1,
     "failed": 0,
     "completed": 1
    },
    "e322d549-4e80-11e6-af2d-9baf604d14b0": {
     "type": "device",
     "deviceType": "singlewire:icop",
     "total": 0,
     "failed": 0,
     "completed": 0
    },
    "17c57b50-833d-11e5-b222-def38c5ff9e6": {
     "type": "device",
     "deviceType": "SMS",
     "total": 0,
     "failed": 0,
     "completed": 0
    }
   }
 }

A map whose keys are all the various delivery details associated with the notification, and whose values are the count for that key. For the extensions map, each device type includes three keys (total, failed, and completed) where the success count must be inferred by subtracting failed from completed. Note that the failed and inferred success count are only final when completed is equal to total. Also note the iOS device type is represented by apns (the Apple Push Notification Service).

Notification Activities

Notification activities are the mechanism for tracking and reviewing interactions that all Users have had with a particular Notification. This ranges from simply seeing the list of all recipients to determining who has marked it read or unread, and gathering any responses to an associated Confirmation Request. Administrators and other users with appropriate permissions can also create new activities for a particular notification to cancel or expire it.

Get All Notification Activities

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "readStatus": "read",
      "userId": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
      "confirmationOption": null,
      "notificationId": "c893b700-23c9-11e4-b7ec-3c970e7ff560",
      "createdAt": "2014-08-14T15:46:40.350Z",
      "type": "set-read-status",
      "permissions": ["delete", "put", "get"],
      "user": {
        "createdAt": "2014-08-01T19:02:15.595Z",
        "id": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
        "email": "craig.smith@acme.com",
        "name": "Craig Smith",
        "lock": { "start": null, "end": null }
      },
      "id": "2eccd7e0-23ca-11e4-b7ec-3c970e7ff560"
    },
    {
      "readStatus": null,
      "userId": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
      "confirmationOption": "chicken and waffles",
      "notificationId": "c893b700-23c9-11e4-b7ec-3c970e7ff560",
      "createdAt": "2014-08-14T15:46:44.777Z",
      "type": "confirmation",
      "permissions": ["delete", "put", "get"],
      "user": {
        "createdAt": "2014-08-01T19:02:15.595Z",
        "id": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
        "email": "craig.smith@acme.com",
        "name": "Craig Smith",
        "lock": { "start": null, "end": null }
      },
      "id": "31705990-23ca-11e4-b7ec-3c970e7ff560"
    }
  ]
}

Retrieves the list of all activities recorded for the specified notification.

HTTP Request

GET /notifications/{notificationId}/activities

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification for which activity information is desired.

Query Parameters

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

The API has pseudo field names which combine the field name, createdAt, with a comparison operation. The 4 pseudo field names are createdAt__lt (less than), createdAt__lte (less than or equals), createdAt__gt (greater than) and createdAt__gte (greater than or equals). When specifying one of these createdAt filters the timestamp format must be in RFC3339 format, including the timezone offset.

Ex. q=createdAt__gt:2019-07-29T01:53:00-05:00

Response

The notification activity response format is detailed here.

Get a Specific Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities/f1b2ec20-23c2-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities/f1b2ec20-23c2-11e4-b7ec-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities/f1b2ec20-23c2-11e4-b7ec-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    activity = requests.get(url, headers=headers).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "readStatus": "read",
  "userId": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
  "confirmationOption": null,
  "notificationId": "14ca7b10-23be-11e4-b7ec-3c970e7ff560",
  "createdAt": "2014-08-14T14:54:51.362Z",
  "type": "set-read-status",
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-01T19:02:15.595Z",
    "id": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "lock": { "start": null, "end": null }
  },
  "id": "f1b2ec20-23c2-11e4-b7ec-3c970e7ff560"
}

Retrieves a specific activity based the id values of the notification and activity. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /notifications/{notificationId}/activities/{activityId}

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification for which activity information is desired.
activityId The id of the specific Activity of interest.

Response

The notification activity response format is detailed here.

Create an Activity To Cancel Or Expire a Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'type': 'expire'
,
    'details': {
        'comment': 'brief comment'

}


}

begin: 
    activity = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"type": "expire", \
       "details": {"comment": "brief comment"}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/notifications/14ca7b10-23be-11e4-b7ec-3c970e7ff560/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'type': 'expire',
    'details': {
        'comment': 'brief comment'
}

}

try: 
    activity = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "readStatus": "read",
  "userId": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
  "confirmationOption": null,
  "notificationId": "14ca7b10-23be-11e4-b7ec-3c970e7ff560",
  "createdAt": "2017-12-28T17:45:18.622Z",
  "type": "expire",
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-01T19:02:15.595Z",
    "id": "5a2e5fb0-19ae-11e4-9195-3c970e7ff560",
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "lock": { "start": null, "end": null }
  },
  "id": "4f37b619-3656-4862-83f7-d32Bf8917889"
}

Creates a new activity based on the type for the specified notification. This mechanism can currently be used to cancel or expire notifications. Canceling can be attempted while a notification is actively being sent to recipients. Canceling will not delete notifications that were successfully delivered to recipients and cannot be initiated after all recipients have been notified (i.e. after the notification’s status is complete). You can expire notifications that have been completed and are active. This does not remove the notification from your history, nor does it delete notifications from users who have already viewed the message. It does, however, update the status of the notification to show that it has expired.

Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

POST /notifications/{notificationId}/activities

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Required Description
notificationId UUID Yes The id of the Notification for which activity information is desired.
type String Yes Options: abort (cancel), expire. Updates the notification if it is in an available state.
details Map No Typically just a comment field e.g. {"comment":"Weather alert removed by NWS"}

Response

The notification activity response format is detailed here. If the notification is not in the right state to be canceled or expired, a 400 validation error will be returned.

Notification Activity Response

The JSON document used to represent a notification activity resource has the following content:

Attribute Type Description
confirmation­Option String When the type attribute is confirmation, this contains the Confirmation Request response the user has chosen. This will be a value from the options list of the confirmation request attached to the notification, and there will be at most one activity of this type recorded for this user and notification.
createdAt ISO 8601 date/time When this activity was created.
id String The id of this specific activity, allowing it to be manipulated or retrieved individually.
notificationId String The id of the Notification whose activities are being examined.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
readStatus String Present when the type attribute is set-read-status, and will have the value read or unread. Marks the notification as read or unread as of the time of this activity. The read status can be toggled multiple times; the value set by the most recent activity is considered the current state.
type String Options: set-read-status, confirmation sms-sent, sms-received, call-placed, call-answered, sms-failed, call-failed, email-queued, email-sent, email-failed. Identifies the type of activity that was recorded. Extensions may add more type values; this is where the email-related values came from. Such extension-defined types will not be present in the API Explorer documentation, since the API is not aware of them.
user User The User whose interaction with the notification is being recorded.
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.

Notification Recipients

Notification recipients provide a convenient view of all the recipient Users of a particular Notification, aggregating information about the user as well as whether they have read the notification, and their response to an associated Confirmation Request, if any.

Get All Notification Recipients

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/644a3b1c-b63b-11e5-a84d-63257415c09d/recipients"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/644a3b1c-b63b-11e5-a84d-63257415c09d/recipients" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/644a3b1c-b63b-11e5-a84d-63257415c09d/recipients"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
   {
    "email": "craig.smith@acme.com",
    "permissions": [
     "delete",
     "put",
     "get"
    ],
    "read": false,
    "name": "Craig Smith",
    "notificationId": "644a3b1c-b63b-11e5-a84d-63257415c09d",
    "createdAt": "2015-12-21T16:58:10.440Z",
    "type": "regular",
    "confirmationResponse": null,
    "id": "03f5208a-a804-11e5-86c1-fba3bbf30afd"
   }
  ]
}

Retrieves the list of all recipients of the specified notification.

HTTP Request

GET /notifications/{notificationId}/recipients

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification for which recipient information is desired.

Query Parameters

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Additionally, you can optionally filter list requests using some recipient-specific query parameters:

Parameter Type Description
confirmable­Only Boolean If true, returns only recipients that can respond to confirmation requests
endpointIdentifier UUID If present, returns only recipients associated with to the corresponding endpoint
types String A comma-delimited list of the recipient types you would like included (such as regular, application, anonymous…)

Response

The notification recipients response format is detailed here.

Get a Specific Notification Recipient

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/644a3b1c-b63b-11e5-a84d-63257415c09d/recipients/03f5208a-a804-11e5-86c1-fba3bbf30afd"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/644a3b1c-b63b-11e5-a84d-63257415c09d/recipients/03f5208a-a804-11e5-86c1-fba3bbf30afd" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/644a3b1c-b63b-11e5-a84d-63257415c09d/recipients/03f5208a-a804-11e5-86c1-fba3bbf30afd"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    activity = requests.get(url, headers=headers).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "email": "craig.smith@acme.com",
  "permissions": [
   "delete",
   "put",
   "get"
  ],
  "read": false,
  "name": "Craig Smith",
  "notificationId": "644a3b1c-b63b-11e5-a84d-63257415c09d",
  "createdAt": "2015-12-21T16:58:10.440Z",
  "type": "regular",
  "confirmationResponse": null,
  "id": "03f5208a-a804-11e5-86c1-fba3bbf30afd"
}

Retrieves recipient information based the id values of the notification and recipient. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /notifications/{notificationId}/recipients/{recipientId}

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification for which recipient information is desired.
recipientId The User id of the specific recipient of interest.

Response

The notification recipients response format is detailed here.

Notification Recipients Response

The JSON document used to represent a notification recipient resource has the following content:

Attribute Type Description
confirmation­Response String Contains the Confirmation Request response the user has chosen, if any. This will be a value from the options list of the confirmation request attached to the notification.
email String The recipient User’s email address.
endpoint Object When endpoint is not null, provides more information about the associated endpoint.
endpointId UUID Identifies the endpoint, if any, associated with the recipient.
id String The recipient User’s id.
name String The recipient User’s name.
notificationId String The id of the Notification whose activities are being examined.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
read Boolean Will be true if the recipient has read the notification.
type String Options: regular, anonymous application. Identifies the type of the recipient User.

Notification Devices

Fusion Only

Provides a unified view of all the Devices that received a particular Notification.

Get All Notification Devices

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/a83d4d12-6e53-11e7-9840-c1d676aa582b/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/a83d4d12-6e53-11e7-9840-c1d676aa582b/devices" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/a83d4d12-6e53-11e7-9840-c1d676aa582b/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "previous": null,
  "next": null,
  "partial": true,
  "data": [{
    "deviceIdentifier": "28a92caf-3d37-11e6-834a-431f5104df9d:CiscoPhone-55:SEPDCA5F43E696A",
    "permissions": ["delete", "put", "get"],
    "name": "Cisco IP Phone: Auto 105186; DNs: 105186; SEPDCA5F43E696A",
    "notificationId": "a83d4d12-6e53-11e7-9840-c1d676aa582b",
    "createdAt": "2017-07-21T20:31:37.903Z",
    "type": "singlewire:CiscoIPPhone",
    "id": "989069d6-6e53-11e7-b773-0242ac110002",
    "userId": "51d63c2a-a015-11e5-b60a-b3fe0dce4648",
    "attributes": null
  }]
}

Retrieves the list of all devices the notification was sent to.

HTTP Request

GET /notifications/{notificationId}/devices

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification for which device information is desired.

Query Parameters

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Additionally, you can optionally filter list requests using some device-specific query parameters:

Parameter Type Description
deviceIdentifier String The identifier of the single device type you would like included
endpointIdentifier UUID If present, returns only devices associated with to the corresponding endpoint
type String The single device type you would like included (such as apns, SMS, phone-call…)
types String A comma-delimited list of the device types you would like included (such as SMS, phone-call, singlewire:email…)

Response

The notification devices response format is detailed here.

Get a Specific Notification Device

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/a83d4d12-6e53-11e7-9840-c1d676aa582b/devices/989069d6-6e53-11e7-b773-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    device = JSON.parse(HTTParty.get(url, headers: headers))
    puts(device)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/a83d4d12-6e53-11e7-9840-c1d676aa582b/devices/989069d6-6e53-11e7-b773-0242ac110002" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/a83d4d12-6e53-11e7-9840-c1d676aa582b/devices/989069d6-6e53-11e7-b773-0242ac110002"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    device = requests.get(url, headers=headers).json()
    print(device)
except RequestException as e:
    print('Unexpected error!', e)
{
  "deviceIdentifier": "28a92caf-3d37-11e6-834a-431f5104df9d:CiscoPhone-55:SEPDCA5F43E696A",
  "permissions": ["delete", "put", "get"],
  "name": "Cisco IP Phone: Auto 105186; DNs: 105186; SEPDCA5F43E696A",
  "notificationId": "a83d4d12-6e53-11e7-9840-c1d676aa582b",
  "createdAt": "2017-07-21T20:31:37.903Z",
  "type": "singlewire:CiscoIPPhone",
  "id": "989069d6-6e53-11e7-b773-0242ac110002",
  "userId": "51d63c2a-a015-11e5-b60a-b3fe0dce4648",
  "attributes": null
}

Retrieves device information based the id values of the notification and device. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /notifications/{notificationId}/devices/{deviceId}

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification for which device information is desired.
deviceId The Device id of the specific device of interest.

Response

The notification devices response format is detailed here.

Notification Devices Response

The JSON document used to represent a notification device resource has the following content:

Attribute Type Description
attributes Object The attributes of the device.createdAt
createdAt ISO 8601 date/time When this notification device was created.
endpoint Object When endpoint is not null, provides more information about the associated endpoint.
endpointId UUID Identifies the endpoint, if any, associated with the device.
id UUID The device’s id.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
name String The device’s name.
notificationId String The id of the Notification whose devices are being examined.
type String The type of the device, such as singlewire:email, singlewire:CiscoIPPhone, apns, Android, etc. (see below)
userId String The id of the User the device belongs to. null indicates it doesn’t belong to a user.

Notification Device Types

The type parameter provides information about what kind of device received the notification. If it was delivered through the cloud over the public internet, this will be one of the following values:

Type Description
Android Push notifications to Android devices
apns Push notifications to Apple iOS devices
apns-desktop Push notifications to macOS desktops
msteams-chat Microsoft Teams clients
phone-call Voice phone call devices
singlewire:email Email clients
SMS Mobile phone Short Message Service text devices
WNS Push notifications to Windows devices

If the device was reached over an on-premises network through a Fusion server, it will be one of:

Type Description
IPSpeaker Physical IP speaker or an InformaCast Desktop Notifier
M2M_OutputPort Machine-to-machine interface port
Multicast Stream Preconfigured multicast stream
PagingGateway Paging gateway
QuickURL Preconfigured QuickURL
singlewire:CiscoIPPhone Cisco IP phone

Notification Device Types

The type parameter provides information about what kind of device received the notification. If it was delivered through the cloud over the public internet, this will be one of the following values:

Type Description
Android Push notifications to Android devices
apns Push notifications to Apple iOS devices
apns-desktop Push notifications to macOS desktops
msteams-chat Microsoft Teams clients
phone-call Voice phone call devices
singlewire:email Email clients
SMS Mobile phone Short Message Service text devices
WNS Push notifications to Windows devices

If the device was reached over an on-premises network through a Fusion server, it will be one of:

Type Description
IPSpeaker Physical IP speaker or an InformaCast Desktop Notifier
M2M_OutputPort Machine-to-machine interface port
Multicast Stream Preconfigured multicast stream
PagingGateway Paging gateway
QuickURL Preconfigured QuickURL
singlewire:CiscoIPPhone Cisco IP phone

Notification Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Notifications are assigned to the acting domain of the sending user. This resource lets you see which Notifications were sent in which Domains.

List All Notification Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "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/",
      "notificationId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Notification belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /notifications/{notificationId}/domains

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification whose associated Domains are to be listed.

Query Parameters

There will always only be one Domain associated with a Notification, reflecting the Domain in which the sender was acting at the time it was sent, so the standard pagination mechanism is not needed for this resource.

Additionally, you can request the subdomains of the Domain attached to the specified Notification 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 the Domain that is directly attached to the specified Notification, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the notification whose domains were requested is returned under the key notificationId inside each domain response.

Check if a Notification contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/notifications/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/notifications/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/notifications/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "notificationId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Notification Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /notifications/{notificationId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
notificationId The id of the Notification whose Domains are of interest.
id The id of the Domain you want to know whether the Notification belongs to.

Additionally, you can check if the Notification is attached to any subdomains of the specified Domain using a query parameter:

Parameter Type Description
recursive boolean If true, in addition to the Domain that is directly attached to the specified Notification, any of its subdomains will be considered.

Response

If the Notification 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.

Outbound Rules

Outbound Rules are attached to Inbound Email configurations and determine which message template and recipients will be used to generate a notification based on matching criteria. The criteria consist of keywords found in either the body or the subject of an incoming email. Note that these rules work in conjunction with the source whitelist of the Inbound Email configuration. Matching contents must still come from an approved source.

List All Outbound Rules

For any given Inbound Email configuration, you can list all of its attached rules.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
    "id": "005ee115-1d7f-11e8-b54a-9f98cdfae16f",
    "name": "Fire Door Info",
    "messageTemplateId": "0f6a8665-ba87-11e7-b746-8303657d168e",
    "messageTemplate": { ... },
    "bodyCriteria": [],
    "subjectCriteria": [ "door" ],
    "createdAt": "2018-03-01T18:34:06.807Z",
    "distributionListIds": [],
    "distributionLists": [],
    "userIds": [],
    "users": [],
    "inboundEmailId": "bd263f53-1d66-11e8-b54a-d7bec9371d33",
    "permissions": [ "delete", "put", "get" ]
  },
 ]
}

Retrieves the list of all Outbound Rules.

HTTP Request

GET /inbound-email/{inboundId}/outbound-rules/

Produces

application/json

Query Parameters

Results can be retrieved in groups using the API’s pagination parameters. There was only 1 ruleset available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can filter requests using some ruleset-specific query parameters:

Parameter Type Description
name String Returns Rules whose names match the supplied value

Response

The Outbound Rules response format is detailed here.

Get an Outbound Rule

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules/005ee115-1d7f-11e8-b54a-9f98cdfae16f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    rule = JSON.parse(HTTParty.get(url, headers: headers))
    puts(rule)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules/005ee115-1d7f-11e8-b54a-9f98cdfae16f" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules/005ee115-1d7f-11e8-b54a-9f98cdfae16f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    rule = requests.get(url, headers=headers).json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "005ee115-1d7f-11e8-b54a-9f98cdfae16f",
 "name": "Fire Door Info",
 "messageTemplateId": "0f6a8665-ba87-11e7-b746-8303657d168e",
 "messageTemplate": { ... },
 "bodyCriteria": [],
 "subjectCriteria": [ "door" ],
 "createdAt": "2018-03-01T18:34:06.807Z",
 "distributionListIds": [],
 "distributionLists": [],
 "userIds": [],
 "users": [],
 "inboundEmailId": "bd263f53-1d66-11e8-b54a-d7bec9371d33",
 "permissions": [ "delete", "put", "get" ]
}

Retrieves a single Outbound Rule by ruleId and inboundId. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /inbound-email/{inboundId}/outbound-rules/{ruleId}

Produces

application/json

Path Parameters

Parameter Description
inboundId The id of the owning Inbound Email configuration
ruleId The id of the Outbound Rule to retrieve

Response

The Outbound Rules response format is detailed here.

Create an Outbound Rule

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Fire Door Info'
,
    'messageTemplateId': '0f6a8665-ba87-11e7-b746-8303657d168e'
,
    'subjectCriteria': 'door'

}

begin: 
    rule = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(rule)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fire Door Info", \
       "messageTemplateId": "0f6a8665-ba87-11e7-b746-8303657d168e", \
       "subjectCriteria": "door"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Fire Door Info',
    'messageTemplateId': '0f6a8665-ba87-11e7-b746-8303657d168e',
    'subjectCriteria': 'door'
}

try: 
    rule = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(rule)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "005ee115-1d7f-11e8-b54a-9f98cdfae16f",
  "name": "Fire Door Info",
  "messageTemplateId": "0f6a8665-ba87-11e7-b746-8303657d168e",
  "messageTemplate": { ... },
  "bodyCriteria": [],
  "subjectCriteria": [ "door" ],
  "createdAt": "2018-03-01T18:34:06.807Z",
  "distributionListIds": [],
  "distributionLists": [],
  "userIds": [],
  "users": [],
  "inboundEmailId": "bd263f53-1d66-11e8-b54a-d7bec9371d33",
  "permissions": [ "delete", "put", "get" ]
}

Create a new Outbound Rule.

HTTP Request

POST /inbound-email/{inboundId}/outbound-rules

Path Parameters

Parameter Description
inboundId The id of the owning Inbound Email configuration

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
bodyCriteria Array[String] N/A Optional list of words or phrases that will match in the body of the inbound email
disabled Boolean false Whether or not this rule should be used in evaluating inbound emails
distributionListIds Array[UUID] N/A Optional list of distribution list IDs to use when creating the notification
messageTemplateId UUID N/A The Message Template to use when creating a notification
name String N/A The Rule’s display name
subjectCriteria Array[String] N/A Optional list of words or phrases that will match in the subject of the inbound email
userIds Array[UUID] N/A Optional list of user IDs to use when creating the notification

Note that the recipients (users and distribution lists) will override any recipients specified in the associated message template. If no overrides are given, the values from the message template will be used.

Also note that the subject and body criteria are considered “any” criteria. If any keywords are found in their respective location, the ruleset will be used to generate a notification. If multiple criteria from one ruleset match, only one notification will be sent. However, if multiple rulesets from a given Inbound Email configuration match, each ruleset will generate its own notification.

Response

The Outbound Rules response format is detailed here.

Update an Outbound Rule

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules/005ee115-1d7f-11e8-b54a-9f98cdfae16f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Gym Fire Doors'
,
    'subjectCriteria': ['gym'
, 'door'
]

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules/005ee115-1d7f-11e8-b54a-9f98cdfae16f" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Gym Fire Doors", \
       "subjectCriteria": ["gym", "door"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules/005ee115-1d7f-11e8-b54a-9f98cdfae16f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Gym Fire Doors',
    'subjectCriteria': ['gym', 'door']
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "005ee115-1d7f-11e8-b54a-9f98cdfae16f",
  "name": "Gym Fire Doors",
  "messageTemplateId": "0f6a8665-ba87-11e7-b746-8303657d168e",
  "messageTemplate": { ... },
  "bodyCriteria": [],
  "subjectCriteria": [ "gym", "door" ],
  "createdAt": "2018-03-01T18:34:06.807Z",
  "distributionListIds": [],
  "distributionLists": [],
  "userIds": [],
  "users": [],
  "inboundEmailId": "bd263f53-1d66-11e8-b54a-d7bec9371d33",
  "permissions": [ "delete", "put", "get" ]
}

Updates an existing Outbound Rule.

HTTP Request

PUT /inbound-email/{inboundId}/outbound-rules/{ruleId}

Path Parameters

Parameter Description
inboundId The id of the owning Inbound Email configuration
ruleId The id of the Outbound Rule to retrieve

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
bodyCriteria Array[String] N/A Optional list of words or phrases that will match in the body of the inbound email
disabled Boolean false Whether or not this rule should be used in evaluating inbound emails
distributionListIds Array[UUID] N/A Optional list of distribution list IDs to use when creating the notification
messageTemplateId UUID N/A The Message Template to use when creating a notification
name String N/A The Rule’s display name
subjectCriteria Array[String] N/A Optional list of words or phrases that will match in the subject of the inbound email
userIds Array[UUID] N/A Optional list of user IDs to use when creating the notification

Note that the recipients (users and distribution lists) will override any recipients specified in the associated message template. If no overrides are given, the values from the message template will be used.

Also note that the subject and body criteria are considered “any” criteria. If any keywords are found in their respective location, the ruleset will be used to generate a notification. If multiple criteria from one ruleset match, only one notification will be sent. However, if multiple rulesets from a given Inbound Email configuration match, each ruleset will generate its own notification.

Response

The Outbound Rules response format is detailed here.

Remove an Outbound Rule

# Continuing with the outbound rule object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/inbound-email/bd263f53-1d66-11e8-b54a-d7bec9371d33/outbound-rules/005ee115-1d7f-11e8-b54a-9f98cdfae16f" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the outbound rule object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted  005ee115-1d7f-11e8-b54a-9f98cdfae16f"
}

Deletes an existing Outbound Rule.

HTTP Request

DELETE /inbound-email/{inboundId}/outbound-rules/{ruleId}

Produces

application/json

Path Parameters

Parameter Description
inboundId The id of the owning Inbound Email configuration
ruleId The id of the Outbound Rule to retrieve

Response

The deletion response format is detailed here.

Outbound Rules Response

The JSON document used to represent a Outbound Rule resource has the following content:

Attribute Type Description
id UUID The id of the ruleset
inboundEmailId UUID The id of the associated Inbound Email configuration
bodyCriteria Array[String] List of keywords to be compared against the body of the incoming email. If any matches are found, this rule will be used
createdAt ISO 8601 date/time When this Outbound Rule was created.
disabled Boolean Whether or not this outbound ruleset is active. A disabled ruleset does not necessarily disable the associated Inbound Email configuration
distributionLists Array[JSON] The Distribution Lists (if any) that will receive notifications sent from this ruleset
messageTemplate JSON A filled-out copy of the Message Template associated with this ruleset
name String The Rule’s display name
subjectCriteria Array[String] List of keywords to be compared against the subject of the incoming email. If any matches are found, this rule will be used
users Array[JSON] The Users (if any) that will receive notifications sent from this ruleset

Note that the recipients (users and distribution lists) will override any recipients specified in the associated message template. If no overrides are given, the values from the message template will be used.

Also note that the subject and body criteria are considered “any” criteria. If any keywords are found in their respective location, the ruleset will be used to generate a notification. If multiple criteria from one ruleset match, only one notification will be sent. However, if multiple rulesets from a given Inbound Email configuration match, each ruleset will generate its own notification.

Outbound Systems

Reports

Provides information about consumable resources available to the account associated with the access token. Currently this focuses on voice dialing and SMS messaging, but other reports will be added as more features are made available.

List the Available Reports

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    reports = JSON.parse(HTTParty.get(url, headers: headers))
    puts(reports)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    reports = requests.get(url, headers=headers).json()
    print(reports)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 12,
 "previous": null,
 "next": null,
 "data": [
  {
   "id": "ffb9be7a-73bf-11e7-81a9-bb2acacbf0d9",
   "name": "AnonymousUsers",
   "description": null,
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2017-07-28T18:10:12.440Z"
  },
  {
    "id": "fba2f02e-7d23-11eb-9439-0242ac130002",
    "name": "Confirmation",
    "description": "Provides information about confirmation responses by date ranges and other filters",
    "permissions": [
      "delete",
      "put",
      "get"
    ],
    "createdAt": "2021-03-04T19:58:26.401Z"
  },
  {
   "id": "30a05e90-9156-11e6-b405-11f7f6be9a24",
   "name": "GeneralCounts",
   "description": "Provides general counts such as subscription sizes and usage.",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2016-10-13T15:03:25.041Z"
  },
  {
   "id": "3928be41-8695-11e7-826d-bf8eb3f35a45",
   "name": "NotificationActivitiesRollingSum",
   "description": "Provides a rolling sum of notification activities at second or minute intervals",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2017-08-21T17:21:52.531Z"
  },
  {
   "id": "fffce1fb-73bf-11e7-81a9-f312ef69431f",
   "name": "NotificationHistory",
   "description": "Provides notification history and usage information by date ranges and other filters",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2017-07-28T18:10:12.880Z"
  },
  {
   "id": "ff695489-73bf-11e7-81a9-3557b17e8348",
   "name": "OptedOut",
   "description": "Deprecated (users can no longer opt out of message templates).",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2017-07-28T18:10:11.913Z"
  },
  {
   "id": "40c2d980-5c87-11e5-836c-92a0fedb8915",
   "name": "TelephonyNumbers",
   "description": "Provides the current telephony numbers available for this account.",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2015-09-16T15:26:08.152Z"
  },
  {
   "id": "fec17bc8-73bf-11e7-81a9-f7379b42fa1e",
   "name": "Users",
   "description": "Provides information about users, optionally filtered by distribution lists or security groups",
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "createdAt": "2017-07-28T18:10:10.813Z"
  }
 ]
}

Retrieves the list of all reports available. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of reports.)

HTTP Request

GET /reports

Produces

application/json

Query Parameters

Even though the response is wrapped in the structure used by the standard Informacast Mobile API pagination mechanism for list requests, the Reports resource cannot yet be paginated or queried, and this list request will always return the fixed list of available reports, ignoring pagination or query parameters. This may change when more reports are available.

Response

The reports response format is different for each individual report. The response to this list query has the following content:

Attribute Type Description
created­At ISO 8601 date/time When this report was created.
name String The report name
id String The id of the report, used to GET its contents.
desc­ription String The purpose and contents of this report.
permi­ssions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Get the Telephony Numbers report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/40c2d980-5c87-11e5-836c-92a0fedb8915"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/40c2d980-5c87-11e5-836c-92a0fedb8915" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/40c2d980-5c87-11e5-836c-92a0fedb8915"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    report = requests.get(url, headers=headers).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
[
  {
    "id": "43ef84bf-cde4-11eb-a68f-ab869a740f69",
    "phoneNumber": "+16082162326",
    "createdAt": "2015-09-12T13:57:10.000Z",
    "type": "local",
    "primary": true,
    "serviceProvider": "twilio"
  },
  {
    "id": "44ef84bf-cde4-11eb-a68f-ab869a740132",
    "number": "+18883716604",
    "createdAt": "2015-09-10T14:56:49.000Z",
    "type": "toll-free",
    "primary": true,
    "serviceProvider": "twilio"
  }
]

Provides the current telephony numbers available for this account

HTTP Request

GET /reports/40c2d980-5c87-11e5-836c-92a0fedb8915

Produces

application/json

Response

The Telephony Numbers Report is an array of small maps, each with the following content:

Attribute Type Description
id UUID The unique identifier of this phone number entry.
phoneNumber String The E164 formatted phone number. If type is “toll-free-unverified” this will have the value “pending” until the number has been verified for high-throughput calling, and it will not yet be used.
created­At ISO 8601 date/time When this phone number was added to the account.
type String One of “local”, “toll-free”, or “toll-free-unverified”.
primary Boolean A boolean showing if this number comes from the primary telephony service provider assigned to the account.
serviceProvider String The name of the underlying telephony service provider which provides access to the phone number.

Get the General Counts Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/30a05e90-9156-11e6-b405-11f7f6be9a24"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/30a05e90-9156-11e6-b405-11f7f6be9a24" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/30a05e90-9156-11e6-b405-11f7f6be9a24"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    report = requests.get(url, headers=headers).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
 "usersCount": 7817,
 "androidDevicesCount": 0,
 "speakersCount": 0,
 "pluginsCount": 1,
 "maxSpeakers": 1000,
 "fusionServersCount": 1,
 "anonymousUsersCount": 2,
 "applicationsCount": 36,
 "idnsCount": 0,
 "lockedUsersCount": 13,
 "emailDevicesCount": 7793,
 "anonymousSubscriptionSize": 0,
 "maxFusionServers": 12,
 "phoneCallDevicesCount": 0,
 "phonesCount": 7892,
 "userIpPhonesCount": 0,
 "iosDevicesCount": 0,
 "smsDevicesCount": 1,
 "maxIdns": 1000,
 "maxPhones": 20000,
 "subscriptionSize": 10000
}

Provides general counts such as subscription sizes and usage.

HTTP Request

GET /reports/30a05e90-9156-11e6-b405-11f7f6be9a24

Produces

application/json

General Counts Report Response

The General Counts Report is an object with the following keys/counts:

Attribute Type Description
usersCount Integer The number of users currently in the system
androidDevicesCount Integer The number of android devices currently in the system
speakersCount Integer The number of fusion speakers currently in the system
pluginsCount Integer The number of fusion plugins currently in the system
maxSpeakers Integer The max number of speakers the system is licensed for
fusionServersCount Integer The number of fusion servers currently in the system
anonymousUsersCount Integer The number of anonymous users currently in the system
applicationsCount Integer The number of applications currently in the system
idnsCount Integer The number of fusion desktop notifiers currently in the system
lockedUsersCount Integer The number of locked users currently in the system
emailDevicesCount Integer The number of email devices currently in the system
anonymousSubscriptionSize Integer The max number of anonymous users the system is licensed for
maxFusionServers Integer The max number of fusion servers the system is licensed for
maxIdns Integer The max number of fusion desktop notifiers the system is licensed for
maxPhones Integer The max number of fusion phones the system is licensed for
subscriptionSize Integer The max number of users the system is licensed for
phoneCallDevicesCount Integer The number of phone call devices currently in the system
userIpPhonesCount Integer The number of fusion phones attached to users currently in the system
iosDevicesCount Integer The number of iOS devices currently in the system
smsDevicesCount Integer The number of SMS devices currently in the system

Get the Users Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/fec17bc8-73bf-11e7-81a9-f7379b42fa1e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/fec17bc8-73bf-11e7-81a9-f7379b42fa1e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/fec17bc8-73bf-11e7-81a9-f7379b42fa1e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    report = requests.get(url, headers=headers).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 3,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "securityGroups": [
    {
     "name": "West Office"
    }
   ],
   "email": "inigo.montoya@singlewire.com",
   "dnd": null,
   "name": "Inigo Montoya",
   "passwordResetRequired": false,
   "id": "4fe68e57-9c5d-11e6-afd5-71c33bd4bd8a",
   "devices": [
    {
     "id": "4472c080-6f93-11ed-bd45-e9015319eec7",
     "name": null,
     "type": "singlewire:email",
     "deviceIdentifier": "revenge@singlewire.com",
     "blocklistTimestamp": null,
     "isBlocklistedInUserLoader": false
    },
   ],
   "isLocked": false,
   "distributionLists": [
    {
     "name": "Administrator Alerts"
    }
   ]
  },
  {
   "securityGroups": [
    {
     "name": "Admin"
    }
   ],
   "email": "mycroft.holmes@singlewire.com",
   "dnd": null,
   "name": "Mycroft Holmes",
   "passwordResetRequired": false,
   "id": "42532c36-4478-11e6-9ba6-fb22bf89f89a",
   "devices": [
    {
     "id": "ccc651ef-9091-11ed-97df-8162c2b6de92",
     "name": "Mobile",
     "type": "SMS",
     "deviceIdentifier": "+15552342345",
     "disabled": false,
     "blocklistTimestamp": null,
     "isBlocklistedInUserLoader": false
    },
    {
     "id": "5be92f6c-8de1-11ed-b24e-ad2a1e080a9c",
     "name": "Mobile",
     "type": "phone-call",
     "deviceIdentifier": "+15552342345",
     "disabled": false,
     "blocklistTimestamp": "2020-01-01T09:41:00+00:00",
     "isBlocklistedInUserLoader": true
    },
    {
     "id": "8fee244b-8de1-11ed-b24e-118907468a97",
     "name": "Lunar iPhone",
     "type": "apns",
     "disabled": false,
     "deviceIdentifier": "5b1c7a840a2b715d45357700bfdd9de56c9ad7aed7bdc858d367828797a557ae",
     "blocklistTimestamp": null,
     "isBlocklistedInUserLoader": true
    }
   ],
   "isLocked": false,
   "distributionLists": [
    {
     "name": "Administrator Alerts"
    }
   ]
  },
  {
   "securityGroups": null,
   "email": "westley@singlewire.com",
   "dnd": null,
   "name": "Westley",
   "passwordResetRequired": false,
   "id": "4fd79a30-9c5d-11e6-afd5-dd18ca160fa0",
   "devices": [
    {
     "id": "1b026c51-dddc-11ec-b834-692eee7c86cc",
     "name": null,
     "type": "singlewire:email",
     "disabled": true,
     "deviceIdentifier": "first@singlewire.com",
     "blocklistTimestamp": null,
     "isBlocklistedInUserLoader": false
    }
   ],
   "isLocked": false,
   "distributionLists": null
  }
 ]
}

Provides information about users registered with InformaCast Mobile.

HTTP Request

GET /reports/fec17bc8-73bf-11e7-81a9-f7379b42fa1e

Produces

application/json

Query Parameters

The content of the report can be customized by supplying the following query parameters as part of the request:

Parameter Type Description
distribution­ListIds UUID or Array[UUID] Return users belonging to these distribution lists.
security­GroupIds UUID or Array[UUID] Return users belonging to these security groups.

If both parameters are given, the users who are present in either the specified distribution lists or security groups will be included in the report. If neither is given, then all users will be included in the report.

The standard Informacast Mobile API pagination parameters can also be used.

Users Report Response

The Users Report has the following content:

Attribute Type Description
devices Array[Device] The endpoint devices associated with the user. Note this is the device object below, not a standard device responce.
dnd Object Do not disturb settings for the user, if any.
distribution­Lists Array[DistributionList] The distribution lists to which the user is subscribed.
email String The user’s email address; will be missing for users whose type is anonymous or application.
id String The id of the user, for efficient retrieval, manipulation, or looking up sub-resources attached to the user.
isLocked Boolean Indicates whether the user account has been locked out.
name String The user’s name.
passwordReset­Required boolean Whether the user will be forced to set a new password on next login (available only for Providers configured to use InformaCast’s own Identity Provider for login). Note that includeIdp=true must be passed as a query param for this value to be shown.
securityGroups Array[SecurityGroup] The user’s security groups.

Users Report Device Object

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.
type String The type of device, such as `“apns”
disabled Boolean Whether to skip this device when sending notifications.
deviceIdentifier String The unique identifier used to address this device, such as an email address, normalized phone number, or push notification token.
blocklistTimestamp String The ISO-8601 timestamp when the device was added to the user loader blocklist, if blocklisted. May be null if blocklisted before timestamps were tracked.
isBlocklistedInUserLoader Boolean Whether a match for this device is on the user loader blocklist, preventing it from being updated by future runs of the user loader.

Get the Anonymous Users Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/ffb9be7a-73bf-11e7-81a9-bb2acacbf0d9"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/ffb9be7a-73bf-11e7-81a9-bb2acacbf0d9" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/ffb9be7a-73bf-11e7-81a9-bb2acacbf0d9"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    report = requests.get(url, headers=headers).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "userId": "1a172e36-3f02-11e6-9617-9fc8b50f4de3",
   "devices": [
    {
     "name": null,
     "type": "SMS",
     "deviceIdentifier": "+16085551234"
    }
   ],
   "distributionLists": [
    {
     "name": "Homecoming",
     "campaignSubscribeTag": "#homeagain",
     "campaignEnrollmentEndDate": null
    }
   ]
  }
 ]
}

Provides information about anonymous users that have signed up with InformaCast Mobile. This may be useful to clean up users who signed up for notification during campaigns that are no longer in use.

HTTP Request

GET /reports/ffb9be7a-73bf-11e7-81a9-bb2acacbf0d9

Produces

application/json

Query Parameters

The content of the report can be customized by supplying the following query parameter as part of the request:

Parameter Type Description
distribution­ListIds UUID or Array[UUID] Return users belonging to these distribution lists.

If the parameter is not given, then all anonymous users will be included in the report.

The standard Informacast Mobile API pagination parameters can also be used.

Anonymous Users Report Response

The Anonymous Users Report has the following content:

Attribute Type Description
devices Array[Device] The endpoint devices associated with the user.
distribution­Lists Array[DistributionList] The distribution lists to which the user is subscribed, most likely via a campaign, but an administrator may have added them to others.
email String The user’s email address; will be missing for users whose type is anonymous or application.
userId String The id of the user, for efficient retrieval, manipulation, or looking up sub-resources attached to the user.

Get the Opted Out Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/ff695489-73bf-11e7-81a9-3557b17e8348"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'messageTemplateId': '4f86d775-4478-11e6-906f-65d9c7017cc7'

}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/ff695489-73bf-11e7-81a9-3557b17e8348?messageTemplateId=4f86d775-4478-11e6-906f-65d9c7017cc7" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/ff695489-73bf-11e7-81a9-3557b17e8348"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'messageTemplateId': '4f86d775-4478-11e6-906f-65d9c7017cc7'
}

try: 
    report = requests.get(url, headers=headers, params=params).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
    "total": 0,
    "previous": null,
    "next": null,
    "partial": false,
    "data": []
    ]
}

No longer provides any values.

HTTP Request

GET /reports/ff695489-73bf-11e7-81a9-3557b17e8348?messageTemplateId=4f86d775-4478-11e6-906f-65d9c7017cc7

Produces

application/json

Query Parameters

You must specify which message template you are interested in finding opted-out users for using the following query parameter as part of the request:

Parameter Type Description
message­templateId UUID Return users who have opted out from this message template.

The standard Informacast Mobile API pagination parameters can also be used.

Opted Out Report Response

The Users Report has the following content:

Attribute Type Description
email String The user’s email address.
id String The id of the user, for efficient retrieval, manipulation, or looking up sub-resources attached to the user.
name String The user’s name.

Get the Notification History Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/fffce1fb-73bf-11e7-81a9-f312ef69431f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/fffce1fb-73bf-11e7-81a9-f312ef69431f?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/fffce1fb-73bf-11e7-81a9-f312ef69431f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    report = requests.get(url, headers=headers, params=params).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
    "total": 126,
    "previous": null,
    "next": "2",
    "partial": true,
    "data": [
        {
            "id": "22578ad8-447a-11e6-8b4b-05d1e2b39e7a",
            "createdAt": "2016-07-07T14:36:43Z",
            "subject": "Get out of the pool!",
            "recipientCount": 1,
            "senderName": "Sandra Smith",
            "notificationProgress": {
              "0a466b30-7670-11e5-ba6e-765ae9d26291": {"type": "device", "total": 1, "failed": 0, "completed": 1, "deviceType": "phone-call"},
              "1a172e36-3f02-11e6-9617-9fc8b50f4de1": {"type": "device", "total": 1, "failed": 0, "completed": 0, "deviceType": "apns-sandbox"},
              "5a181177-3f02-11e6-9617-6bb7c7eddc0e": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "Android"},
              "5fdb030c-18e7-11e7-9f96-273f619cf339": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "apns-qa"},
              "6ff812ad-18e7-11e7-9f96-1d559a8159e8": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "Android-qa"},
              "17c57b50-833d-11e5-b222-def38c5ff9e6": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "SMS"},
              "56d6e006-542e-11e6-ae77-e3b4cf41fce9": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:idn-fusion"},
              "80cfc5a5-07d4-11e6-aff6-531fd60d022a": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:cisco-phone"},
              "839771a8-4915-11e6-8b2f-d310e58d9c03": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "apns"},
              "b6d90e60-2a40-11e5-8134-9a9e6c05013a": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:email"},
              "d9a04cbb-1845-11e6-ab29-f702f1c59dca": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:sip-call"},
              "e1b2db4b-626a-11e7-a3f9-0de43455e893": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "outbound-cap-device"},
              "e322d549-4e80-11e6-af2d-9baf604d14b0": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:fusion"},
              "f0e5d932-c31f-11e8-b4c1-7831c1bab3f6": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "msteams-chat"}
            }
        },
        {
            "id": "e77f148c-447b-11e6-8b4b-e7f937426603",
            "createdAt": "2016-07-07T14:49:23Z",
            "subject": "ALL CLEAR! Resume normal activities.",
            "recipientCount": 14,
            "senderName": "Amit Feldman",
            "notificationProgress": {
              "0a466b30-7670-11e5-ba6e-765ae9d26291": {"type": "device", "total": 1, "failed": 0, "completed": 1, "deviceType": "phone-call"},
              "1a172e36-3f02-11e6-9617-9fc8b50f4de1": {"type": "device", "total": 1, "failed": 0, "completed": 0, "deviceType": "apns-sandbox"},
              "5a181177-3f02-11e6-9617-6bb7c7eddc0e": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "Android"},
              "5fdb030c-18e7-11e7-9f96-273f619cf339": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "apns-qa"},
              "6ff812ad-18e7-11e7-9f96-1d559a8159e8": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "Android-qa"},
              "17c57b50-833d-11e5-b222-def38c5ff9e6": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "SMS"},
              "56d6e006-542e-11e6-ae77-e3b4cf41fce9": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:idn-fusion"},
              "80cfc5a5-07d4-11e6-aff6-531fd60d022a": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:cisco-phone"},
              "839771a8-4915-11e6-8b2f-d310e58d9c03": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "apns"},
              "b6d90e60-2a40-11e5-8134-9a9e6c05013a": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:email"},
              "d9a04cbb-1845-11e6-ab29-f702f1c59dca": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:sip-call"},
              "e1b2db4b-626a-11e7-a3f9-0de43455e893": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "outbound-cap-device"},
              "e322d549-4e80-11e6-af2d-9baf604d14b0": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "singlewire:fusion"},
              "f0e5d932-c31f-11e8-b4c1-7831c1bab3f6": {"type": "device", "total": 0, "failed": 0, "completed": 0, "deviceType": "msteams-chat"}
            }
        }
    ]
}

Provides a historical summary of notifications sent, with a variety of filtering options.

HTTP Request

GET /reports/fffce1fb-73bf-11e7-81a9-f312ef69431f

Produces

application/json

Query Parameters

You can filter the specific notifications you are interested in learning about by using combinations of the following query parameters in the request:

Parameter Type Description
begin­Timestamp ISO 8601 date/time If present, only notifications which were sent at or after this time will be included.
distribution­ListId UUID If present, only notifications that were sent to a current member of this distribution list will be returned. Only one of distributionListId, securityGroupId, and userId can be supplied.
end­Timestamp ISO 8601 date/time If present, only notifications which were sent before or at this time will be included.
filter­Conference boolean If true, only notifications which started conference calls will be included.
filter­Sms boolean If true, only notifications which sent SMS messages will be included.
filter­Telephony boolean If true, only notifications which placed individual voice calls will be included.
security­GroupId UUID If present, only notifications that were sent by a current member of this security group will be returned. Only one of distributionListId, securityGroupId, and userId can be supplied.
userId UUID If present, only notifications that were sent to this user will be returned. Only one of distributionListId, securityGroupId, and userId can be supplied.

To make this example more concise, only the first two notifications were requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 126 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Notification History Response

The Notification History Report has the following content:

Attribute Type Description
activity­Counts Object A map of activity types to counts, summarizing the notification activities associated with the notification. Their details can be retrieved using the Notification Activities resource.
createdAt ISO 8601 date/time When the notification was sent.
id String The id of the notification, allowing more details about it and its activities to be retrieved.
recipient­Count Integer The number of recipients to whom the notification was sent.
sender­Name String The name of the user who sent the notification.
subject String The subject text of the notification.

Get the Notification Activity Rolling Sum Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/3928be41-8695-11e7-826d-bf8eb3f35a45"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'notificationId': '22578ad8-447a-11e6-8b4b-05d1e2b39e7a'
,
    'type': 'confirmation'

}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/3928be41-8695-11e7-826d-bf8eb3f35a45?notificationId=22578ad8-447a-11e6-8b4b-05d1e2b39e7a&type=confirmation" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/3928be41-8695-11e7-826d-bf8eb3f35a45"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'notificationId': '22578ad8-447a-11e6-8b4b-05d1e2b39e7a',
    'type': 'confirmation'
}

try: 
    report = requests.get(url, headers=headers, params=params).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
    "data": [
        {
            "time": "2016-07-07T14:37:47Z",
            "sum": 1
        }
        {
            "time": "2016-07-07T14:42:05Z",
            "sum": 2
        }
    ]
}

Provides a second-by-second (or minute-by-minute) view of the number of notification activities of a particular type that are coming in for a notification. This is used to provide the graphs in the live notification view of the administrative interface.

HTTP Request

GET /reports/3928be41-8695-11e7-826d-bf8eb3f35a45?notificationId=22578ad8-447a-11e6-8b4b-05d1e2b39e7a&type=confirmation

Produces

application/json

Query Parameters

You must specify which notification and activity type you are interested in by supplying the notificationId and type parameters in your request. You can get less fine-grained results by supplying a true value for minuteInterval.

Parameter Type Description
notification­Id UUID Identifies the notification whose activities you would like information about.
type String Options: set-read-status, confirmation sms-sent, sms-received, call-placed, call-answered, sms-failed, call-failed, email-queued, email-sent, email-failed. Identifies the type of activity you are interested in.
minute­Interval Boolean If true, activities will be summed at the level of minutes, otherwise they will be summed at the level of seconds.

Notification Activity Rolling Sum Response

The Notification History Report has the following content:

Attribute Type Description
time ISO 8601 date/time The minute (or second) at which the rolling sum is being computed.
sum Integer The total number of activities of the specified type which had been reported for the specified notification by the end of the reported time.

Get the Confirmation Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/ff695489-73bf-11e7-81a9-3557b17e8348"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'beginTimestamp': '2021-05-01T05:00:00.000Z'
,
    'endTimestamp': '2021-06-04T04:59:00.000Z'

}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/ff695489-73bf-11e7-81a9-3557b17e8348?beginTimestamp=2021-05-01T05:00:00.000Z&endTimestamp=2021-06-04T04:59:00.000Z" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/ff695489-73bf-11e7-81a9-3557b17e8348"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'beginTimestamp': '2021-05-01T05:00:00.000Z',
    'endTimestamp': '2021-06-04T04:59:00.000Z'
}

try: 
    report = requests.get(url, headers=headers, params=params).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "email": "westley@singlewire.com",
      "name": "Westley",
      "userId": "4fd79a30-9c5d-11e6-afd5-dd18ca160fa0",
      "confirmationResponseTimestamp": "2021-05-24T23:39:05Z",
      "notificationSubject": "Emergency Lockdown! The <INSERT COMPANY> has issued a lockdown. Please follow lockdown procedures and wait for the all-clear notification.",
      "confirmationRequestName": "Emergency Lockdown",
      "confirmationResponse": "I am safe: outside building",
      "notificationId": "2ee9d446-bce9-11eb-b7e1-1dcf88b8c199"
    }
  ]
}

Provides information about Users who have responded to Confirmation Requests within a specified time period.

HTTP Request

GET /reports/ff695489-73bf-11e7-81a9-3557b17e8348

Produces

application/json

Query Parameters

Parameter Type Description
beginTimestamp ISO 8601 date/time If present, only responses recorded at or after this time will be included.
endTimestamp ISO 8601 date/time If present, only responses recorded before or at this time will be included.

The standard Informacast Mobile API pagination parameters can also be used.

Confirmation Report Response

Attribute Type Description
confirmationRequestName String The name of the Confirmation Request.
confirmationResponse String The confirmation response the User selected.
confirmationResponseTimestamp ISO 8601 date/time When the User responded to the Confirmation Request.
email String The email address of the User.
name String The User’s name.
notificationId String The ID of the Notification whose Confirmation Request the User is responding to.
notificationSubject String The subject of the Notification whose Confirmation Request the User is responding to.
userId String The id of the User, for efficient retrieval, manipulation, or looking up sub-resources attached to the User.

Get the Token Expiration Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/reports/8fda36f6-4d02-11ee-a811-79b58e8b3a00"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'expires': '2023-11-01T05:00:00.000Z'

}

begin: 
    report = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(report)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/reports/8fda36f6-4d02-11ee-a811-79b58e8b3a00?expires=2023-11-01T05:00:00.000Z" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/reports/8fda36f6-4d02-11ee-a811-79b58e8b3a00"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'expires': '2023-11-01T05:00:00.000Z'
}

try: 
    report = requests.get(url, headers=headers, params=params).json()
    print(report)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [{
    "name": "Service Account Token",
    "client": null,
    "scope": null,
    "expires": "2023-11-18T13:51:24.337Z",
    "id": "979cc257-6e86-11ee-90b4-15fa97df7e15",
    "userId": "ccce7e69-6849-11ee-82df-4fd8c2594650",
    "notValidAfter": "2023-11-18T13:51:24.337Z",
    "endpoint": null,
    "user": {
        "id": "ccce7e69-6849-11ee-82df-4fd8c2594650",
        "name": "Service Account",
        "type": "application",
        "email": null,
        "application": "custom"
    }
  }]
}

Provides a list showing all tokens that are near expiration

HTTP Request

`GET /reports/8fda36f6-4d02-11ee-a811-79b58e8b3a00

Produces

application/json

Query Parameters

Parameter Type Description
expires ISO 8601 date/time If present, shows tokens that are filtered on their expiration time. This parameter supports the following operators: gte, lte, gt, lt. These may also be supplied to filter on a specific range such as with ?expires__gte=<ts>&expires__lte=<ts>. The default will only show 30 days.

The standard Informacast Mobile API pagination parameters can also be used.

Token Expiration Report Response

Attribute Type Description
id String The id of the User’s Token.
userId String The id of the User, for efficient retrieval, manipulation, or looking up sub-resources attached to the User.
name String The name of the token
client String The id of the client
scope String The scope of the token
expires ISO 8601 date/time When the token expires
notValidAfter ISO 8601 date/time The maximum amount of time a session can be extended.
user Object The User object that owns the token
endpoint Object The Extension Endpoint object that owns the token

Ring Lists

Ring lists represent the times and notifications that will be sent throughout the dates defined by the Bell Schedule. One can configure a time of day and the message template (with device group overrides or distribution list overrides) that will be broadcasted at that time.

List all Ring Lists

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    ring_lists = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(ring_lists)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    ring_lists = requests.get(url, headers=headers, params=params).json()
    print(ring_lists)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "data": [
    {
      "id": "95f5006b-7a3f-11e8-bcdc-798f6371a42a",
      "name": "Long Day",
      "description": "Schedule for Monday, Wednesday, and Friday",
      "entries": [
        {
          "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
          "time": "08:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
          "time": "09:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
          "time": "10:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
          "time": "11:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        }
      ],
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-06-27T19:23:35.219Z",
      "updatedAt": "2018-06-27T19:23:35.219Z"
    }
  ]
}

Retrieves a list of all ring lists. (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 /ring-lists

Produces

application/json

Query Parameters

To make this example more manageable, only the first ring list 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.
assoc-sync-state-for-endpoint String Include the current synchronization state for a specific fusion endpoint.
includeDomains Boolean If true, include the list of Domains to which the ring list belongs.

Response

The ring list response format is detailed here.

Get a Ring List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    ring_list = JSON.parse(HTTParty.get(url, headers: headers))
    puts(ring_list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    ring_list = requests.get(url, headers=headers).json()
    print(ring_list)
except RequestException as e:
    print('Unexpected error!', e)
{
      "id": "95f5006b-7a3f-11e8-bcdc-798f6371a42a",
      "name": "Long Day",
      "description": "Schedule for Monday, Wednesday, and Friday",
      "entries": [
        {
          "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
          "time": "08:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
          "time": "09:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
          "time": "10:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
          "time": "11:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        }
      ],
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-06-27T19:23:35.219Z",
      "updatedAt": "2018-06-27T19:23:35.219Z"
    }

Retrieves a single ring list by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /ring-lists/{ringListId}

Produces

application/json

Path Parameters

Parameter Description
ringListId The id of the Ring List to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which the ring list belongs.

Response

The ring list response format is detailed here.

Create a Ring List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Long Day'
,
    'description': 'Schedule for Monday, Wednesday, and Friday'
,
    'entries': [{
        'time': '08:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

, {
        'time': '09:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

, {
        'time': '10:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

, {
        'time': '11:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

]

}

begin: 
    ring_list = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(ring_list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Long Day", \
       "description": "Schedule for Monday, Wednesday, and Friday", \
       "entries": [{"time": "08:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}, {"time": "09:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}, {"time": "10:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}, {"time": "11:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Long Day',
    'description': 'Schedule for Monday, Wednesday, and Friday',
    'entries': [{
        'time': '08:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
, {
        'time': '09:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
, {
        'time': '10:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
, {
        'time': '11:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
]
}

try: 
    ring_list = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(ring_list)
except RequestException as e:
    print('Unexpected error!', e)
{
      "id": "95f5006b-7a3f-11e8-bcdc-798f6371a42a",
      "name": "Long Day",
      "description": "Schedule for Monday, Wednesday, and Friday",
      "entries": [
        {
          "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
          "time": "08:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
          "time": "09:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
          "time": "10:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
          "time": "11:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        }
      ]
    }

Creates a new ring list (limit: 3500).

HTTP Request

POST /ring-lists

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 ring list.
description String null An optional description for the ring list.
entries Array[Object] [] A list of entries attached to a ring list. Please see here for more information.

Response

The ring list response format is detailed here.

Update a Ring List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Long Day'
,
    'description': 'Schedule for Monday, Wednesday, and Friday'
,
    'entries': [{
        'time': '08:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

, {
        'time': '09:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

, {
        'time': '10:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

, {
        'time': '11:00:00'
,
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867'
,
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'
]
,
        'distributionListIds': []

}

]

}

begin: 
    ring_list = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(ring_list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Long Day", \
       "description": "Schedule for Monday, Wednesday, and Friday", \
       "entries": [{"time": "08:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}, {"time": "09:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}, {"time": "10:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}, {"time": "11:00:00", \
         "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867", \
         "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"], \
         "distributionListIds": []}]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Long Day',
    'description': 'Schedule for Monday, Wednesday, and Friday',
    'entries': [{
        'time': '08:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
, {
        'time': '09:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
, {
        'time': '10:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
, {
        'time': '11:00:00',
        'messageTemplateId': '0e5459e4-7a3e-11e8-bcdc-f74772038867',
        'deviceGroupIds': ['906828da-838e-11e8-ad75-c18b0bef82c4'],
        'distributionListIds': []
}
]
}

try: 
    ring_list = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(ring_list)
except RequestException as e:
    print('Unexpected error!', e)
{
      "id": "95f5006b-7a3f-11e8-bcdc-798f6371a42a",
      "name": "Long Day",
      "description": "Schedule for Monday, Wednesday, and Friday",
      "entries": [
        {
          "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
          "time": "08:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
          "time": "09:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
          "time": "10:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        },
        {
          "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
          "time": "11:00:00",
          "deviceGroups": [
            {
              "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
              "name": "All Speakers"
            }
          ],
          "distributionLists": null,
          "messageTemplate": {
            "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
            "name": "School Bell"
          },
          "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
          "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
          "distributionListIds": []
        }
      ]
    }

Updates an existing ring list.

HTTP Request

PUT /ring-lists/{ringListId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
ringListId The id of the Ring List to update.

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the ring list.
description String null An optional description for the ring list.
entries Array[Object] [] A list of entries attached to a ring list. Please see here for more information.

Response

The ring list response format is detailed here.

Remove a Ring List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted 95f5006b-7a3f-11e8-bcdc-798f6371a42a"
}

Deletes an existing ring list.

HTTP Request

DELETE /ring-lists/{ringListId}

Produces

application/json

Path Parameters

Parameter Description
ringListId The id of the Ring List to delete.

Response

The deletion response format is detailed here.

Ring List Entries

Ring list entries are the parts of a ring list that tie times to a bell tone to play, and recipients to broadcast to.

Ring list entries do not have their own endpoint, and they are strictly a nested resource within a ring list.

Attribute Type Description
id String The id of the ring list entry.
time String The time to broadcast the message templates audio to the recipients defined in the ring list entry. Must be in ISO 8601 hh:mm:ss format.
deviceGroups Array[Object] An array of objects which contain the id and name of a Device Group attached to the ring list entry.
distributionLists Array[Object] An array of objects which contain the id and name of a Distribution List attached to the ring list entry.
messageTemplate Object An object with the id and name of a Message Template attached to the ring list entry.
messageTemplateId String The id of the Message Template attached to the ring list entry.
deviceGroupIds Array[String] The id(s) of the Device Groups attached to the ring list entry.
distributionListIds Array[String] The id(s) of the Distribution Lists attached to the ring list entry.

Ring List Response

The JSON document used to represent a ring list resource has the following content:

Attribute Type Description
id String The id of this specific ring list, allowing it to be manipulated or retrieved individually.
name String The unique name of the ring list.
description String The description of the ring list.
entries Array[Objects] An array of ring list entries. Please see here for more details.
syncState Array[Object] The endpoints’ sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
endpointSyncState Object The specific endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state-for-endpoint is true.
createdAt ISO 8601 date/time When this ring list was created.
updatedAt ISO 8601 date/time When this ring list was last updated.

Ring List Domains

Domains allow for hierarchical delegation of authority over supported resources. When they are in use, Ring Lists are assigned to at least one Domain, and can be associated with more than one. This resource lets you see and adjust which Ring Lists are assigned to which Domains.

List All Ring List Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "ringListId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "ringListId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Ring 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 /ring-lists/{ringListId}/domains

Produces

application/json

Path Parameters

Parameter Description
ringListId The id of the Ring List whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Ring 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 Ring 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 Ring List, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the ring list whose domains were requested is returned under the key ringListId inside each domain response.

Check if a Ring List contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "ringListId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Ring List Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /ring-lists/{ringListId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
ringListId The id of the Ring List whose Domains are of interest.
id The id of the Domain you want to know whether the Ring List belongs to.

Additionally, you can check if the Ring 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 Ring List, any of their subdomains will be considered.

Response

If the Ring 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 Ring List Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-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"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "ringListId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

Puts the Ring 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 /ring-lists/{ringListId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
ringListId String The id of the Ring 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 Ring List out of a parent Domain?
id String n/a The id of the Domain to which the Ring List should be added.
promote Boolean false Allow this request to proceed even if it will promote the Ring List out of one or more child Domains?

A Ring 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 Ring 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 Ring List Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Ring List c54e4241-299b-11e8-94d3-2be9464da125"
}

Removes the specified Ring List from the specified Domain. As described below, if this is the only Domain that the Ring List currently belongs to, you need to supply an additional request parameter to confirm the deletion of the Ring List itself.

HTTP Request

DELETE /ring-lists/{ringListId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
ringListId The id of the Ring List whose Domain should be removed.
id The id of the Domain to be removed from the Ring List.

Request Parameters

Parameter Type Default Description
orphans String fail Option: delete, fail. What to do if this would leave the Ring List in no Domain.

A Ring List must always belong to at least one Domain, so if you try to remove the Ring List from the only Domain that it belongs to, the request must either fail, or delete the Ring 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 Ring List out of its last Domain will delete the Ring List.

Response

The deletion response format is detailed here.

Ring List Cloning

This resource is used to make a copy of the Ring List specified by id in the request path.

The only operation supported is POST.

Clone a Ring List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/ring-lists/95f5006b-7a3f-11e8-bcdc-798f6371a42a/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "14f5006b-7a3f-22e8-bcdc-798fa71a42a9",
  "name": "Long Day (Copy)",
  "description": "Schedule for Monday, Wednesday, and Friday",
  "entries": [
    {
      "id": "95fa308c-7a3f-11e8-bcdc-f58c41e03040",
      "time": "08:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95faa5bf-7a3f-11e8-bcdc-0d608ef926e9",
      "time": "09:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95faf3e2-7a3f-11e8-bcdc-79b029467fd3",
      "time": "10:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    },
    {
      "id": "95fb4205-7a3f-11e8-bcdc-270967cbcd4d",
      "time": "11:00:00",
      "deviceGroups": [
        {
          "id": "906828da-838e-11e8-ad75-c18b0bef82c4",
          "name": "All Speakers"
        }
      ],
      "distributionLists": null,
      "messageTemplate": {
        "id": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
        "name": "School Bell"
      },
      "messageTemplateId": "0e5459e4-7a3e-11e8-bcdc-f74772038867",
      "deviceGroupIds": ["906828da-838e-11e8-ad75-c18b0bef82c4"],
      "distributionListIds": []
    }
  ],
  "permissions": [],
  "createdAt": "2018-06-27T19:24:35.219Z"
}

Creates a copy of the specified Ring List. The name of the new copy is simply the original Ring List’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /ring-lists resource and GET permission to the Ring List they wish to copy.

HTTP Request

POST /ring-lists/{ringListId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
ringListId String The id of the Ring List to copy.

Response

The Ring List response format is detailed here.

Rule Actions

Rule actions provide a way to perform an action when a specific event takes place in InformaCast. Rule Actions are a composite resource, composed of a Rule and an Action. The rule is a JSON object that follows the format of the AWS Event Ruler library. If the rule matches an InformaCast event that has occurred then the action will fire. Currently the only supported InformaCast event to match on is initiating a Scenario Notification and the only action is sending a webhook request. Currently the only way to create a new rule action is through the Scenario Rule Actions APIs.

List Rule Actions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/rule-actions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/rule-actions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/rule-actions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
    {
      "id": "b3b9208b-6776-11ee-9019-f573fd11931c",
      "name": "My Rule Action",
      "description": "Rule Action Description",
      "action": {
        "type": "webhook",
        "webhook": {
          "url": "https://myapi.com",
          "body": {
            "value": "{\"createdAt\": }",
            "encryption": "none"
          },
          "method": "POST",
          "headers": [],
          "expireAfter": 90,
          "queryParams": [
            {
              "key": "includeTotal",
              "value": "true",
              "encryption": "none",
              "description": "Query param sent to webhook"
            }
          ]
        }
      },
      "rule": {
        "event": {
          "scenarioNotification": {
            "scenarioId": [
              "548b801e-1b3c-11ee-a926-83e8a52234b4"
            ]
          }
        },
        "sourceType": [
          "scenario-notification"
        ]
      },
      "createdAt": "2023-10-10T14:10:01.412Z",
      "permissions": [
        "get"
      ]
    }
  ]
}

Retrieves the list of all rule actions. The visibility of rule actions may be limited by the permissions associated with the request, which are attributed through the user attached to the access token.

HTTP Request

GET /rule-actions

Produces

application/json

Query Parameters

To make this example more manageable, only the first Rule Action was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The rule action response format is detailed here

Get a Rule Action

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/rule-actions/cd2ec764-01a7-11e6-91d9-339e9d3d9df4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    rule_action = JSON.parse(HTTParty.get(url, headers: headers))
    puts(rule_action)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/rule-actions/cd2ec764-01a7-11e6-91d9-339e9d3d9df4" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/rule-actions/cd2ec764-01a7-11e6-91d9-339e9d3d9df4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    rule_action = requests.get(url, headers=headers).json()
    print(rule_action)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "b3b9208b-6776-11ee-9019-f573fd11931c",
  "name": "My Rule Action",
  "description": "Rule Action Description",
  "action": {
    "type": "webhook",
    "webhook": {
      "url": "https://myapi.com",
      "body": {
        "value": "{\"createdAt\": }",
        "encryption": "none"
      },
      "method": "POST",
      "headers": [],
      "expireAfter": 90,
      "queryParams": [
        {
          "key": "includeTotal",
          "value": "true",
          "encryption": "none",
          "description": "Query param sent to webhook"
        }
      ]
    }
  },
  "rule": {
    "event": {
      "scenarioNotification": {
        "scenarioId": [
          "548b801e-1b3c-11ee-a926-83e8a52234b4"
        ]
      }
    },
    "sourceType": [
      "scenario-notification"
    ]
  },
  "createdAt": "2023-10-10T14:10:01.412Z",
  "permissions": [
    "get"
  ]
}

Retrieves a single rule action by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /rule-actions/{ruleActionId}

Produces

application/json

Path Parameters

Parameter Description
ruleActionId The id of the rule action to retrieve.

Response

The rule action response format is detailed here

Rule Action Response

The JSON document used to represent a Rule Action resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this rule action was created.
id String The id of the rule action.
name String The Name of the rule action.
permissions array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
description String The description of the rule action.
action Object The JSON object that describes the action to be taken when a rule matches an event.
rule Object The JSON object that describes which events to match on using the AWS Event Ruler.

Scenarios

Scenarios allow users to press a button and send a series of notifications to separate audiences in response to an emergency or a set of circumstances. There are several types of scenarios:

List Scenarios

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 3,
  "partial": true,
  "previous": null,
  "next": "1",
  "data": [
    {
      "id": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "incidentPlanId": null,
      "name": "Severe Weather",
      "icon": "flash",
      "backgroundColor": "#0d2458",
      "locationEnabled": true,
      "locationQuestionName": "At which location?",
      "locationVariable": null,
      "defaultSite": null,
      "defaultBuilding": null,
      "defaultFloor": null,
      "defaultZone": null,
      "fields": [
        {
          "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
          "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
          "name": "At which location?",
          "rank": 0,
          "variable": "site",
          "type": "site",
          "answer": null,
          "options": null,
          "createdAt": "2019-02-28T18:23:38.329Z"
        },
        {
          "id": "397d424a-39fd-11e9-8c83-8de4247efba1",
          "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
          "name": "What type of severe weather is in the area?",
          "rank": 1,
          "variable": "weather_type",
          "type": "option",
          "answer": "Tornado Warning",
          "options": [
            "Tornado Warning",
            "Tornado Watch",
            "Winter Weather Warning"
          ],
          "createdAt": "2019-02-26T19:32:16.553Z"
        },
        {
          "id": "397d424c-39fd-11e9-8c83-d795bd1d0ad9",
          "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
          "name": "Are there any further instructions that should be sent to the security team?",
          "rank": 2,
          "variable": "info",
          "type": "text",
          "answer": "Hotkey-triggered Tornado Warning",
          "options": null,
          "createdAt": "2019-02-26T19:32:16.553Z"
        }
      ],
      "messages": [
        {
          "siteRoleIds": [
            "bf5f4f46-2bb5-11e9-8180-5fe10bc30744"
          ],
          "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
          "messageTemplate": { ... },
          "name": "Severe Weather Warning -- Employees",
          "createdAt": "2019-02-26T19:32:16.576Z",
          "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
          "confirmationRequestId": null,
          "id": "3980c4bd-39fd-11e9-8c83-03cd8082dd16",
          "confirmationRequest": null,
          "siteRoles": [
            {
              "id": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
              "name": "Employees and Contractors",
              "createdAt": "2019-02-08T15:25:21.128Z"
            }
          ],
          "body": "The National Weather Service has issued a . Please take action for your personal safety.",
          "subject": " - "
        },
        {
          "siteRoleIds": [
            "724030a9-2b09-11e9-9638-578e7c043866"
          ],
          "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
          "messageTemplate": { ... },
          "name": "Severe Weather Warning -- Security Team",
          "createdAt": "2019-02-26T19:32:16.576Z",
          "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
          "confirmationRequestId": null,
          "id": "3980c4be-39fd-11e9-8c83-85c39c3525c6",
          "confirmationRequest": null,
          "siteRoles": [
            {
              "id": "724030a9-2b09-11e9-9638-578e7c043866",
              "name": "Security",
              "createdAt": "2019-02-07T18:51:58.302Z"
            }
          ],
          "body": "The National Weather Service has issued a . Move to secure the building and take action for your personal safety. ",
          "subject": " - "
        }
      ],
      "incidentPlan": null,
      "emergency": false,
      "createdAt": "2019-01-28T15:21:29.691Z",
      "domains": [
        {
          "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
          "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
          "name": "North Campus",
          "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
          "namePath": "/North Campus/"
        }
      ],
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "type": "standard",
      "source": null,
      "secret": null,
      "winHotkeys": "alt+shift+f6",
      "silentHotkey": true,
      "customConfirm": "Warning Sent",
      "eventType": null,
      "confirmationType": null,
      "instructions": null,
      "phoneNumber": null
    },
    {
      "incidentPlanId": null,
      "name": "Fire",
      "fields": null,
      "icon": "fire",
      "backgroundColor": "#1791CE",
      "messages": [ ... ],
      "id": "e31809e0-cfac-11eb-bb25-2d6e9c8dade4",
      "incidentPlan": null,
      "createdAt": "2021-10-28T15:21:29.691Z",
      "domains": [
        {
          "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
          "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
          "name": "North Campus",
          "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
          "namePath": "/North Campus/"
        }
      ],
      "emergency": false,
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "type": "panic-button",
      "instructions": {
        "step1": "Find the closest fire escape route",
        "step2": "Stay low",
        "step3": "Do not open any doors with warm door knobs"
      },
      "source": null,
      "secret": null,
      "winHotkeys": null,
      "silentHotkey": null,
      "customConfirm": null,
      "eventType": null,
      "confirmationType": null,
      "phoneNumber": "+16085551212"
    },
    {
      "eventType": "none",
      "permissions": [
        "put",
        "delete",
        "get"
      ],
      "incidentPlanId": null,
      "name": "Cisco Enterprise integration",
      "locationEnabled": false,
      "locationQuestionName": null,
      "locationVariable": null,
      "defaultSite": null,
      "defaultBuilding": null,
      "defaultFloor": null,
      "defaultZone": null,
      "fields": [
        {
          "variable": "affectedSite",
          "name": "Stubbed question for specifying variable",
          "rank": 1,
          "createdAt": "2022-04-20T17:27:33.465Z",
          "type": "option",
          "scenarioId": "823b20c7-c012-11ec-b608-0f5884481cb9",
          "id": "29db64b1-c0cf-11ec-b608-cfcd2e82ce1a",
          "answer": "Site 2 on fire",
          "options": [
            "Site 1 on fire",
            "Site 2 on fire"
          ]
        }
      ],
      "instructions": {

      },
      "createdAt": "2022-04-19T18:57:06.850Z",
      "type": "integration",
      "source": "cisco-enterprise",
      "icon": null,
      "secret": "9D35ev5VnaIuaqJYgQcjlw",
      "winHotkeys": null,
      "silentHotkey": null,
      "customConfirm": null,
      "messages": [ ... ],
      "emergency": false,
      "id": "823b20c7-c012-11ec-b608-0f5884481cb9",
      "confirmationType": "pin",
      "incidentPlan": null,
      "backgroundColor": "#1791CE",
      "phoneNumber": null
    }
  ]
}

Gets a list of all scenarios 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 scenarios allows administrators to decide which users can send or configure scenarios.)

HTTP Request

GET /scenarios

Produces

application/json

Query Parameters

To make this example more manageable, only the first scenario was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each scenario belongs.

Response

The scenario response format is detailed here.

Get a Scenario

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/62e192ca-2310-11e9-b378-cfd5de99d56b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/62e192ca-2310-11e9-b378-cfd5de99d56b" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/62e192ca-2310-11e9-b378-cfd5de99d56b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "62e192ca-2310-11e9-b378-cfd5de99d56b",
  "incidentPlanId": null,
  "name": "Severe Weather",
  "icon": "flash",
  "backgroundColor": "#0d2458",
  "locationEnabled": true,
  "locationQuestionName": "At which location?",
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [
    {
      "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "name": "At which location?",
      "rank": 0,
      "variable": "site",
      "type": "site",
      "answer": null,
      "options": null,
      "createdAt": "2019-02-28T18:23:38.329Z"
    },
    {
      "id": "397d424a-39fd-11e9-8c83-8de4247efba1",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "name": "What type of severe weather is in the area?",
      "rank": 1,
      "variable": "weather_type",
      "type": "option",
      "answer": null,
      "options": [
        "Tornado Warning",
        "Tornado Watch",
        "Winter Weather Warning"
      ],
      "createdAt": "2019-02-26T19:32:16.553Z"
    },
    {
      "id": "397d424c-39fd-11e9-8c83-d795bd1d0ad9",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "name": "Are there any further instructions that should be sent to the security team?",
      "rank": 2,
      "variable": "info",
      "type": "text",
      "answer": null,
      "options": null,
      "createdAt": "2019-02-26T19:32:16.553Z"
    }
  ],
  "messages": [
    {
      "siteRoleIds": [
        "bf5f4f46-2bb5-11e9-8180-5fe10bc30744"
      ],
      "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
      "messageTemplate": { ... },
      "name": "Severe Weather Warning -- Employees",
      "createdAt": "2019-02-26T19:32:16.576Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "confirmationRequestId": null,
      "id": "3980c4bd-39fd-11e9-8c83-03cd8082dd16",
      "confirmationRequest": null,
      "siteRoles": [
        {
          "id": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
          "name": "Employees and Contractors",
          "createdAt": "2019-02-08T15:25:21.128Z"
        }
      ],
      "body": "The National Weather Service has issued a . Please take action for your personal safety.",
      "subject": " - "
    },
    {
      "siteRoleIds": [
        "724030a9-2b09-11e9-9638-578e7c043866"
      ],
      "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
      "messageTemplate": { ... },
      "name": "Severe Weather Warning -- Security Team",
      "createdAt": "2019-02-26T19:32:16.576Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "confirmationRequestId": null,
      "id": "3980c4be-39fd-11e9-8c83-85c39c3525c6",
      "confirmationRequest": null,
      "siteRoles": [
        {
          "id": "724030a9-2b09-11e9-9638-578e7c043866",
          "name": "Security",
          "createdAt": "2019-02-07T18:51:58.302Z"
        }
      ],
      "body": "The National Weather Service has issued a . Move to secure the building and take action for your personal safety. ",
      "subject": " - "
    }
  ],
  "incidentPlan": null,
  "emergency": false,
  "createdAt": "2019-01-28T15:21:29.691Z",
  "domains": [
    {
      "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
      "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
      "name": "North Campus",
      "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
      "namePath": "/North Campus/"
    }
  ],
  "type": "standard",
  "instructions": null,
  "phoneNumber": null,
  "source": null,
  "secret": null,
  "winHotkeys": null,
  "silentHotkey": null,
  "customConfirm": null,
  "eventType": null,
  "confirmationType": null,
  "permissions": [
    "delete",
    "put",
    "get"
  ]
}

Retrieves a single scenario by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scenarios/{scenarioId}

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this scenario belongs.

Response

The scenario response format is detailed here.

Simulate Answers

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/62e192ca-2310-11e9-b378-cfd5de99d56b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/62e192ca-2310-11e9-b378-cfd5de99d56b" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/62e192ca-2310-11e9-b378-cfd5de99d56b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "High Molarity Chemical Spill",
  "backgroundColor": "#33AA55",
  "locationEnabled": true,
  "locationQuestionName": "Where is the chemical spill?",
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [],
  "createdAt": "2019-02-28T18:23:38.267Z",
  "icon": "flash",
  "messages": [
    {
      "siteRoleIds": [],
      "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
      "messageTemplate": { ... },
      "name": "Chemical Spill",
      "createdAt": "2019-02-28T20:41:25.214Z",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "confirmationRequestId": null,
      "id": "371c300d-3b99-11e9-81d7-010bc7a87d6b",
      "confirmationRequest": null,
      "siteRoles": [],
      "body": null,
      "subject": null
    }
  ],
  "id": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
  "simulatedResponse": [
    {
      "collaborationGroups": [],
      "messageId": "371c300d-3b99-11e9-81d7-010bc7a87d6b",
      "name": "Chemical Spill",
      "distributionListIds": [],
      "deviceGroupIds": [],
      "areasOfInterest": [],
      "collaborationGroupIds": [],
      "distributionLists": [],
      "body": "There is a chemical spill in the lab. Avoid the area if possible. The cleanup team is on the way.",
      "userIds": [],
      "deviceGroups": [],
      "areaOfInterestIds": [],
      "subject": "Chemical Spill",
      "messageName": "Chemical Spill",
      "users": []
    }
  ],
  "incidentPlanId": null,
  "incidentPlan": null,
  "type": "standard",
  "instructions": null,
  "phoneNumber": null,
  "source": null,
  "secret": null,
  "winHotkeys": null,
  "eventType": null,
  "confirmationType": null,
  "domains": [
    {
      "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
      "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
      "name": "North Campus",
      "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
      "namePath": "/North Campus/"
    }
  ],
  "emergency": false,
  "permissions": [
    "delete",
    "put",
    "get"
  ]
}

Simulate Answers allows you to pass query parameters simulatedAnswers and optionally location (if the scenario is location-enabled), and will build a simulated scenario which has the contents of all scenario messages that would be sent if the scenario is sent with those answers and location choices. This is useful for previewing Scenario Notifications, since it will interpolate variables from questions and location and join the recipients from sites/site roles and message templates.

If the scenario is an emergency scenario, it is also possible when simulating answers to pass the query parameter checkPanicRange to test whether a particular latitude and longitude is within a mile from any emergency building. Such a query will return a withinPanicRange boolean attribute in the response, indicating whether launching an emergency mobile panic button scenario from that location will automatically contact emergency services. The value sent as checkPanicRange will also be returned as position.

HTTP Request

GET /scenarios/{scenarioId}

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario to simulate.

Request Parameters

Parameter Type Description
check­PanicRange Object If the scenario is an emergency scenario, this can hold an object in the format {"latitude": Number, "longitude": Number} to check whether a mobile panic button launched from that geographic position can automatically contact emergency services.
location Object If the scenario is location-enabled, a Location object that specifies the site, building, floor, and/or zone to associate with the scenario.
simulatedAnswers Array[Object] An array of objects in the format {"fieldId": UUID, "answer": String}. These are the answers to any questions attached to the scenario.

Response

The scenario response format is detailed here.

Create a Scenario

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Chemical Spill'
,
    'backgroundColor': '#33AA55'
,
    'messages': [{
        'name': 'Chemical Spill'
,
        'messageTemplateId': '10ec2090-3b85-11e9-81d7-3bae1bf35696'

}

]
,
    'icon': 'flash'
,
    'locationEnabled': true
,
    'locationQuestionName': 'Where is the chemical spill?'
,
    'type': 'standard'

}

begin: 
    role = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Chemical Spill", \
       "backgroundColor": "#33AA55", \
       "messages": [{"name": "Chemical Spill", \
         "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696"}], \
       "icon": "flash", \
       "locationEnabled": true, \
       "locationQuestionName": "Where is the chemical spill?", \
       "type": "standard"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Chemical Spill',
    'backgroundColor': '#33AA55',
    'messages': [{
        'name': 'Chemical Spill',
        'messageTemplateId': '10ec2090-3b85-11e9-81d7-3bae1bf35696'
}
],
    'icon': 'flash',
    'locationEnabled': true,
    'locationQuestionName': 'Where is the chemical spill?',
    'type': 'standard'
}

try: 
    role = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "Chemical Spill",
  "icon": "flash",
  "backgroundColor": "#33AA55",
  "id": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
  "locationEnabled": true,
  "locationQuestionName": "Where is the chemical spill?",
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [
    {
      "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "name": "Where is the chemical spill?",
      "rank": 0,
      "variable": "site",
      "type": "site",
      "answer": null,
      "options": null,
      "createdAt": "2019-02-28T18:23:38.329Z"
    }
  ],
  "messages": [
    {
      "siteRoleIds": [],
      "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
      "messageTemplate": { ... },
      "name": "Chemical Spill",
      "createdAt": "2019-02-28T18:23:38.343Z",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "confirmationRequestId": null,
      "id": "f7abc793-3b85-11e9-81d7-93ad6ba0c356",
      "confirmationRequest": null,
      "siteRoles": [],
      "body": null,
      "subject": null
    }
  ],
  "incidentPlanId": null,
  "incidentPlan": null,
  "type": "standard",
  "instructions": null,
  "phoneNumber": null,
  "createdAt": "2019-02-28T18:23:38.267Z",
  "source": null,
  "secret": null,
  "winHotkeys": null,
  "silentHotkey": null,
  "customConfirm": null,
  "eventType": null,
  "confirmationType": null,
  "emergency": false,
  "domains": [
    {
      "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
      "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
      "name": "North Campus",
      "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
      "namePath": "/North Campus/"
    }
  ],
  "permissions": [
    "delete",
    "put",
    "get"
  ]
}

Notice that in the first, location-enabled scenario creation example, a simulated site question is present in the fields response; this is deprecated and present for backwards compatibility with older clients, and will be removed in a future release; you should instead use the more powerful Location object when sending such a scenario.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Fire'
,
    'backgroundColor': '#33AA55'
,
    'messages': [{
        'name': 'Fire'
,
        'messageTemplateId': '10ec2090-3b85-11e9-81d7-3bae1bf35696'

}

]
,
    'icon': 'flash'
,
    'fields': []
,
    'type': 'panic-button'
,
    'instructions': {
        'step1': 'Find the closest fire escape route'
,
        'step2': 'Stay low'
,
        'step3': 'Do not open any doors with warn door knobs'

}

,
    'phoneNumber': '16085551212'

}

begin: 
    role = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fire", \
       "backgroundColor": "#33AA55", \
       "messages": [{"name": "Fire", \
         "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696"}], \
       "icon": "flash", \
       "fields": [], \
       "type": "panic-button", \
       "instructions": {"step1": "Find the closest fire escape route", \
         "step2": "Stay low", \
         "step3": "Do not open any doors with warn door knobs"}, \
       "phoneNumber": "16085551212"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Fire',
    'backgroundColor': '#33AA55',
    'messages': [{
        'name': 'Fire',
        'messageTemplateId': '10ec2090-3b85-11e9-81d7-3bae1bf35696'
}
],
    'icon': 'flash',
    'fields': [],
    'type': 'panic-button',
    'instructions': {
        'step1': 'Find the closest fire escape route',
        'step2': 'Stay low',
        'step3': 'Do not open any doors with warn door knobs'
}
,
    'phoneNumber': '16085551212'
}

try: 
    role = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "Fire",
  "icon": "flash",
  "backgroundColor": "#33AA55",
  "id": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
  "locationEnabled": false,
  "locationQuestionName": null,
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [

  ],
  "messages": [
    {
      "siteRoleIds": [],
      "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
      "messageTemplate": { ... },
      "name": "Fire",
      "createdAt": "2019-02-28T18:23:38.343Z",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "confirmationRequestId": null,
      "id": "f7abc793-3b85-11e9-81d7-93ad6ba0c356",
      "confirmationRequest": null,
      "siteRoles": [],
      "body": null,
      "subject": null
    }
  ],
  "type": "panic-button",
  "incidentPlan": null,
  "phoneNumber": "+16085551212",
  "createdAt": "2019-02-28T18:23:38.267Z",
  "source": null,
  "secret": null,
  "winHotkeys": null,
  "silentHotkey": null,
  "customConfirm": null,
  "eventType": null,
  "confirmationType": null,
  "domains": [
    {
      "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
      "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
      "name": "North Campus",
      "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
      "namePath": "/North Campus/"
    }
  ],
  "emergency": false,
  "permissions": [
    "delete",
    "put",
    "get"
  ]
}
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Cisco Integration'
,
    'backgroundColor': '#1791CE'
,
    'messages': [{
        'name': 'Fire'
,
        'messageTemplateId': '10ec2090-3b85-11e9-81d7-3bae1bf35696'

}

]
,
    'icon': 'fire'
,
    'fields': []
,
    'type': 'integration'
,
    'source': 'cisco-integration'
,
    'confirmationType': 'none'

}

begin: 
    role = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Cisco Integration", \
       "backgroundColor": "#1791CE", \
       "messages": [{"name": "Fire", \
         "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696"}], \
       "icon": "fire", \
       "fields": [], \
       "type": "integration", \
       "source": "cisco-integration", \
       "confirmationType": "none"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scenarios"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Cisco Integration',
    'backgroundColor': '#1791CE',
    'messages': [{
        'name': 'Fire',
        'messageTemplateId': '10ec2090-3b85-11e9-81d7-3bae1bf35696'
}
],
    'icon': 'fire',
    'fields': [],
    'type': 'integration',
    'source': 'cisco-integration',
    'confirmationType': 'none'
}

try: 
    role = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
  "eventType": "none",
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "incidentPlanId": null,
  "name": "Cisco Integration",
  "locationEnabled": false,
  "locationQuestionName": null,
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [],
  "instructions": {},
  "fieldAnswers": null,
  "createdAt": "2022-04-27T19:19:22.987Z",
  "type": "integration",
  "source": "cisco-enterprise",
  "icon": "fire",
  "secret": "WixeCSpYFhnCOAY2qJ603Q",
  "winHotkeys": null,
  "silentHotkey": null,
  "customConfirm": null,
   "messages": [
    {
     "siteRoleIds": [],
     "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
     "messageTemplate": { ... },
     "name": "Fire",
     "createdAt": "2019-02-28T18:23:38.343Z",
     "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
     "confirmationRequestId": null,
     "id": "f7abc793-3b85-11e9-81d7-93ad6ba0c356",
     "confirmationRequest": null,
     "siteRoles": [],
     "body": null,
     "subject": null
    }
   ],
  "id": "f1ef7472-c65e-11ec-826f-6ff68321e451",
  "emergency": false,
  "confirmationType": "none",
  "incidentPlan": null,
  "backgroundColor": "#1791CE",
  "phoneNumber": null
}

Create a new scenario.

HTTP Request

POST /scenarios

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
background­Color String N/A The scenario’s background color. Should be a hexadecimal color value lead with a #.
cisco­ConfigurationUrl String N/A URL used in InformaCast XML service.
confirmationPin String N/A Numeric pin user must enter to initiate scenario when confirmationType is pin.
confirmationType String N/A Options: none pin prompt. Informs the user interface how and if to require confirmation before initating the scenario.
defaultBuilding UUID N/A For location-enabled scenarios, specifies the building to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultFloor UUID N/A For location-enabled scenarios, specifies the floor to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultSite UUID N/A For location-enabled scenarios, specifies the site to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultZone UUID N/A For location-enabled scenarios, specifies the zone to use when sending the scenario in a way which does not allow the user to be prompted for a location.
emergency Boolean false Indicates that emergency services should be contacted when this scenario is sent. (The emergency calling feature must be enabled for your organization before you can send a true value here.)
eventType String N/A Options: none zoom-emergency-call double-click. The type of scenario triggered events.
fields Array[Object] [] The list of questions attached to a standard scenario. More information about questions can be found here.
icon String N/A The icon to be displayed on the scenario’s triggering button. Can be one of the following: close-circle, fire, hospital, lock, shield-security, traffic, alert-circle, info, account-circle, local-airport, navigation, eye, flare, flash, invert-colors, cloud, check, gps-dot, block, wifi-lock
incident­Plan Object N/A The agendas to follow when there are ongoing incidents in your organization. More information about incident plan can be found here.
incident­PlanId String N/A The id of the incident plan that this scenario triggers.
instructions Object N/A The list of user instructions to give the user direction on what to do after pressing the mobile panic button.
location­Enabled Boolean false Does this scenario support the submission of a Location object when creating or simulating Scenario Notifications?
location­QuestionName String N/A The text to use when prompting a user to specify a location when sending a location-enabled scenario.
messages Array[Object] N/A The list of messages attached to a scenario. More information about scenario messages can be found here.
name String N/A The scenario’s unique name. Maximum of 140 characters.
phoneNumber String N/A The phone number the user can call after pressing the mobile panic button.
simulatedAnswers Array[Object] N/A simulatedAnswers is not recommended on POST.
source String N/A Options: cisco-enterprise wearable-panic-button zoom. The source of the scenario.
type String N/A Options: standard panic-button integration. The type of the scenario.

Response

The scenario response format is detailed here.

Update a Scenario

# Continuing with the scenario object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/f7a9a4b2-3b85-11e9-81d7-2f036bfac606" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "High Molarity Chemical Spill", \
       "backgroundColor": "#33AA55", \
       "messages": [{"name": "Chemical Spill", \
         "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696"}], \
       "icon": "flash", \
       "locationEnabled": true, \
       "locationQuestionName": "Where is the chemical spill?"}'
# Continuing with the scenario object from
# the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
  "name": "High Molarity Chemical Spill",
  "icon": "flash",
  "backgroundColor": "#33AA55",
  "locationEnabled": true,
  "locationQuestionName": "Where is the chemical spill?",
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [
    {
      "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "name": "Where is the chemical spill?",
      "rank": 0,
      "variable": "site",
      "type": "site",
      "answer": null,
      "options": null,
      "createdAt": "2019-02-28T18:23:38.329Z"
    }
  ],
  "messages": [
    {
      "siteRoleIds": [],
      "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
      "messageTemplate": { ... },
      "name": "Chemical Spill",
      "rank": 1,
      "createdAt": "2019-02-28T18:29:38.449Z",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "confirmationRequestId": null,
      "id": "ce4f9835-3b86-11e9-81d7-f7b4663b561b",
      "confirmationRequest": null,
      "siteRoles": [],
      "body": null,
      "subject": null
    }
  ],
  "incidentPlanId": null,
  "incidentPlan": null,
  "type": "standard",
  "instructions": null,
  "phoneNumber": null,
  "domains": [
    {
      "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
      "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
      "name": "North Campus",
      "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
      "namePath": "/North Campus/"
    }
  ],
  "createdAt": "2019-02-28T18:23:38.267Z",
  "source": null,
  "secret": null,
  "winHotkeys": null,
  "silentHotkey": null,
  "customConfirm": null,
  "eventType": null,
  "confirmationType": null,
  "emergency": false,
  "permissions": [
    "delete",
    "put",
    "get"
  ]
}

Notice that in the first, location-enabled scenario creation example, a simulated site question is present in the fields response; this is deprecated and present for backwards compatibility with older clients, and will be removed in a future release; you should instead use the more powerful Location object when sending such a scenario.

# Continuing with the scenario object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/f7a9a4b2-3b85-11e9-81d7-2f036bfac606" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Live Fire", \
       "backgroundColor": "#33AA55", \
       "messages": [{"name": "Fire", \
         "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696"}], \
       "icon": "fire", \
       "phoneNumber": "911"}'
# Continuing with the scenario object from
# the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "Live Fire",
  "icon": "fire",
  "backgroundColor": "#33AA55",
  "id": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
  "locationEnabled": false,
  "locationQuestionName": null,
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [
  ],
  "messages": [
    {
      "siteRoleIds": [],
      "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
      "messageTemplate": { ... },
      "name": "Chemical Spill",
      "createdAt": "2019-02-28T18:23:38.343Z",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "confirmationRequestId": null,
      "id": "f7abc793-3b85-11e9-81d7-93ad6ba0c356",
      "confirmationRequest": null,
      "siteRoles": [],
      "body": null,
      "subject": null
    }
  ],
  "type": "panic-button",
  "incidentPlan": null,
  "phoneNumber": "911",
  "createdAt": "2019-02-28T18:23:38.267Z",
  "source": null,
  "secret": null,
  "winHotkeys": null,
  "silentHotkey": null,
  "customConfirm": null,
  "eventType": null,
  "confirmationType": null,
  "domains": [
    {
      "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
      "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
      "name": "North Campus",
      "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
      "namePath": "/North Campus/"
    }
  ],
  "emergency": false,
  "permissions": [
    "delete",
    "put",
    "get"
  ]
}
# Continuing with the scenario object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/f7a9a4b2-3b85-11e9-81d7-2f036bfac606" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"incidentPlanId": "fe5167b3-3354-11ec-87a0-2fb805a1776a", \
       "name": "Cisco Integration", \
       "fields": [], \
       "type": "integration", \
       "source": "cisco-integration", \
       "icon": "fire", \
       "messages": [{"name": "Fire", \
         "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696"}], \
       "confirmationType": "none", \
       "incidentPlan": {"id": "fe5167b3-3354-11ec-87a0-2fb805a1776a", \
         "name": "Fire Evacuation Plan"}, \
       "backgroundColor": "#1791CE"}'
# Continuing with the scenario object from
# the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "eventType": "none",
  "permissions": [
    "put",
    "delete",
    "get"
  ],
  "incidentPlanId": null,
  "name": "Cisco Integration",
  "locationEnabled": false,
  "locationQuestionName": null,
  "locationVariable": null,
  "defaultSite": null,
  "defaultBuilding": null,
  "defaultFloor": null,
  "defaultZone": null,
  "fields": [],
  "instructions": {},
  "fieldAnswers": null,
  "createdAt": "2022-04-27T19:19:22.987Z",
  "type": "integration",
  "source": "cisco-enterprise",
  "icon": "fire",
  "secret": "WixeCSpYFhnCOAY2qJ603Q",
  "winHotkeys": null,
  "silentHotkey": null,
  "customConfirm": null,
  "incidentPlanId": "fe5167b3-3354-11ec-87a0-2fb805a1776a",
  "incidentPlan": {
      "id": "fe5167b3-3354-11ec-87a0-2fb805a1776a",
      "name": "Fire Evacuation Plan"
    },
  "messages": [
    {
     "siteRoleIds": [],
     "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
     "messageTemplate": { ... },
     "name": "Fire",
     "createdAt": "2019-02-28T18:23:38.343Z",
     "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
     "confirmationRequestId": null,
     "id": "f7abc793-3b85-11e9-81d7-93ad6ba0c356",
     "confirmationRequest": null,
     "siteRoles": [],
     "body": null,
     "subject": null
    }
   ],
  "emergency": false,
  "id": "f1ef7472-c65e-11ec-826f-6ff68321e451",
  "confirmationType": "none",
  "incidentPlan": null,
  "backgroundColor": "#1791CE",
  "phoneNumber": null
}

Updates an existing scenario.

HTTP Request

PUT /scenarios/{scenarioId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario to update.

Request Parameters

Parameter Type Default Description
background­Color String N/A The scenario’s background color. Should be a hexadecimal color value lead with a #.
cisco­ConfigurationUrl String N/A URL used in InformaCast XML service.
confirmationPin String N/A Numeric pin user must enter to initiate scenario when confirmationType is pin.
confirmationType String N/A Options: none pin prompt. Informs the user interface how and if to require confirmation before initating the scenario.
defaultBuilding UUID N/A For location-enabled scenarios, specifies the building to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultFloor UUID N/A For location-enabled scenarios, specifies the floor to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultSite UUID N/A For location-enabled scenarios, specifies the site to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultZone UUID N/A For location-enabled scenarios, specifies the zone to use when sending the scenario in a way which does not allow the user to be prompted for a location.
emergency Boolean false Indicates that emergency services should be contacted when this scenario is sent. (The emergency calling feature must be enabled for your organization before you can send a true value here.)
eventType String N/A Options: none zoom-emergency-call double-click. The type of scenario triggered events.
fields Array[Object] [] The list of questions attached to a standard scenario. More information about questions can be found here.
icon String N/A The icon to be displayed on the scenario’s triggering button. Can be one of the following: close-circle, fire, hospital, lock, shield-security, traffic, alert-circle, info, account-circle, local-airport, navigation, eye, flare, flash, invert-colors, cloud, check, gps-dot, block, wifi-lock
incident­Plan Object N/A The agendas to follow when there are ongoing incidents in your organization. More information about incident plan can be found here.
incident­PlanId String N/A The id of the incident plan that this scenario triggers.
instructions Object N/A The list of user instructions to give the user direction on what to do after pressing the mobile panic button.
location­Enabled Boolean false Does this scenario support the submission of a Location object when creating or simulating Scenario Notifications?
location­QuestionName String N/A The text to use when prompting a user to specify a location when sending a location-enabled scenario.
messages Array[Object] N/A The list of messages attached to a scenario. More information about scenario messages can be found here.
name String N/A The scenario’s unique name. Maximum of 140 characters.
phoneNumber String N/A The phone number the user can call after pressing the mobile panic button.
simulatedAnswers Array[Object] N/A simulatedAnswers is not recommended on PUT.
source String N/A Options: cisco-enterprise wearable-panic-button zoom. The source of the scenario.
type String N/A Options: standard panic-button integration. The type of the scenario.
deleteRuleActions Boolean False When true will delete all the rule actions associated with the scenario.

Response

The scenario response format is detailed here.

Remove a Scenario

# Continuing with the scenario object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/f7a02ed1-3b85-11e9-81d7-e5938f344a04" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the scenario object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted f7a02ed1-3b85-11e9-81d7-e5938f344a04"
}

Deletes an existing scenario.

HTTP Request

DELETE /scenarios/{scenarioId}

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario to delete.

Response

The deletion response format is detailed here.

Scenario Fields

Fields, known as Questions in the admin user interface, are objects that contain the questions asked to a dispatcher during a scenario.

Scenario Fields do not have their own endpoint, and are instead nested inside of an array in scenario resources.

Attribute Type Description
id String The id of the field.
scenarioId String The id of the associated scenario.
createdAt ISO 8601 date/time When this field was created.
variable String The variable that stores an answer which can be interpolated in scenario messages. 3-32 alphanumeric characters plus underscores, and it must start with a letter.
type String The type of answer that should be provided. option gives a dropdown menu and text allows text entry.
answer String Saved response to the field’s variable (required when scenario is configured using hotkeys to send immediately).
options Array[String] Contains the list of options for a dropdown menu. Only necessary if the type is option. Up to 16 options, all of which must be at most 64 characters long.

During the backwards compatibility period, you may see fields of type site in scenarios that used them prior to the migration to the use of Location objects, in order to avoid breaking integrations with systems that are still expecting to use those site questions. Those integrations need to be updated to use location instead, because this backwards compatibility feature will only be available for a release or two.

Scenario Messages

Messages, known as Scenario Notifications in the admin user interface, contain specific information unique to the scenario, such as a replacement subject and body and the associated message template, which is the vehicle for sending scenario notifications.

Scenario Messages do not have their own endpoint, and are instead nested inside of an array in scenario resources.

Attribute Type Description
id String The id of the site role’s recipients.
scenarioId String The id of the associated scenario.
createdAt ISO 8601 date/time When this scenario message was created.
messageTemplate Message Template The information about the message template used by the message.
messageTemplateId String The ids of the message template associated with the message.
name String The name of the message. Used to differentiate between multiple messages attached to one scenario. Maximum of 140 characters.
siteRoles Array[Site Roles] The site roles associated with a message. For example, a message meant for the security team might have a Security site role attached. May only be included if a field of type site is included in the scenario.
siteRoleIds Array[String] The list of ids for the site roles associated with a message. May only be included if a field of type site is included in the scenario.
confirmationRequest Confirmation Request] The confirmation request associated with this message.
confirmationRequestId String The id of the associated confirmation request.
subject String The subject of the scenario message which can override the subject of the associated message template. May include information wrapped in to interpolate variables from sites. Maximum of 256 characters.
body String The body of the scenario message which can override the body of the associated message template. May include information wrapped in to interpolate variables from sites. Maximum of 10000 characters.

Request Parameters

Attribute Type Description
id String The id of the site role’s recipients.
scenarioId String The id of the associated scenario.
messageTemplateId String The ids of the message template associated with the message.
name String The name of the message. Used to differentiate between multiple messages attached to one scenario. Maximum of 140 characters.
siteRoleIds Array[String] The list of ids for the site roles associated with a message. May only be included if a field of type site is included in the scenario.
confirmationRequestId String The id of the associated confirmation request.
subject String The subject of the scenario message which can override the subject of the associated message template. May include information wrapped in to interpolate variables from sites. Maximum of 256 characters.
body String The body of the scenario message which can override the body of the associated message template. May include information wrapped in to interpolate variables from sites. Maximum of 10000 characters.

Scenario Response

The JSON object used to represent a Scenario resource has the following content:

Attribute Type Description
background­Color String The scenario’s background color. Should be a hexadecimal color value beginning with a #.
confirmationType String Options: none pin prompt. Informs the user interface how and if to require confirmation before initiating the scenario.
createdAt ISO 8601 date/time When this scenario was created.
customConfirm String Set a custom confirmation string for Immediate-send scenarios (default text will be “Success!” if not set)
defaultBuilding UUID For location-enabled scenarios, specifies the building to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultFloor UUID For location-enabled scenarios, specifies the floor to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultSite UUID For location-enabled scenarios, specifies the site to use when sending the scenario in a way which does not allow the user to be prompted for a location.
defaultZone UUID For location-enabled scenarios, specifies the zone to use when sending the scenario in a way which does not allow the user to be prompted for a location.
domains Array[Domain] When Domains are in use and includeDomains was true in your request, this response will list the Domains to which the scenario belongs.
emergency Boolean Indicates that emergency services should be contacted when this scenario is sent.
eventType String Options: none zoom-emergency-call double-click. The type of scenario triggered events.
id String The id of the scenario, for efficient retrieval or manipulation of the scenario.
fields Array[Object] The list of questions attached to a scenario. More information about questions can be found here.
icon String The icon to be displayed on the scenario’s triggering button. Can be one of the following: close-circle, fire, hospital, lock, shield-security, traffic, alert-circle, info, account-circle, local-airport, navigation, eye, flare, flash, invert-colors, cloud, check, gps-dot, block, wifi-lock
incidentPlanId UUID The id of the incident plan that this scenario triggers.
incidentPlan Object The agendas to follow when there are ongoing incidents in your organization. More information about incident plan can be found here.
instructions Object The list of user instructions to give the user direction on what to do after pressing the mobile panic button.
location­Enabled Boolean Does this scenario support the submission of a Location object when creating or simulating Scenario Notifications?
location­QuestionName String The text to use when prompting a user to specify a location when sending a location-enabled scenario.
location­Variable String If this scenario was using a site question in a release prior to migration to using Location objects, this holds the variable in which the site will also be made available, for backwards compatibility with existing integrations. This is deprecated because it will go away once backwards compatibility is no longer supported.
messages Array[Object] The list of messages attached to a scenario. More information about scenario messages can be found here.
name String The scenario’s unique 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.
phoneNumber String The phone number the user can call after pressing the mobile panic button.
position Object When simulating answers, if a checkPanicRange query was sent, this will echo back the value sent in that query.
secret String Generated secret to be used by UIs to authorize initiation of this scenario.
silentHotkey Boolean Whether this scenario’s hotkey launch should be Immediate (true) or Interactive (false)
source String Options: cisco-enterprise wearable-panic-button zoom. The source of the scenario.
type String Options: standard panic-button integration. The type of the scenario.
winHotkeys String String representing a hotkey combination used to launch this scenario via InformaCast on Windows desktop apps
within­PanicRange boolean When simulating answers, if a checkPanicRange query was sent, this will hold the response.

Location Object

The JSON object used to represent a location when creating or simulating a Scenario Notification has the following content:

Attribute Type Description
site Object If present, contains a single attribute id which specifies the ID of a Site
building Object If present, contains a single attribute id which specifies the ID of a Site Building. If both are present, this must be a building that is part of site.
floor Object If present, contains a single attribute id which specifies the ID of a Site Building Floor. If all are present, this must be a floor that is part of site and building.
zone Object If present, contains a single attribute id which specifies the ID of a Site Building Floor Zone. If all are present, this must be a floor that is part of site, building, and floor.

A full Location object specifying all four levels would have a structure shown on the right:

{
  "site": { "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b" },
  "building": { "id": "b321c52b-064b-11ea-9265-f333e562b36b" },
  "floor": { "id": "b321c52b-064b-11ea-9265-f333e562b36b" },
  "zone": { "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b" }
}

As noted above in the attribute list, it is possible as a shorthand to specify only the lowest level element that you want to specify, and the system can figure out the parent levels. For example, if you specify a zone, it can figure out the corresponding floor, building, and site. If you do specify all levels, they must actually belong in the hierarchy that you specified or a validation error will occur. And of course, you can leave out lower levels if they don’t exist or are not relevant to the Scenario Notification being simulated or created. The minimal requirement is that at least a site with its id must be provided.

Additionally, to support integration with outside systems which have their own notions of locations, but which may not be aware of the specific id values used by Singlewire, when specifying each location level you can supply a name key instead of id for that level, and the value that you supply with that key which will be used to look up the resource whose name exactly matches, and the corresponding id will be used to build the location object.

Alternatively, if external sites, buildings, floors, or zones have been imported, their IDs can be used to set up a location object by supplying an externalId key instead of id. The value supplied with externalId is a colon-separated string, where the first part is the source associated with the external resource, and the second part is the ID by which that resource is known in the external system from which it was imported. If a corresponding external site, building, floor, or zone can be found, then it will be used to build the location object (but the id reported in the built object will still be the internal Singlewire ID associated with that external resource).

If multiple keys are supplied for a level, they are consulted in priority order. if id is present, it is always preferred. If there is no id but externalId is present, then externalId will be used. Finally, if neither id nor externalId was provided, name will be used. If none of these three keys is provided for a level, the location object is invalid. And if the value provided for a key does not correspond to an existing resource, the location object is invalid even if other keys were provided for that location level.

Scenario Cloning

This resource is used to make a copy of the Scenario specified by id in the request path.

The only operation supported is POST.

Clone a Scenario

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/25bfec4d-c2eb-11eb-9318-77e1fa016b97/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/25bfec4d-c2eb-11eb-9318-77e1fa016b97/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/25bfec4d-c2eb-11eb-9318-77e1fa016b97/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "permissions": [],
    "incidentPlanId": null,
    "name": "Notification to Admins (Copy)",
    "fields": [
        {
            "id": "7f34fa12-ebd4-11eb-bcba-0242ac320002",
            "scenarioId": "7f3425da-ebd4-11eb-81b3-bffa341ab068",
            "name": "Message",
            "variable": "message",
            "type": "text",
            "options": null,
            "rank": 1,
            "createdAt": "2021-07-23T16:39:06.470Z"
        }
    ],
    "createdAt": "2021-07-23T16:39:06.465Z",
    "icon": "alert-circle",
    "messages": [
        {
            "siteRoleIds": [],
            "messageTemplateId": "25b4a1ab-c2eb-11eb-9318-7d9eb9480a11",
            "ttsCustomContent": null,
            "messageTemplate": {
                "imageDisplay": "auto",
                "optOut": false,
                "inferredMessageType": "Text",
                "userIdsDisplay": "auto",
                "ttsVoiceIdCustomizable": true,
                "imageCustomizable": true,
                "ttsVoiceIdDisplay": "auto",
                "imageFiles": [],
                "ttsCustomContent": null,
                "deviceGroupIdsDisplay": "auto",
                "collaborationGroups": [],
                "ttsCustomContentCustomizable": true,
                "incidentPlanId": null,
                "name": "Test Notification - To Administrators",
                "audioDisplay": "auto",
                "expiration": null,
                "createdAt": "2021-06-01T15:07:57.063Z",
                "distributionListIds": [
                    "22233d74-c2eb-11eb-9318-43f163c84556"
                ],
                "subjectCustomizable": true,
                "confirmationRequestIdCustomizable": true,
                "distributionListIdsCustomizable": true,
                "deviceGroupIds": [],
                "syncId": "25b4a1ab-c2eb-11eb-9318-7d9eb9480a11:1622560077063",
                "areaOfInterestIdsCustomizable": true,
                "areasOfInterest": [],
                "deviceGroupIdsCustomizable": true,
                "collaborationGroupIdsCustomizable": true,
                "audioFiles": [],
                "bodyDisplay": "auto",
                "expirationCustomizable": true,
                "confirmationRequestId": null,
                "incidentPlanIdDisplay": "auto",
                "collaborationGroupIdsDisplay": "auto",
                "alertToneDisplay": "auto",
                "userIdsCustomizable": true,
                "ttsVoiceId": null,
                "id": "25b4a1ab-c2eb-11eb-9318-7d9eb9480a11",
                "notificationProfileId": "21433da8-c2eb-11eb-9318-a30932361bc7",
                "collaborationGroupIds": [],
                "ttsType": "none",
                "bodyCustomizable": true,
                "imageMimeType": null,
                "distributionListIdsDisplay": "auto",
                "confirmationRequest": null,
                "ttsCustomContentDisplay": "auto",
                "image": 0,
                "subjectDisplay": "auto",
                "audio": 0,
                "distributionLists": [
                    {
                        "campaign": null,
                        "name": "Administrator Alerts",
                        "syncId": "22233d74-c2eb-11eb-9318-43f163c84556:1622560071078",
                        "id": "22233d74-c2eb-11eb-9318-43f163c84556",
                        "createdAt": "2021-06-01T15:07:51.077Z",
                        "isSubscribable": false
                    }
                ],
                "audioCustomizable": true,
                "incidentPlan": null,
                "expirationDisplay": "auto",
                "incidentPlanIdCustomizable": false,
                "body": "This is a test notification sent to the administrators",
                "userIds": [],
                "confirmationRequestIdDisplay": "auto",
                "deviceGroups": [],
                "followUp": false,
                "alertToneCustomizable": true,
                "areaOfInterestIds": [],
                "metadata": null,
                "subject": "This is a test notification sent to the administrators",
                "alertTone": "default",
                "users": [],
                "areaOfInterestIdsDisplay": "auto",
                "metadataCustomizable": true
            },
            "name": "Notification to Administrators",
            "createdAt": "2021-07-23T16:39:06.471Z",
            "scenarioId": "7f3425da-ebd4-11eb-81b3-bffa341ab068",
            "confirmationRequestId": null,
            "id": "7f35103b-ebd4-11eb-81b3-dff626141d3f",
            "confirmationRequest": null,
            "siteRoles": [],
            "body": null,
            "subject": ""
        }
    ],
    "id": "7f3425da-ebd4-11eb-81b3-bffa341ab068",
    "scenarioLaunchers": null,
    "incidentPlan": null,
    "backgroundColor": "#1772ce"
}

Creates a copy of the specified Scenario. The name of the new copy is simply the original Scenario’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /scenarios resource and GET permission to the Scenario they wish to copy.

HTTP Request

POST /scenarios/{scenarioId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
scenarioId String The id of the Scenario to copy.

Response

The scenario response format is detailed here.

Scenario Domains

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 Scenario Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "scenarioId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "scenarioId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Scenario belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /scenarios/{scenarioId}/domains

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the Scenario whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Scenario 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 Scenario 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 Scenario, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the scenario whose domains were requested is returned under the key scenarioId inside each domain response.

Check if a Scenario contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "scenarioId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Scenario Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scenarios/{scenarioId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the Scenario whose Domains are of interest.
id The id of the Domain you want to know whether the Scenario belongs to.

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 Domains that are directly attached to the specified Scenario, any of their subdomains will be considered.

Response

If the Scenario 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 Scenario Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "scenarioId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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 /scenarios/{scenarioId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
scenarioId String The id of the Scenario 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 Scenario out of a parent Domain?
id String n/a The id of the Domain to which the Scenario should be added.
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 Scenario Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Scenario c54e4241-299b-11e8-94d3-2be9464da125"
}

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 /scenarios/{scenarioId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
scenarioId The id of the Scenario whose Domain should be removed.
id The id of the Domain to be removed from the Scenario.

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.

Scenario Notifications

Scenario Notifications is how Scenarios send notifications. This endpoint ultimately sends as a Notification.

List Scenario Notifications

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenario-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenario-notifications?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenario-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)

Notice that in this location-enabled scenario example, a simulated site question is present in the fields responses; this is deprecated and present for backwards compatibility with older clients, and will be removed in a future release; you should instead use the more powerful Location object when sending such a scenario.

{
 "total": 10,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "id": "f9f90795-3a07-11e9-bd59-bb116a332f2e",
   "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
   "createdAt": "2019-02-26T20:49:15.250Z",
   "fields": [
    {
      "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "name": "At which location?",
      "rank": 0,
      "variable": "site",
      "type": "site",
      "answer": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
      "options": null,
      "createdAt": "2019-02-28T18:23:38.329Z"
    },
    {
     "id": "397d424a-39fd-11e9-8c83-8de4247efba1",
     "name": "What type of severe weather is in the area?",
     "rank": 1,
     "type": "option",
     "answer": "Tornado Warning",
     "options": [
      "Tornado Warning",
      "Tornado Watch",
      "Winter Weather Warning"
     ],
     "variable": "weather_type"
    },
    {
     "id": "397d424c-39fd-11e9-8c83-d795bd1d0ad9",
     "name": "Are there any further instructions that should be sent to the security team?",
     "rank": 2,
     "type": "text",
     "answer": "Dime-sized hail is also expected. Please instruct other employees to avoid windows.",
     "variable": "info"
    }
   ],
   "location": {
    "site": {
     "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
     "name": "East Campus"
    },
    "description": "East Campus"
   },
   "scenario": {
    "id": "62e192ca-2310-11e9-b378-cfd5de99d56b",
    "icon": "flash",
    "name": "Severe Weather",
    "defaultLocation": {},
    "defaultSiteId": null,
    "defaultBuildingId": null,
    "defaultFloorId": null,
    "defaultZoneId": null,
    "locationEnabled": true,
    "locationQuestionName": "At which location?",
    "locationVariable": null,
    "fields": [
     {
       "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
       "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
       "name": "At which location?",
       "rank": 0,
       "variable": "site",
       "type": "site",
       "createdAt": "2019-02-28T18:23:38.329Z"
     },
     {
      "id": "397d424a-39fd-11e9-8c83-8de4247efba1",
      "name": "What type of severe weather is in the area?",
      "rank": 1,
      "type": "option",
      "options": [
       "Tornado Warning",
       "Tornado Watch",
       "Winter Weather Warning"
      ],
      "variable": "weather_type",
      "createdAt": "2019-02-26T19:32:16.553Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b"
     },
     {
      "id": "397d424c-39fd-11e9-8c83-d795bd1d0ad9",
      "name": "Are there any further instructions that should be sent to the security team?",
      "rank": 2,
      "type": "text",
      "options": null,
      "variable": "info",
      "createdAt": "2019-02-26T19:32:16.553Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b"
     }
    ],
    "messages": [
     {
      "siteRoleIds": [
       "bf5f4f46-2bb5-11e9-8180-5fe10bc30744"
      ],
      "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
      "messageTemplate": { ... },
      "name": "Severe Weather Warning -- Employees",
      "createdAt": "2019-02-26T19:32:16.576Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "confirmationRequestId": null,
      "id": "3980c4bd-39fd-11e9-8c83-03cd8082dd16",
      "confirmationRequest": null,
      "siteRoles": [
       {
        "id": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
        "name": "Employees",
        "createdAt": "2019-02-08T15:25:21.128Z"
       }
      ],
      "body": "The National Weather Service has issued a . Please take action for your personal safety.",
      "subject": " - "
     },
     {
      "siteRoleIds": [
       "724030a9-2b09-11e9-9638-578e7c043866"
      ],
      "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
      "messageTemplate": { ... },
      "name": "Severe Weather Warning -- Security Team",
      "createdAt": "2019-02-26T19:32:16.576Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "confirmationRequestId": null,
      "id": "3980c4be-39fd-11e9-8c83-85c39c3525c6",
      "confirmationRequest": null,
      "siteRoles": [
       {
        "id": "724030a9-2b09-11e9-9638-578e7c043866",
        "name": "Security",
        "createdAt": "2019-02-07T18:51:58.302Z"
       }
      ],
      "body": "The National Weather Service has issued a . Move to secure the building and take action for your personal safety. ",
      "subject": " - "
     }
    ],
    "createdAt": "2019-01-28T15:21:29.691Z",
    "backgroundColor": "#0d2458"
   },
   "events": [
    {
     "id": "fa3e9c1c-3a07-11e9-bd59-cd4f5783da8a",
     "scenarioNotificationId": "f9f90795-3a07-11e9-bd59-bb116a332f2e",
     "notificationId": "fa020846-3a07-11e9-bd59-ed84da3f903d",
     "createdAt": "2019-02-26T20:49:14.910Z",
     "notification": { ... }
    },
    {
     "id": "fa5a1361-3a07-11e9-bd59-f1706503467c",
     "scenarioNotificationId": "f9f90795-3a07-11e9-bd59-bb116a332f2e",
     "notificationId": "fa415b3d-3a07-11e9-bd59-45cb239a430a",
     "createdAt": "2019-02-26T20:49:15.090Z",
     "notification": { ... }
    }
   ],
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Gets a list of all scenario notifications that have been sent.

HTTP Request

GET /scenario-notifications

Produces

application/json

Query Parameters

To make this example more manageable, only the first site was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 10 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The scenario notification response format is detailed here.

Get a Scenario Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenario-notifications/48fa0f0c-39fc-11e9-8c83-c128c081826b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    scenario_notification = JSON.parse(HTTParty.get(url, headers: headers))
    puts(scenario_notification)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenario-notifications/48fa0f0c-39fc-11e9-8c83-c128c081826b" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenario-notifications/48fa0f0c-39fc-11e9-8c83-c128c081826b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    scenario_notification = requests.get(url, headers=headers).json()
    print(scenario_notification)
except RequestException as e:
    print('Unexpected error!', e)

Notice that in this location-enabled scenario example, a simulated site question is present in the fields responses; this is deprecated and present for backwards compatibility with older clients, and will be removed in a future release; you should instead use the more powerful Location object when sending such a scenario.

  {
   "id": "f9f90795-3a07-11e9-bd59-bb116a332f2e",
   "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
   "createdAt": "2019-02-26T20:49:15.250Z",
   "location": {
     "site": {
       "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
       "name": "East Campus"
     },
     "description": "East Campus"
   },
   "fields": [
    {
      "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
      "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
      "name": "At which location?",
      "rank": 0,
      "variable": "site",
      "type": "site",
      "answer": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
      "options": null,
      "createdAt": "2019-02-28T18:23:38.329Z"
    },
    {
     "id": "397d424a-39fd-11e9-8c83-8de4247efba1",
     "name": "What type of severe weather is in the area?",
     "rank": 1,
     "type": "option",
     "answer": "Tornado Warning",
     "options": [
      "Tornado Warning",
      "Tornado Watch",
      "Winter Weather Warning"
     ],
     "variable": "weather_type"
    },
    {
     "id": "397d424c-39fd-11e9-8c83-d795bd1d0ad9",
     "name": "Are there any further instructions that should be sent to the security team?",
     "rank": 2,
     "type": "text",
     "answer": "Dime-sized hail is also expected. Please instruct other employees to avoid windows.",
     "variable": "info"
    }
   ],
   "scenario": {
    "id": "62e192ca-2310-11e9-b378-cfd5de99d56b",
    "icon": "flash",
    "name": "Severe Weather",
    "locationEnabled": true,
    "locationQuestionName": "At which location?",
    "locationVariable": null,
    "defaultLocation": {
      "site": {
        "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
        "name": "East Campus"
      }
    },
    "defaultSiteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
    "defaultBuildingId": null,
    "defaultFloorId": null,
    "defaultZoneId": null,
    "fields": [
     {
       "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
       "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
       "name": "At which location?",
       "rank": 0,
       "variable": "site",
       "type": "site",
       "createdAt": "2019-02-28T18:23:38.329Z"
     },
     {
      "id": "397d424a-39fd-11e9-8c83-8de4247efba1",
      "name": "What type of severe weather is in the area?",
      "rank": 1,
      "type": "option",
      "options": [
       "Tornado Warning",
       "Tornado Watch",
       "Winter Weather Warning"
      ],
      "variable": "weather_type",
      "createdAt": "2019-02-26T19:32:16.553Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b"
     },
     {
      "id": "397d424c-39fd-11e9-8c83-d795bd1d0ad9",
      "name": "Are there any further instructions that should be sent to the security team?",
      "rank": 2,
      "type": "text",
      "options": null,
      "variable": "info",
      "createdAt": "2019-02-26T19:32:16.553Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b"
     }
    ],
    "messages": [
     {
      "siteRoleIds": [
       "bf5f4f46-2bb5-11e9-8180-5fe10bc30744"
      ],
      "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
      "messageTemplate": { ... },
      "name": "Severe Weather Warning -- Employees",
      "createdAt": "2019-02-26T19:32:16.576Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "confirmationRequestId": null,
      "id": "3980c4bd-39fd-11e9-8c83-03cd8082dd16",
      "confirmationRequest": null,
      "siteRoles": [
       {
        "id": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
        "name": "Employees",
        "createdAt": "2019-02-08T15:25:21.128Z"
       }
      ],
      "body": "The National Weather Service has issued a . Please take action for your personal safety.",
      "subject": " - "
     },
     {
      "siteRoleIds": [
       "724030a9-2b09-11e9-9638-578e7c043866"
      ],
      "messageTemplateId": "2b493ddc-39fd-11e9-8c83-010cd570f63b",
      "messageTemplate": { ... },
      "name": "Severe Weather Warning -- Security Team",
      "createdAt": "2019-02-26T19:32:16.576Z",
      "scenarioId": "62e192ca-2310-11e9-b378-cfd5de99d56b",
      "confirmationRequestId": null,
      "id": "3980c4be-39fd-11e9-8c83-85c39c3525c6",
      "confirmationRequest": null,
      "siteRoles": [
       {
        "id": "724030a9-2b09-11e9-9638-578e7c043866",
        "name": "Security",
        "createdAt": "2019-02-07T18:51:58.302Z"
       }
      ],
      "body": "The National Weather Service has issued a . Move to secure the building and take action for your personal safety. ",
      "subject": " - "
     }
    ],
    "createdAt": "2019-01-28T15:21:29.691Z",
    "backgroundColor": "#0d2458"
   },
   "events": [
    {
     "id": "fa3e9c1c-3a07-11e9-bd59-cd4f5783da8a",
     "scenarioNotificationId": "f9f90795-3a07-11e9-bd59-bb116a332f2e",
     "notificationId": "fa020846-3a07-11e9-bd59-ed84da3f903d",
     "createdAt": "2019-02-26T20:49:14.910Z",
     "notification": { ... }
    },
    {
     "id": "fa5a1361-3a07-11e9-bd59-f1706503467c",
     "scenarioNotificationId": "f9f90795-3a07-11e9-bd59-bb116a332f2e",
     "notificationId": "fa415b3d-3a07-11e9-bd59-45cb239a430a",
     "createdAt": "2019-02-26T20:49:15.090Z",
     "notification": { ... }
    }
   ],
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }

Retrieves a single scenario notification by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scenario-notifications/{scenarioNotificationId}

Produces

application/json

Path Parameters

Parameter Description
scenarioNotificationId The id of the scenario notification to retrieve.

Response

The scenario notification response format is detailed here.

Send a Scenario Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenario-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'scenarioId': 'f7a02ed1-3b85-11e9-81d7-e5938f344a04'
,
    'messages': [{
        'messageId': '371c300d-3b99-11e9-81d7-010bc7a87d6b'
,
        'distributionListIds': []
,
        'deviceGroupIds': []
,
        'userIds': ['1e9758e5-73ff-11e8-9b03-239fcdffd087'
]
,
        'areaOfInterestIds': []
,
        'collaborationGroupIds': []

}

]
,
    'location': {
        'site': {
            'id': 'fb8aaa11-759c-11ed-8cd9-b5a5933ad084'

}


}


}

begin: 
    scenario_notification = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(scenario_notification)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenario-notifications" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04", \
       "messages": [{"messageId": "371c300d-3b99-11e9-81d7-010bc7a87d6b", \
         "distributionListIds": [], \
         "deviceGroupIds": [], \
         "userIds": ["1e9758e5-73ff-11e8-9b03-239fcdffd087"], \
         "areaOfInterestIds": [], \
         "collaborationGroupIds": []}], \
       "location": {"site": {"id": "fb8aaa11-759c-11ed-8cd9-b5a5933ad084"}}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scenario-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'scenarioId': 'f7a02ed1-3b85-11e9-81d7-e5938f344a04',
    'messages': [{
        'messageId': '371c300d-3b99-11e9-81d7-010bc7a87d6b',
        'distributionListIds': [],
        'deviceGroupIds': [],
        'userIds': ['1e9758e5-73ff-11e8-9b03-239fcdffd087'],
        'areaOfInterestIds': [],
        'collaborationGroupIds': []
}
],
    'location': {
        'site': {
            'id': 'fb8aaa11-759c-11ed-8cd9-b5a5933ad084'
}

}

}

try: 
    scenario_notification = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(scenario_notification)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "9d5ac3c5-3ba3-11e9-81d7-294576acb40b",
 "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
 "location": {
   "site": {
     "id": "fb8aaa11-759c-11ed-8cd9-b5a5933ad084",
     "name": "Chemical Plant 1"
   },
   "description": "Chemical Plant 1"
 },
 "fields": [
  {
    "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
    "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
    "name": "Where did it occur?",
    "rank": 0,
    "variable": "site",
    "type": "site",
    "answer": "fb8aaa11-759c-11ed-8cd9-b5a5933ad084",
    "options": null,
    "createdAt": "2019-02-28T18:23:38.329Z"
  },
  {
   "id": "371af78c-3b99-11e9-81d7-8557b571d3d5",
   "name": "What was the damage?",
   "rank": 1,
   "variable": "damage",
   "type": "text",
   "answer": null
  }
 ],
 "scenario": {
  "id": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
  "name": "High Molarity Chemical Spill",
  "icon": "flash",
  "backgroundColor": "#33AA55",
  "defaultSiteId": null,
  "defaultBuildingId": null,
  "defaultFloorId": null,
  "defaultZoneId": null,
  "defaultLocation": {},
  "locationEnabled": true,
  "locationQuestionName": "Where did it occur?",
  "locationVariable": null,
  "fields": [
   {
     "id": "55ca36de-4b3c-11ed-aeff-17a043a08a03",
     "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
     "name": "Where did it occur?",
     "rank": 0,
     "variable": "site",
     "type": "site",
     "options": null,
     "createdAt": "2019-02-28T18:23:38.329Z"
   },
   {
    "id": "371af78c-3b99-11e9-81d7-8557b571d3d5",
    "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
    "name": "What was the damage?",
    "rank": 1,
    "variable": "damage",
    "type": "text",
    "options": null,
    "createdAt": "2019-02-28T20:41:25.206Z"
   }
  ],
  "messages": [
   {
    "siteRoleIds": [],
    "messageTemplateId": "10ec2090-3b85-11e9-81d7-3bae1bf35696",
    "messageTemplate": { ... },
    "name": "Chemical Spill",
    "createdAt": "2019-02-28T20:41:25.214Z",
    "scenarioId": "f7a02ed1-3b85-11e9-81d7-e5938f344a04",
    "confirmationRequestId": null,
    "id": "371c300d-3b99-11e9-81d7-010bc7a87d6b",
    "confirmationRequest": null,
    "siteRoles": [],
    "body": null,
    "subject": null
   }
  ],
  "createdAt": "2019-02-28T18:23:38.267Z"
 },
 "events": [
  {
   "id": "9d74664a-3ba3-11e9-81d7-efae047719e9",
   "scenarioNotificationId": "9d5ac3c5-3ba3-11e9-81d7-294576acb40b",
   "notificationId": "9d5bd536-3ba3-11e9-81d7-01f3e168411d",
   "createdAt": "2019-02-28T21:55:51.887Z",
   "notification": { ... }
  }
 ],
 "createdAt": "2019-02-28T21:55:51.719Z",
 "eventIds": [
  "9d74664a-3ba3-11e9-81d7-efae047719e9"
 ],
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Send a new scenario notification.

HTTP Request

POST /scenario-notifications

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 site’s name. Maximum of 140 characters.
messages Array[Object] N/A The array of messages associated with a scenario. More information can be found here.
fields Array[Object] [] The array of fields that answer the questions of a scenario. More information can be found here
location Object N/A If the scenario is location-enabled, a Location object that specifies the site, building, floor, and/or zone to associate with the scenario.

Response

The scenario notification response format is detailed here.

Scenario Notification Messages

Messages are associated with each individual scenario notification, and allow the sender to control which messages are sent along with the recipients to which the message will be sent.

Scenario Notification Messages do not have their own endpoint, and are instead nested inside of an array in scenario notification resources.

Attribute Type Description
messageId String The id of the scenario notification with which the individual message is associated.
areaOfInterestIds Array[String] The list of ids for areas of interest that should be attached to this scenario notification.
collabroationGroupIds Array[String] The list of ids for collaboration groups that should be attached to this scenario notification.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) that should be attached to this scenario notification.
distributionListIds Array[String] The list of ids for distribution lists that should be attached to this scenario notification.
userIds Array[String] The list of ids for users that should be attached to this scenario notification.

Scenario Notification Fields

Fields are associated with each individual scenario notification, and allow the sender manipulate the content of certain messages sent by a scenario.

Scenario Notification Fields do not have their own endpoint, and are instead nested inside of an array in scenario notification resources.

Attribute Type Description
fieldId String The id of the field with which the answer is associated.
type String The type of field that the answer is associated with. Can be option, or text. site is now deprecated and present for backwards compatibility with clients that have not yet been updated to use the more powerful location object; it will be fully removed at a future date.
answer String The answer to the question indicated by the fieldId.

Scenario Notification Events

Events are pieces of notifications sent by a scenario. They contain information which associates a notification and a scenario.

Scenario Notification Events do not have their own endpoint, and are instead nested inside of an array in scenario notification resources.

Attribute Type Description
createdAt ISO 8601 date/time When this scenario notification was created.
id String The id of the scenario notification event.
scenarioNotifcationId String The id of the scenario notification.
notification Notification The notification sent as part of the scenario notification send.
notificationId String The notification id associated with the event.

Scenario Notification Response

The JSON object used to represent a Scenario Notification resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this scenario notification was created.
emergencyAction String Options: contacting-emergency-services, none-need-emergency-building, open-dialer. If the scenario notification was created from an emergency scenario, this will indicate whether emergency services are being contacted, or if the user needs to themselves (in the case of an emergency panic button sent more than a mile from the nearest emergency building).
id String The id of the scenario notification, for efficient retrieval of the scenario notification.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
scenario Scenario The scenario being sent as part of the scenario notification.
scenarioId String The id of the scenario that was sent.
initiationSource JSON Details about the initiator of the scenario.
fields Array[Object] The fields associated with the send. Very similar to a Scenario Field, but also contains information about the answer given.
event Array[Object] The events created by the send. More information about this can be found here.
eventIds Array[String] The list of ids associated with the events created as part of the scenario notification send.
location Object If the scenario is location-enabled, a Location object that specifies the site, building, floor, and/or zone to associate with the scenario.

Scenario Rule Actions

Rule actions provide a way to perform an action when a specific event takes place in InformaCast. Rule Actions are a composite resource, composed of a Rule and an Action. The rule is a JSON object that follows the format of the AWS Event Ruler library. The configured rule will match on the Scenario Notification event object’s scenario id. When the given Scenario Notification is initiated it will cause the configured action to trigger.

List Scenario Rule Actions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "description": "A rule action for testing",
      "scenarioRuleActionId": "cbfd1b60-99ef-11ee-90a2-7bd6ec84aab7",
      "permissions": [
        "get",
        "delete",
        "put"
      ],
      "name": "For-Testing",
      "rule": {
        "event": {
          "scenarioNotification": {
            "scenarioId": [
              "db8d12ba-8328-11ee-a19c-87272a90a5a2"
            ]
          }
        },
        "sourceType": [
          "scenario-notification"
        ]
      },
      "createdAt": "2023-12-13T19:42:49.236Z",
      "scenarioId": "db8d12ba-8328-11ee-a19c-87272a90a5a2",
      "id": "cbe9463f-99ef-11ee-90a2-6d21cf26f5f2",
      "action": {
        "type": "webhook",
        "webhook": {
          "url": "https://api.api",
          "body": {
            "value": "{\"id\": \"123\"}",
            "encryption": "none"
          },
          "method": "POST",
          "headers": [
            {
              "key": "header1",
              "value": "",
              "encryption": "encrypted"
            }
          ],
          "expireAfter": 90,
          "queryParams": [
            {
              "key": "queryParam",
              "value": "",
              "encryption": "encrypted",
              "description": "A query param"
            }
          ],
          "authorization": {
            "type": "oauth2",
            "scope": "code",
            "request": {
              "url": "https://oauth.oauth",
              "body": [
                {
                  "key": "auth-body-key",
                  "value": "data",
                  "encryption": "none"
                }
              ],
              "headers": [
                {
                  "key": "content-type",
                  "value": "application/json",
                  "encryption": "none"
                }
              ],
              "queryParams": [
                {
                  "key": "force",
                  "value": "true",
                  "encryption": "none"
                }
              ]
            },
            "clientId": {
              "value": "",
              "encryption": "encrypted"
            },
            "grantType": "client_credentials",
            "clientSecret": {
              "value": "",
              "encryption": "encrypted"
            },
            "headerPrefix": "bearer",
            "credentialFormat": "basicAuthHeader"
          }
        }
      }
    }
  ],
  "total": 1
}

Retrieves the list of all rule actions that are associated with the given scenario. The visibility of rule actions may be limited by the permissions associated with the request, which are attributed through the user attached to the access token.

HTTP Request

GET /scenarios/{scenarioId}/rule-actions

Produces

application/json

Query Parameters

To make this example more manageable, only the first Scenario Rule Action was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The scenario rule action response format is detailed here

Get a Scenario Rule Action

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions/cbe9463f-99ef-11ee-90a2-6d21cf26f5f2"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    scenario_rule_action = JSON.parse(HTTParty.get(url, headers: headers))
    puts(scenario_rule_action)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions/cbe9463f-99ef-11ee-90a2-6d21cf26f5f2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions/cbe9463f-99ef-11ee-90a2-6d21cf26f5f2"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    scenario_rule_action = requests.get(url, headers=headers).json()
    print(scenario_rule_action)
except RequestException as e:
    print('Unexpected error!', e)
{
  "description": "A rule action for testing.",
  "scenarioRuleActionId": "cbfd1b60-99ef-11ee-90a2-7bd6ec84aab7",
  "permissions": [
    "get",
    "delete",
    "put"
  ],
  "name": "For-Testing",
  "rule": {
    "event": {
      "scenarioNotification": {
        "scenarioId": [
          "db8d12ba-8328-11ee-a19c-87272a90a5a2"
        ]
      }
    },
    "sourceType": [
      "scenario-notification"
    ]
  },
  "createdAt": "2023-12-13T19:42:49.236Z",
  "scenarioId": "db8d12ba-8328-11ee-a19c-87272a90a5a2",
  "id": "cbe9463f-99ef-11ee-90a2-6d21cf26f5f2",
  "action": {
    "type": "webhook",
    "webhook": {
      "url": "https://api.api",
      "body": {
        "value": "{\"id\": \"123\"}",
        "encryption": "none"
      },
      "method": "POST",
      "headers": [
        {
          "key": "header1",
          "value": "",
          "encryption": "encrypted"
        }
      ],
      "expireAfter": 90,
      "queryParams": [
        {
          "key": "queryParam",
          "value": "",
          "encryption": "encrypted",
          "description": "A query param"
        }
      ],
      "authorization": {
        "type": "oauth2",
        "scope": "code",
        "request": {
          "url": "https://oauth.oauth",
          "body": [
            {
              "key": "auth-body-key",
              "value": "data",
              "encryption": "none"
            }
          ],
          "headers": [
            {
              "key": "content-type",
              "value": "application/json",
              "encryption": "none"
            }
          ],
          "queryParams": [
            {
              "key": "force",
              "value": "true",
              "encryption": "none"
            }
          ]
        },
        "clientId": {
          "value": "",
          "encryption": "encrypted"
        },
        "grantType": "client_credentials",
        "clientSecret": {
          "value": "",
          "encryption": "encrypted"
        },
        "headerPrefix": "bearer",
        "credentialFormat": "basicAuthHeader"
      }
    }
  }
}

Retrieves a single scenario rule action by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scenarios/{scenarioId}/rule-actions/{ruleActionId}

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario the rule action is associated with.
ruleActionId The id of the rule action to retrieve.

Response

The scenario rule action response format is detailed here

Create a Scenario Rule Action

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    scenario_rule_action = JSON.parse(HTTParty.post(url, headers: headers))
    puts(scenario_rule_action)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    scenario_rule_action = requests.post(url, headers=headers).json()
    print(scenario_rule_action)
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "For-Testing",
  "description": "description",
  "action": {
    "type": "webhook",
    "webhook": {
      "url": "https://api.api",
      "method": "POST",
      "headers": [
        {
          "value": "secret-value",
          "description": "Auth header",
          "encryption": "should-encrypt",
          "key": "Authorization"
        }
      ],
      "body": {
        "value": "{\"id\": \"123\"}",
        "encryption": "none"
      },
      "queryParams": [
        {
          "key": "includeTotal",
          "encryption": "none",
          "value": "true",
          "description": "Query param sent in webhook"
        }
      ],
      "expireAfter": 90,
      "authorization": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "clientId": {
          "value": "oauth-client-id-value",
          "encryption": "should-encrypt"
        },
        "clientSecret": {
          "value": "secret-value",
          "encryption": "should-encrypt"
        },
        "credentialFormat": "basicAuthHeader",
        "scope": "code",
        "request": {
          "url": "https://oauth.oauth",
          "body": [
            {
              "key": "auth-body-key",
              "value": "data",
              "encryption": "none"
            }
          ],
          "headers": [
            {
              "key": "content-type",
              "value": "application/json",
              "encryption": "none"
            }
          ],
          "queryParams": [
            {
              "key": "force",
              "value": "true",
              "encryption": "none"
            }
          ]
        }
      }
    }
  }
}

Creates a new scenario rule action.

HTTP Request

POST /scenarios/{scenarioId}/rule-actions

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario the rule action is associated with.

Request Parameters

Parameter Type Default Description
name String N/A The name of the rule action
description String N/A The description of the rule action
action Object N/A The JSON object that describes the action to be taken when a rule matches an event. Currently this can only be a webhook.

Response

The scenario rule action response format is detailed here

Update a Scenario Rule Action

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions/cbe9463f-99ef-11ee-90a2-6d21cf26f5f2"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    scenario_rule_action = JSON.parse(HTTParty.put(url, headers: headers))
    puts(scenario_rule_action)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions/cbe9463f-99ef-11ee-90a2-6d21cf26f5f2" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions/cbe9463f-99ef-11ee-90a2-6d21cf26f5f2"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    scenario_rule_action = requests.put(url, headers=headers).json()
    print(scenario_rule_action)
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "For-Testing",
  "description": "description",
  "action": {
    "type": "webhook",
    "webhook": {
      "url": "https://api.api",
      "method": "POST",
      "headers": [
        {
          "value": "secret-value",
          "description": "Auth header",
          "encryption": "should-encrypt",
          "key": "Authorization"
        }
      ],
      "body": {
        "value": "{\"id\": \"123\"}",
        "encryption": "none"
      },
      "queryParams": [
        {
          "key": "includeTotal",
          "encryption": "none",
          "value": "true",
          "description": "Query param sent in webhook"
        }
      ],
      "expireAfter": 90,
      "authorization": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "clientId": {
          "value": "oauth-client-id-value",
          "encryption": "should-encrypt"
        },
        "clientSecret": {
          "value": "secret-value",
          "encryption": "should-encrypt"
        },
        "credentialFormat": "basicAuthHeader",
        "scope": "code",
        "request": {
          "url": "https://oauth.oauth",
          "body": [
            {
              "key": "auth-body-key",
              "value": "data",
              "encryption": "none"
            }
          ],
          "headers": [
            {
              "key": "content-type",
              "value": "application/json",
              "encryption": "none"
            }
          ],
          "queryParams": [
            {
              "key": "force",
              "value": "true",
              "encryption": "none"
            }
          ]
        }
      }
    }
  }
}

Update an existing scenario rule action.

HTTP Request

PUT /scenarios/{scenarioId}/rule-actions/{ruleActionId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario the rule action is associated with.
ruleActionId The id of the rule action to retrieve.

Produces

application/json

Request Parameters

Parameter Type Default Description
name String N/A The name of the rule action
description String N/A The description of the rule action
action Object N/A The JSON object that describes the action to be taken when a rule matches an event. Currently this can only be a webhook.

Response

The scenario rule action response format is detailed here

Remove a Scenario Rule Action

# Continuing with the scenario and ruleAction
# objects from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scenarios/db8d12ba-8328-11ee-a19c-87272a90a5a2/ruleActions/cbe9463f-99ef-11ee-90a2-6d21cf26f5f2" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the scenario and ruleAction
# objects from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted cbe9463f-99ef-11ee-90a2-6d21cf26f5f2"
}

Delete an existing scenario rule action

HTTP Request

DELETE /scenarios/{scenarioId}/rule-actions/{ruleActionId}

Produces

application/json

Path Parameters

Parameter Description
scenarioId The id of the scenario the rule action is associated with.
ruleActionId The id of the rule action to retrieve.

Response

The deletion response format is detailed here.

Scenario Rule Action Response

The JSON document used to represent a Rule Action resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this rule action was created.
id String The id of the rule action.
name String The name of the rule action.
permissions array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
description String The description of the rule action.
action Object The JSON object that describes the action to be taken when a rule matches an event. Currently this can only be a webhook.
rule Object The JSON object that describes which events to match on using the AWS Event Ruler.
scenarioId String The id of the scenario.
scenarioRuleActionId String The id of the scenario to rule action relationship.

SCIM Users

There are two varieties of the SCIM users endpoint, /scim/Users and /scim-users. /scim/Users ultimately forwards to /scim-users after doing some parsing, meaning that this documenation will cover functionality of the /scim-users endpoint. All of these requests must be associated with an instance of a Load Definition. Note that this is explicitly meant to interact with servers that send data in the SCIM format (for example, Azure AD).

List SCIM Users

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "itemsPerPage": 20,
    "startIndex": 0,
    "Resources": [
        {
            "id": "e1298c43-8be5-11eb-b0f1-efafc96c199f",
            "name": {
                "formatted": "John Doe",
                "givenName": "John",
                "familyName": "Doe"
            },
            "active": true,
            "emails": [
                {
                    "type": "work",
                    "value": "testing9876@singlewire.com",
                    "primary": true
                },
                {
                    "type": "home",
                    "value": "testinghome1234@singlewire.com",
                    "primary": false
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "userName": "JohnDoe",
            "externalId": "john.doe",
            "displayName": "john.doe"
        },
    ]
}

This return is the JSON format necessary to be consumed by an active directory server and includes all of the information associated with a given SCIM User. Note also that this is a identical response to what is given when filtering SCIM users, and will be returned when a SCIM filter is sent on a GET request.

HTTP Request

GET /scim/Users or GET /scim-users

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Response

The SCIM user response format is detailed here.

List SCIM Users for Display

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true',
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
   "next": null,
   "partial": false,
   "previous": null,
   "total": 1,
   "data": [
      {
         "createdAt": "2021-03-04T14:48:14.243Z",
         "createdUserId": "a5f4a7d6-7cf8-11eb-9d7e-55bdbfc46699",
         "error": null,
         "externalId": "SCIM-1",
         "id": "a5d33d25-7cf8-11eb-9d7e-95d568029afb",
         "loadSourceId": "1d286d5c-6708-11eb-861d-89adc650ae34",
         "name": "John Doe",
         "permissions":
           [
             "put",
             "delete",
             "get"
           ],
         "scimMetadata":
           {
             "active": true,
             "displayName": "John Doe",
             "emails":
               [
                 {
                   "primary": true,
                   "type": "work",
                   "value": "test@singlewire.com"
                 }
               ],
             "externalId": "SCIM-1",
             "id": "a5d33d25-7cf8-11eb-9d7e-95d568029afb",
             "phoneNumbers":
               [
                 {
                   "value": "15555556309"
                 }
               ],
             "schemas":
               [
                 "urn:ietf:params:scim:schemas:core:2.0:User"
               ],
             "userName": "john.doe",
             "userId": "a5f4a7d6-7cf8-11eb-9d7e-55bdbfc46699"
           },
         "userId": "a5f4a7d6-7cf8-11eb-9d7e-55bdbfc46699"
      }
   ]
}

Returns the standard fusion list payload, including the scim metadata, which is detailed here

HTTP Request

GET /scim-users?loadDisplay=true

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Response

The list response format is detailed here.

Get a SCIM User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/a5d33d25-7cf8-11eb-9d7e-95d568029afb"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users/a5d33d25-7cf8-11eb-9d7e-95d568029afb" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/a5d33d25-7cf8-11eb-9d7e-95d568029afb"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)

{
    "id": "a5d33d25-7cf8-11eb-9d7e-95d568029afb",
    "active": true,
    "emails": [
        {
            "type": "work",
            "value": "test-update@singlewire.com",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "john.doe",
    "externalId": "SCIM-1",
    "displayName": "John Doe",
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Retrieves a single SCIM User by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scim-users/{scimUserId} or GET /scim/Users/{scimUserId}

Produces

application/json

Path Parameters

Parameter Description
scimUserId The id of the SCIM user to retrieve.

Response

The SCIM user response format is detailed here.

Create a SCIM User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'userName': 'John Doe'
,
    'active': true
,
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'
]
,
    'externalId': 'SCIM-1'

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"userName": "John Doe", \
       "active": true, \
       "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], \
       "externalId": "SCIM-1"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scim-users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'userName': 'John Doe',
    'active': true,
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'],
    'externalId': 'SCIM-1'
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db",
    "active": true,
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "John Doe",
    "externalId": "SCIM-1",
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Creates a new SCIM User.

HTTP Request

POST /scim-users or POST /scim/Users

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
userName String N/A The user’s name, usually corresponding to a name field on the IDP.
externalId String N/A The id of the user not corresponding to its identifier within fusion, but instead its identifier on the external server/IDP.

Response

The SCIM user response format is detailed here

Update a SCIM User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'userName': 'Johnny Doe'
,
    'active': false
,
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'
]
,
    'externalId': 'SCIM-1'
,
    'id': 'bee2ff93-90b5-11eb-a956-9dd0ae8bf1db'

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"userName": "Johnny Doe", \
       "active": false, \
       "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], \
       "externalId": "SCIM-1", \
       "id": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'userName': 'Johnny Doe',
    'active': false,
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'],
    'externalId': 'SCIM-1',
    'id': 'bee2ff93-90b5-11eb-a956-9dd0ae8bf1db'
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db",
    "active": false,
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "Johnny Doe",
    "externalId": "SCIM-1",
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Fully updates a SCIM User. Note that unlike other PUT requests in our system, this is a full replace that will update to exactly the data sent. This is because the SCIM endpoints support PATCH requests.

HTTP Request

PUT /scim-users/{scimUserId} or PUT /scim/Users/{scimUserId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scimUserId The id of the SCIM user to modify.

Request Parameters

Parameter Type Default Description
userName String N/A The user’s name, usually corresponding to a name field on the IDP.
externalId String N/A The id of the user not corresponding to its identifier within fusion, but instead its identifier on the external server/IDP.

Response

The SCIM user response format is detailed here

Update a SCIM User’s Attributes

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'
]
,
    'Operations': {
        'op': 'replace'
,
        'path': 'userName'
,
        'value': 'Jonathan Doe'

}


}

begin: 
    puts(JSON.parse(HTTParty.patch(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db" \
  -X PATCH \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], \
       "Operations": {"op": "replace", \
         "path": "userName", \
         "value": "Jonathan Doe"}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User'],
    'Operations': {
        'op': 'replace',
        'path': 'userName',
        'value': 'Jonathan Doe'
}

}

try: 
    print(requests.patch(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db",
    "active": false,
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "Jonathan Doe",
    "externalId": "SCIM-1",
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Updates specified attributes of a SCIM user. Note that the path can be any legal filter path in SCIM; for further information about that, reference the SCIM RFC.

HTTP Request

PATCH /scim-users/{scimUserId} or PATCH /scim/Users/{scimUserId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scimUserId The id of the SCIM user to modify.

Request Parameters

Parameter Type Default Description
userName String N/A The user’s name, usually corresponding to a name field on the IDP.
externalId String N/A The id of the user not corresponding to its identifier within fusion, but instead its identifier on the external server/IDP.

Remove a SCIM User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
}

Deletes an existing SCIM user and its associated fusion user.

HTTP Request

DELETE /scim-users/{scimUserId}

Produces

application/json

Path Parameters

Parameter Description
scimUserId The id of the SCIM user to delete.

Response

The deletion response format is detailed here.

List SCIM User Response

Attribute Type Description
externalId String The id of this SCIM user which we received from the IDP.
id UUID The id of this SCIM user which we generated internally.
loadSourceId UUID The id of the cloud user loader this user was created in association with.
scimMetadata Object The SCIM data we’ve received about this user, which we store in case of creation errors and for future use. Should be identical to the SCIM User Response.
createdAt ISO 8601 date/time The time at which this SCIM user was created.
createdUserId UUID The id associated with the SCIM user which belongs to the created user within our system.
userId UUID The id of the user. Should be redundant with the above.
name String The name of the created user, if available.
error String Our SCIM endpoint consumes all legal data from an IDP, but not all legal data from an IDP can create a user in InformaCast. If such an error occurs, that information is returned here.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

SCIM User Response

Attribute Type Description
id UUID The fusion-owned uuid of the resource
externalId String The external/IDP-owned id of the resource (can be a UUID)
schemas Array[String] Schemas used to identify the request and the attributes it may contain.
userName String The userName of the user. May not necessarily be the name of the user created in InformaCast, but will always be passed by an IDP.
displayName String The displayName of the user. Depending on the IDP, this might be the default name of the user.
name Object The name of the user, broken into a number of attributes. More information can be found here.
active Boolean Whether the user is active or not. Corresponds to locking the user in InformaCast.
emails Array[Object] The emails for the user, sent as an array of objects. More information about the standard device format is here.
phoneNumbers Array[Object] The phone numbers for the user, sent as an array of objects. More information about the standard device format is here.
addresses Array[Object] The addresses that belong to the user, sent as an array of objects. Unused, but may be used for location services in the future. More information about the address format is here.
preferredLanguage String The user’s preferred language, written out, ie “English”.
locale String The user’s preferred language, as a locale code, ie “en-us”.
timezone String The user’s timezone, ie “UTC”.
entitlements Array[Object] A list of entitlements for the user. Unused, but may be used in the future. More information about the entitlements’ format is here.
roles Array[Object] A list of roles for the user. Unused, but may be used in the future. More information about the roles’ format is here.
enterpriseSchema Object An optional schema that stores information about a user’s position within the company using the IDP. If passed to “/scim/Users”, the attribute is instead urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Currently unused, but may be used in the future. More information about the enterprise schema is here.
schoolSchema Object A custom schema that stores information about a user’s school data. If passed to “/scim/Users”, the attribute is instead urn:ietf:params:scim:schemas:extension:singlewire:school:2.0:User. Primarily used to store data about OneRoster Users, and is thus only available to school loaders. More information about the enterprise schema is here.
meta Object Any extra information about the user sent from an IDP. Unused in InformaCast.

SCIM Name Object

Attribute Type Description
formatted String The full name of the user, with all of the below combined, ie “Sir Dwight Kurt Shrute III”. This is the only attribute of this object used in Fusion.
familyName String The user’s family name, ie “Shrute”
givenName String The user’s given name, ie “Dwight”
middleName String The user’s middle name, ie “Kurt”
honorificPrefix String The prefix to the user’s name, ie “Sir”, “Mrs.”
honorificSuffix String The suffix to the user’s name, ie “III”, “Sr”

SCIM Standard Object

Attribute Type Description
value String What this value is depends on the array its in; for emails, this is an email; for phone numbers, this is a phone number; and so on.
type String A description of what the purpose of this object is; in many cases, this is to note whether an email or phone is for work or home use.
display String Taken in, but unused in InformaCast.
primary Boolean Whether this is the primary instance of the object in the array; only used to determine the email to assign the InformaCast user.

SCIM Address Object

Attribute Type Description
type String The type of address, usually used to specify whether this is a work or home address.
streetAddress String The street address for this instance.
locality String The locality of the address, if necessary.
region String The region of the address, if necessary.
postalCode String The postal code for the address.
country String The country in which the address resides.
formatted String The fully-formatted address for use.
primary Boolean Whether this is the primary address for the user.

SCIM Enterprise Schema

Attribute Type Description
employeeNumber String The employee’s id number.
costCenter String The employee’s cost center.
organization String The organization to which the employee belongs.
division String The division in which the employee works.
department String The department in which the employee works.
manager Object The employee’s manager, and potentially a different user sent to this SCIM endpoint. More information can be found here.

SCIM School Schema

Attribute Type Description
sourcedId String The id of the user in its original resource (in most cases, the OneRoster API integrated with).
status String The user’s status.
dateLastModified String The date the user was last modified in OneRoster.
username String The user’s OneRoster username.
type String The user’s type.
identifier String An additional identifier for the user.
enabledUser String Whether the user is enabled in OneRoster.
givenName String The user’s given name, redundant with the generic SCIM’s name object.
familyName String The user’s family name, redundant with the generic SCIM’s name object.
middleName String The user’s middle name, redundant with the generic SCIM’s name object.
role String The user’s role, usually one of student, teacher, or parent/guardian.
email String The user’s email.
phone String The user’s phone.
agents Array[String] A list of users associated with user, such as a parent/guardian for a student.
orgs Array[String] A list of associated organizations, usually schools in OneRoster.
grades Array[String] Grade(s) associated with the student.

SCIM Manager Object

Attribute Type Description
value String The identifier (id of the SCIM user) associated with the manager of the employee.
$ref String A URI reference to the manager, possibly within the IDP.
displayName String The manager’s display name from the IDP.

List User SCIM Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/685c2400-dd09-11e3-8c49-b8e856327746/groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    groups = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(groups)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-users/685c2400-dd09-11e3-8c49-b8e856327746/groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-users/685c2400-dd09-11e3-8c49-b8e856327746/groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    groups = requests.get(url, headers=headers, params=params).json()
    print(groups)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "previous": null,
  "next": null,
  "partial": false,
  "data":[
    {
      "id": "5b068001-8beb-11eb-8f4c-c11036bf4068",
      "name": "SCIM Group Name",
      "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
      "createdAt": "2021-03-23T15:20:52.566Z",
      "permissions": ["get"]
    }
  ]
}

Returns the standard fusion list payload of SCIM Groups to which the SCIM User belongs.

HTTP Request

GET /scim-users/{scimUserId}/groups

Produces

application/json

Path Parameters

Parameter Description
scimUserId The id of the SCIM user to retrieve.

SCIM Groups

There are two varieties of the SCIM groups endpoint, /scim/Groups and /scim-groups. /scim/Groups ultimately forwards to /scim-groups after doing some parsing, meaning that this documenation will cover functionality of the /scim-groups endpoint. All of these requests must be associated with an instance of a Load Definition. Note that this is explicitly meant to interact with servers that send data in the SCIM format (for example, Azure AD).

List SCIM Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "itemsPerPage": 1,
    "totalResults": 16,
    "startIndex": 0,
    "Resources": [
        {
            "memberCount": 0,
            "superGroup": false,
            "name": "Group20",
            "createdAt": "2021-03-30T15:20:13.584Z",
            "distributionListIds": [],
            "loadSourceName": "USER LOADER NAME",
            "securityGroupIds": [],
            "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
            "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
            "id": "6ca1c0ba-916b-11eb-8b4c-094c1ed1043d",
            "licenseUsers": true
        }    
    ],
}

This return is the JSON format necessary to be consumed by an active directory server and includes all of the information associated with a given SCIM Group.

HTTP Request

GET /scim/Groups or GET /scim-groups

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

List SCIM Groups for Display

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "partial": false,
    "total": 16,
    "next": null,
    "previous": null,
    "data": [
        {
            "memberCount": 3,
            "permissions": [
                "put",
                "delete",
                "get"
            ],
            "superGroup": false,
            "name": "Group2",
            "createdAt": "2021-02-03T20:57:34.969Z",
            "distributionListIds": [],
            "loadSourceName": "USER LOADER NAME",
            "securityGroupIds": [],
            "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
            "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
            "id": "70c0be09-6662-11eb-b962-b1e9a4e7ca6e",
            "licenseUsers": false
        },
    ]
}

HTTP Request

GET /scim-groups?loadDisplay=true

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Get a SCIM Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/a5d33d25-7cf8-11eb-9d7e-95d568029afb"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-groups/a5d33d25-7cf8-11eb-9d7e-95d568029afb" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/a5d33d25-7cf8-11eb-9d7e-95d568029afb"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "a5d33d25-7cf8-11eb-9d7e-95d568029afb",
    "memberCount": 0,
    "permissions": [
        "put",
        "delete",
        "get"
    ],
    "superGroup": false,
    "name": "Group Name",
    "createdAt": "2021-03-30T15:20:13.584Z",
    "distributionListIds": [],
    "loadSourceName": "USER LOADER NAME",
    "securityGroupIds": [],
    "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
    "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
    "licenseUsers": true
}

Retrieves a single SCIM Group by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scim-groups/{scimGroupId} or GET /scim/Groups/{scimGroupId}

Produces

application/json

Path Parameters

Parameter Description
scimGroupId The id of the SCIM group to retrieve.

Create a SCIM Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'externalId': 'e242b813-6249-11eb-976e-2bfbd7d5032e'
,
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:Group'
]
,
    'displayName': 'New Group Name'

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e", \
       "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], \
       "displayName": "New Group Name"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'externalId': 'e242b813-6249-11eb-976e-2bfbd7d5032e',
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:Group'],
    'displayName': 'New Group Name'
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "6ca1c0ba-916b-11eb-8b4c-094c1ed1043d",
    "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
    "createdAt": "2021-03-30T15:20:13.584Z",
    "name": "New Group Name",
    "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
    "licenseUsers": true,
    "superGroup": false,
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Creates a new SCIM Group.

HTTP Request

POST /scim-groups or POST /scim/Groups

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Update a SCIM Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:Group'
]
,
    'id': 'bee2ff93-90b5-11eb-a956-9dd0ae8bf1db'
,
    'displayName': 'Group Name'
,
    'members': [{
        'value': '7a1b42e4-25e4-11eb-a458-0b8a164b051e'
,
        'display': 'VP'

}

, {
        'value': '81032505-25e4-11eb-a458-19a8237b8fc4'
,
        'display': 'SenorVP'

}

]

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], \
       "id": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db", \
       "displayName": "Group Name", \
       "members": [{"value": "7a1b42e4-25e4-11eb-a458-0b8a164b051e", \
         "display": "VP"}, {"value": "81032505-25e4-11eb-a458-19a8237b8fc4", \
         "display": "SenorVP"}]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'schemas': ['urn:ietf:params:scim:schemas:core:2.0:Group'],
    'id': 'bee2ff93-90b5-11eb-a956-9dd0ae8bf1db',
    'displayName': 'Group Name',
    'members': [{
        'value': '7a1b42e4-25e4-11eb-a458-0b8a164b051e',
        'display': 'VP'
}
, {
        'value': '81032505-25e4-11eb-a458-19a8237b8fc4',
        'display': 'SenorVP'
}
]
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db",
    "memberCount": 2,
    "permissions": [
        "put",
        "delete",
        "get"
    ],
    "superGroup": true,
    "name": "Group Name",
    "createdAt": "2021-02-26T19:21:41.631Z",
    "distributionListIds": [],
    "loadSourceName": "USER LOADER NAME",
    "securityGroupIds": [],
    "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
    "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
    "licenseUsers": true
}

Fully updates a SCIM Group. Note that unlike other PUT requests in our system, this is a full replace that will update to exactly the data sent. This is because the SCIM endpoints support PATCH requests.

HTTP Request

PUT /scim-groups/{scimGroupId} or PUT /scim/Groups/{scimUserId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scimGroupId The id of the SCIM group to modify.

Update a SCIM Group’s Attributes

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'schemas': ['urn:ietf:params:scim:api:messages:2.0:PatchOp'
]
,
    'Operations': {
        'op': 'replace'
,
        'path': 'displayName'
,
        'value': 'New Group Name'

}


}

begin: 
    puts(JSON.parse(HTTParty.patch(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db" \
  -X PATCH \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], \
       "Operations": {"op": "replace", \
         "path": "displayName", \
         "value": "New Group Name"}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'schemas': ['urn:ietf:params:scim:api:messages:2.0:PatchOp'],
    'Operations': {
        'op': 'replace',
        'path': 'displayName',
        'value': 'New Group Name'
}

}

try: 
    print(requests.patch(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db",
    "security-group-ids": [],
    "member-count": 2,
    "name": "New Group Name",
    "distribution-list-ids": [],
    "load-source-id": "42e6c501-6662-11eb-b962-912753d8c0a0",
    "external-id": "e242b813-6249-11eb-976e-2bfbd7d5032e",
    "license-users": true,
    "load-source-name": "USER LOADER NAME",
    "super-group": true,
    "created-at": "2021-02-26T19:21:41Z"
}

Updates specified attributes of a SCIM Group. Note that the path can be any legal filter path in SCIM; for further information about that, reference the SCIM RFC.

HTTP Request

PATCH /scim-groups/{scimGroupId} or PATCH /scim/Groups/{scimGroupId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scimGroupId The id of the SCIM group to modify.

Remove a SCIM Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted bee2ff93-90b5-11eb-a956-9dd0ae8bf1db"
}

Deletes an existing SCIM group.

HTTP Request

DELETE /scim-groups/{scimGroupId}

Produces

application/json

Path Parameters

Parameter Description
scimGroupId The id of the SCIM group to delete.

Response

The deletion response format is detailed here.

List SCIM Group Members

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/members" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "total": 2,
    "previous": null,
    "next": null,
    "partial": false,
    "data": [
        {
            "email": null,
            "permissions": [
                "get"
            ],
            "name": null,
            "createdAt": "2021-03-23T15:56:44.704Z",
            "scimMetadata": {
                "id": "53a1ec10-6705-11eb-9a55-1b4f72adf5bd",
                "name": {
                    "formatted": "Ryan Leenay",
                    "givenName": "Ryan",
                    "familyName": "Leenay"
                },
                "emails": [
                    {
                        "type": "work",
                        "value": "testing4@bob.com",
                        "primary": true
                    },
                    {
                        "type": "home",
                        "value": "testing4home@bob.com",
                        "primary": false
                    }
                ],
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:User"
                ],
                "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e"
            },
            "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
            "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
            "id": "5dccb2ae-8bf0-11eb-8f4c-8b8c7875b550",
            "isLicensed": null,
            "userId": null,
            "scimGroupId": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db",
            "scimUserId": "53a1ec10-6705-11eb-9a55-1b4f72adf5bd"
        },
        {
            "email": null,
            "permissions": [
                "get"
            ],
            "name": null,
            "createdAt": "2021-03-23T16:51:49.093Z",
            "scimMetadata": {
                "id": "ad0b8247-67eb-11eb-9273-8d03e2192ebd",
                "name": {
                    "formatted": "Ryan Leenay",
                    "givenName": "Ryan",
                    "familyName": "Leenay"
                },
                "emails": [
                    {
                        "type": "work",
                        "value": "testing5@bob.com",
                        "primary": true
                    },
                    {
                        "type": "home",
                        "value": "testing5home@bob.com",
                        "primary": false
                    }
                ],
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:User"
                ],
                "externalId": "e242b813-6249-11eb-976e-2bfbd7d12345"
            },
            "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
            "externalId": "e242b813-6249-11eb-976e-2bfbd7d12345",
            "id": "0f5e71e9-8bf8-11eb-9939-2796acf1695a",
            "isLicensed": null,
            "userId": null,
            "scimGroupId": "bee2ff93-90b5-11eb-a956-9dd0ae8bf1db",
            "scimUserId": "ad0b8247-67eb-11eb-9273-8d03e2192ebd"
        }
    ]
}

Gets SCIM Group members, returns the data in paginated format.

HTTP Request

GET /scim-groups/{scimGroupId}/members

Produces

application/json

Path Parameters

Parameter Description
scimGroupId The id of the SCIM group.

List SCIM Group Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scim-group/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "domains": [
        {
            "path": "/f5bb3fa4-3d62-11ea-8f36-d9cfa653df09/fa26fe35-3d62-11ea-8f36-47d1617acbb8/",
            "name": "B",
            "namePath": "/A/B/",
            "provider-2": "BulkImport",
            "domainId": "fa26fe35-3d62-11ea-8f36-47d1617acbb8",
            "id": "fa26fe35-3d62-11ea-8f36-47d1617acbb8",
            "scimGroupId": "d80aa1de-8026-11eb-a543-53c5fa2d317e",
            "parentId": "f5bb3fa4-3d62-11ea-8f36-d9cfa653df09",
            "provider": "BulkImport"
        }
    ],
    "domainIds": [
        "fa26fe35-3d62-11ea-8f36-47d1617acbb8"
    ]
}

Gets SCIM Group domains, returns the data in non-paginated format.

HTTP Request

GET /scim-groups/{scimGroupId}/domains

Produces

application/json

Path Parameters

Parameter Description
scimGroupId The id of the SCIM group.

Update a SCIM Group’s Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'domainIds': ['fa26fe35-3d62-11ea-8f36-47d1617acbb8'
]

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"domainIds": ["fa26fe35-3d62-11ea-8f36-47d1617acbb8"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scim-groups/bee2ff93-90b5-11eb-a956-9dd0ae8bf1db/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'domainIds': ['fa26fe35-3d62-11ea-8f36-47d1617acbb8']
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "memberCount": 1,
  "domains":[
    {
      "domainId": "fa26fe35-3d62-11ea-8f36-47d1617acbb8",
      "provider": "Provider Name",
      "scimGroupId": "d80aa1de-8026-11eb-a543-53c5fa2d317e"
    }
  ],
  "superGroup": false,
  "name": "Group Name",
  "createdAt": "2021-03-08T15:56:28.748Z",
  "distributionListIds": [],
  "loadSourceName": "USER LOADER NAME",
  "securityGroupIds": [],
  "loadSourceId": "42e6c501-6662-11eb-b962-912753d8c0a0",
  "externalId": "e242b813-6249-11eb-976e-2bfbd7d5032e",
  "id": "d80aa1de-8026-11eb-a543-53c5fa2d317e",
  "licenseUsers": true,
  "permissions": ["delete","get"]
}

Updates a SCIM Group’s Domain associations.

HTTP Request

POST /scim-groups/{scimGroupId}/domains

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scimGroupId The id of the SCIM group to modify.

Scheduled Notifications

A scheduled notification provides a mechanism for configuring repeating or single event notifications. One can configure when a scheduled notification will fire, which message template it will use, and to whom it will be sent. You can also disable a scheduled notification if needed.

List All Scheduled Notifications

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    schedules = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(schedules)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    schedules = requests.get(url, headers=headers, params=params).json()
    print(schedules)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "timeZone": "America/Chicago",
   "schedule": "0 0 0 1 1 ? 2020",
   "permissions": ["delete", "put", "get"],
   "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8",
   "nextFireTime": "2020-01-01T06:00:00.000Z",
   "disabled": false,
   "messageTemplate": {
    "name": "Blank",
    "id": "179a1e31-c52b-11e5-80ea-95f83e09f4e8"
   },
   "name": "Midnight 2020",
   "createdAt": "2017-07-25T15:59:43.894Z",
   "updatedAt": "2017-07-25T15:59:43.894Z",
   "distributionListIds": [],
   "deviceGroupIds": [],
   "id": "464f2bb0-7152-11e7-963b-7317a53c5894",
   "distributionLists": [],
   "deviceGroups": []
  },
  {
   "timeZone": "America/Chicago",
   "schedule": "0 0 1 1/1 * ? *",
   "permissions": ["delete", "put", "get"],
   "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8",
   "nextFireTime": "2017-07-26T06:00:00.000Z",
   "disabled": false,
   "messageTemplate": {
    "name": "Blank",
    "id": "179a1e31-c52b-11e5-80ea-95f83e09f4e8"
   },
   "name": "Repeating Schedule",
   "createdAt": "2017-07-25T15:58:33.204Z",
   "updatedAt": "2017-07-25T15:58:33.204Z",
   "distributionListIds": [
    "c200c39f-8e17-11e5-9196-d17102d54b6d"
   ],
   "deviceGroupIds": [
    "9fb8c937-fd05-11e6-a30e-e198ed79b70a"
   ],
   "id": "1c2cbb8d-7152-11e7-963b-b75830b20e2f",
   "distributionLists": [
    {
     "id": "c200c39f-8e17-11e5-9196-d17102d54b6d",
     "name": "Administrator Alerts",
     "campaign": null,
     "createdAt": "2015-11-18T17:13:59.489Z"
    }
   ],
   "deviceGroups": [
    {
     "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
     "name": "All Phones",
     "filters": []
    }
   ]
  }
 ]
}

Retrieves a list of all scheduled notifications. (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 /scheduled-notifications

Produces

application/json

Query Parameters

To make this example more manageable, only the first two scheduled notifications were requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of three 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.
assoc-sync-state-for-endpoint String Include the current synchronization state for a specific fusion endpoint.

Response

The scheduled notification response format is detailed here.

Get a Scheduled Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    schedule = JSON.parse(HTTParty.get(url, headers: headers))
    puts(schedule)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    schedule = requests.get(url, headers=headers).json()
    print(schedule)
except RequestException as e:
    print('Unexpected error!', e)
{
 "timeZone": "America/Chicago",
 "schedule": "0 0 1 1/1 * ? *",
 "permissions": ["delete", "put", "get"],
 "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8",
 "nextFireTime": "2017-07-26T06:00:00.000Z",
 "disabled": false,
 "messageTemplate": {
  "name": "Blank",
  "id": "179a1e31-c52b-11e5-80ea-95f83e09f4e8"
 },
 "name": "Repeating Schedule",
 "createdAt": "2017-07-25T15:58:33.204Z",
 "updatedAt": "2017-07-25T15:59:43.894Z",
 "distributionListIds": [
  "c200c39f-8e17-11e5-9196-d17102d54b6d"
 ],
 "deviceGroupIds": [
  "9fb8c937-fd05-11e6-a30e-e198ed79b70a"
 ],
 "id": "1c2cbb8d-7152-11e7-963b-b75830b20e2f",
 "distributionLists": [
  {
   "id": "c200c39f-8e17-11e5-9196-d17102d54b6d",
   "name": "Administrator Alerts",
   "campaign": null,
   "createdAt": "2015-11-18T17:13:59.489Z"
  }
 ],
 "deviceGroups": [
  {
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones",
   "filters": []
  }
 ]
}

Retrieves a single scheduled notification by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scheduled-notifications/{scheduledNotificationId}

Produces

application/json

Path Parameters

Parameter Description
scheduledNotificationId The id of the scheduled notification to retrieve.

Response

The scheduled notification response format is detailed here.

Create a Scheduled Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'timeZone': 'America/Chicago'
,
    'schedule': '0 0 1 1/1 * ? *'
,
    'messageTemplateId': '179a1e31-c52b-11e5-80ea-95f83e09f4e8'
,
    'disabled': false
,
    'name': 'Repeating Schedule'
,
    'distributionListIds': ['c200c39f-8e17-11e5-9196-d17102d54b6d'
]
,
    'deviceGroupIds': ['9fb8c937-fd05-11e6-a30e-e198ed79b70a'
]

}

begin: 
    schedule = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(schedule)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"timeZone": "America/Chicago", \
       "schedule": "0 0 1 1/1 * ? *", \
       "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8", \
       "disabled": false, \
       "name": "Repeating Schedule", \
       "distributionListIds": ["c200c39f-8e17-11e5-9196-d17102d54b6d"], \
       "deviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'timeZone': 'America/Chicago',
    'schedule': '0 0 1 1/1 * ? *',
    'messageTemplateId': '179a1e31-c52b-11e5-80ea-95f83e09f4e8',
    'disabled': false,
    'name': 'Repeating Schedule',
    'distributionListIds': ['c200c39f-8e17-11e5-9196-d17102d54b6d'],
    'deviceGroupIds': ['9fb8c937-fd05-11e6-a30e-e198ed79b70a']
}

try: 
    schedule = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(schedule)
except RequestException as e:
    print('Unexpected error!', e)
{
 "timeZone": "America/Chicago",
 "schedule": "0 0 1 1/1 * ? *",
 "permissions": ["delete", "put", "get"],
 "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8",
 "nextFireTime": "2017-07-26T06:00:00.000Z",
 "disabled": false,
 "messageTemplate": {
  "name": "Blank",
  "id": "179a1e31-c52b-11e5-80ea-95f83e09f4e8"
 },
 "name": "Repeating Schedule",
 "createdAt": "2017-07-25T15:58:33.204Z",
 "updatedAt": "2017-07-25T15:58:33.204Z",
 "distributionListIds": [
  "c200c39f-8e17-11e5-9196-d17102d54b6d"
 ],
 "deviceGroupIds": [
  "9fb8c937-fd05-11e6-a30e-e198ed79b70a"
 ],
 "id": "1c2cbb8d-7152-11e7-963b-b75830b20e2f",
 "distributionLists": [
  {
   "id": "c200c39f-8e17-11e5-9196-d17102d54b6d",
   "name": "Administrator Alerts",
   "campaign": null,
   "createdAt": "2015-11-18T17:13:59.489Z"
  }
 ],
 "deviceGroups": [
  {
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones",
   "filters": []
  }
 ]
}

Creates a new scheduled notification (limit: 3500). Once the schedule is created, it should begin firing at the time returned in the nextFireTime response property.

HTTP Request

POST /scheduled-notifications

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 scheduled notification.
timeZone String N/A A timezone such as “America/Chicago”. This list is too long to enumerate here.
schedule String N/A A Quartz cron schedule. The format is described in detail here.
disabled Boolean false A flag to indiciate whether the schedule is currently enabled/disabled.
messageTemplateId UUID N/A Which message template will be sent when the scheduled notification fires.
distribution­ListIds Array[UUID] N/A A list of optional distribution list overrides. Note, it will only override the message template settings if the distribution list ids flag is set to customizable.
device­GroupIds Array[UUID] N/A A list of optional device group overrides. Note, it will only override the message template settings if the device group ids flag is set to customizable.

Response

The scheduled notification response format is detailed here.

Update a Scheduled Notification

# Continuing with the scheduled notification
# object from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"timeZone": "America/Chicago", \
       "schedule": "0 0 1 1/1 * ? *", \
       "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8", \
       "disabled": false, \
       "name": "Repeating Schedule", \
       "distributionListIds": ["c200c39f-8e17-11e5-9196-d17102d54b6d"], \
       "deviceGroupIds": ["9fb8c937-fd05-11e6-a30e-e198ed79b70a"]}'
# Continuing with the scheduled notification
# object from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
 "timeZone": "America/Chicago",
 "schedule": "0 0 1 1/1 * ? *",
 "permissions": ["delete", "put", "get"],
 "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8",
 "nextFireTime": "2017-07-26T06:00:00.000Z",
 "disabled": false,
 "messageTemplate": {
  "name": "Blank",
  "id": "179a1e31-c52b-11e5-80ea-95f83e09f4e8"
 },
 "name": "Repeating Schedule",
 "createdAt": "2017-07-25T15:58:33.204Z",
 "updatedAt": "2017-08-11T12:51:23.843Z",
 "distributionListIds": [
  "c200c39f-8e17-11e5-9196-d17102d54b6d"
 ],
 "deviceGroupIds": [
  "9fb8c937-fd05-11e6-a30e-e198ed79b70a"
 ],
 "id": "1c2cbb8d-7152-11e7-963b-b75830b20e2f",
 "distributionLists": [
  {
   "id": "c200c39f-8e17-11e5-9196-d17102d54b6d",
   "name": "Administrator Alerts",
   "campaign": null,
   "createdAt": "2015-11-18T17:13:59.489Z"
  }
 ],
 "deviceGroups": [
  {
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones",
   "filters": []
  }
 ]
}

Updates an existing scheduled notification’s name.

HTTP Request

PUT /scheduled-notifications/{scheduledNotificationId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
scheduledNotificationId The id of the scheduled notification to update.

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the scheduled notification.
timeZone String N/A A timezone such as “America/Chicago”. This list is too long to enumerate here.
schedule String N/A A Quartz cron schedule. The format is described in detail (http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html)[here].
disabled Boolean false A flag to indiciate whether the schedule is currently enabled/disabled.
messageTemplateId UUID N/A Which message template will be sent when the scheduled notification fires.
distribution­ListIds Array[UUID] N/A A list of optional distribution list overrides. Note, it will only override the message template settings if the distribution list ids flag is set to customizable.
device­GroupIds Array[UUID] N/A A list of optional device group overrides. Note, it will only override the message template settings if the device group ids flag is set to customizable.

Response

The scheduled notification response format is detailed here.

Remove a Scheduled Notification

# Continuing with the scheduled notification
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the scheduled notification
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"ScheduledNotifications\"} 1c2cbb8d-7152-11e7-963b-b75830b20e2f"
}

Deletes an existing scheduled notification.

HTTP Request

DELETE /scheduled-notifications/{scheduledNotificationId}

Produces

application/json

Path Parameters

Parameter Description
scheduledNotificationId The id of the scheduled notification to delete.

Response

The deletion response format is detailed here.

Scheduled Notification Response

The JSON document used to represent a scheduled notification resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this scheduled notification was created.
updatedAt ISO 8601 date/time When this scheduled notification was last updated.
id String The id of this specific scheduled notification, allowing it to be manipulated or retrieved individually.
name String The scheduled notification’s 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.
timeZone String A timezone such as “America/Chicago”. This list is too long to enumerate here.
disabled Boolean A flag to indiciate whether the schedule is currently enabled/disabled.
syncState Array[Object] The endpoints’ sync state. Only applicable if fusion servers are configured and query param assoc-sync-state is true.
endpointSyncState Object The specific endpoint’s sync state. Only applicable if fusion servers are configured and query param assoc-sync-state-for-endpoint is true.
messageTemplate Object The assigned message template.
distributionLists Array[Object] The assigned distribution lists.
deviceGroups Array[Object] The assigned device groups.
messageTemplateId UUID Which message template will be sent when the scheduled notification fires.
distribution­ListIds Array[UUID] A list of optional distribution list overrides. Note, it will only override the message template settings if the distribution list ids flag is set to customizable.
device­GroupIds Array[UUID] A list of optional device group overrides. Note, it will only override the message template settings if the device group ids flag is set to customizable.

Scheduled Notification Activities

Scheduled Notification activities are the mechanism for tracking and reviewing Notifications triggered by a Scheduled Notification.

Get All Scheduled Notification Activities

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/464f2bb0-7152-11e7-963b-7317a53c5894/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/464f2bb0-7152-11e7-963b-7317a53c5894/activities" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/464f2bb0-7152-11e7-963b-7317a53c5894/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "id": "0a39087e-7158-11e7-963b-9751771222c3",
   "scheduledNotificationId": "464f2bb0-7152-11e7-963b-7317a53c5894",
   "createdAt": "2017-07-25T16:41:00.066Z",
   "status": {
    "status": "success"
   },
   "notificationId": "0a3cb1ff-7158-11e7-963b-a5de057243b8",
   "fireTime": "2017-07-25T16:41:00.014Z",
   "scheduledFireTime": "2017-07-25T16:41:00.000Z",
   "permissions": ["delete", "put", "get"]
  },
  {
   "id": "0a36be8d-7158-11e7-963b-bff3aa34d822",
   "scheduledNotificationId": "464f2bb0-7152-11e7-963b-7317a53c5894",
   "createdAt": "2017-07-25T16:41:00.051Z",
   "status": {
    "status": "pending"
   },
   "notificationId": null,
   "fireTime": "2017-07-25T16:41:00.014Z",
   "scheduledFireTime": "2017-07-25T16:41:00.000Z",
   "permissions": ["delete", "put", "get"]
  }
 ]
}

Retrieves the list of all activities recorded for the specified scheduled notification.

HTTP Request

GET /scheduled-notifications/{scheduledNotificationId}/activities

Produces

application/json

Path Parameters

Parameter Description
scheduledNotificationId The id of the Scheduled Notification for which activity information is desired.

Query Parameters

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

The scheduled notification activity response format is detailed here.

Get a Specific Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/464f2bb0-7152-11e7-963b-7317a53c5894/activities/0a39087e-7158-11e7-963b-9751771222c3"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/464f2bb0-7152-11e7-963b-7317a53c5894/activities/0a39087e-7158-11e7-963b-9751771222c3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/464f2bb0-7152-11e7-963b-7317a53c5894/activities/0a39087e-7158-11e7-963b-9751771222c3"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    activity = requests.get(url, headers=headers).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "0a39087e-7158-11e7-963b-9751771222c3",
 "scheduledNotificationId": "464f2bb0-7152-11e7-963b-7317a53c5894",
 "createdAt": "2017-07-25T16:41:00.066Z",
 "status": {
  "status": "success"
 },
 "notificationId": "0a3cb1ff-7158-11e7-963b-a5de057243b8",
 "fireTime": "2017-07-25T16:41:00.014Z",
 "scheduledFireTime": "2017-07-25T16:41:00.000Z",
 "permissions": ["delete", "put", "get"]
}

Retrieves a specific activity based the id values of the scheduled notification and activity. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /scheduled-notifications/{scheduledNotificationId}/activities/{activityId}

Produces

application/json

Path Parameters

Parameter Description
scheduledNotificationId The id of the Scheduled Notification for which activity information is desired.
activityId The id of the specific Activity of interest.

Response

The scheduled notification activity response format is detailed here.

Scheduled Notification Activity Response

The JSON document used to represent a notification activity resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this activity was created.
id String The id of this specific activity, allowing it to be manipulated or retrieved individually.
scheduledNotificationId String The id of the Scheduled Notification whose activities are being examined.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
status String Options: success, failure, validation-error, pending.
fireTime ISO 8601 date/time When the scheduled notification actually fired.
scheduledFireTime ISO 8601 date/time When the scheduled notification was supposed to fire.

Scheduled Notification Cloning

This resource is used to make a copy of the Scheduled Notification specified by id in the request path.

The only operation supported is POST.

Clone a Scheduled Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/scheduled-notifications/1c2cbb8d-7152-11e7-963b-b75830b20e2f/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "timeZone": "America/Chicago",
 "schedule": "0 0 1 1/1 * ? *",
 "permissions": [],
 "messageTemplateId": "179a1e31-c52b-11e5-80ea-95f83e09f4e8",
 "nextFireTime": "2017-07-26T06:00:00.000Z",
 "disabled": false,
 "messageTemplate": {
  "name": "Blank",
  "id": "179a1e31-c52b-11e5-80ea-95f83e09f4e8"
 },
 "name": "Repeating Schedule (Copy)",
 "createdAt": "2017-07-26T15:58:33.204Z",
 "distributionListIds": [
  "c200c39f-8e17-11e5-9196-d17102d54b6d"
 ],
 "deviceGroupIds": [
  "9fb8c937-fd05-11e6-a30e-e198ed79b70a"
 ],
 "id": "1c2cbb77-7153-11e7-96cb-b7583abc4e2f",
 "distributionLists": [
  {
   "id": "c200c39f-8e17-11e5-9196-d17102d54b6d",
   "name": "Administrator Alerts",
   "campaign": null,
   "createdAt": "2015-11-18T17:13:59.489Z"
  }
 ],
 "deviceGroups": [
  {
   "id": "9fb8c937-fd05-11e6-a30e-e198ed79b70a",
   "name": "All Phones",
   "filters": []
  }
 ]
}

Creates a copy of the specified Scheduled Notification. The name of the new copy is simply the original Scheduled Notification’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /scheduled-notifications resource and GET permission to the Scheduled Notification they wish to copy.

HTTP Request

POST /scheduled-notifications/{scheduledNotificationId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
scheduledNotificationId String The id of the Scheduled Notification to copy.

Response

The Scheduled Notification response format is detailed here.

Security Groups

A Security Group is a convenient way of organizing a named set of reusable permissions which can be assigned to multiple Users in the system. The Security Group acts to establish the relationship between its Security Group Members and Security Group Permissions. Each member of the group is implicitly granted all of the associated permissions.

Every Security Group can be assigned to any number of Users. A user can do anything which is mentioned in the permissions of any Security Groups of which they are a member, as well as any direct User Permissions assigned to them.

A single Security Group is designated a “super group”, which means that its members implicitly have every possible permission, and will thus automatically gain new permissions as they are developed along with new features in InformaCast Mobile. This group is initially named “Administrators” although you are free to rename it if you so desire. You cannot, however, delete it, nor change its superGroup status.

List All Security Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'
,
    'limit': 1

}

begin: 
    groups = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(groups)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true',
    'limit': 1
}

try: 
    groups = requests.get(url, headers=headers, params=params).json()
    print(groups)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "previous": null,
  "next": "2",
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-08-01T19:02:15.511Z",
      "id": "5a218e70-19ae-11e4-9195-3c970e7ff560",
      "superGroup": true,
      "name": "Administrators",
      "domains": [
        {
          "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
          "parentId": null,
          "name": "Root",
          "path": "/",
          "namePath": "/"
        }
      ]
    }
  ]
}

Retrieves a list of all Security Groups. (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 manipulate Security Groups.)

HTTP Request

GET /security-groups

Produces

application/json

Query Parameters

To make this example more manageable, only the first Security Group was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this Security Group belongs.

Response

The Security Group response format is detailed here.

Get a Security Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/5a218e70-19ae-11e4-9195-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'

}

begin: 
    group = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/5a218e70-19ae-11e4-9195-3c970e7ff560?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/5a218e70-19ae-11e4-9195-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true'
}

try: 
    group = requests.get(url, headers=headers, params=params).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-01T19:02:15.511Z",
  "id": "5a218e70-19ae-11e4-9195-3c970e7ff560",
  "superGroup": true,
  "name": "Administrators",
  "domains": [
    {
      "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
      "parentId": null,
      "name": "Root",
      "path": "/",
      "namePath": "/"
    }
  ]
}

Retrieves a single Security Group by its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /security-groups/{securityGroupId}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this Security Group belongs.

Response

The Security Group response format is detailed here.

Create a Security Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Students'

}

begin: 
    group = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Students"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Students'
}

try: 
    group = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-12T14:32:22.033Z",
  "id": "789c2810-222d-11e4-8f54-3c970e7ff560",
  "superGroup": false,
  "name": "Students",
  "domains": [
    {
      "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
      "parentId": null,
      "name": "Root",
      "path": "/",
      "namePath": "/"
    }
  ]
}

Creates a new Security Group. Once the group is created, permissions will need to be assigned to it, and then members.

HTTP Request

POST /security-group

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 Security Group.

Response

The Security Group response format is detailed here.

Update a Security Group

# Continuing with the security group object
# from the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/789c2810-222d-11e4-8f54-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Student Council Members"}'
# Continuing with the security group object
# from the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "id": "789c2810-222d-11e4-8f54-3c970e7ff560",
  "createdAt": "2014-08-12T14:32:22.033Z",
  "superGroup": false,
  "name": "Student Council Members",
  "domains": [
    {
      "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
      "parentId": null,
      "name": "Root",
      "path": "/",
      "namePath": "/"
    }
  ]
}

Updates an existing Security Group’s name.

HTTP Request

PUT /security-groups/{securityGroupId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group to update.

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the Security Group.

Response

The Security Group response format is detailed here.

Remove a Security Group

# Continuing with the security group object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/789c2810-222d-11e4-8f54-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the security group object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"SecurityGroups\"} 789c2810-222d-11e4-8f54-3c970e7ff560"
}

Deletes an existing Security Group.

HTTP Request

DELETE /security-groups/{securityGroupId}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group to delete.

Response

The deletion response format is detailed here.

Security Group Response

The JSON document used to represent a Security Group resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this Security Group 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 Security Group, allowing it to be manipulated or retrieved individually.
name String The Security 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.
superGroup Boolean Indicates whether this group is the “super group” whose members implicitly have all possible application permissions.

Security Groups Cloning

This resource is used to make a copy of the Security Group specified by id in the request path.

The only operation supported is POST.

Clone a Security Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/2130a0d8-c2eb-11eb-9318-558fffe32ad2/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/2130a0d8-c2eb-11eb-9318-558fffe32ad2/clone" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/2130a0d8-c2eb-11eb-9318-558fffe32ad2/clone"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.post(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "id": "93dae61a-ebd5-11eb-81b3-2ba7fd062f40",
    "name": "Command Center Admin (Copy)",
    "superGroup": false,
    "createdAt": "2021-07-23T16:46:50.609Z",
    "permissions": []
}

Creates a copy of the specified Security Group. The name of the new copy is simply the original Security Group’s name with “ (Copy)” appended. In order to perform this operation, the user must have both POST permission to the /security-groups resource and GET permission to the Security Group they wish to copy.

HTTP Request

POST /security-groups/{securityGroupId}/clone

Produces

application/json

Request Parameters

Parameter Type Description
securityGroupId String The id of the Security Group to copy.

Response

The security group response format is detailed here.

Security Group Domains

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 Security Group Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "securityGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "securityGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Security Group belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /security-groups/{securityGroupId}/domains

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Security Group belonged to when the request was made, and both were returned. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the subdomains of any Domain attached to the specified Security Group using a query parameter, and/or filter the results by matching on the Domain name:

Parameter Type Description
name String Returns only Domains whose names exactly match the supplied value.
recursive Boolean If true, in addition to Domains that are directly attached to the specified Security Group, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the security group whose domains were requested is returned under the key securityGroupId inside each domain response.

Check if a Domain contains a Security Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "securityGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Security Group Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /security-groups/{securityGroupId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group whose Domains are of interest.
id The id of the Domain you want to know whether the Security Group belongs to.

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 Domains that are directly attached to the specified Security Group, any of their subdomains will be considered.

Response

If the Security Group is part of the Domain (or its subdomains, 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 Security Group Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "securityGroupId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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 /security-groups/{securityGroupId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
securityGroupId String The id of the Security Group to be added to the Domain.

Request Parameters

Parameter Type Default Description
demote Boolean false Allow this request to proceed even if it will demote the Security Group out of a parent Domain?
id String n/a The id of the Domain to which the Security Group should be added.
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 Security Group Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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 /security-groups/{securityGroupId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
securityGroupId The id of the Security Group whose Domain should be removed.
id The id of the Domain to be removed from the Security Group.

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.

Security Group Members

A Security Group is a convenient way of organizing a named set of reusable permissions which can be assigned to multiple Users in the system. The member list is the set of users who belong to the security group, and who are thereby implicitly granted all of its Security Group Permissions.

Every security group can be assigned to any number of users. A user can do anything which is mentioned in the permissions of any security groups of which they are a member, as well as any direct User Permissions assigned to them. If the Domains feature is enabled, a user may be granted permission to act in a given domain through a security group without the user being placed directly in that domain.

List All Members

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 3,
  "partial": true,
  "next": "WyZwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJk",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "user": {
        "createdAt": "2014-08-05T17:48:03.048Z",
        "id": "a5e89e80-1cc8-11e4-8507-3c970e7ff560",
        "email": "craig.smith@acme.com",
        "name": "Craig Smith",
        "domains": [
          {
            "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
            "parentId": null,
            "name": "Root",
            "path": "/",
            "namePath": "/"
          }
        ]
      },
      "createdAt": "2014-08-12T14:53:48.882Z",
      "updatedAt": "2014-08-12T14:53:48.882Z",
      "userId": "a5e89e80-1cc8-11e4-8507-3c970e7ff560",
      "id": "821e2b20-222f-11e4-8f54-3c970e7ff560",
      "securityGroupId": "03f9a7f0-1d80-11e4-a054-3c970e7ff560"
    }
  ]
}

Retrieves the list of users that belong to the security group and thereby receive its permissions. (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 manipulate security groups.)

HTTP Request

GET /security-groups/{securityGroupId}/members

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group whose members are being enumerated.

Query Parameters

To make this example more manageable, only the first security group was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of three available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The security group member response format is detailed here.

Get a Member

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members/821e2b20-222f-11e4-8f54-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    member = JSON.parse(HTTParty.get(url, headers: headers))
    puts(member)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members/821e2b20-222f-11e4-8f54-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members/821e2b20-222f-11e4-8f54-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    member = requests.get(url, headers=headers).json()
    print(member)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-05T17:48:03.048Z",
    "id": "a5e89e80-1cc8-11e4-8507-3c970e7ff560",
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "domains": [
      {
        "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
        "parentId": null,
        "name": "Root",
        "path": "/",
        "namePath": "/"
      }
    ]
  },
  "createdAt": "2014-08-12T14:46:56.978Z",
  "updatedAt": "2014-08-12T14:53:48.882Z",
  "userId": "a5e89e80-1cc8-11e4-8507-3c970e7ff560",
  "id": "821e2b20-222f-11e4-8f54-3c970e7ff560",
  "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560"
}

Retrieves a member of the security group through the id values of the group and member entry. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /security-groups/{securityGroupId}/members/{memberId}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group in which a member is being looked up.
memberId The id of the specific member entry to be retrieved.

Response

The security group member response format is detailed here.

Add a Member

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'userId': 'a5e89e80-1cc8-11e4-8507-3c970e7ff560'

}

begin: 
    member = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(member)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"userId": "a5e89e80-1cc8-11e4-8507-3c970e7ff560"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'userId': 'a5e89e80-1cc8-11e4-8507-3c970e7ff560'
}

try: 
    member = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(member)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-08-05T17:48:03.048Z",
    "id": "a5e89e80-1cc8-11e4-8507-3c970e7ff560",
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "domains": [
      {
        "id": "69dab71b-12b2-11e8-bfe3-41154f2b6534",
        "parentId": null,
        "name": "Root",
        "path": "/",
        "namePath": "/"
      }
    ]
  },
  "createdAt": "2014-08-12T15:56:51.254Z",
  "updatedAt": "2014-08-12T16:53:48.882Z",
  "userId": "a5e89e80-1cc8-11e4-8507-3c970e7ff560",
  "id": "4619e560-2239-11e4-8f54-3c970e7ff560",
  "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560"
}

Adds a user to a security group.

HTTP Request

POST /security-groups/{securityGroupId}/members

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group to which a member is to be added.

Request Parameters

Parameter Type Default Description
userId String N/A The id of the User to add to the security group.

Response

The security group member response format is detailed here.

Remove a Member

# Continuing with the member object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/members/4619e560-2239-11e4-8f54-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the member object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"SecurityGroups\"} 4619e560-2239-11e4-8f54-3c970e7ff560"
}

Removes a user from a security group.

HTTP Request

DELETE /security-groups/{securityGroupId}/members/{memberId}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group from which a member is to be removed.
memberId The id of the specific member entry to remove.

Response

The deletion response format is detailed here.

Members Response

The JSON document used to represent a security group member resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this member was added.
updatedAt ISO 8601 date/time When this member was last updated.
id String The id of the membership record, 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.
securityGroupId String The id of the Security Group the user belongs to.
user User The User identified as a member of the security group. (Only a subset of the normal (User response is returned, containing the information most likely to be needed for displaying and working with the security group including the user’s domains if the domains feature is enabled.)
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.

Security Groups SCIM Groups

Security Group SCIM Groups connect Security Groups to SCIM Users. Every security group can be assigned to any number of scim groups. A user can do anything which is mentioned in the permissions of any security groups of which they are a member through their associated SCIM Groups, as well as any direct User Permissions assigned to them.

List All SCIM Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total":1,
  "previous":null,
  "next":null,
  "partial":false,
  "data": [
    {
      "id": "d80aa1de-8026-11eb-a543-53c5fa2d317e",
      "name": "SCIM Group",
      "memberCount": 1,
      "createdAt": "2021-03-08T15:56:28.662Z",
      "permissions": ["put","delete","get"]
    }
  ]
}

Retrieves all member SCIM Groups of this security group.

HTTP Request

GET /security-groups/{securityGroupId}/scim-groups

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group whose member SCIM Groups should be listed.

Response

The security group SCIM group response format is detailed here.

Update Security Group SCIM Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'scimGroupId': '70c0be09-6662-11eb-b962-b1e9a4e7ca6e'

}

begin: 
    sub = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(sub)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"scimGroupId": "70c0be09-6662-11eb-b962-b1e9a4e7ca6e"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'scimGroupId': '70c0be09-6662-11eb-b962-b1e9a4e7ca6e'
}

try: 
    sub = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
{
  "id": "70c0be09-6662-11eb-b962-b1e9a4e7ca6e",
  "name": "Group Name",
  "memberCount": 6,
  "createdAt": "2021-02-03T20:57:34.944Z",
  "permissions": ["put","delete","get"]
}

Create a link between a SCIM Group and a Security Group so that the member SCIM Users will receive the permissions of the security group.

HTTP Request

POST /security-groups/{securityGroupId}/scim-groups

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group to which a new SCIM group is to be added.

Request Parameters

Parameter Type Default Description
scimGroupId String N/A The id of the SCIM Group to add to the security group.

Response

The security group SCIM group response format is detailed here.

Remove Security Group SCIM Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups/d0b13a1e-67d6-11eb-bde7-a53355563835"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups/d0b13a1e-67d6-11eb-bde7-a53355563835" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/af94ef60-1d9a-11e4-a054-3c970e7ff560/scim-groups/d0b13a1e-67d6-11eb-bde7-a53355563835"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status":200,
  "message":"deleted d0b13a1e-67d6-11eb-bde7-a53355563835"
}

Removes the association between a SCIM Group and a Security Group.

HTTP Request

DELETE /security-groups/{securityGroupId}/scim-groups/{scimGroupId}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group from which the SCIM group is to be removed.
scimGroupId The id of the specific SCIM group to delete.

Response

The deletion response format is detailed here.

Security Group SCIM Groups Response

The JSON document used to represent a security group SCIM group resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this SCIM Group was created.
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.
name String The name of the SCIM Group.
memberCount Integer The number of members in the SCIM Group.

Security Group Permissions

A Security Group is a convenient way of organizing a named set of reusable permissions which can be assigned to multiple Users in the system. The member list is the set of users who belong to the security group, and who are thereby implicitly granted all of its permissions.

Permissions are required to perform any action with the InformaCast Mobile API. When validating an action that a user is trying to perform through the API, the User Permissions assigned directly to the user (through the access token which accompanies all API requests) are combined with any that come from security groups to which the user belongs.

Each permission is made up of two attributes: the spec which identifies the resource being controlled, and the verb which identifies the action (HTTP method) being permitted. For example, a permission granting the ability to read a particular User resource would use the spec /users/{userId} and a verb of get. To grant the ability to read every user, the spec would use the * wildcard character rather than a specific user id. This same pattern can also be applied with the verbs post (create), put (update), and delete. In the case of post permissions, a trailing /* is not required to give create access to a specific resource, because the id value is not assigned until after the post action is in progress.

Every security group can be assigned to any number of users. A user can do anything which is mentioned in the permissions of any security groups of which they are a member, as well as any direct User Permissions assigned to them.

When Domains are in use, Security Groups are assigned to Domains, and users who are members of the Security Group are granted the ability to act in those Domains and their subdomains. Permissions that refer to Domain-enabled resources, unless their spec values tie them to a single resource by id, are Domain scoped and will be attached to the acting Domain that was in effect when the Permision was created. This means the permission will only operate within that Domain and its subdomains.

List All Group Permissions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 15,
  "partial": true,
  "next": "WyJwYXJ0aWFsIGFjY2VzcyIsIjAzZjlhN2YwLTFkODAtMTFlNC1hMDU0LTNjOTcwZTdmZjU2MCJd",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-08-12T15:09:33.697Z",
      "verb": "get",
      "spec": "/notifications/*",
      "id": "aac90f10-2232-11e4-8f54-3c970e7ff560",
      "domainId": null,
      "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560"
    }
  ]
}

This permission means the user is able to view all Notifications that have been sent.

Retrieves the list of permissions users receive though their membership in the security group. (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 manipulate security groups.)

HTTP Request

GET /security-groups/{securityGroupId}/permissions

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the security group whose permissions are being enumerated.

Query Parameters

To make this example more manageable, only the first permission was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of fifteen available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The security group permission response format is detailed here.

Get a Group Permission

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions/aac90f10-2232-11e4-8f54-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    perm = JSON.parse(HTTParty.get(url, headers: headers))
    puts(perm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions/aac90f10-2232-11e4-8f54-3c970e7ff560" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions/aac90f10-2232-11e4-8f54-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    perm = requests.get(url, headers=headers).json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-12T15:09:33.697Z",
  "verb": "get",
  "spec": "/notifications/*",
  "id": "aac90f10-2232-11e4-8f54-3c970e7ff560",
  "domainId": null,
  "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560"
}

Retrieves a permission granted to the security group through the id values of the group and permission entry. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /security-groups/{securityGroupId}/permissions/{permissionId}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group in which a permission is being looked up.
permissionId The id of the specific permission entry to be retrieved.

Response

The security group permission response format is detailed here.

Grant a Group Permission

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'spec': '/confirmation-requests'
,
    'verb': 'post'

}

begin: 
    perm = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(perm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"spec": "/confirmation-requests", \
       "verb": "post"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'spec': '/confirmation-requests',
    'verb': 'post'
}

try: 
    perm = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-12T16:10:53.715Z",
  "verb": "post",
  "spec": "/confirmation-requests",
  "id": "3c3f3e30-223b-11e4-8f54-3c970e7ff560",
  "domainId": null,
  "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560"
}

This permission grants the group the ability to create new Confirmation Requests.

Grants a group the permission to perform a specific action on a specified resource or list of resources.

Tied Extensions

There are two pairs of extensions which are now treated by the user interface as a single concept: the iOS and Android push extensions are jointly managed as InformaCast for iOS/Android, and the macOS and Windows push extensions are jointly managed as InformaCast for Mac/Windows. Because of this, granting a permission to one of either pair will automatically grant permission to the other.

HTTP Request

POST /security-groups/{securityGroupId}/permissions

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group to which permission is being granted.

Request Parameters

Parameter Type Default Description
spec String N/A Identifies the path to the resource(s) the group is being permitted to act on.
verb String N/A Options: get post put delete. The action (HTTP method) which is to be permitted.
promote Boolean false Automatically delete any matching security group permissions attached to subdomains of the current acting Domain when creating this one?

Response

The security group permission response format is detailed here.

Update a Group Permission

# Continuing with the permission object from
# the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions/3c3f3e30-223b-11e4-8f54-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"spec": "/confirmation-requests/*", \
       "verb": "get"}'
# Continuing with the permission object from
# the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-12T15:09:33.697Z",
  "verb": "get",
  "spec": "/confirmation-requests/*",
  "id": "3c3f3e30-223b-11e4-8f54-3c970e7ff560",
  "domainId": null,
  "securityGroupId": "37b9faa0-222f-11e4-8f54-3c970e7ff560"
}

This permission grants the user the ability to view all Confirmation Requests.

Updates an existing security group permission, to change the spec or the verb, as needed.

Tied Extensions

There are two pairs of extensions which are now treated by the user interface as a single concept: the iOS and Android push extensions are jointly managed as InformaCast for iOS/Android, and the macOS and Windows push extensions are jointly managed as InformaCast for Mac/Windows. Because of this, granting or revoking a permission to one of either pair will automatically grant or revoke permission to the other.

HTTP Request

PUT /security-groups/{securityGroupId}/permissions/{permissionId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group whose permission is being altered.
permissionId The id of the specific permission to change.

Request Parameters

Parameter Type Default Description
spec String N/A Identifies the path to the resource(s) the group is being permitted to act on.
verb String N/A Options: get post put delete. The action (HTTP method) which is to be permitted.
promote Boolean false Automatically delete any matching security group permissions attached to subdomains of the current acting Domain when updating this one?

Response

The security group permission response format is detailed here.

Revoke a Group Permission

# Continuing with the permission object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/security-groups/37b9faa0-222f-11e4-8f54-3c970e7ff560/permissions/3c3f3e30-223b-11e4-8f54-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the permission object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"SecurityGroups\"} 3c3f3e30-223b-11e4-8f54-3c970e7ff560"
}

Tied Extensions

There are two pairs of extensions which are now treated by the user interface as a single concept: the iOS and Android push extensions are jointly managed as InformaCast for iOS/Android, and the macOS and Windows push extensions are jointly managed as InformaCast for Mac/Windows. Because of this, revoking a permission to one of either pair will automatically revoke permission to the other.

HTTP Request

DELETE /security-groups/{securityGroupId}/permissions/{permissionId}

Produces

application/json

Path Parameters

Parameter Description
securityGroupId The id of the Security Group whose permission is being revoked.
permissionId The id of the specific permission to revoke.

Response

The deletion response format is detailed here.

Group Permission Response

The JSON document used to represent a security group permission resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this permission was created.
domainId String Limits the maximum scope at which the permission can be applied: will be null unless Domains are enabled and the permission is domain-scoped (that is, it can match more than one domain-enabled resource, rather than referring to a specific resource by id). In those cases, for Domain-enabled resources, only those belonging to the specified Domain or its subdomains are affected by the permission.
id String The id of this specific permission, allowing it to be manipulated or retrieved individually.
permissions Array[String] Options: get put delete. What operations are possible on this permission resource itself.
securityGroupId String The id of the Security Group to which this permission applies.
spec String Identifies the path to the resource(s) the 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.

Session

Provides information about the login session associated with the access token.

This is particularly useful when your application offers an interactive login interface, because it is the way you can obtain information about the user who logged in. You will need, for example, the userId value in order to look up or create other resources associated with the user.

Get the Current Session

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/session"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/session" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/session"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "features": [],
  "providerId": "0605547e-d829-11e6-906a-bdcaa2d55966",
  "email": "road.runner@acme.com",
  "idleTimeoutCustom": false,
  "name": "Road Runner",
  "isDomainsAvailable": false,
  "isLicenseValid": true,
  "accessToken": "S35QCVBN6S6TUQKHOND=",
  "providerName": "Acme Corp",
  "providerExpiration": null,
  "idleTimeout": 30,
  "userId": "51d63c2a-a015-11e5-b60a-b3fe0dce4648"
}

Retrieves the authentication session information associated with the access token.

HTTP Request

GET /session

Produces

application/json

Response

Attribute Type Description
accessToken String The access token used to authenticate this request
userId String The id of the user associated with the session; this user’s Permissions and Security Groups are what control access to API resources for requests with this access token
providerName String The name of the provider to which the session is logged in; this defines which set of API resources are being accessed
providerId String The id of the provider to which the session is logged in
email String The email address of the user associated with the session
name String The name of the user associated with the session
features Array A list of features that are enabled.
isLicense­Valid Boolean Whether the provider to which the session is logged in has a current, valid license
idleTimeout Int The idle time (in minutes) before the session will timeout
idleTimeout­Custom Boolean Whether the user associated with the session has a custom idleTimeout value or is using the system default
isDomains­Available Boolean Will become true when the Domains feature is released
domain Object Once the administrator has chosen to use Domains, this will report the Acting Domain that was in effect for the Session request (which may have been chosen by default if the request did not specify a Domain)

Session Feature

Name Description
phoneCall Represents that the phone call extension is enabled and phone devices can be registered and calls placed
applePush Represents that the Apple push extension is enabled and Apple devices can be registered and push notifications placed
desktopNotifier Represents that the desktop notifier extension is enabled and desktop notifier devices can be registered and sent notifications
outboundCapDevice Represents that the outbound CAP device extension is enabled
outboundCap Represents that the outbound CAP extension is enabled
webexTeams Represents that the Cisco Webex Teams extension is enabled
inboundCap Represents that the inbound CAP extension is enabled
twitter Represents that the Twitter extension is enabled
facebook Represents that the Facebook extension is enabled
firebasePush Represents that the Android/Firebase extension is enabled and Android/Firebase devices can be registered and push notifications placed
dnd Represents that the do not disturb extension is enabled and can be used
inboundRss Represents that the inbound RSS extension is enabled and can be used
reporting Represents that the reporting extension is enabled and the reporting extension can be used
conferenceCall Represents that the conference call extension is enabled and conference call collaboration groups can be used
email Represents that the email extension is enabled and email devices can be registered and sent messages to
sms Represents that the SMS extension is enabled and SMS devices can be registered and sent messages to
msteamsChat Represents the Microsoft Teams chat extension is enabled
msteamsCall Represents the Microsoft Teams call extension is enabled
fusion Represents that fusion mode is enabled
failover Represents that failover mode is enabled
domains Represents that domain usage is enabled
cucmEnabled Represents that integration with Cisco Unified Communications Manager is enabled
gms Represents that GMS mode is enabled
demo Represents that the provider’s account is in demo mode

Expired Sessions

{
    "status": 401,
    "type": "expired-token",
    "message": "Expired Token"
}

If your token has expired (this only applies to normal, interactively-obtained tokens; permanent application tokens do not expire, which is why they are needed for unattended applications), you will receive an error response indicating this fact.

Log Out

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/session"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/session" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/session"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "Session deleted"
}

When you want to explicitly end a session, and ensure that the authentication token can no longer be used, you simply delete the Session resource.

HTTP Request

DELETE /session

Produces

application/json

Response

The deletion response format is detailed here.

{
  "status": 401,
  "type": "unauthorized",
  "message": "Unauthorized"
}

Subsequent attempts to use the authentication token will yield authentication errors; the user needs to log in again and obtain a new one.

Settings

Settings is the area where you can globally control certain preferences such as preferred timezones and preferred locales.

Get Settings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/settings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {

}

begin: 
    list = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(list)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/settings?" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/settings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {

}

try: 
    list = requests.get(url, headers=headers, params=params).json()
    print(list)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["put", "get"],
  "preferredLocale": "en-US",
  "preferredTimezone": "America/Los_Angeles"
}

Fetches the current global settings. This is not a paginated result.

HTTP Request

GET /settings

Produces

application/json

Response

The settings response format is detailed here.

Update Settings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/settings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'preferredLocale': 'en-US'
,
    'preferredTimezone': 'America/Los_Angeles'

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/settings" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"preferredLocale": "en-US", \
       "preferredTimezone": "America/Los_Angeles"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/settings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'preferredLocale': 'en-US',
    'preferredTimezone': 'America/Los_Angeles'
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["put", "get"],
  "preferredLocale": "en-US",
  "preferredTimezone": "America/Los_Angeles"
}

Modifies the global provider settings.

HTTP Request

PUT /settings

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
preferredLocale String en-US The preferred locale of the provider. Examples include en-US, es, fr, etc. This list is too long to enumerate here.
preferredTimezone String UTC The preferred timezone of the provider. Examples include America/Los_Angeles, America/Chicago, etc. This list is too long to enumerate here.

Response

The settings response format is detailed here.

Settings Response

The JSON document used to represent a settings resource has the following content:

Attribute Type Description
preferredLocale String The preferred locale of the provider. Examples include en-US, es, fr, etc. This list is too long to enumerate here.
preferredTimezone String The preferred timezone of the provider. Examples include America/Los_Angeles, America/Chicago, etc. This list is too long to enumerate here.
permissions Array[String] Options: get put. Which operations are possible on this resource, given the authentication token being used to access the API.

Sites

Sites are meant to be used in tandem with Site Roles to determine the recipients to be used by a Scenario. Sites have recipients associated with each individual site role, which may include Areas of Interest, Collaboration Groups, Device Groups (if in Fusion mode), Distribution Lists, and Users. Based on the site chosen when a notification is sent, recipients will be selected based on site roles associated with scenario notifications.

List Sites

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'
,
    'includeExternalSources': 'true'
,
    'includeBuildingTotal': 'true'
,
    'includeBuildings': 'true'
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites?includeDomains=true&includeExternalSources=true&includeBuildingTotal=true&includeBuildings=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true',
    'includeExternalSources': 'true',
    'includeBuildingTotal': 'true',
    'includeBuildings': 'true',
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "name": "East Campus",
   "createdAt": "2019-02-26T19:25:33.040Z",
   "latitude": null,
   "longitude": null,
   "recipients": [
    {
     "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
     "collaborationGroups": [],
     "createdAt": "2019-02-26T19:30:29.502Z",
     "distributionListIds": [
      "c6e970a8-39fc-11e9-8c83-f91be012dad7"
     ],
     "deviceGroupIds": [],
     "areasOfInterest": [],
     "id": "f9ae9275-39fc-11e9-8c83-1ddb12dc3e43",
     "siteRoleId": "724030a9-2b09-11e9-9638-578e7c043866",
     "collaborationGroupIds": [],
     "distributionLists": [
      {
       "id": "c6e970a8-39fc-11e9-8c83-f91be012dad7",
       "name": "East Campus - Security",
       "campaign": null,
       "createdAt": "2019-02-26T19:29:04.324Z"
      }
     ],
     "userIds": [
      "1e9758e5-73ff-11e8-9b03-239fcdffd087"
     ],
     "deviceGroups": [],
     "areaOfInterestIds": [],
     "users": [
      {
       "email": "john.doe@example.com",
       "name": "John Doe",
       "type": "regular",
       "loadSourceId": null,
       "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
       "createdAt": "2018-06-19T20:27:00.189Z",
       "lock": null,
       "idleTimeout": 90
      }
     ]
    },
    {
     "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
     "collaborationGroups": [
      {
       "id": "f55f3583-39fc-11e9-8c83-a7bc2f883b6a",
       "name": "East Campus Digital Signs",
       "type": "outbound-cap",
       "createdAt": "2019-02-26T19:30:22.271Z"
      }
     ],
     "createdAt": "2019-02-26T19:30:29.502Z",
     "distributionListIds": [
      "c2efd4c0-39fc-11e9-8c83-bbc0c28d718a"
     ],
     "deviceGroupIds": [],
     "areasOfInterest": [],
     "id": "f9ae9274-39fc-11e9-8c83-eddd6d9694b4",
     "siteRoleId": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
     "collaborationGroupIds": [
      "f55f3583-39fc-11e9-8c83-a7bc2f883b6a"
     ],
     "distributionLists": [
      {
       "id": "c2efd4c0-39fc-11e9-8c83-bbc0c28d718a",
       "name": "East Campus - Employees",
       "campaign": null,
       "createdAt": "2019-02-26T19:28:57.655Z"
      }
     ],
     "userIds": [],
     "deviceGroups": [],
     "areaOfInterestIds": [],
     "users": []
     "externalSources": [
      {
       "externalId": "228473",
       "type": "zoom"
      }
     ],
     "buildingCount": 1,
     "buildings": [
      {
        "id": "3eb28fab-4a72-11ed-ba69-05db1c8d216f",
        "name": "Building 1"
      }
     ]
    }
   ],
   "domains": [
     {
       "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
       "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
       "name": "North Campus",
       "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
       "namePath": "/North Campus/"
     }
   ],
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Gets a list of all sites 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 sites allows administrators to decide which users can configure recipients of scenarios.)

HTTP Request

GET /sites

Produces

application/json

Query Parameters

To make this example more manageable, only the first site was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeBuildings Boolean If true, include the list of Site Buildings in this Site.
includeBuildingTotal Boolean If true, include the number of Site Buildings in this Site.
includeDomains Boolean If true, include the list of Domains to which each site belongs.
includeExternalSources Boolean If true, include the list of external sources linked to this site (via Zoom or Kontakt.io integration)
requireEmergencyBuildings Boolean If true, returns sites that contain at least one emergency building

Response

The site response format is detailed here.

Get a Site

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'

}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true'
}

try: 
    role = requests.get(url, headers=headers, params=params).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "name": "East Campus",
 "createdAt": "2019-02-26T19:25:33.040Z",
 "latitude": null,
 "longitude": null,
 "recipients": [
  {
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "collaborationGroups": [],
   "createdAt": "2019-02-26T19:30:29.502Z",
   "distributionListIds": [
    "c6e970a8-39fc-11e9-8c83-f91be012dad7"
   ],
   "deviceGroupIds": [],
   "areasOfInterest": [],
   "id": "f9ae9275-39fc-11e9-8c83-1ddb12dc3e43",
   "siteRoleId": "724030a9-2b09-11e9-9638-578e7c043866",
   "collaborationGroupIds": [],
   "distributionLists": [
    {
     "id": "c6e970a8-39fc-11e9-8c83-f91be012dad7",
     "name": "East Campus - Security",
     "campaign": null,
     "createdAt": "2019-02-26T19:29:04.324Z"
    }
   ],
   "userIds": [
    "1e9758e5-73ff-11e8-9b03-239fcdffd087"
   ],
   "deviceGroups": [],
   "areaOfInterestIds": [],
   "users": [
    {
     "email": "john.doe@example.com",
     "name": "John Doe",
     "type": "regular",
     "loadSourceId": null,
     "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
     "createdAt": "2018-06-19T20:27:00.189Z",
     "lock": null,
     "idleTimeout": 90
    }
   ],
  },
  {
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "collaborationGroups": [
    {
     "id": "f55f3583-39fc-11e9-8c83-a7bc2f883b6a",
     "name": "East Campus Digital Signs",
     "type": "outbound-cap",
     "createdAt": "2019-02-26T19:30:22.271Z"
    }
   ],
   "createdAt": "2019-02-26T19:30:29.502Z",
   "distributionListIds": [
    "c2efd4c0-39fc-11e9-8c83-bbc0c28d718a"
   ],
   "deviceGroupIds": [],
   "areasOfInterest": [],
   "id": "f9ae9274-39fc-11e9-8c83-eddd6d9694b4",
   "siteRoleId": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
   "collaborationGroupIds": [
    "f55f3583-39fc-11e9-8c83-a7bc2f883b6a"
   ],
   "distributionLists": [
    {
     "id": "c2efd4c0-39fc-11e9-8c83-bbc0c28d718a",
     "name": "East Campus - Employees",
     "campaign": null,
     "createdAt": "2019-02-26T19:28:57.655Z"
    }
   ],
   "userIds": [],
   "deviceGroups": [],
   "areaOfInterestIds": [],
   "users": [],
   "externalSources": [
    {
     "externalId": "228473",
     "type": "zoom"
    }
   ],
   "buildingCount": 1,
   "buildings": [
    {
      id: "3eb28fab-4a72-11ed-ba69-05db1c8d216f",
      name: "Building 1"
    }
   ]
  }
 ],
 "domains": [
   {
    "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
    "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
    "name": "North Campus",
    "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
    "namePath": "/North Campus/"
   }
 ],
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Retrieves a single site by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /sites/{siteId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site to retrieve.

Query Parameters

Parameter Type Description
includeBuildings Boolean If true, include the list of Site Buildings in this Site.
includeBuildingTotal Boolean If true, include the number of Site Buildings in this Site.
includeDomains Boolean If true, include the list of Domains to which this site belongs.
includeExternalSources Boolean If true, include the list of external sources linked to this site (via Zoom or Kontakt.io integration)
requireEmergencyBuildings Boolean If true, and the site contains no emergency buildings a 404 will be returned instead of the site

Response

The site response format is detailed here.

Create a Site

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'North Campus'

}

begin: 
    role = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "North Campus"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'North Campus'
}

try: 
    role = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "name": "North Campus",
 "id": "5742fff6-3ade-11e9-81d7-c730f23d2548",
 "createdAt": "2019-02-27T22:23:43.267Z",
 "latitude": null,
 "longitude": null,
 "recipients": [],
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Create a new site.

HTTP Request

POST /sites

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 site’s unique name. Maximum of 140 characters.
recipients Array[Object] [] The array of site roles and their recipients in the form of a json object. More information can be found here.

Response

The site response format is detailed here.

Update a Site

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/bf5f4f46-2bb5-11e9-8180-5fe10bc30744" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Employees and Contractors"}'
# Continuing with the site object from the
# previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "name": "South Campus",
 "createdAt": "2019-02-26T19:25:33.040Z",
 "latitude": null,
 "longitude": null,
 "recipients": [
  {
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "collaborationGroups": [],
   "createdAt": "2019-02-28T14:53:56.509Z",
   "distributionListIds": [
    "c6e970a8-39fc-11e9-8c83-f91be012dad7"
   ],
   "deviceGroupIds": [],
   "areasOfInterest": [],
   "id": "ac504599-3b68-11e9-81d7-5744d5bbf9e1",
   "siteRoleId": "724030a9-2b09-11e9-9638-578e7c043866",
   "collaborationGroupIds": [],
   "distributionLists": [
    {
     "id": "c6e970a8-39fc-11e9-8c83-f91be012dad7",
     "name": "East Campus - Security",
     "campaign": null,
     "createdAt": "2019-02-26T19:29:04.324Z"
    }
   ],
   "userIds": [
    "1e9758e5-73ff-11e8-9b03-239fcdffd087"
   ],
   "deviceGroups": [],
   "areaOfInterestIds": [],
   "users": [
    {
     "email": "sarah.murphy@singlewire.com",
     "name": "Sarah Murphy",
     "type": "regular",
     "loadSourceId": null,
     "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
     "createdAt": "2018-06-19T20:27:00.189Z",
     "lock": null,
     "idleTimeout": 90
    }
   ]
  },
  {
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "collaborationGroups": [
    {
     "id": "f55f3583-39fc-11e9-8c83-a7bc2f883b6a",
     "name": "East Campus Digital Signs",
     "type": "outbound-cap",
     "createdAt": "2019-02-26T19:30:22.271Z"
    }
   ],
   "createdAt": "2019-02-28T14:53:56.509Z",
   "distributionListIds": [
    "c2efd4c0-39fc-11e9-8c83-bbc0c28d718a"
   ],
   "deviceGroupIds": [],
   "areasOfInterest": [],
   "id": "ac50459a-3b68-11e9-81d7-a737ad52ba39",
   "siteRoleId": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
   "collaborationGroupIds": [
    "f55f3583-39fc-11e9-8c83-a7bc2f883b6a"
   ],
   "distributionLists": [
    {
     "id": "c2efd4c0-39fc-11e9-8c83-bbc0c28d718a",
     "name": "East Campus - Employees",
     "campaign": null,
     "createdAt": "2019-02-26T19:28:57.655Z"
    }
   ],
   "userIds": [],
   "deviceGroups": [],
   "areaOfInterestIds": [],
   "users": []
  }
 ],
 "domains": [
   {
    "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
    "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
    "name": "North Campus",
    "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
    "namePath": "/North Campus/"
   }
 ],
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Updates an existing site.

HTTP Request

PUT /sites/{siteId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site to update.

Request Parameters

Parameter Type Default Description
id String The id of the site, for efficient retrieval or manipulation of the site.
name String N/A The site’s unique name. Maximum of 140 characters.
recipients Array[Object] The array of site roles and their recipients in the form of a json object. More information can be found here.

Response

The site response format is detailed here.

Remove a Site

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/f6138825-3ad9-11e9-81d7-f104ab17fd00" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  5742fff6-3ade-11e9-81d7-c730f23d2548"
}

Deletes an existing site.

HTTP Request

DELETE /sites/{siteId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site to delete.

Response

The deletion response format is detailed here.

Site Role Recipients

Site Role Recipients are associated with each individual site, and store information about recipients based on a site role, which can be later used on a scenario notification.

Site Role Recipients are created as part of a site, and are nested inside of an array in site resources. They include Areas of Interest, Collaboration Groups, Device Groups (fusion only), Distribution Lists, and Users.

Attribute Type Description
areasOfInterest Array[Area of Interest] The areas of interest in this group of site role recipients.
areaOfInterestIds Array[String] The list of ids for areas of interest in this group of site role recipients.
collaborationGroups Array[Collaboration Group] The collaboration groups in this group of site role recipients.
collabroationGroupIds Array[String] The list of ids for collaboration groups in this group of site role recipients.
createdAt ISO 8601 date/time When this group of site role recipients was created.
deviceGroups Array[Device Group] The device groups (fusion only) in this group of site role recipients.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) in this group of site role recipients.
distributionLists Array[Distribution List] The distribution lists in this group of site role recipients.
distributionListIds Array[String] The list of ids for distribution lists in this group of site role recipients.
id String The id of the site role’s recipients.
siteId String The id of the site with which the recipients are associated.
users Array[User] The users in this group of site role recipients.
userIds Array[String] The list of ids for users in this group of site role recipients.

Request Parameters

Parameter Type Default Description
areaOfInterestIds Array[String] The list of ids for areas of interest in this group of site role recipients.
collabroationGroupIds Array[String] The list of ids for collaboration groups in this group of site role recipients.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) in this group of site role recipients.
distributionListIds Array[String] The list of ids for distribution lists in this group of site role recipients.
id String The id of the site, for efficient retrieval or manipulation of the site.
siteId String The id of the site with which the recipients are associated.
userIds Array[String] The list of ids for users in this group of site role recipients.

Site Response

The JSON document used to represent a Site resource has the following content:

Attribute Type Description
buildingCount Number The number of buildings in this Site. Returned when the includeBuildingTotal query parameter is true.
buildings Array[Site Building] The list of buildings in this Site. Returned when the includeBuildings query parameter is true.
createdAt ISO 8601 date/time When this site 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 site belongs.
externalSources Array[External Source] The list of external sources for the site. Returned when the includeExternalSources query parameter is true.
id String The id of the site, for efficient retrieval or manipulation of the site.
latitude number The latitude of the geographic average of any Site Buildings with known locations.
longitude number The longitude of the geographic average of any Site Buildings with known locations.
name String The site’s unique name.
recipients Array[Object] The array of site roles and their recipients in the form of a json object. More information can be found here.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.

Include External Sources Response

The JSON document used to represent an External Source for a Site, Building, Floor, or Zone when the includeExternalSources query parameter is true has the following content:

Attribute Type Description
type String The type of the external source, such as “zoom” or “kontaktio-wearable-panic-button”
externalId String the id of the external source according to the entity providing that external source. For a Zoom Site, this is the ID of that Site in Zoom, for example.

Sites Management

Sites Management is a limited API to bulk-edit Sites, generally used with integrations to handle imports. While this API is public, it is relatively volatile and the structure of the requests is subject to change.

Get Import Status

Gets a list of the current import status for various integrations (Kontakt.io, Zoom, etc).

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites-management"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites-management" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites-management"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "import": {
  "zoom": {
   "imported": true,
   "importDate": "2022-08-08T21:24:19.967Z"
  },
  "kontaktioWearablePanicButton": {
   "imported": true,
   "importDate": "2022-10-10T23:17:05.260Z"
  }
 },
 "data": []
}

Gets the status of the Zoom and Kontakt.io integrations. imported is true if at least one site has been imported and has an externalSource, with the importDate being the date of that externalSource being created.

HTTP Request

GET /sites-management

Produces

application/json

Response

The sites-management response format is detailed here.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites-management"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'action': 'unlink-sources'
,
    'sources': 'zoom'

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites-management" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"action": "unlink-sources", \
       "sources": "zoom"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites-management"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'action': 'unlink-sources',
    'sources': 'zoom'
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "message": "Unlink sources successful",
 "permissions": ["get"]
}

Unlink all sites with the given source. Removes the externalSource record for the site. Does not delete or modify the site in any other way.

HTTP Request

POST /sites-management

Produces

application/json

Query Parameters

Parameter Type Description
action String Must be “unlink-sources”
sources Array[String] List of sources to remove, like [“zoom”]

Response

The sites-management response format is detailed here.

Import

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites-management"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'action': 'import'
,
    'externalSites': [{
        'name': 'Singlewire'
,
        'source': 'kontaktio-wearable-panic-button'
,
        'externalId': '194795'
,
        'matchedResource': null
,
        'importedResource': null
,
        'buildings': [{
            'name': 'Singlewire HQ'
,
            'source': 'kontaktio-wearable-panic-button'
,
            'externalId': '194994'
,
            'matchedResource': null
,
            'importedResource': null
,
            'floors': [{
                'name': 'First Floor'
,
                'source': 'kontaktio-wearable-panic-button'
,
                'externalId': '194237'
,
                'matchedResource': null
,
                'importedResource': null
,
                'zones': [{
                    'name': 'Living Room'
,
                    'source': 'kontaktio-wearable-panic-button'
,
                    'externalId': '195034'
,
                    'matchedResource': null
,
                    'importedResource': null

}

]

}

]

}

]

}

]

}

begin: 
    puts(JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites-management" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"action": "import", \
       "externalSites": [{"name": "Singlewire", \
         "source": "kontaktio-wearable-panic-button", \
         "externalId": "194795", \
         "matchedResource": null, \
         "importedResource": null, \
         "buildings": [{"name": "Singlewire HQ", \
           "source": "kontaktio-wearable-panic-button", \
           "externalId": "194994", \
           "matchedResource": null, \
           "importedResource": null, \
           "floors": [{"name": "First Floor", \
             "source": "kontaktio-wearable-panic-button", \
             "externalId": "194237", \
             "matchedResource": null, \
             "importedResource": null, \
             "zones": [{"name": "Living Room", \
               "source": "kontaktio-wearable-panic-button", \
               "externalId": "195034", \
               "matchedResource": null, \
               "importedResource": null}]}]}]}]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites-management"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'action': 'import',
    'externalSites': [{
        'name': 'Singlewire',
        'source': 'kontaktio-wearable-panic-button',
        'externalId': '194795',
        'matchedResource': null,
        'importedResource': null,
        'buildings': [{
            'name': 'Singlewire HQ',
            'source': 'kontaktio-wearable-panic-button',
            'externalId': '194994',
            'matchedResource': null,
            'importedResource': null,
            'floors': [{
                'name': 'First Floor',
                'source': 'kontaktio-wearable-panic-button',
                'externalId': '194237',
                'matchedResource': null,
                'importedResource': null,
                'zones': [{
                    'name': 'Living Room',
                    'source': 'kontaktio-wearable-panic-button',
                    'externalId': '195034',
                    'matchedResource': null,
                    'importedResource': null
}
]
}
]
}
]
}
]
}

try: 
    print(requests.post(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "message": "Import successful",
 "permissions":["get"]
}

Import the supplied externalSites. Note that this is in a very particular format that we only expect to be used via the UI.

HTTP Request

POST /sites-management

Produces

application/json

Query Parameters

Parameter Type Description
action String Must be “import”
externalSites Array[Object] List of sites to import. Site contains a nested list of buildings, which has a nested list of floors, which has a nested list of zones. Each ‘level’ can have a matchedResource and importedResource. matchedResource is the ID of the internal resource to link with the external resource. importedResource is the ID of the internal resource that has already been linked to the external resource.

Response

The sites-management response format is detailed here.

Sites Management Response

The JSON document used to represent a Sites Management response has the following content:

Attribute Type Description
import Object Dictionary object containing the import info for zoom and kontaktioWearablePanicButton. Has a boolean for imported and a date for importDate. Only returned on a GET.
message String Message from the server on whether the action was successful. Only returned in a POST.
permissions Array[String] Options: get post. Which operations are possible on this resource, given the authentication token being used to access the API. Not returned on GET.

Site Recipients

Site Recipients are the Site Roles associated with a given site. A site used to have all site roles automatically assigned to it, so the endpoint was created to prevent automatic site role creation. The data returned here is functionally equivalent to the data returned in the recipients object in the Site endpoint. Note: passing recipients to the Site endpoint functions as it did previously in which recipients can be added to the Site.

List Site Recipients

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "collaborationGroups": [],
   "createdAt": "2019-02-26T19:30:29.502Z",
   "distributionListIds": [
    "c6e970a8-39fc-11e9-8c83-f91be012dad7"
   ],
   "deviceGroupIds": [],
   "areasOfInterest": [],
   "id": "f9ae9275-39fc-11e9-8c83-1ddb12dc3e43",
   "siteRoleId": "724030a9-2b09-11e9-9638-578e7c043866",
   "collaborationGroupIds": [],
   "distributionLists": [
    {
     "id": "c6e970a8-39fc-11e9-8c83-f91be012dad7",
     "name": "East Campus - Security",
     "campaign": null,
     "createdAt": "2019-02-26T19:29:04.324Z"
    }
   ],
   "userIds": [
    "1e9758e5-73ff-11e8-9b03-239fcdffd087"
   ],
   "deviceGroups": [],
   "areaOfInterestIds": [],
   "users": [
    {
     "email": "john.doe@example.com",
     "name": "John Doe",
     "type": "regular",
     "loadSourceId": null,
     "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
     "createdAt": "2018-06-19T20:27:00.189Z",
     "lock": null,
     "idleTimeout": 90
    }
   ]
  }
 ]
}

Gets a list of all site recipients in use for the specified site. (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 /sites/{siteId}/recipients

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the site recipient belongs to.

Query Parameters

To make this example more manageable, only the first site recipient was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The site recipient response format is detailed here.

Get a Site Recipient

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients/f9ae9275-39fc-11e9-8c83-1ddb12dc3e43"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients/f9ae9275-39fc-11e9-8c83-1ddb12dc3e43" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients/f9ae9275-39fc-11e9-8c83-1ddb12dc3e43"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "collaborationGroups": [],
 "createdAt": "2019-02-26T19:30:29.502Z",
 "distributionListIds": [
  "c6e970a8-39fc-11e9-8c83-f91be012dad7"
 ],
 "deviceGroupIds": [],
 "areasOfInterest": [],
 "id": "f9ae9275-39fc-11e9-8c83-1ddb12dc3e43",
 "siteRoleId": "724030a9-2b09-11e9-9638-578e7c043866",
 "collaborationGroupIds": [],
 "distributionLists": [
  {
   "id": "c6e970a8-39fc-11e9-8c83-f91be012dad7",
   "name": "East Campus - Security",
   "campaign": null,
   "createdAt": "2019-02-26T19:29:04.324Z"
  }
 ],
 "userIds": [
  "1e9758e5-73ff-11e8-9b03-239fcdffd087"
 ],
 "deviceGroups": [],
 "areaOfInterestIds": [],
 "users": [
  {
   "email": "john.doe@example.com",
   "name": "John Doe",
   "type": "regular",
   "loadSourceId": null,
   "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
   "createdAt": "2018-06-19T20:27:00.189Z",
   "lock": null,
   "idleTimeout": 90
  }
 ]
}

Retrieves a single site recipient by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /sites/{siteId}/recipients/{siteRecipientId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the site recipient belongs to.
siteRecipientId The id of the site to retrieve.

Response

The site recipient response format is detailed here.

Create a Site Recipient

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'siteRoleId': 'a97d4e1d-18b2-11ed-b3a2-43ed4b226a26'

}

begin: 
    role = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"siteRoleId": "a97d4e1d-18b2-11ed-b3a2-43ed4b226a26"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'siteRoleId': 'a97d4e1d-18b2-11ed-b3a2-43ed4b226a26'
}

try: 
    role = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "collaborationGroups": [],
 "createdAt": "2019-02-26T19:30:29.502Z",
 "distributionListIds": [],
 "deviceGroupIds": [],
 "areasOfInterest": [],
 "id": "b441f043-18b9-11ed-b3a2-0b5a888c68e9",
 "siteRoleId": "a97d4e1d-18b2-11ed-b3a2-43ed4b226a26",
 "collaborationGroupIds": [],
 "distributionLists": [],
 "userIds": [],
 "deviceGroups": [],
 "areaOfInterestIds": [],
 "users": []
}

Create a new site recipient.

HTTP Request

POST /sites/{siteId}/recipients

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the site recipient belongs to.

Request Parameters

Parameter Type Default Description
id String The id of the site roles’ recipients record, for efficient retrieval or manipulation of the site role’s recipients record.
siteRoleId String The id of the site role with which the recipients are associated.
areaOfInterestIds Array[String] The list of ids for areas of interest in this group of site role recipients.
collabroationGroupIds Array[String] The list of ids for collaboration groups in this group of site role recipients.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) in this group of site role recipients.
distributionListIds Array[String] The list of ids for distribution lists in this group of site role recipients.
userIds Array[String] The list of ids for users in this group of site role recipients.

Response

The site recipient response format is detailed here.

Update a Site Recipient

# Continuing with the site and recipient objects
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/recipients/f9ae9275-39fc-11e9-8c83-1ddb12dc3e43" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"siteRoleId": "a97d4e1d-18b2-11ed-b3a2-43ed4b226a26", \
       "distributionListIds": [], \
       "userIds": ["1e9758e5-73ff-11e8-9b03-239fcdffd087", "d9e2d16d-ec1d-11ec-8579-0d23e4601999"]}'
# Continuing with the site and recipient objects
# from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "collaborationGroups": [],
 "createdAt": "2019-02-26T19:30:29.502Z",
 "distributionListIds": [],
 "deviceGroupIds": [],
 "areasOfInterest": [],
 "id": "f9ae9275-39fc-11e9-8c83-1ddb12dc3e43",
 "siteRoleId": "a97d4e1d-18b2-11ed-b3a2-43ed4b226a26",
 "collaborationGroupIds": [],
 "distributionLists": [],
 "userIds": [
  "1e9758e5-73ff-11e8-9b03-239fcdffd087",
  "d9e2d16d-ec1d-11ec-8579-0d23e4601999"
 ],
 "deviceGroups": [],
 "areaOfInterestIds": [],
 "users": [
  {
   "email": "john.doe@example.com",
   "name": "John Doe",
   "type": "regular",
   "loadSourceId": null,
   "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
   "createdAt": "2018-06-19T20:27:00.189Z",
   "lock": null,
   "idleTimeout": 90
  },
  {
   "email": "jane.doe@example.com",
   "name": "Jane Doe",
   "type": "regular",
   "loadSourceId": null,
   "id": "d9e2d16d-ec1d-11ec-8579-0d23e4601999",
   "createdAt": "2018-06-19T20:27:00.189Z",
   "lock": null,
   "idleTimeout": 90
  }
 ]
}

Updates an existing site recipient record.

HTTP Request

PUT /sites/{siteId}/recipients/{siteRecipientId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site to update.
siteRecipientId The id of the site recipient to update.

Request Parameters

Parameter Type Default Description
id String The id of the site roles’ recipients record, for efficient retrieval or manipulation of the site role’s recipients record.
siteRoleId String The id of the site role with which the recipients are associated.
areaOfInterestIds Array[String] The list of ids for areas of interest in this group of site role recipients.
collabroationGroupIds Array[String] The list of ids for collaboration groups in this group of site role recipients.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) in this group of site role recipients.
distributionListIds Array[String] The list of ids for distribution lists in this group of site role recipients.
userIds Array[String] The list of ids for users in this group of site role recipients.

Response

The site recipient response format is detailed here.

Remove a Site Recipient

# Continuing with the site and recipient objects
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/f6138825-3ad9-11e9-81d7-f104ab17fd00/recipients/f9ae9275-39fc-11e9-8c83-1ddb12dc3e43" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site and recipient objects
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  f9ae9275-39fc-11e9-8c83-1ddb12dc3e43"
}

Deletes an existing site recipient record.

HTTP Request

DELETE /sites/{siteId}/recipients/{siteRecipientId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site to delete.
siteRecipientId The id of the site recipient to delete.

Response

The deletion response format is detailed here.

Request Parameters

Parameter Type Default Description
id String The id of the site roles’ recipients record, for efficient retrieval or manipulation of the site role’s recipients record.
siteId String The id of the site with which the recipients are associated.
siteRoleId String The id of the site role with which the recipients are associated.
areaOfInterestIds Array[String] The list of ids for areas of interest in this group of site role recipients.
collabroationGroupIds Array[String] The list of ids for collaboration groups in this group of site role recipients.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) in this group of site role recipients.
distributionListIds Array[String] The list of ids for distribution lists in this group of site role recipients.
userIds Array[String] The list of ids for users in this group of site role recipients.

Site Recipient Response

The JSON document used to represent a Site Recipient resource has the following content:

Attribute Type Description
id String The id of the site roles’ recipients record.
siteId String The id of the site with which the recipients are associated.
createdAt ISO 8601 date/time When this group of site role recipients was created.
areasOfInterest Array[Area of Interest] The areas of interest in this group of site role recipients.
areaOfInterestIds Array[String] The list of ids for areas of interest in this group of site role recipients.
collaborationGroups Array[Collaboration Group] The collaboration groups in this group of site role recipients.
collabroationGroupIds Array[String] The list of ids for collaboration groups in this group of site role recipients.
deviceGroups Array[Device Group] The device groups (fusion only) in this group of site role recipients.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) in this group of site role recipients.
distributionLists Array[Distribution List] The distribution lists in this group of site role recipients.
distributionListIds Array[String] The list of ids for distribution lists in this group of site role recipients.
users Array[User] The users in this group of site role recipients.
userIds Array[String] The list of ids for users in this group of site role recipients.

Site Buildings

Site Buildings are meant to increase granularity of a given location from where a notification can originate from. Since a site can have multiple buildings, pinpointing where a notification is initiated from can improve response times in the event of an emergency.

List Site Buildings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'include-external-sources': 'true'
,
    'include-floors': 'true'
,
    'include-floor-total': 'true'
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings?include-external-sources=true&include-floors=true&include-floor-total=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'include-external-sources': 'true',
    'include-floors': 'true',
    'include-floor-total': 'true',
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "id": "a6afa1eb-0392-11ed-9c86-6989ae6bd013",
   "name": "East Campus",
   "createdAt": "2022-02-26T19:25:33.040Z",
   "floorCount": 0,
   "floors": [],
   "externalSources": [],
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "addressLine1": null,
   "addressLine2": null,
   "city": null,
   "state": null,
   "postalCode": null,
   "country": null,
   "latitude": null,
   "longitude": null,
   "primaryPhone": null,
   "emergency": false,
   "respondingPsap": null,
   "preferredPsapNumber": null,
   "fccId": null,
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Gets a list of all site buildings for a given site 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 sites allows administrators to decide which users can configure recipients of scenarios.)

HTTP Request

GET /sites/{siteId}/buildings

Produces

application/json

Query Parameters

To make this example more manageable, only the first site building was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeExternalSources Boolean If true, include the external sources of the site building.
includeFloors Boolean If true, include the site building floors of the site building.
includeFloorTotal Boolean If true, include the number of site building floors which the building contains.
includeParentNames Boolean If true, include siteName in the response.

Response

The site building response format is detailed here.

Get a Site Building

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    building = JSON.parse(HTTParty.get(url, headers: headers))
    puts(building)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    building = requests.get(url, headers=headers).json()
    print(building)
except RequestException as e:
    print('Unexpected error!', e)
{
    "siteId": "68e70d51-e75d-11ec-93fe-914fcd30779c",
    "id": "372c92c8-18d2-11ed-b0b8-55fd00a55370",
    "name": "Example Site Building",
    "createdAt": "2022-08-10T17:31:06.622Z",
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "state": null,
    "postalCode": null,
    "country": null,
    "latitude": null,
    "longitude": null,
    "primaryPhone": null,
    "emergency": false,
    "respondingPsap": null,
    "preferredPsapNumber": null,
    "fccId": null,
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Retrieves a single site building by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the building belongs to.
buildingId The id of the site building.

Query Parameters

Parameter Type Description
includeExternalSources Boolean If true, include the external sources of the site building.
includeFloors Boolean If true, include the site building floors of the site building.
includeFloorTotal Boolean If true, include the number of site building floors which the building contains.
includeParentNames Boolean If true, include siteName in the response.

Response

The site building response format is detailed here.

Create a Site Building

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Brand New Building'
,
    'type': 'LBBY'

}

begin: 
    building = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(building)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Brand New Building", \
       "type": "LBBY"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Brand New Building',
    'type': 'LBBY'
}

try: 
    building = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(building)
except RequestException as e:
    print('Unexpected error!', e)
{
    "siteId": "68e70d51-e75d-11ec-93fe-914fcd30779c",
    "id": "7310aff0-18d4-11ed-b0b8-2114a6835db5",
    "name": "Brand New Building",
    "createdAt": "2022-08-10T17:47:06.096Z",
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "state": null,
    "postalCode": null,
    "country": null,
    "latitude": null,
    "longitude": null,
    "primaryPhone": null,
    "emergency": false,
    "respondingPsap": null,
    "preferredPsapNumber": null,
    "fccId": null,
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Create a new site building.

HTTP Request

POST /sites/{siteId}/buildings

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the building belongs to.

Request Parameters

Parameter Type Default Description
acceptRapid­SosEula boolean false If true, attests that this user is accepting the end-user license agreement for RapidSOS services. This must be done by one user before a building can be configured with emergency set to true.
addressLine1 String null The street address of the building.
addressLine2 String null Additional address details, such as suite number.
city String null The city (or town, village, etc.) of the building’s address.
country String null The country of the building’s address.
emergency Boolean false Automatically notify emergency services when emergency scenarios are sent for this building? (The emergency calling feature must be enabled for your organization before you can send a true value here.)
fccId String null When emergency is true, must hold the ID that the FCC assigned to the PSAP responsible for responding to emergencies at this building. This should begin with a two letter state abbreviation followed by an underscore.
latitude Number N/A This value is ignored unless skipAddressValidation is true, when it must contain the geographic latitude of the building.
longitude Number N/A This value is ignored unless skipAddressValidation is true, when it must contain the geographic longitude of the building.
name String N/A The sites building’s unique name. Maximum of 140 characters.
postalCode String null The ZIP or postal code of the building’s address.
preferred­PsapNumber String null When emergency is true, must hold the phone number of the PSAP responsible for responding to emergencies at this building.
primaryPhone String null The primary phone number associated with the building; will be required for emergency buildings.
responding­Psap String null When emergency is true, must hold the PSAP responsible for responding to emergencies at this building.
skip­Address­Validation boolean false This should only be used when there is a problem with the Google Maps data for a building which prevents a stable submission with validation. When true, the exact address values submitted will be stored for the building address; they must be correct and include the actual building longitude and latitude.
state String null The state or province of the building’s address.

If any address fields are present, then all fields other than addressLine2, emergency, and primaryPhone are required.

If emergency is true, then all fields other than addressLine2 are required.

Response

The site building response format is detailed here.

Update a Site Building

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/buildings/b321c52b-064b-11ea-9265-f333e562b36b" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "The Penthouse"}'
# Continuing with the site object from the
# previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "siteId": "68e70d51-e75d-11ec-93fe-914fcd30779c",
    "id": "372c92c8-18d2-11ed-b0b8-55fd00a55370",
    "name": "The Penthouse",
    "createdAt": "2022-08-10T17:31:06.622Z",
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "state": null,
    "postalCode": null,
    "country": null,
    "latitude": null,
    "longitude": null,
    "primaryPhone": null,
    "emergency": false,
    "respondingPsap": null,
    "preferredPsapNumber": null,
    "fccId": null,
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Updates an existing site building.

HTTP Request

PUT /sites/{siteId}/buildings/{buildingId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the building belongs to.
buildingId The id of the site building.

Request Parameters

Parameter Type Default Description
acceptRapid­SosEula boolean false If true, attests that this user is accepting the end-user license agreement for RapidSOS services. This must be done by one user before a building can be configured with emergency set to true.
addressLine1 String null The street address of the building.
addressLine2 String null Additional address details, such as suite number.
city String null The city (or town, village, etc.) of the building’s address.
country String null The country of the building’s address.
emergency Boolean false Automatically notify emergency services when emergency scenarios are sent for this building? (The emergency calling feature must be enabled for your organization before you can send a true value here.)
fccId String null When emergency is true, must hold the ID that the FCC assigned to the PSAP responsible for responding to emergencies at this building. This should begin with a two letter state abbreviation followed by an underscore.
latitude Number N/A This value is ignored unless skipAddressValidation is true, when it must contain the geographic latitude of the building.
longitude Number N/A This value is ignored unless skipAddressValidation is true, when it must contain the geographic longitude of the building.
name String N/A The sites building’s unique name. Maximum of 140 characters.
postalCode String null The ZIP or postal code of the building’s address.
preferred­PsapNumber String null When emergency is true, must hold the phone number of the PSAP responsible for responding to emergencies at this building.
primaryPhone String null The primary phone number associated with the building; will be required for emergency buildings.
responding­Psap String null When emergency is true, must hold the PSAP responsible for responding to emergencies at this building.
skip­Address­Validation boolean false This should only be used when there is a problem with the Google Maps data for a building which prevents a stable submission with validation. When true, the exact values submitted will be stored for the building address; they must be correct and include the actual building longitude and latitude.
state String null The state or province of the building’s address.

If any address fields are present, then all fields other than addressLine2, emergency, and primaryPhone are required.

If emergency is true, then all fields other than addressLine2 are required.

Response

The site building response format is detailed here.

Remove a Site Building

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted b321c52b-064b-11ea-9265-f333e562b36b"
}

Deletes an existing site building.

HTTP Request

DELETE /sites/{siteId}/buildings/{buildingId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the building belongs to.
buildingId The id of the site building.

Response

The deletion response format is detailed here.

Site Building Response

The JSON document used to represent a Site Building resource has the following content:

Attribute Type Description
addressLine1 String The street address of the building.
addressLine2 String Additional address details, such as suite number.
city String The city (or town, village, etc.) of the building’s address.
country String The country of the building’s address.
createdAt ISO 8601 date/time When this site building was created.
emergency Boolean Automatically notify emergency services when emergency scenarios are sent for this building?
external­Sources Array[External Source] The list of external sources in this Site Building. Returned if the includeExternalSources query parameter was true.
fccId String When emergency is true, holds the ID that the FCC assigned to the PSAP responsible for responding to emergencies at this building. This should begin with a two letter state abbreviation followed by an underscore.
floorCount Number The number of Site Building Floors in this Site Building. Returned if the include&shy;FloorTotal query parameter was true.
floors Array[Site Building Floor] The list of Site Building Floors in this Site Building. Returned if the includeFloors query parameter was true.
id UUID The id of the site building, for efficient retrieval or manipulation of the site building.
latitude Number The geographic latitude of the building (calculated by geocoding when address information is supplied).
longitude Number The geographic longitude of the building (calculated by geocoding when address information is supplied).
name String The site building floor’s unique 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.
postalCode String The ZIP or postal code of the building’s address.
preferred­PsapNumber String When emergency is true, holds the phone number of the PSAP responsible for responding to emergencies at this building.
primaryPhone String The primary phone number associated with the building; will be required for emergency buildings.
siteId UUID The ID of the site to which this building belongs.
responding­Psap String When emergency is true, holds the PSAP responsible for responding to emergencies at this building.
siteName String The name of the site to which this building belongs, present only when the includeParentNames query parameter was true.
state String The state or province of the building’s address.

Site Building External Sources

Site Building External Sources are intended to represent an InformaCast site building being linked to an external entity to facilitate integration workflows, such as Zoom or Kontakt.io.

List Site Building External Sources

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/external-sources?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "updatedAt": "2022-08-08T21:24:19.967Z",
   "permissions": [
    "delete",
    "get"
   ],
   "name": "Building 1",
   "source": "zoom",
   "externalId": "SDFSDFxcfvkjsHJFDKF325234",
   "id": "7713aa2f-1760-11ed-9083-1dc243401jkj",
   "siteId": "7712238e-1760-11ed-9083-238bkjld3",
   "buildingId": "3eae9809-4a72-11ed-ba69-c7f2bbe20104",
   "createdAt": "2022-08-08T21:24:19.967Z"
  }
 ]
}

Gets a list of all external sources for the given site building.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/externalSources

Produces

application/json

Query Parameters

To make this example more manageable, only the first site building external source was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The external source response format is detailed here.

Get a Site Building External Source

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkj"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkj" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkj"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "updatedAt": "2022-08-08T21:24:19.967Z",
 "permissions": [
  "delete",
  "get"
 ],
 "name": "Building 1",
 "source": "zoom",
 "externalId": "SDFSDFxcfvkjsHJFDKF325235",
 "id": "7713aa2f-1760-11ed-9083-1dc243401jkj",
 "siteId": "7712238e-1760-11ed-9083-238bkjld3",
 "buildingId": "3eae9809-4a72-11ed-ba69-c7f2bbe20104",
 "createdAt": "2022-08-08T21:24:19.967Z"
}

Retrieves a single site building external source by id. Since this is not a list request, there is no pagination wrapper around the result. Note that this is by ID, not external ID.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
buildingId The id of the site building
siteId The id of the site
externalSourceId The id of the external source to retrieve. Not the external ID!

Response

The site building external source response format is detailed here.

Remove a Site Building External Source

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkj" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  7713aa2f-1760-11ed-9083-1dc243401jkj"
}

Deletes an existing site building external source.

HTTP Request

DELETE /sites/{siteId}/buildings/{buildingId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
buildingId The id of the site building with the external source to delete.
externalSourceId The id of the external source to delete. Not the external ID!
siteId The id of the site with the external source to delete.

Response

The deletion response format is detailed here.

Site Building Floors

Site Building Floors are meant to increase granularity of a given location from where a notification can originate from. Since a site building can have multiple floors, pinpointing where a notification is initiated from can improve response times in the event of an emergency.

List Site Building Floors

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'include-external-sources': 'true'
,
    'include-zones': 'true'
,
    'include-zone-total': 'true'
,
    'include-zone-boundaries': 'true'
,
    'include-binary-urls': 'true'
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors?include-external-sources=true&include-zones=true&include-zone-total=true&include-zone-boundaries=true&include-binary-urls=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'include-external-sources': 'true',
    'include-zones': 'true',
    'include-zone-total': 'true',
    'include-zone-boundaries': 'true',
    'include-binary-urls': 'true',
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "id": "a6afa1eb-0392-11ed-9c86-6989ae6bd013",
   "name": "East Campus - Lobby",
   "type": "LBBY",
   "createdAt": "2022-02-26T19:25:33.040Z",
   "zoneCount": 0,
   "zones": [],
   "externalSources": [],
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
   "imageOrigins": {
       "type": "MultiPoint",
       "coordinates": [
         [
           -89.382141742,
           43.074601708
         ],
         [
           -89.386384997,
           43.074731023
         ]
       ]
   },
   "boundary": {
       "type": "Polygon",
       "coordinates": [
         [
           [
             -89.382946405,
             43.074609545
           ],
           [
             -89.384311649,
             43.073745507
           ],
           [
             -89.385548148,
             43.074723186
           ],
           [
             -89.38430092,
             43.075830154
           ],
           [
             -89.382946405,
             43.074609545
           ]
         ]
       ]
   },
   "floorPlanImageFiles": [
        {
          "fileName": "lobbyfloorplan.jpeg",
           "size": 89528,
           "contentType": "image/jpeg",
           "metadata": {
               "width": 900,
               "chroma": {
                   "numChannels": 3,
                   "colorSpaceType": "YCbCr"
               },
               "height": 900,
               "dimension": {
                   "imageOrientation": "Normal",
                   "pixelAspectRatio": 1.0,
                   "verticalPixelSize": 0.26458332,
                   "horizontalPixelSize": 0.26458332
               },
               "compression": {
                   "lossless": false,
                   "compressionTypeName": "JPEG",
                   "numProgressiveScans": 1}},
           "url": ""
        }
      ],
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Gets a list of all site building floors for a given site building 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 sites allows administrators to decide which users can configure recipients of scenarios.)

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/floors

Produces

application/json

Query Parameters

To make this example more manageable, only the first site building was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The InformaCast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeExternalSources Boolean If true, include the external sources of the site building floor.
includeParentNames Boolean If true, include siteName and buildingName in the response.
includeZones Boolean If true, include the zones of the site building floor.
includeZoneTotal Boolean If true, include the number of site building floor zones which the floor contains.
includeZoneBoundaries Boolean If true, include the boundary of all zones returned by includeZones
includeBinaryUrls Boolean If true, include signed CloudFront URLs for the floor plan image in the response when available.

Response

The site building floor response format is detailed here.

Get a Site Building Floor

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/372c92c8-18d2-11ed-b0b8-55fd00a55370"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'include-zones': 'true'
,
    'include-zone-total': 'true'
,
    'include-zone-boundaries': 'true'
,
    'include-binary-urls': 'true'

}

begin: 
    floor = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(floor)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/372c92c8-18d2-11ed-b0b8-55fd00a55370?include-zones=true&include-zone-total=true&include-zone-boundaries=true&include-binary-urls=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/372c92c8-18d2-11ed-b0b8-55fd00a55370"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'include-zones': 'true',
    'include-zone-total': 'true',
    'include-zone-boundaries': 'true',
    'include-binary-urls': 'true'
}

try: 
    floor = requests.get(url, headers=headers, params=params).json()
    print(floor)
except RequestException as e:
    print('Unexpected error!', e)
{
    "siteId": "68e70d51-e75d-11ec-93fe-914fcd30779c",
    "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
    "id": "372c92c8-18d2-11ed-b0b8-55fd00a55370",
    "name": "Example Site Building Floor",
    "type": "FL",
    "floorPlanImageFiles": [{
        "fileName": "examplefloorplan.jpeg",
        "size": 89528,
        "contentType": "image/jpeg",
        "metadata": {
            "width": 900,
            "chroma": {
                "numChannels": 3,
                "colorSpaceType": "YCbCr"
            },
            "height": 900,
            "dimension": {
                "imageOrientation": "Normal",
                "pixelAspectRatio": 1.0,
                "verticalPixelSize": 0.26458332,
                "horizontalPixelSize": 0.26458332
            },
            "compression": {
                "lossless": false,
                "compressionTypeName": "JPEG",
                "numProgressiveScans": 1
            }
        },
        "url": ""
    }],
    "imageOrigins": {
       "type": "MultiPoint",
       "coordinates": [
         [
           -89.382141742,
           43.074601708
         ],
         [
           -89.386384997,
           43.074731023
         ]
       ]
    },
    "boundary": {
       "type": "Polygon",
       "coordinates": [
         [
           [
             -89.382946405,
             43.074609545
           ],
           [
             -89.384311649,
             43.073745507
           ],
           [
             -89.385548148,
             43.074723186
           ],
           [
             -89.38430092,
             43.075830154
           ],
           [
             -89.382946405,
             43.074609545
           ]
         ]
       ]
    },
    "zoneCount": 1,
    "zones": [
      {
        "id": "3acfa610-4c22-11ee-baa8-21a3f3c72fcd",
        "name": "lobby",
        "type": "LBBY",
        "boundary": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -89.384013924,
                43.074699671
              ],
              [
                -89.38511363,
                43.074762371
              ],
              [
                -89.384574506,
                43.074962213
              ],
              [
                -89.384013924,
                43.074699671
              ]
            ]
          ]
        }
      }
    ],
    "createdAt": "2022-08-10T17:31:06.622Z",
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Retrieves a single site building floor by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/floors/{floorId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site building the floor belongs to
floorId The id of the site building floor

Query Parameters

Parameter Type Description
includeExternalSources Boolean If true, include the external sources of the site building floor.
includeParentNames Boolean If true, include siteName and buildingName in the response.
includeZones Boolean If true, include the zones of the site building floor.
includeZoneTotal Boolean If true, include the number of site building floor zones which the floor contains.
includeZoneBoundaries Boolean If true, include the boundary of all zones returned by includeZones
includeBinaryUrls Boolean If true, include signed CloudFront URLs for the floor plan image in the response when available.

Response

The site building floor response format is detailed here.

Create a Site Building Floor

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Brand New Floor'
,
    'type': 'LBBY'

}

begin: 
    floor = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(floor)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Brand New Floor", \
       "type": "LBBY"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Brand New Floor',
    'type': 'LBBY'
}

try: 
    floor = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(floor)
except RequestException as e:
    print('Unexpected error!', e)
{
    "siteId": "68e70d51-e75d-11ec-93fe-914fcd30779c",
    "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
    "id": "7310aff0-18d4-11ed-b0b8-2114a6835db5",
    "name": "Brand New Floor",
    "type": "LBBY",
    "floorPlanImageFiles": [],
    "imageOrigins": null,
    "boundary": null,
    "createdAt": "2022-08-10T17:47:06.096Z",
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Create a new site building floor.

HTTP Request

POST /sites/{siteId}//buildings/{buildingId}floors

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site building the floor belongs to

Request Parameters

Parameter Type Default Description
name String N/A The site building floor’s unique name. Maximum of 140 characters.
type String FL The type of floor. Maximum of 4 characters.
floorPlanImage File N/A A JPG/JPEG, PNG, or GeoTIFF file of up to 20mb. Non-GeoTIFF images will also require imageOrigins to be provided.
imageOrigins JSON N/A The geometry property of a GeoJSON MultiPoint object containing two points, representing the lower-left and upper-right placement of the image on a map. Requires floorPlanImage.
boundary JSON N/A The geometry property of a GeoJSON Polygon object containing a single polygon, representing the outer boundary of the floor plan. Requires imageOrigins.

Response

The site building response format is detailed here.

Update a Site Building Floor

# Continuing with the site and floor objects
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/372c92c8-18d2-11ed-b0b8-55fd00a55370" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "The Penthouse", \
       "type": 'PH'}'
# Continuing with the site and floor objects
# from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "siteId": "68e70d51-e75d-11ec-93fe-914fcd30779c",
    "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
    "id": "372c92c8-18d2-11ed-b0b8-55fd00a55370",
    "name": "The Penthouse",
    "type": "FL",
    "floorPlanImageFiles": [],
    "boundary": null,
    "imageOrigins": null,
    "createdAt": "2022-08-10T17:31:06.622Z",
    "permissions": [
        "put",
        "delete",
        "get"
    ]
}

Updates an existing site building floor.

HTTP Request

PUT /sites/{siteId}/buildings/{buildingId}/floors/{floorId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site building the floor belongs to
floorId The id of the site building floor

Request Parameters

Parameter Type Default Description
name String N/A The site building floor’s unique name. Maximum of 140 characters.
type String FL The type of floor. Maximum of 4 characters.
floorPlanImage File N/A A JPG/JPEG, PNG, or GeoTIFF file of up to 20mb. Non-GeoTIFF images will also require imageOrigins to be provided.
imageOrigins JSON N/A The geometry property of a GeoJSON MultiPoint object containing two points, representing the lower-left and upper-right placement of the image on a map. Requires image.
boundary JSON N/A The geometry property of a GeoJSON Polygon object containing a single polygon, representing the outer boundary of the floor plan. Requires imageOrigins.

Response

The site building floor response format is detailed here.

Remove a Site Building Floor

# Continuing with the site and building objects
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/68e70d51-e75d-11ec-93fe-914fcd30779c/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/372c92c8-18d2-11ed-b0b8-55fd00a55370" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site and building objects
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted 372c92c8-18d2-11ed-b0b8-55fd00a55370"
}

Deletes an existing site building floor.

HTTP Request

DELETE /sites/{siteId}/buildings/{buildingId}/floors/{floorId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site building the floor belongs to
floorId The id of the site building floor

Response

The deletion response format is detailed here.

Site Building Floor Response

The JSON document used to represent a Site Building Floor resource has the following content:

Attribute Type Description
buildingId UUID The ID of the building to which this floor belongs.
buildingName String The name of the building to which this floor belongs, present only when the includeParentNames query parameter was true.
type String The type of floor. Maximum of 4 characters.
createdAt ISO 8601 date/time When this site building floor was created.
externalSources Array[External Source] List of external sources for this site building floor. Returned if the includeExternalSources query parameter was true.
id UUID The id of the site building floor, for efficient retrieval or manipulation of the site building floor.
name String The site building floor’s unique 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.
siteId UUID The ID of the site to which this floor belongs.
siteName String The name of the site to which this floor belongs, present only when the includeParentNames query parameter was true.
type String The type of floor. Maximum of 4 characters.
zoneCount Number The number of site building floor zones in this site building floor. Returned if the includeZoneTotal query parameter was true.
zones Array[Site Building Floor Zone] List of the site building floor zones in this site building floor. Returned if the includeZones query parameter was true.
floorPlanImageFiles Array[Object] An array containing up to two JSON objects representing floor plan image data. If a GeoTIFF is uploaded, the array will contain a converted JPEG first, followed by the original GeoTIFF. If includeBinaryURls is checked, will also include the CloudFront URL.
imageOrigins JSON A GeoJSON MultiPoint object as saved, representing the lower left and upper right pinned location of the image on a map.
boundary JSON A GeoJSON Polygon object as saved, representing the outer boundary of the floor plan.

Site Building Floor External Sources

Site Building Floor External Sources are intended to represent an InformaCast site building floor being linked to an external entity to facilitate integration workflows, such as Zoom or Kontakt.io.

List Site Building Floor External Sources

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/external-sources?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "updatedAt": "2022-08-08T21:24:19.967Z",
   "permissions": [
    "delete",
    "get"
   ],
   "name": "Floor 1",
   "source": "zoom",
   "externalId": "SDFSDFxcfvkjsHJFDKF325235",
   "id": "7713aa2f-1760-11ed-9083-1dc243401jkq",
   "siteId": "7712238e-1760-11ed-9083-238bkjld3",
   "buildingId": "3eae9809-4a72-11ed-ba69-c7f2bbe20104",
   "floorId": "3eae9809-4a72-11ed-ba69-c7f2bbe20105",
   "createdAt": "2022-08-08T21:24:19.967Z"
  }
 ]
}

Gets a list of all external sources for the given site building.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/externalSources

Produces

application/json

Query Parameters

To make this example more manageable, only the first site building floor external source was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The external source response format is detailed here.

Get a Site Building Floor External Source

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkq"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkq" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkq"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "updatedAt": "2022-08-08T21:24:19.967Z",
 "permissions": [
  "delete",
  "get"
 ],
 "name": "Floor 1",
 "source": "zoom",
 "externalId": "SDFSDFxcfvkjsHJFDKF325235",
 "id": "7713aa2f-1760-11ed-9083-1dc243401jkq",
 "siteId": "7712238e-1760-11ed-9083-238bkjld3",
 "buildingId": "3eae9809-4a72-11ed-ba69-c7f2bbe20104",
 "floorId": "3eae9809-4a72-11ed-ba69-c7f2bbe20105",
 "createdAt": "2022-08-08T21:24:19.967Z"
}

Retrieves a single site building floor external source by id. Since this is not a list request, there is no pagination wrapper around the result. Note that this is by ID, not external ID.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
buildingId The id of the site building
floorId The id of the site building floor
siteId The id of the site
externalSourceId The id of the external source to retrieve. Not the external ID!

Response

The site building floor external source response format is detailed here.

Remove a Site Building Floor External Source

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkq" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  7713aa2f-1760-11ed-9083-1dc243401jkq"
}

Deletes an existing site building external source.

HTTP Request

DELETE /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
buildingId The id of the site building with the external source to delete.
externalSourceId The id of the external source to delete. Not the external ID!
floorId The id of the site building floor with the external source to delete.
siteId The id of the site with the external source to delete.

Response

The deletion response format is detailed here.

Site Building Floor Zones

Site Building Floor Zones are meant to increase granularity of a given location from where a notification can originate from. Since a site building floor can have multiple zones, pinpointing where a notification is initiated from can improve response times in the event of an emergency.

List Site Building Floor Zones

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'include-external-sources': 'true'
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones?include-external-sources=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'include-external-sources': 'true',
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
   "id": "aac3caa4-0392-11ed-9c86-aff5c203e1f4",
   "name": "Front Desk",
   "type": "LBBY",
   "floorId": "a6afa1eb-0392-11ed-9c86-6989ae6bd013",
   "createdAt": "2022-02-26T19:25:33.040Z",
   "externalSources": [],
   "boundary": {
     "type": "Polygon",
     "coordinates": [
       [
         [
           -89.384013924,
           43.074699671
         ],
         [
           -89.38511363,
           43.074762371
         ],
         [
           -89.384574506,
           43.074962213
         ],
         [
           -89.384013924,
           43.074699671
         ]
       ]
     ]
   },
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Gets a list of all site floor zones for a given site 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 /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zones

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site buidling the floor belongs to.
floorId The id of the site building floor the zone belongs to.

Query Parameters

Parameter Description
includeExternalSources If true, include the external sources of the site building floor zone.
includeParentNames Boolean

To make this example more manageable, only the first site building floor zone was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The site building floor zone response format is detailed here.

Get a Site Building Floor Zone

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones/aac3caa4-0392-11ed-9c86-aff5c203e1f4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'include-external-sources': 'true'

}

begin: 
    zone = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(zone)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones/aac3caa4-0392-11ed-9c86-aff5c203e1f4?include-external-sources=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones/aac3caa4-0392-11ed-9c86-aff5c203e1f4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'include-external-sources': 'true'
}

try: 
    zone = requests.get(url, headers=headers, params=params).json()
    print(zone)
except RequestException as e:
    print('Unexpected error!', e)
{
 "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
 "id": "aac3caa4-0392-11ed-9c86-aff5c203e1f4",
 "name": "Front Desk",
 "type": "LBBY",
 "floorId": "a6afa1eb-0392-11ed-9c86-6989ae6bd013",
 "createdAt": "2022-02-26T19:25:33.040Z",
 "externalSources": [],
 "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -89.384013924,
          43.074699671
        ],
        [
          -89.38511363,
          43.074762371
        ],
        [
          -89.384574506,
          43.074962213
        ],
        [
          -89.384013924,
          43.074699671
        ]
      ]
    ]
 },
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Retrieves a single site building floor zone by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zones/{zoneId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site buidling the floor belongs to.
floorId The id of the site building floor the zone belongs to.

Query Parameters

Parameter Description
includeExternalSources If true, include the external sources of the site building floor zone.
includeParentNames Boolean

Response

The site building floor zone response format is detailed here.

Create a Site Building Floor Zone

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Lecture Hall'
,
    'type': 'RM'

}

begin: 
    zone = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(zone)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lecture Hall", \
       "type": "RM"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Lecture Hall',
    'type': 'RM'
}

try: 
    zone = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(zone)
except RequestException as e:
    print('Unexpected error!', e)
{
 "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
 "id": "aac3caa4-0392-11ed-9c86-aff5c203e1f4",
 "name": "Lecture Hall",
 "type": "RM",
 "floorId": "a6afa1eb-0392-11ed-9c86-6989ae6bd013",
 "createdAt": "2022-02-26T19:25:33.040Z",
 "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -89.384013924,
          43.074699671
        ],
        [
          -89.38511363,
          43.074762371
        ],
        [
          -89.384574506,
          43.074962213
        ],
        [
          -89.384013924,
          43.074699671
        ]
      ]
    ]
 },
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Create a new site building floor zone.

HTTP Request

POST /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zones

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site buidling the floor belongs to.
floorId The id of the site building floor the zone belongs to.

Request Parameters

Parameter Type Default Description
name String N/A The site’s unique name. Maximum of 140 characters.
type String RM The type of area the zone is referring to.
boundary JSON N/A The geometry property of a GeoJSON Polygon object containing a single polygon, representing the outer boundary of the room. The parent floor must have a boundary.

Response

The site building floor zone response format is detailed here.

Update a Site Building Floor Zone

# Continuing with the site, building, floor
# and zone objects from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones/aac3caa4-0392-11ed-9c86-aff5c203e1f4" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lecture Hall A", \
       "type": "UNIT"}'
# Continuing with the site, building, floor
# and zone objects from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "siteId": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "buildingId": "b321c52b-064b-11ea-9265-f333e562b36b",
 "id": "aac3caa4-0392-11ed-9c86-aff5c203e1f4",
 "name": "Lecture Hall A",
 "type": "UNIT",
 "floorId": "a6afa1eb-0392-11ed-9c86-6989ae6bd013",
 "createdAt": "2022-02-26T19:25:33.040Z",
 "boundary": {
     "type": "Polygon",
     "coordinates": [
       [
         [
           -89.384013924,
           43.074699671
         ],
         [
           -89.38511363,
           43.074762371
         ],
         [
           -89.384574506,
           43.074962213
         ],
         [
           -89.384013924,
           43.074699671
         ]
       ]
     ]
  },
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Updates an existing site building floor zone.

HTTP Request

PUT /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zones/{zoneId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site buidling the floor belongs to.
floorId The id of the site building floor the zone belongs to.

Request Parameters

Parameter Type Default Description
id String N/A The id of the zone, for efficient retrieval or manipulation of the zone.
name String N/A The site’s unique name. Maximum of 140 characters.
type String RM The type of area the zone is referring to.
boundary JSON N/A The geometry property of a GeoJSON Polygon object containing a single polygon, representing the outer boundary of the room. The parent floor must have a boundary.

Response

The site building floor zone response format is detailed here.

Remove a Site Building Floor Zone

# Continuing with the site, building, floor
# and zone objects from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/b321c52b-064b-11ea-9265-f333e562b36b/floors/a6afa1eb-0392-11ed-9c86-6989ae6bd013/zones/aac3caa4-0392-11ed-9c86-aff5c203e1f4" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site, building, floor
# and zone objects from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  aac3caa4-0392-11ed-9c86-aff5c203e1f4"
}

Deletes an existing site building floor zone.

HTTP Request

DELETE /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zones/{zoneId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site the floor belongs to.
buildingId The id of the site building the floor belongs to.
floorId The id of the site building floor the zone belongs to.

Response

The deletion response format is detailed here.

Site Building Floor Zone Response

The JSON document used to represent a Site resource has the following content:

Attribute Type Description
buildingId UUID The ID of the building to which this zone belongs.
buildingName String The name of the building to which this zone belongs, present only when the includeParentNames query parameter was true.
createdAt ISO 8601 date/time When this site was created.
externalSources Array[External Source] List of the external sources for this site building floor zone. Returned if the includeExternalSources query parameter was true.
floorId UUID The ID of the floor to which this zone belongs.
floorName String The name of the floor to which this zone belongs, present only when the includeParentNames query parameter was true.
id UUID The id of the zone, for efficient retrieval or manipulation of the zone.
name String The site’s unique name.
type String The type of area the zone is referring to.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
siteId UUID The ID of the site to which this zone belongs.
siteName String The name of the site to which this zone belongs, present only when the includeParentNames query parameter was true.
boundary JSON A GeoJSON Polygon object as saved, representing the outer boundary of the room.

Site Building Floor Zone External Sources

Site Building Floor Zone External Sources are intended to represent an InformaCast site building floor zone being linked to an external entity to facilitate integration workflows, such as Zoom or Kontakt.io.

List Site Building Floor Zone External Sources

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/zones/3eae9809-4a72-11ed-ba69-c7f2bbe20106/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/zones/3eae9809-4a72-11ed-ba69-c7f2bbe20106/external-sources?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/zones/3eae9809-4a72-11ed-ba69-c7f2bbe20106/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "updatedAt": "2022-08-08T21:24:19.967Z",
   "permissions": [
    "delete",
    "get"
   ],
   "name": "Room 1",
   "source": "zoom",
   "externalId": "SDFSDFxcfvkjsHJFDKF325236",
   "id": "7713aa2f-1760-11ed-9083-1dc243401jkx",
   "siteId": "7712238e-1760-11ed-9083-238bkjld3",
   "buildingId": "3eae9809-4a72-11ed-ba69-c7f2bbe20104",
   "floorId": "3eae9809-4a72-11ed-ba69-c7f2bbe20105",
   "zoneId": "3eae9809-4a72-11ed-ba69-c7f2bbe20106",
   "createdAt": "2022-08-08T21:24:19.967Z"
  }
 ]
}

Gets a list of all external sources for the given site building floor zone.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zone/{zoneId}/externalSources

Produces

application/json

Query Parameters

To make this example more manageable, only the first site building floor zone external source was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The external source response format is detailed here.

Get a Site Building Floor Zone External Source

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/zones/3eae9809-4a72-11ed-ba69-c7f2bbe20106/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkx"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/zones/3eae9809-4a72-11ed-ba69-c7f2bbe20106/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkx" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/zones/3eae9809-4a72-11ed-ba69-c7f2bbe20106/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkx"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "updatedAt": "2022-08-08T21:24:19.967Z",
 "permissions": [
  "delete",
  "get"
 ],
 "name": "Floor 1",
 "source": "zoom",
 "externalId": "SDFSDFxcfvkjsHJFDKF325235",
 "id": "7713aa2f-1760-11ed-9083-1dc243401jkj",
 "siteId": "7712238e-1760-11ed-9083-238bkjld3",
 "buildingId": "3eae9809-4a72-11ed-ba69-c7f2bbe20104",
 "floorId": "3eae9809-4a72-11ed-ba69-c7f2bbe20105",
 "zoneId": "3eae9809-4a72-11ed-ba69-c7f2bbe20106",
 "createdAt": "2022-08-08T21:24:19.967Z"
}

Retrieves a single site building floor zone external source by id. Since this is not a list request, there is no pagination wrapper around the result. Note that this is by ID, not external ID.

HTTP Request

GET /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zones/{zoneId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
buildingId The id of the site building
floorId The id of the site building floor
siteId The id of the site
externalSourceId The id of the external source to retrieve. Not the external ID!
zoneId The id of the zone

Response

The site building floor zone external source response format is detailed here.

Remove a Site Building Floor Zone External Source

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/buildings/3eae9809-4a72-11ed-ba69-c7f2bbe20104/floors/3eae9809-4a72-11ed-ba69-c7f2bbe20105/zones/3eae9809-4a72-11ed-ba69-c7f2bbe20106/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkx" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  7713aa2f-1760-11ed-9083-1dc243401jkx"
}

Deletes an existing site building external source.

HTTP Request

DELETE /sites/{siteId}/buildings/{buildingId}/floors/{floorId}/zones/{zoneId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
buildingId The id of the site building with the external source to delete.
externalSourceId The id of the external source to delete. Not the external ID!
floorId The id of the site building floor with the external source to delete.
siteId The id of the site with the external source to delete.
zoneId The id of the zone with the external source to delete.

Response

The deletion response format is detailed here.

Site Domains

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 Site Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "siteId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "siteId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Site belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /sites/{siteId}/domains

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the Site whose associated Domains are to be listed.

Query Parameters

In this example, there were a total of 2 Domains that the specified Site 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 Site 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 Site, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the site whose domains were requested is returned under the key siteId inside each domain response.

Check if a Site contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "siteId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Site Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /sites/{siteId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the Site whose Domains are of interest.
id The id of the Domain you want to know whether the Site belongs to.

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 Domains that are directly attached to the specified Site, any of their subdomains will be considered.

Response

If the Site 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 Site Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "siteId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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 /sites/{siteId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
siteId String The id of the Site 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 Site out of a parent Domain?
id String n/a The id of the Domain to which the Site should be added.
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 Site Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Site c54e4241-299b-11e8-94d3-2be9464da125"
}

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 /sites/{siteId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
siteId The id of the Site whose Domain should be removed.
id The id of the Domain to be removed from the Site.

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.

Site External Sources

Site External Sources are intended to represent an InformaCast site being linked to an external entity to facilitate integration workflows, such as Zoom or Kontakt.io.

List Site External Sources

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/external-sources?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/3eae9809-4a72-11ed-ba69-c7f2bbe20103/external-sources"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "updatedAt": "2022-08-08T21:24:19.967Z",
   "permissions": [
    "delete",
    "get"
   ],
   "name": "Madison Square Garden",
   "source": "zoom",
   "externalId": "SDFSDFxcfvkjsHJFDKF325235",
   "id": "7713aa2f-1760-11ed-9083-1dc243401jkl",
   "siteId": "7712238e-1760-11ed-9083-238bkjld3",
   "createdAt": "2022-08-08T21:24:19.967Z"
  }
 ]
}

Gets a list of all external sources for the given site.

HTTP Request

GET /sites/{siteId}/externalSources

Produces

application/json

Query Parameters

To make this example more manageable, only the first site external source was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The external source response format is detailed here.

Get a Site External Source

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkl"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkl" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkl"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "updatedAt": "2022-08-08T21:24:19.967Z",
 "permissions": [
  "delete",
  "get"
 ],
 "name": "Madison Square Garden",
 "source": "zoom",
 "externalId": "SDFSDFxcfvkjsHJFDKF325235",
 "id": "7713aa2f-1760-11ed-9083-1dc243401jkl",
 "siteId": "7712238e-1760-11ed-9083-238bkjld3",
 "createdAt": "2022-08-08T21:24:19.967Z"
}

Retrieves a single site external source by id. Since this is not a list request, there is no pagination wrapper around the result. Note that this is by ID, not external ID.

HTTP Request

GET /sites/{siteId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site to retrieve.
externalSourceId The id of the external source to retrieve. Not the external ID!

Response

The site external source response format is detailed here.

Remove a Site External Source

# Continuing with the site object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b/externalSources/7713aa2f-1760-11ed-9083-1dc243401jkl" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  7713aa2f-1760-11ed-9083-1dc243401jkl"
}

Deletes an existing site external source.

HTTP Request

DELETE /sites/{siteId}/externalSources/{externalSourceId}

Produces

application/json

Path Parameters

Parameter Description
siteId The id of the site with the external source to delete.
externalSourceId The ‘id’ of the external source to delete. Not the external ID!

Response

The deletion response format is detailed here.

External Source Response

The JSON document used to represent an External Source resource for a Site, Site Building, Site Building Floor, or Site Building Floor Zone resource has the following content:

Attribute Type Description
buildingId String The id of the building this external source is in. Only exists if this is the external source for a building, floor, or zone.
createdAt ISO 8601 date/time When this external source was created.
floorId String The id of the floor this external source is in. Only exists if this is the external source for a floor or zone.
id String The id of the external source, for efficient retrieval or manipulation of the external source.
name String The external source’s unique name within its parent resource.
permissions Array[String] Options: get delete. Which operations are possible on this resource, given the authentication token being used to access the API.
siteId String The id of the site for this external source. Returned always.
source String The source of this external source. Also called 'type’ - the external entity providing this resource. For example “zoom” or “kontaktioWearablePanicButton”.
zone String The id of the zone this external source is in. Only exists if this is in the external source for a zone.

Site Roles

Site roles are meant to be used in tandem with Sites, which help determine recipients of a notification sent by a Scenario. They describe a group of people in an organization, such as Security or Employees.

List Site Roles

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles?includeDomains=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true',
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "id": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
   "name": "Employees",
   "createdAt": "2019-02-08T15:25:21.128Z",
   "domains": [
     {
       "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
       "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
       "name": "North Campus",
       "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
       "namePath": "/North Campus/"
     }
   ],
   "permissions": [
    "delete",
    "put",
    "get"
   ]
  }
 ]
}

Gets a list of all site roles 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 site roles allows administrators to decide which users are allowed to configure higher level divisions of their organization from the perspective of the command center.)

HTTP Request

GET /site-roles

Produces

application/json

Query Parameters

To make this example more manageable, only the first site role was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this site role belongs.

Response

The site role response format is detailed here.

Get a Site Role

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'includeDomains': 'true'

}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744?includeDomains=true" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'includeDomains': 'true'
}

try: 
    role = requests.get(url, headers=headers, params=params).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)

{
 "id": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
 "name": "Employees",
 "createdAt": "2019-02-08T15:25:21.128Z",
 "domains": [
   {
     "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
     "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
     "name": "North Campus",
     "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
     "namePath": "/North Campus/"
   }
 ],
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Retrieves a single site role by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /site-role/{siteRoleId}

Produces

application/json

Path Parameters

Parameter Description
siteRoleId The id of the site role to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which this site role belongs.

Response

The site role response format is detailed here.

Create a Site Role

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Administrators'

}

begin: 
    role = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Administrators"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/site-roles"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Administrators'
}

try: 
    role = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)

{
 "name": "Administrators",
 "id": "f6138825-3ad9-11e9-81d7-f104ab17fd00",
 "createdAt": "2019-02-27T21:52:22.230Z",
 "domains": [
   {
     "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
     "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
     "name": "North Campus",
     "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
     "namePath": "/North Campus/"
   }
 ],
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Create a new site role.

HTTP Request

POST /site-roles

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 site role’s unique name. Maximum of 140 characters.

Response

The site role response format is detailed here.

Update a Site Role

# Continuing with the site role object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Employees and Contractors"}'
# Continuing with the site role object from
# the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "bf5f4f46-2bb5-11e9-8180-5fe10bc30744",
 "name": "Employees and Contractors",
 "createdAt": "2019-02-08T15:25:21.128Z",
 "domains": [
   {
     "id": "d694a3b4-45c5-11e9-88d0-6d31bf4fd21e",
     "parentId": "2e5dbaf2-45c1-11e9-88d0-ddb588624ce9",
     "name": "North Campus",
     "path": "/2e5dbaf2-45c1-11e9-88d0-ddb588624ce9/d694a3b4-45c5-11e9-88d0-6d31bf4fd21e/",
     "namePath": "/North Campus/"
   }
 ],
 "permissions": [
  "delete",
  "put",
  "get"
 ]
}

Updates an existing site role.

HTTP Request

PUT /site-roles/{siteRoleId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
siteRoleId The id of the site role to update.

Request Parameters

Parameter Type Default Description
name String N/A The site role’s unique name. Maximum of 140 characters.

Response

The site role response format is detailed here.

Remove a Site Role

# Continuing with the site role object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/f6138825-3ad9-11e9-81d7-f104ab17fd00" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the site role object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)

{
 "status": 200,
 "message": "deleted  f6138825-3ad9-11e9-81d7-f104ab17fd00"
}

Deletes an existing site role.

HTTP Request

DELETE /site-roles/{siteRoleId}

Produces

application/json

Path Parameters

Parameter Description
siteRoleId The id of the site role to delete.

Response

The deletion response format is detailed here.

Site Role Response

The JSON document used to represent a Site Role resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this site role 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 site role belongs.
id String The id of the user, for efficient retrieval, manipulation, or looking up sub-resources attached to the site role.
name String The site role’s unique 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.

Site Roles Associated Sites

Site roles are meant to be used in tandem with Sites, which help determine recipients of a notification sent by a Scenario. They describe a group of people in an organization, such as Security or Employees. When there are associated sites with a given Site Role, this endpoint will list them.

List Site Role Associated Sites

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/sites?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/sites"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "permissions": ["get"],
   "collaborationGroups": [],
   "name": "East Campus",
   "createdAt": "2019-02-26T19:25:33.040Z",
   "distributionListIds": [
    "c6e970a8-39fc-11e9-8c83-f91be012dad7"
   ],
   "deviceGroupIds": [],
   "areasOfInterest": [],
   "siteRecipientId": "f9ae9275-39fc-11e9-8c83-1ddb12dc3e43",
   "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
   "collaborationGroupIds": [],
   "distributionLists": [
    {
     "id": "c6e970a8-39fc-11e9-8c83-f91be012dad7",
     "name": "East Campus - Security",
     "campaign": null,
     "createdAt": "2019-02-26T19:29:04.324Z"
    }
   ],
   "userIds": [
    "1e9758e5-73ff-11e8-9b03-239fcdffd087"
   ],
   "deviceGroups": [],
   "areaOfInterestIds": [],
   "users": [
    {
     "email": "john.doe@example.com",
     "name": "John Doe",
     "type": "regular",
     "loadSourceId": null,
     "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
     "createdAt": "2018-06-19T20:27:00.189Z",
     "lock": null,
     "idleTimeout": 90
    }
   ]
  }
 ]
}

Gets a list of all associated sites for a given site role 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 /site-roles/{siteRoleId}/sites

Produces

application/json

Path Parameters

Parameter Description
siteRoleId The id of the site role to retrieve.

Query Parameters

To make this example more manageable, only the first site role was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 2 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The site role associated sites response format is detailed here.

Get a Site Role’s Associated Site

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    role = JSON.parse(HTTParty.get(url, headers: headers))
    puts(role)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/bf5f4f46-2bb5-11e9-8180-5fe10bc30744/sites/48fa0f0c-39fc-11e9-8c83-c128c081826b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    role = requests.get(url, headers=headers).json()
    print(role)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": ["get"],
 "collaborationGroups": [],
 "name": "East Campus",
 "createdAt": "2019-02-26T19:25:33.040Z",
 "distributionListIds": [
  "c6e970a8-39fc-11e9-8c83-f91be012dad7"
 ],
 "deviceGroupIds": [],
 "areasOfInterest": [],
 "siteRecipientId": "f9ae9275-39fc-11e9-8c83-1ddb12dc3e43",
 "id": "48fa0f0c-39fc-11e9-8c83-c128c081826b",
 "collaborationGroupIds": [],
 "distributionLists": [
  {
   "id": "c6e970a8-39fc-11e9-8c83-f91be012dad7",
   "name": "East Campus - Security",
   "campaign": null,
   "createdAt": "2019-02-26T19:29:04.324Z"
  }
 ],
 "userIds": [
  "1e9758e5-73ff-11e8-9b03-239fcdffd087"
 ],
 "deviceGroups": [],
 "areaOfInterestIds": [],
 "users": [
  {
   "email": "john.doe@example.com",
   "name": "John Doe",
   "type": "regular",
   "loadSourceId": null,
   "id": "1e9758e5-73ff-11e8-9b03-239fcdffd087",
   "createdAt": "2018-06-19T20:27:00.189Z",
   "lock": null,
   "idleTimeout": 90
  }
 ]
}

Retrieves a single site role site association by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /site-role/{siteRoleId}/sites/{siteId}

Produces

application/json

Path Parameters

Parameter Description
siteRoleId The id of the site role to retrieve.
siteId The id of the associated site to retrieve.

Response

The site role associated sites response format is detailed here.

Site Role Associated Sites Response

The JSON document used to represent a Site Role’s Associated Sites resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this site role was created.
id String The id of the user, for efficient retrieval, manipulation, or looking up sub-resources attached to the site role.
name String The site’s unique name.
permissions Array[String] Options: get. Which operations are possible on this resource, given the authentication token being used to access the API.
areasOfInterest Array[Area of Interest] The areas of interest in this group of site role recipients.
areaOfInterestIds Array[String] The list of ids for areas of interest in this group of site role recipients.
collaborationGroups Array[Collaboration Group] The collaboration groups in this group of site role recipients.
collabroationGroupIds Array[String] The list of ids for collaboration groups in this group of site role recipients.
deviceGroups Array[Device Group] The device groups (fusion only) in this group of site role recipients.
deviceGroupIds Array[String] The list of ids for device groups (fusion only) in this group of site role recipients.
distributionLists Array[Distribution List] The distribution lists in this group of site role recipients.
distributionListIds Array[String] The list of ids for distribution lists in this group of site role recipients.
users Array[User] The users in this group of site role recipients.
userIds Array[String] The list of ids for users in this group of site role recipients.

Site Role Domains

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 Site Role Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
      "siteRoleId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T06:02:44.441Z"
    },
    {
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "name": "Grounds",
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "namePath": "/West Campus/Stadium/Grounds/",
      "siteRoleId": "c54e4241-299b-11e8-94d3-2be9464da125",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "createdAt": "2018-03-16T20:52:28.522Z"
    }
  ]
}

Retrieves the list of all Domains to which the Site Role belongs. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /site-roles/{siteRoleId}/domains

Produces

application/json

Path Parameters

Parameter Description
siteRoleId The id of the Site Role whose associated Domains are to be listed.

Query Parameters

In this example, There were a total of 2 Domains that the specified Site Role 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 Site Role 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 Site Role, any subdomains will be returned.

Response

The Domain response format is detailed here. Additionally, the id of the site role whose domains were requested is returned under the key siteRoleId inside each domain response.

Check if a Site Role contains a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "siteRoleId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T20:52:28.522Z"
}

Retrieves a single Site Role Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /site-roles/{siteRoleId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
siteRoleId The id of the Site Role whose Domains are of interest.
id The id of the Domain you want to know whether the Site Role belongs to.

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 Domains that are directly attached to the specified Site Role, any of their subdomains will be considered.

Response

If the Site Role 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 Site Role Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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/",
  "siteRoleId": "c54e4241-299b-11e8-94d3-2be9464da125",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "createdAt": "2018-03-16T06:02:44.441Z"
}

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 /site-roles/{siteRoleId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
siteRoleId String The id of the Site Role 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 Site Role out of a parent Domain?
id String n/a The id of the Domain to which the Site Role should be added.
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 Site Role Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/site-roles/c54e4241-299b-11e8-94d3-2be9464da125/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Domain Site Role c54e4241-299b-11e8-94d3-2be9464da125"
}

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 /site-roles/{siteRoleId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
siteRoleId The id of the Site Role whose Domain should be removed.
id The id of the Domain to be removed from the Site Role.

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.

Text-to-Speech Previews

This resource allows you to access and create previews of what text-to-speech synthesis will sound like for a particular set of parameters (type, content, voice).

There are two steps involved, first creating the preview, and then using the hash returned from that operation to retrieve the actual audio data.

Get a Preview’s Audio

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts/d407687e07f2ade3009b589d6d16bd866826ef4a547ecc6ddb7974c7bf685554"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    sound = HTTParty.get(url, headers: headers)
    puts(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts/d407687e07f2ade3009b589d6d16bd866826ef4a547ecc6ddb7974c7bf685554" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts/d407687e07f2ade3009b589d6d16bd866826ef4a547ecc6ddb7974c7bf685554"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    sound = requests.get(url, headers=headers)
    print(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Retrieves the audio, if any, with the specified hash. Typically this is in PCM (WAV) format.

Produces a binary stream of audio data, with the specific MIME type identified in the response header.

HTTP Request

GET /tts/{audioHash}

Produces

audio/wav

Path Parameters

Parameter Description
audioHash The hash that identifies the particular audio preview desired (see below for how that is obtained).

Create a Preview

Typically this is done in a single step, and the actual audio data is returned in response to the POST. If, for some reason, it is more convenient to separate the creation from the retrieval of the audio, the query parameter return can be passed with the value hash, and after creating or finding the audio, a description of it will be returned that can be used with GET when the audio itself is desired.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'ttsType': 'subject'
,
    'ttsVoiceId': '37f0f500-1be0-11e4-9181-3c970e7ff560'
,
    'subject': 'What’s going on?'
,
    'return': 'hash'

}

begin: 
    preview = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(preview)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"ttsType": "subject", \
       "ttsVoiceId": "37f0f500-1be0-11e4-9181-3c970e7ff560", \
       "subject": "What’s going on?", \
       "return": "hash"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/tts"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'ttsType': 'subject',
    'ttsVoiceId': '37f0f500-1be0-11e4-9181-3c970e7ff560',
    'subject': 'What’s going on?',
    'return': 'hash'
}

try: 
    preview = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(preview)
except RequestException as e:
    print('Unexpected error!', e)
{
 "audioHash": "d407687e07f2ade3009b589d6d16bd866826ef4a547ecc6ddb7974c7bf685554",
 "audioSize": 28292
}

Returns the audio of the synthesized speech, or the hash that can be used to obtain it (as described above), that results from the specified parameters.

HTTP Request

POST /tts

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json or audio/wav, depending on the value of return.

Request Parameters

Parameter Type Default Description
body String empty A field which will be spoken if ttsType is body or ‘subject-and-body`.
return String audio Option: audio, hash. Controls what is returned after the audio is created or found.
subject String empty A field which will be spoken if ttsType is subject or subject-and-body.
ttsCustom­content String empty A field which will be spoken if ttsType is custom-text or custom-ssml.
ttsType String N/A Option: subject, body, subject-and-body, custom-text, custom-ssml. Controls which parameters are synthesized, and how they are interpreted.
ttsVoiceId UUID N/A Chooses the Text-to-Speech Voice used to synthesize the text.
validate String none Option: length, none. Controls whether a validation error will occur of the specified text (after variable substitution) is too long to be spoken. The default is to truncate it to a speakable length.

Response

The JSON document used to describe a text-to-speech preview when return is sent as hash has the following content:

Attribute Type Description
audioHash String The hash which can be used to retrieve the actual audio data of the preview.
audioSize Integer The size of the preview audio data, in bytes.

Text-to-Speech Defaults

This resource allows you view and change the default configuration for text-to-speech synthesis. Currently the only configurable option is the default voice, but more options are expected in the future.

List All Text-to-Speech Defaults

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-defaults"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-defaults" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts-defaults"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "previous": null,
 "next": null,
 "partial": false,
 "data": [
  {
   "id": "2d01d5d6-8589-11ea-aeb4-636b2c90ef7c",
   "ttsVoiceId": "751de142-841a-11ea-a32f-17f989f7588d",
   "createdAt": "2020-04-23T17:38:00.033Z",
   "updatedAt": "2020-04-23T17:38:00.033Z",
   "permissions": [
    "put",
    "get"
   ]
  }
 ]
}

Retrieves a list of all the text-to-speech defaults. There will always only be one entry in this list.

HTTP Request

GET /tts-defaults

Produces

application/json

Response

The text-to-speech defaults response format is detailed here.

Get the Text-to-Speech Defaults

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-voices/2d01d5d6-8589-11ea-aeb4-636b2c90ef7c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    defaults = JSON.parse(HTTParty.get(url, headers: headers))
    puts(defaults)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-voices/2d01d5d6-8589-11ea-aeb4-636b2c90ef7c" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts-voices/2d01d5d6-8589-11ea-aeb4-636b2c90ef7c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    defaults = requests.get(url, headers=headers).json()
    print(defaults)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "2d01d5d6-8589-11ea-aeb4-636b2c90ef7c",
 "ttsVoiceId": "751de142-841a-11ea-a32f-17f989f7588d",
 "createdAt": "2020-04-23T17:38:00.033Z",
 "updatedAt": "2020-04-23T17:38:00.033Z",
 "permissions": [
  "put",
  "get"
 ]
}

Retrieves the single text-to-speech defaults entry based on its id. Since this is not a list request, there is no pagination wrapper around the result, which would be the only reason to bother performing the request this way, but it would require already knowing the value of id.

HTTP Request

GET /tts-voice-default-voice-configs/{ttsDefaultsId}

Produces

application/json

Path Parameters

Parameter Description
ttsDefaultsId The id of the specific text-to-speech defaults entry to retrieve.

Response

The text-to-speech defaults response format is detailed here.

Update the Text-to-Speech Defaults

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/text-to-speech-default-voice-configs/2d01d5d6-8589-11ea-aeb4-636b2c90ef7c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'ttsVoiceId': '751e2f79-841a-11ea-a32f-9b44b29552d9'

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/text-to-speech-default-voice-configs/2d01d5d6-8589-11ea-aeb4-636b2c90ef7c" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"ttsVoiceId": "751e2f79-841a-11ea-a32f-9b44b29552d9"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/text-to-speech-default-voice-configs/2d01d5d6-8589-11ea-aeb4-636b2c90ef7c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'ttsVoiceId': '751e2f79-841a-11ea-a32f-9b44b29552d9'
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "2d01d5d6-8589-11ea-aeb4-636b2c90ef7c",
 "ttsVoiceId": "751e2f79-841a-11ea-a32f-9b44b29552d9",
 "createdAt": "2020-04-23T17:38:00.033Z",
 "updatedAt": "2020-04-24T18:21:12.324Z",
 "permissions": [
  "put",
  "get"
 ]
}

Updates the text-to-speech defaults, allowing you to specify a different default voice to be used when configuring new message templates. (Changing the default has no effect on message templates that are already using text-to-speech.)

HTTP Request

PUT /text-to-speech-default-voice-configs/{defaultsId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
defaultsId The id of the text-to-speech defaults.

Request Parameters

Parameter Type Default Description
ttsVoiceId UUID N/A The id of the Text-to-Speech Voice that should be the new default for message templates being configured for text-to-speech.

Text-to-Speech Defaults Response

The JSON document used to represent a text-to-speech defaults resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When the defaults were created.
updatedAt ISO 8601 date/time When this defaults were last updated.
id UUID The id of the defaults entry, which can be used to update it.
permissions Array[String] Options: get put delete. Only get and put are ever seen because defaults cannot be created or deleted.
ttsVoiceId UUID The id of the Text-to-Speech Voice to be used by default when configuring new message templates for text-to-speech.

Text-to-Speech Lexicons

Lexicons allow you to substitute a word which is mispronounced by the text-to-speech voice with another word or a variation on its spelling which sounds the way you want it to. This substitution happens at send time, without end-users needing to worry about it. Lexicon substitution happens only for plain text, it is not used with custom SSML content, because the use of SSML is an expert feature that allows you to control every aspect of pronunciation and intonation.

List Text-to-Speech Lexicons

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-lexicons?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": true,
 "previous": null,
 "next": "1",
 "data": [
  {
   "id": "31799f74-9aaf-11ea-90b1-1b03819cc58f",
   "language": "en-US",
   "find": "bldg",
   "replace": "building",
   "createdAt": "2020-05-20T15:33:02.823Z",
   "updatedAt": "2020-05-20T15:33:02.823Z",
   "permissions": [
    "put",
    "delete",
    "get"
   ]
  }
 ]
}

Gets a list of all lexicon entries 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 /tts-lexicons

Produces

application/json

Query Parameters

To make this example more manageable, only the first lexicon 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
find String If present, only lexicon entries whose find attribute exactly matches this value will be returned.
language String If present, only lexicon entries whose language attribute exactly matches this value will be returned.
replace String If present, only lexicon entries whose replace attribute exactly matches this value will be returned.

Response

The text-to-speech lexicon response format is detailed here.

Get a Text-to-Speech Lexicon Entry

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/31799f74-9aaf-11ea-90b1-1b03819cc58f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    lexicon = JSON.parse(HTTParty.get(url, headers: headers))
    puts(lexicon)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/31799f74-9aaf-11ea-90b1-1b03819cc58f" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/31799f74-9aaf-11ea-90b1-1b03819cc58f"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    lexicon = requests.get(url, headers=headers).json()
    print(lexicon)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "31799f74-9aaf-11ea-90b1-1b03819cc58f",
 "language": "en-US",
 "find": "bldg",
 "replace": "building",
 "createdAt": "2020-05-20T15:33:02.823Z",
 "createdAt": "2020-05-20T15:33:02.823Z",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

Retrieves a single lexicon entry by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /tts-lexicons/{lexiconId}

Produces

application/json

Path Parameters

Parameter Description
lexiconId The id of the lexicon entry to retrieve.

Response

The text-to-speech lexicon response format is detailed here.

Create a Text-to-Speech Lexicon Entry

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'language': 'en-US'
,
    'find': 'fl'
,
    'replace': 'floor'

}

begin: 
    lexicon = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(lexicon)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-lexicons" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"language": "en-US", \
       "find": "fl", \
       "replace": "floor"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'language': 'en-US',
    'find': 'fl',
    'replace': 'floor'
}

try: 
    lexicon = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(lexicon)
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "a13e4eea-9b9c-11ea-baeb-6dd5a997728c",
 "language": "en-US",
 "find": "fl",
 "replace": "floor",
 "createdAt": "2020-05-21T19:52:41.064Z",
 "updatedAt": "2020-05-21T19:52:41.064Z",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

Create a new text-to-speech lexicon entry.

HTTP Request

POST /tts-lexicons

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
find String N/A The text which should be replaced when it is found as a standalone word.
language String N/A The ISO 639-1 language code identifying the language for which this entry should be active.
replace String N/A The text which should be spoken instead of find.

Response

The text-to-speech lexicon response format is detailed here.

Update a Text-to-Speech Lexicon Entry

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/a13e4eea-9b9c-11ea-baeb-6dd5a997728c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'language': 'en-GB'

}

begin: 
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/a13e4eea-9b9c-11ea-baeb-6dd5a997728c" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"language": "en-GB"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/a13e4eea-9b9c-11ea-baeb-6dd5a997728c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'language': 'en-GB'
}

try: 
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "id": "a13e4eea-9b9c-11ea-baeb-6dd5a997728c",
 "language": "en-GB",
 "find": "fl",
 "replace": "floor",
 "createdAt": "2020-05-21T19:52:41.064Z",
 "updatedAt": "2020-05-22T09:21:22.123Z",
 "permissions": [
  "put",
  "delete",
  "get"
 ]
}

Updates an existing text-to-speech lexicon entry.

HTTP Request

PUT /tts-lexicons/{lexiconId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
lexiconId The id of the lexicon entry to update.

Request Parameters

Parameter Type Default Description
find String N/A The text which should be replaced when it is found as a standalone word.
language String N/A The ISO 639-1 language code identifying the language for which this entry should be active.
replace String N/A The text which should be spoken instead of find.

Response

The text-to-speech lexicon response format is detailed here.

Remove a Text-to-Speech Lexicon Entry

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/a13e4eea-9b9c-11ea-baeb-6dd5a997728c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/a13e4eea-9b9c-11ea-baeb-6dd5a997728c" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts-lexicons/a13e4eea-9b9c-11ea-baeb-6dd5a997728c"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "status": 200,
 "message": "deleted  a13e4eea-9b9c-11ea-baeb-6dd5a997728c"
}

Deletes an existing lexicon entry.

HTTP Request

DELETE /tts-lexicons/{lexiconId}

Produces

application/json

Path Parameters

Parameter Description
lexiconId The id of the lexicon entry to delete.

Response

The deletion response format is detailed here.

Text-to-Speech Lexicon Response

The JSON document used to represent a Text-to-Speech Lexicon resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this lexicon was created.
updatedAt ISO 8601 date/time When this lexicon was last updated.
find String The text which should be replaced when it is found as a standalone word.
id String The id of the lexicon entry, which can be used to update or delete it.
lang String The ISO 639-1 language code identifying the language for which this entry should be active.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
replace String The text which should be spoken instead of find.

Text-to-Speech Voices

This resource allows you to list the voices that are available for text-to-speech synthesis.

List All Text-to-Speech Voices

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-voices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-voices?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts-voices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 21,
 "previous": null,
 "next": "1",
 "data": [
  {
   "permissions": [
    "get"
   ],
   "name": "Amy",
   "createdAt": "2020-04-21T21:52:55.713Z",
   "updatedAt": "2020-04-21T21:52:55.714Z",
   "language": "en-GB",
   "id": "751de14c-841a-11ea-a32f-2527bd7fe7a8",
   "engine": "standard",
   "gender": "Female",
   "synthesisProvider": "Amazon Polly"
  }
 ]
}

Retrieves a list of all the voices that are available for text-to-speech synthesis.

HTTP Request

GET /tts-voices

Produces

application/json

Query Parameters

To make this example more concise, only the first voice was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of twenty-one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Parameter Type Description
name String Returns only voices whose names exactly match the supplied value.
gender String Returns only voices whose genders exactly match the supplied value
language String Returns only voices whose language codes exactly match the supplied value
engine String Returns only voices whose synthesis engines exactly match the supplied value.

Response

The text-to-speech voice response format is detailed here.

Get a Text-to-Speech Voice

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tts-voices/751e085d-841a-11ea-a32f-a178c14a62b1"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    voice = JSON.parse(HTTParty.get(url, headers: headers))
    puts(voice)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tts-voices/751e085d-841a-11ea-a32f-a178c14a62b1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tts-voices/751e085d-841a-11ea-a32f-a178c14a62b1"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    voice = requests.get(url, headers=headers).json()
    print(voice)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
   "get"
  ],
  "name": "Brian",
  "createdAt": "2020-04-21T21:52:55.714Z",
  "updatedAt": "2020-04-21T21:52:55.714Z",
  "language": "en-GB",
  "id": "751e085d-841a-11ea-a32f-a178c14a62b1",
  "engine": "standard",
  "gender": "Male",
  "synthesisProvider": "Amazon Polly"
}

Retrieves a single text-to-speech voice based on its id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /tts-voices/{ttsVoiceId}

Produces

application/json

Path Parameters

Parameter Description
ttsVoiceId The id of the specific text-to-speech voice to retrieve.

Text-to-Speech Voice Response

The JSON document used to represent a text-to-speech voice resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this voice was created.
updatedAt ISO 8601 date/time When this voice was last updated.
engine String Identifies the type of speech synthesis engine that powers the voice, as reported by the speech synthesis provider.
gender String Identifies the gender of the voice, as reported by the speech synthesis provider.
id UUID The id of this specific voice, allowing it to be retrieved individually, used to create a preview, configured in a Message Template or used in the Defaults.
language String The ISO 639-1 language code identifying the language the voice speaks.
name String The name of the voice.
permissions Array[String] Options: get put delete. Only get is ever seen because voices cannot be created, deleted, or changed.
synthesis­Provider String Identifies the service that provides speech synthesis for this voice.

Tracking Event Notifications

A tracking event notification answers the question “who is suppose to be notified when someone has indicated they should be tracked and what should they be told”.

When a device sends a response to the API indicating that tracking is being activated who gets notified is based on one of two things.

Each notification has a lat/lon location associated with it. When a device POSTs a /tracking-events/*/activities with status=started the API will find the notification closest geographically to the origin of the activity.

Additionally if the notification has values for distributionListIds or userIds and the user is in either of these lists a notification will be sent out based on that notification as well.

List All Tracking Event Notifications

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "messageTemplateId": "457a480f-7091-11e7-819f-6dc7f94a1d78",
   "messageTemplate": {
    "imageDisplay": "auto",
    "optOut": false,
    "userIdsDisplay": "auto",
    "imageCustomizable": false,
    "deviceGroupIdsDisplay": "auto",
    "name": "Notify Admins",
    "audioDisplay": "auto",
    "createdAt": "2017-07-24T16:58:09.630Z",
    "subjectCustomizable": true,
    "confirmationRequestIdCustomizable": false,
    "distributionListIdsCustomizable": true,
    "areaOfInterestIdsCustomizable": false,
    "deviceGroupIdsCustomizable": false,
    "collaborationGroupIdsCustomizable": false,
    "bodyDisplay": "auto",
    "confirmationRequestId": null,
    "collaborationGroupIdsDisplay": "auto",
    "alertToneDisplay": "auto",
    "userIdsCustomizable": true,
    "id": "457a480f-7091-11e7-819f-6dc7f94a1d78",
    "notificationProfileId": "fc65d044-6571-11e7-873f-d72f493aa3eb",
    "bodyCustomizable": true,
    "imageMimeType": null,
    "distributionListIdsDisplay": "auto",
    "confirmationRequest": null,
    "audioSize": 0,
    "imageHash": null,
    "audioHash": null,
    "subjectDisplay": "auto",
    "audioCustomizable": false,
    "imageSize": 0,
    "body": null,
    "confirmationRequestIdDisplay": "auto",
    "alertToneCustomizable": false,
    "metadata": null,
    "subject": "Something happened.",
    "alertTone": "default",
    "areaOfInterestIdsDisplay": "auto",
    "metadataCustomizable": false
   },
   "name": "Test",
   "createdAt": "2017-07-24T17:12:43.964Z",
   "distributionListIds": [
    "10652291-6572-11e7-8e1e-99d12322d052"
   ],
   "geometryValue": {
    "type": "Feature",
    "geometry": {
     "type": "Point",
     "coordinates": [
      -89,
      43
     ]
    }
   },
   "id": "4e9f0ff4-7093-11e7-819f-87f2ea494660",
   "latLonIgnore": false,
   "distributionLists": [
    {
     "id": "10652291-6572-11e7-8e1e-99d12322d052",
     "name": "Administrator Alerts",
     "campaign": null,
     "createdAt": "2017-07-10T13:17:03.383Z"
    }
   ],
   "userIds": [],
   "geometryType": "point",
   "users": []
  }
 ]
}

Retrieves the list of all tracking event notifications.

HTTP Request

GET /tracking-event-notifications

Produces

application/json

Query Parameters

Response

The tracking event notification response format is detailed here.

Get a Tracking Event Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications/4e9f0ff4-7093-11e7-819f-87f2ea494660"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    tracking_event_notifications = JSON.parse(HTTParty.get(url, headers: headers))
    puts(tracking_event_notifications)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications/4e9f0ff4-7093-11e7-819f-87f2ea494660" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications/4e9f0ff4-7093-11e7-819f-87f2ea494660"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    tracking_event_notifications = requests.get(url, headers=headers).json()
    print(tracking_event_notifications)
except RequestException as e:
    print('Unexpected error!', e)
{
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "messageTemplateId": "457a480f-7091-11e7-819f-6dc7f94a1d78",
   "messageTemplate": {
    "imageDisplay": "auto",
    "optOut": false,
    "userIdsDisplay": "auto",
    "imageCustomizable": false,
    "deviceGroupIdsDisplay": "auto",
    "name": "Notify Admins",
    "audioDisplay": "auto",
    "createdAt": "2017-07-24T16:58:09.630Z",
    "subjectCustomizable": true,
    "confirmationRequestIdCustomizable": false,
    "distributionListIdsCustomizable": true,
    "areaOfInterestIdsCustomizable": false,
    "deviceGroupIdsCustomizable": false,
    "collaborationGroupIdsCustomizable": false,
    "bodyDisplay": "auto",
    "confirmationRequestId": null,
    "collaborationGroupIdsDisplay": "auto",
    "alertToneDisplay": "auto",
    "userIdsCustomizable": true,
    "id": "457a480f-7091-11e7-819f-6dc7f94a1d78",
    "notificationProfileId": "fc65d044-6571-11e7-873f-d72f493aa3eb",
    "bodyCustomizable": true,
    "imageMimeType": null,
    "distributionListIdsDisplay": "auto",
    "confirmationRequest": null,
    "audioSize": 0,
    "imageHash": null,
    "audioHash": null,
    "subjectDisplay": "auto",
    "audioCustomizable": false,
    "imageSize": 0,
    "body": null,
    "confirmationRequestIdDisplay": "auto",
    "alertToneCustomizable": false,
    "metadata": null,
    "subject": "Something happened.",
    "alertTone": "default",
    "areaOfInterestIdsDisplay": "auto",
    "metadataCustomizable": false
   },
   "name": "Test",
   "createdAt": "2017-07-24T17:12:43.964Z",
   "distributionListIds": [
    "10652291-6572-11e7-8e1e-99d12322d052"
   ],
   "geometryValue": {
    "type": "Feature",
    "geometry": {
     "type": "Point",
     "coordinates": [
      -89,
      43
     ]
    }
   },
   "id": "4e9f0ff4-7093-11e7-819f-87f2ea494660",
   "latLonIgnore": false,
   "distributionLists": [
    {
     "id": "10652291-6572-11e7-8e1e-99d12322d052",
     "name": "Administrator Alerts",
     "campaign": null,
     "createdAt": "2017-07-10T13:17:03.383Z"
    }
   ],
   "userIds": [],
   "geometryType": "point",
   "users": []
  }

Retrieves a single tracking-event-notification by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /tracking-event-notifications/{trackingEventNotificationId}

Produces

application/json

Path Parameters

Parameter Description
trackingEventNotificationId The id of the tracking event notification to retrieve.

Response

The response format is detailed here.

Create a Tracking Event Notification

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 tracking event notification
messageTemplateId String N/A Message template to use if a notification is to be sent out. Note, this message template must have recipients (DLs or Users) built into it.
latLonIgnore Boolean N/A Set to true if you don’t want to use the lat/lon values when considering proximity of device to location.
geometryType String point GeoJSON geometry type
geometryValue[type] String ‘feature’ feature
geometryValue[geometry][type] String 'point’ point
geometryValue[geometry][coordinates] Array N/A array with lon and lat pair (East hemisphere positive)
distributionListIds Array UUID N/A If specified, if any user associated with these distribution lists requests being tracked, this notification will send out a notification.
userIds Array UUID N/A If specified, if a user in this list requests being tracked, this notification will send out a notification.
require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'messageTemplateId': '457a480f-7091-11e7-819f-6dc7f94a1d78'
,
    'name': 'Route To Administrators'
,
    'latLonIgnore': false
,
    'geometryType': 'point'
,
    'geometryValue': {
        'type': 'feature'
,
        'geometry': {
            'type': 'point'
,
            'coordinates': [-89.0
, 43.0
]

}


}

,
    'distributionListIds': ['10652291-6572-11e7-8e1e-99d12322d052'
]

}

begin: 
    user = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(user)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"messageTemplateId": "457a480f-7091-11e7-819f-6dc7f94a1d78", \
       "name": "Route To Administrators", \
       "latLonIgnore": false, \
       "geometryType": "point", \
       "geometryValue": {"type": "feature", \
         "geometry": {"type": "point", \
           "coordinates": [-89.0, 43.0]}}, \
       "distributionListIds": ["10652291-6572-11e7-8e1e-99d12322d052"]}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'messageTemplateId': '457a480f-7091-11e7-819f-6dc7f94a1d78',
    'name': 'Route To Administrators',
    'latLonIgnore': false,
    'geometryType': 'point',
    'geometryValue': {
        'type': 'feature',
        'geometry': {
            'type': 'point',
            'coordinates': [-89.0, 43.0]
}

}
,
    'distributionListIds': ['10652291-6572-11e7-8e1e-99d12322d052']
}

try: 
    user = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "messageTemplateId": "457a480f-7091-11e7-819f-6dc7f94a1d78",
 "messageTemplate": {
  "imageDisplay": "auto",
  "optOut": false,
  "userIdsDisplay": "auto",
  "imageCustomizable": false,
  "deviceGroupIdsDisplay": "auto",
  "name": "Notify Admins",
  "audioDisplay": "auto",
  "createdAt": "2017-07-24T16:58:09.630Z",
  "subjectCustomizable": true,
  "confirmationRequestIdCustomizable": false,
  "distributionListIdsCustomizable": true,
  "areaOfInterestIdsCustomizable": false,
  "deviceGroupIdsCustomizable": false,
  "collaborationGroupIdsCustomizable": false,
  "bodyDisplay": "auto",
  "confirmationRequestId": null,
  "collaborationGroupIdsDisplay": "auto",
  "alertToneDisplay": "auto",
  "userIdsCustomizable": true,
  "id": "457a480f-7091-11e7-819f-6dc7f94a1d78",
  "notificationProfileId": "fc65d044-6571-11e7-873f-d72f493aa3eb",
  "bodyCustomizable": true,
  "imageMimeType": null,
  "distributionListIdsDisplay": "auto",
  "confirmationRequest": null,
  "audioSize": 0,
  "imageHash": null,
  "audioHash": null,
  "subjectDisplay": "auto",
  "audioCustomizable": false,
  "imageSize": 0,
  "body": null,
  "confirmationRequestIdDisplay": "auto",
  "alertToneCustomizable": false,
  "metadata": null,
  "subject": "Something happened.",
  "alertTone": "default",
  "areaOfInterestIdsDisplay": "auto",
  "metadataCustomizable": false
 },
 "name": "Test2",
 "createdAt": "2017-07-25T14:11:50.285Z",
 "distributionListIds": [
  "10652291-6572-11e7-8e1e-99d12322d052"
 ],
 "geometryValue": {
  "type": "Feature",
  "geometry": {
   "type": "Point",
   "coordinates": [
    -89,
    42
   ]
  }
 },
 "id": "33bcd48c-7143-11e7-abfc-1945b9843e9e",
 "latLonIgnore": false,
 "distributionLists": [
  {
   "id": "10652291-6572-11e7-8e1e-99d12322d052",
   "name": "Administrator Alerts",
   "campaign": null,
   "createdAt": "2017-07-10T13:17:03.383Z"
  }
 ],
 "userIds": [],
 "geometryType": "point",
 "users": []
}

Update a Tracking Event Notification

# Continuing with the trackingEventNotificationId
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications/33bcd48c-7143-11e7-abfc-1945b9843e9e" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Milwaukee Office"}'
# Continuing with the trackingEventNotificationId
# object from the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "Milwaukee Office"
}

Updates an existing user.

HTTP Request

PUT /tracking-event-notifications/{trackingEventNotificationId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
trackingEventNotificationId The id of the tracking event notification to update.

Request Parameters

Parameter Type Default Description
name String N/A The tracking event notification name
messageTemplateId UUID N/A The message template to use when sending out a notification when a user is to be tracked. Note, this message template must have recipients built into it.
latLonIgnore Boolean N/A Set to true if you want to ignore the lat lon of this notification when determining who to notify.
geometryType String point GeoJSON geometry type
geometryValue[type] String 'feature’ feature
geometryValue[geometry][type] String 'point’ point
geometryValue[geometry][coordinates] Array N/A array with lon and lat pair (East hemisphere positive)
distributionListIds Array UUID N/A If specified, if any user associated with these distribution lists requests being tracked, this notification will send out a notification.
userIds Array UUID N/A If specified, if a user in this list requests being tracked, this notification will send out a notification.

Response

The tracking event notification response format is detailed here.

Remove a Tracking Event Notification

# Continuing with the trackingEventNotificationsId
# object from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-event-notifications/6ef1e300-1e3a-11e4-b08e-685b358ea847" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the trackingEventNotificationsId
# object from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Tracking Event Notification 6ef1e300-1e3a-11e4-b08e-685b358ea847"
}

Deletes an existing tracking event notification.

HTTP Request

DELETE /tracking-event-notifications/{trackingEventNotificationId}

Produces

application/json

Path Parameters

Parameter Description
trackingEventNotificationId The id of the notification to delete.

Response

The deletion response format is detailed here.

Tracking Event Notification Response

The JSON document used to represent a tracking event notification resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this tracking event notification was created.
name String Name of the tracking event notification
id String The id of the tracking event notification, for efficient retrieval, manipulation, or looking up sub-resources attached to the notification.
latLonIgnore Boolean Set to false if you want to use proximity to determine who to notify.
geometryType String GeoJson 'point’
geometryValue[type] String 'feature’
geometryValue[geometry][type] String 'point’
geometryValue[geometry][coordinates] Array array with lon and lat pair (East hemisphere positive)
distributionListIds UUIDs If a user is in this distribution list, this tracking event notification will send a notification.
userIds UUIDs If a user is in this list, this tracking event notification will send a notification.

Tracking Events

Tracking Events are parent resources used to associate Tracking Event Activities. Tracking Events are created by the service automatically if someone sends a notification and that notification has a confirmation request with at least one option response flagged to initiate tracking. If a tracking event is created in this manner the notificationId will be populated.

Tracking Events can also be created by the mobile application if the user hits the ‘panic button’. If a tracking event is created in this manner the deviceId will be populated.

Tracking Events themselves are generally not created via the mobile API. They are created automatically when either of the conditions above occur.

List All Tracking Events

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'include-summary': true
,
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-events?include-summary=true&limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'include-summary': true,
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "deviceId": null,
   "name": "Are you safe?",
   "initiator": {
    "email": "john.pyeatt@singlewire.com",
    "name": "John Pyeatt",
    "id": "f27b8386-6571-11e7-95e1-db93fc01272d",
    "lock": null
   },
   "notificationId": "1c68141e-714e-11e7-abfc-1fe0c765b52f",
   "completedAt": null,
   "createdAt": "2017-07-25T15:29:55.779Z",
   "state": "active",
   "id": "1c8279ef-714e-11e7-abfc-717f51395e5a",
   "initiatorId": "f27b8386-6571-11e7-95e1-db93fc01272d",
   "summary": [{
    "deviceId": "abb345a0-13ab-11eb-98e7-d7804f4c3f44",
    "lat": 44.059,
    "lng": -82.9844,
    "mostRecent": "2020-10-21T15:15:40.677Z",
    "state": "updated",
    "userId": "f27b8386-6571-11e7-95e1-db93fc01272d",
    "userName": "John Pyeatt"
   }]
  }
 ]
}

Retrieves all tracking events.

HTTP Request

GET /tracking-events

Produces

application/json

Query Parameters

A query parameter was added to provide insight into the tracking event activities associated with a tracking event. This parameter includes a summary key on the response. This key will contain information about all the users who have been tracked by the notification and their most recently-active activity, including the time and location at which the activity was logged.

Parameter Type Description
includeSummary boolean If true, a summary of recent tracking events will be returned as part of the response.

Get a Tracking Event

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    tracking_event_id = JSON.parse(HTTParty.get(url, headers: headers))
    puts(tracking_event_id)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    tracking_event_id = requests.get(url, headers=headers).json()
    print(tracking_event_id)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "deviceId": null,
 "name": "Are you safe?",
 "initiator": {
  "email": "john.pyeatt@singlewire.com",
  "name": "John Pyeatt",
  "id": "f27b8386-6571-11e7-95e1-db93fc01272d",
  "lock": null
 },
 "notificationId": "1c68141e-714e-11e7-abfc-1fe0c765b52f",
 "completedAt": null,
 "createdAt": "2017-07-25T15:29:55.779Z",
 "state": "active",
 "id": "1c8279ef-714e-11e7-abfc-717f51395e5a",
 "initiatorId": "f27b8386-6571-11e7-95e1-db93fc01272d"
}

Retrieves a single tracking event by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /tracking-events/{trackingEventId}

Produces

application/json

Path Parameters

Parameter Description
trackingEventId The id of the tracking event

Query Parameters

A query parameter was added to provide insight into the tracking event activities associated with a tracking event. This parameter includes a summary key on the response. This key will contain information about all the users who have been tracked by the notification and their most recently-active activity, including the time and location at which the activity was logged.

Parameter Type Description
includeSummary boolean If true, a summary of recent tracking events will be returned as part of the response.

Response

The tracking event response format is detailed here.

Create a Tracking Event

This is generally not done via the API. Tracking events are normally created by the system when someone sends a notification with a confirmation request and that confirmation request has options that expect tracking to be activated.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Active Shooter 08/27/2017'
,
    'state': 'active'
,
    'notification-id': 'bdf85eab-228e-11e6-a729-513ce5b8ef20'

}

begin: 
    tracking_event = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(tracking_event)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-events" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Active Shooter 08/27/2017", \
       "state": "active", \
       "notification-id": "bdf85eab-228e-11e6-a729-513ce5b8ef20"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Active Shooter 08/27/2017',
    'state': 'active',
    'notification-id': 'bdf85eab-228e-11e6-a729-513ce5b8ef20'
}

try: 
    tracking_event = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(tracking_event)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "deviceId": null,
 "name": "Active Shooter 08/27/2017",
 "initiator": {
  "email": "john.pyeatt@singlewire.com",
  "name": "John Pyeatt",
  "id": "f27b8386-6571-11e7-95e1-db93fc01272d",
  "lock": null
 },
 "notificationId": "1c68141e-714e-11e7-abfc-1fe0c765b52f",
 "completedAt": null,
 "createdAt": "2017-07-25T15:29:55.779Z",
 "state": "active",
 "id": "1c8279ef-714e-11e7-abfc-717f51395e5a",
 "initiatorId": "f27b8386-6571-11e7-95e1-db93fc01272d"
}

HTTP Request

POST /tracking-events

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 tracking event.
state String N/A Can either be 'started’ or 'completed’
notificationId UUID N/A Only set if the tracking event was created when a notification was POSTed with a confirmation request which has an initiate tracking option set to 'true’.
deviceId UUID N/A Only set if a device hits the 'panic’ button. Note either deviceId or notificationId will be set, but not both.
completedAt Timestamp N/A The time the tracking event was completed.

Response

The tracking event response format is detailed here.

Update a Tracking Event

# Continuing the previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"state": "completed"}'
# Continuing the previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "deviceId": null,
 "name": "Active Shooter 08/27/2017",
 "initiator": {
  "email": "john.pyeatt@singlewire.com",
  "name": "John Pyeatt",
  "id": "f27b8386-6571-11e7-95e1-db93fc01272d",
  "lock": null
 },
 "notificationId": "1c68141e-714e-11e7-abfc-1fe0c765b52f",
 "completedAt": "2017-07-26T16:00:55.779Z",
 "createdAt": "2017-07-25T15:29:55.779Z",
 "state": "completed",
 "id": "1c8279ef-714e-11e7-abfc-717f51395e5a",
 "initiatorId": "f27b8386-6571-11e7-95e1-db93fc01272d"
}

Updates an existing tracking event.

HTTP Request

PUT /tracking-events/{trackingEventId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
trackingEventId The uuid of the tracking event to modify.

Request Parameters

Parameter Type Default Description
name String N/A A unique name for the tracking event.
state String N/A Can either be 'started’ or 'completed’
notificationId UUID N/A Only set if the tracking event was created when a notification was POSTed with a confirmation request which has an initiate tracking option set to 'true’.
deviceId UUID N/A Only set if a device hits the 'panic’ button. Note either deviceId or notificationId will be set, but not both.
completedAt Timestamp N/A The time the tracking event was completed.

Response

The tracking event response format is detailed here.

Remove a Tracking Event

# Continuing the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted 1c8279ef-714e-11e7-abfc-717f51395e5a"
}

Deletes an existing tracking event.

HTTP Request

DELETE /tracking-events/{trackingEventId}

Produces

application/json

Path Parameters

Parameter Description
trackingEventId The id of the tracking event

Response

The deletion response format is detailed here.

Tracking Events Response

The JSON document used to represent a tracking event resource has the following content:

Attribute Type Description
name String A unique name for the tracking event.
state String Can either be 'started’ or 'completed’
notificationId UUID Only set if the tracking event was created when a notification was POSTed with a confirmation request which has an initiate tracking option set to 'true’.
deviceId UUID Only set if a device hits the 'panic’ button. Note either deviceId or notificationId will be set, but not both.
completedAt Timestamp The time the tracking event was completed.
summary Array[Object] The summary of most-recent tracking event responses, with one entry for each user being tracked.

Summary Response

The summary response is an array of JSON objects of the form below. These objects contain information about the most recent tracking activity associated with each user being tracked by the event.

Attribute Type Description
lat Float The latitude of this activity.
lng Float The longitude of this activity.
mostRecent Timestamp The time associated with the most recent activity registered in association with the user this activity describes.
deviceId UUID The id of the device that created the most recent activity associated with the user id.
state String The state of the activity; one of started, updated, completed, or terminated.
userId UUID The id of the user associated with the tracking event.
userName String The name of the user associated with the tracking event.

Tracking Events Activities

Tracking events activities are created to monitor the location of individual devices under a tracking event.

List All Tracking Event Activities

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
   {
   "trackingEvent": {
    "name": "Are you safe?",
    "id": "1c8279ef-714e-11e7-abfc-717f51395e5a",
    "state": "active",
    "deviceId": null,
    "notificationId": "1c68141e-714e-11e7-abfc-1fe0c765b52f"
   },
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "pollingIntervalSecs": 300,
   "deviceId": "b97af3fc-7369-4a13-8805-10291afe8d59",
   "createdAt": "2017-07-25T15:29:55.779Z",
   "state": "started",
   "trackingEventId": "1c8279ef-714e-11e7-abfc-717f51395e5a",
   "geometryValue": {
    "type": "Feature",
    "geometry": {
     "type": "Point",
     "coordinates": [
      -89.1,
      44.4
     ]
    },
    "properties": {
     "accuracyInM": 100,
     "bearing": 270,
     "speedInMetersPerSec": 4.5
    }
   },
   "id": "1c8279ef-714e-11e7-abfc-717f51395e61",
   "userId": "f27b8386-6571-11e7-95e1-db93fc01272d",
   "device": {
    "id": "123412341234"
   },
   "geometryType": "point"
  }
 ]
}

Retrieves all tracking events activities for a tracking event.

HTTP Request

GET /tracking-events/{trackingEventId}/activities

Produces

application/json

Get a Tracking Event Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities/1c8279ef-714e-11e7-abfc-717f51395e61"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    tracking_event_id = JSON.parse(HTTParty.get(url, headers: headers))
    puts(tracking_event_id)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities/1c8279ef-714e-11e7-abfc-717f51395e61" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities/1c8279ef-714e-11e7-abfc-717f51395e61"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    tracking_event_id = requests.get(url, headers=headers).json()
    print(tracking_event_id)
except RequestException as e:
    print('Unexpected error!', e)
{
   "trackingEvent": {
    "name": "Are you safe?",
    "id": "1c8279ef-714e-11e7-abfc-717f51395e5a",
    "state": "active",
    "deviceId": null,
    "notificationId": "1c68141e-714e-11e7-abfc-1fe0c765b52f"
   },
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "pollingIntervalSecs": 300,
   "deviceId": "b97af3fc-7369-4a13-8805-10291afe8d59",
   "createdAt": "2017-07-25T15:29:55.779Z",
   "state": "started",
   "trackingEventId": "1c8279ef-714e-11e7-abfc-717f51395e5a",
   "geometryValue": {
    "type": "Feature",
    "geometry": {
     "type": "Point",
     "coordinates": [
      -89.1,
      44.4
     ]
    },
    "properties": {
     "accuracyInM": 100,
     "bearing": 270,
     "speedInMetersPerSec": 4.5
    }
   },
   "id": "1c8279ef-714e-11e7-abfc-717f51395e61",
   "userId": "f27b8386-6571-11e7-95e1-db93fc01272d",
   "device": {
    "id": "123412341234"
   },
   "geometryType": "point"
}

Retrieves a single tracking event activity by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /tracking-events/{trackingEventId}/activities/{trackingEventActivityId}

Produces

application/json

Path Parameters

Parameter Description
trackingEventId The id of the tracking event
trackingEventActivityId The id of the activity

Response

The tracking event activity format response format is detailed here.

Create Tracking Event Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'userId': 'f27b8386-6571-11e7-95e1-db93fc01272d'
,
    'deviceId': 'b97af3fc-7369-4a13-8805-10291afe8d59'
,
    'state': 'started'
,
    'geometryType': 'point'
,
    'pollingIntervalSecs': 300
,
    'geometryValue': {
        'type': 'feature'
,
        'geometry': {
            'type': 'point'
,
            'coordinates': [-89.4
, 45.9
]
,
            'properties': {
                'accuracyInM': 100
,
                'bearing': 120
,
                'speedInMetersPerSec': 4.5

}


}


}


}

begin: 
    tracking_events_activity = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(tracking_events_activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"userId": "f27b8386-6571-11e7-95e1-db93fc01272d", \
       "deviceId": "b97af3fc-7369-4a13-8805-10291afe8d59", \
       "state": "started", \
       "geometryType": "point", \
       "pollingIntervalSecs": 300, \
       "geometryValue": {"type": "feature", \
         "geometry": {"type": "point", \
           "coordinates": [-89.4, 45.9], \
           "properties": {"accuracyInM": 100, \
             "bearing": 120, \
             "speedInMetersPerSec": 4.5}}}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/tracking-events/1c8279ef-714e-11e7-abfc-717f51395e5a/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'userId': 'f27b8386-6571-11e7-95e1-db93fc01272d',
    'deviceId': 'b97af3fc-7369-4a13-8805-10291afe8d59',
    'state': 'started',
    'geometryType': 'point',
    'pollingIntervalSecs': 300,
    'geometryValue': {
        'type': 'feature',
        'geometry': {
            'type': 'point',
            'coordinates': [-89.4, 45.9],
            'properties': {
                'accuracyInM': 100,
                'bearing': 120,
                'speedInMetersPerSec': 4.5
}

}

}

}

try: 
    tracking_events_activity = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(tracking_events_activity)
except RequestException as e:
    print('Unexpected error!', e)
{
   "trackingEvent": {
    "name": "Are you safe?",
    "id": "1c8279ef-714e-11e7-abfc-717f51395e5a",
    "state": "active",
    "deviceId": null,
    "notificationId": "1c68141e-714e-11e7-abfc-1fe0c765b52f"
   },
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "pollingIntervalSecs": 300,
   "deviceId": "b97af3fc-7369-4a13-8805-10291afe8d59",
   "createdAt": "2017-07-25T15:29:55.779Z",
   "state": "started",
   "trackingEventId": "1c8279ef-714e-11e7-abfc-717f51395e5a",
   "geometryValue": {
    "type": "Feature",
    "geometry": {
     "type": "Point",
     "coordinates": [
      -89.4,
      45.9
     ]
    },
    "properties": {
     "accuracyInM": 100,
     "bearing": 120,
     "speedInMetersPerSec": 4.5
    }
   },
   "id": "1c8279ef-714e-11e7-abfc-717f51395e61",
   "userId": "f27b8386-6571-11e7-95e1-db93fc01272d",
   "device": {
    "id": "123412341234"
   },
   "geometryType": "point"
}

HTTP Request

POST /tracking-events{trackingEventId}/activities

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
trackingEventId The id of the tracking event

Request Parameters

The tracking event activity request format is detailed here.

Response

The tracking event activity response format is detailed here.

Tracking Events Activities Response

The JSON document used to represent a tracking event activity resource has the following content:

Attribute Type Description
id UUID ID of the tracking event activity
userId UUID ID of the user associated with the activity
deviceId UUID ID of the user’s device
state String Can either be ‘started’, 'updated’, 'completed’, or 'terminated’. completed would be set when the entire tracking event has been completed. terminated means tracking has stopped for one device.
geometryType String 'point’
geometryValue[type] String 'feature’
geometryValue[geometry][type] String 'point’
geometryValue[geometry][coordinates] Array(float) longitude/latitude pair (east hemisphere is positive)
geometryValue[properties][accuracyInM] integer accuracy of measurement in meters.
geometryValue[properties][bearing] integer direction/bearing the device appears to be heading 0=North
geometryValue[properties][speedInMetersPerSec] float speed the device is going in meters per second.

Triggers

Triggers allow an external system to be notified when changes are made to a resource within InformaCast Mobile. Each trigger is associated with a particular resource through the same kind of path-based spec as is used in Permissions. For example, to track changes made to a particular User resource, you would create a trigger with the spec /users/{userId}. To be notified when changes are made to any user (including when new users are created), you would create a trigger with the wildcard character * standing in for the user id: /users/*. You can use multiple wildcards in a spec path: to be notified whenever any distribution list subscriptions are changed, you could create a trigger with the spec /distribution-lists/*/user-subscriptions/*.

Currently, triggers can either perform an HTTP POST to an arbitrary url, or they can send a message to an Amazon SQS Queue. This is controlled by the trigger’s type attribute, which can be either webhook or sqs.

Trigger Content

When a resource monitored by a trigger (one whose path matches the trigger’s spec attribute) is changed, the trigger will fire, reporting the InformaCast Mobile API action which caused the change.

If the trigger’s type is webhook, this will cause an HTTP POST to the url set in the trigger. If the url attribute includes a username and password (as specified by the standard URL format, i.e. https://{username}:{password}@{host}/{path}), then the HTTP request posted by the trigger will include an HTTP Basic Auth header corresponding to that username and password combination, to allow your web application to only process triggers with proper authentication. Since HTTP Basic Auth is not cryptographically secure on its own, we recommend it always be used in conjunction with SSL encryption (HTTPS).

If the trigger type is sqs, then the trigger will post a message to the Amazon SQS queue with the URL that matches the trigger’s url attribute.

Trigger payloads have the following structure:

{
 "type": "put",
 "path": "/users/8fa95070-fd3c-11e3-9c2f-c82a144feb17",
 "url": "https://api.icmobile.singlewire.com/api/v1/users/8fa95070-fd3c-11e3-9c2f-c82a144feb17"
 }

In either case, the payload of the trigger (the body of the HTTP POST or queue message) will be an application/json document with the following attributes:

Attribute Type Description
path String Identifies the path to the resource that has been changed.
type String Options: post put delete. The HTTP verb (action) which was applied to the resource identified by path.
url String The full URL at which the modified resource can be found.

No information about the new contents of the resource are reported in trigger body. The receiving application must use the normal InformaCast Mobile API to GET the resource in order to see its new contents. Note that the application must use an access token with sufficient permissions to access the resource in order to do that. Of course, if type was delete then the specified resource has been deleted and no longer exists.

List All Triggers

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 3

}

begin: 
    triggers = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(triggers)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/triggers?limit=3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 3
}

try: 
    triggers = requests.get(url, headers=headers, params=params).json()
    print(triggers)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 2,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "name": "User changes to SQS",
   "createdAt": "2014-12-23T00:31:57.254Z",
   "type": "sqs",
   "spec": "/users/*",
   "id": "1a0a3e60-8a3b-11e4-bcc0-7e206b5b3fb6",
   "url": "https://sqs.us-east-1.amazonaws.com/288649753650/icmobile"
  },
  {
   "permissions": [
    "delete",
    "put",
    "get"
   ],
   "name": "Batch load requests web hook",
   "createdAt": "2014-12-22T23:18:17.946Z",
   "type": "webhook",
   "spec": "/load-definitions/*/load-requests/*",
   "id": "cfed5ba0-8a30-11e4-8b3e-7e206b5b3fb6",
   "url": "https://username:password@my-host.com/icmobile-trigger/"
  }
 ]
}

Retrieves a list of all triggers. (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 manipulate triggers.)

HTTP Request

GET /triggers

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 three triggers were requested, there were only two available. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The trigger response format is detailed here.

Get a Trigger

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/triggers/cfed5ba0-8a30-11e4-8b3e-7e206b5b3fb6"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    trigger = JSON.parse(HTTParty.get(url, headers: headers))
    puts(trigger)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/triggers/cfed5ba0-8a30-11e4-8b3e-7e206b5b3fb6" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/triggers/cfed5ba0-8a30-11e4-8b3e-7e206b5b3fb6"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    trigger = requests.get(url, headers=headers).json()
    print(trigger)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "delete",
  "put",
  "get"
 ],
 "name": "Batch load requests web hook",
 "createdAt": "2014-12-22T23:18:17.946Z",
 "type": "webhook",
 "spec": "/load-definitions/*/load-requests/*",
 "id": "cfed5ba0-8a30-11e4-8b3e-7e206b5b3fb6",
 "url": "https://username:password@my-host.com/icmobile-trigger/"
}

Retrieves a single trigger by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /triggers/{triggerId}

Produces

application/json

Path Parameters

Parameter Description
triggerId The id of the Trigger of interest.

Response

The trigger response format is detailed here.

Create a Trigger

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Confirmation request changes'
,
    'spec': '/confirmation-requests/*'
,
    'type': 'sqs'
,
    'url': 'https://sqs.us-east-1.amazonaws.com/288649753650/icmobile'

}

begin: 
    trigger = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(trigger)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/triggers" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Confirmation request changes", \
       "spec": "/confirmation-requests/*", \
       "type": "sqs", \
       "url": "https://sqs.us-east-1.amazonaws.com/288649753650/icmobile"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/triggers"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Confirmation request changes',
    'spec': '/confirmation-requests/*',
    'type': 'sqs',
    'url': 'https://sqs.us-east-1.amazonaws.com/288649753650/icmobile'
}

try: 
    trigger = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(trigger)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": [
    "delete",
    "put",
    "get"
 ],
 "name": "Confirmation request changes",
 "createdAt": "2014-12-23T00:31:57.254Z",
 "type": "sqs",
 "spec": "/confirmation-requests/*",
 "id": "1a0a3e60-8a3b-11e4-bcc0-7e206b5b3fb6",
 "url": "https://sqs.us-east-1.amazonaws.com/288649753650/icmobile"
}

Creates a trigger that will post information about any changes made to a particular resource or group of resources.

HTTP Request

POST /triggers

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Description
name String The name to give the trigger, ideally to help explain its purpose.
spec String Identifies the path to the resource(s) the trigger will monitor and report changes to. The wildcard character * can stand in for any resource id.
type String Options: sqs webhook. The mechanism the trigger should use to report changes to the resource it is monitoring.
url String The URL of the Amazon SQS queue or web application to which the trigger should post reports about changes to the monitored resource.

Response

The trigger response format is detailed here.

Update a Trigger

# Continuing with the trigger object from the
# previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/triggers/1a0a3e60-8a3b-11e4-bcc0-7e206b5b3fb6" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Changes to any Confirmation Request"}'
# Continuing with the trigger object from the
# previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
    "delete",
    "put",
    "get"
 ],
 "name": "Changes to any Confirmation Request",
 "createdAt": "2014-12-23T00:31:57.254Z",
 "type": "sqs",
 "spec": "/confirmation-requests/*",
 "id": "1a0a3e60-8a3b-11e4-bcc0-7e206b5b3fb6",
 "url": "https://sqs.us-east-1.amazonaws.com/288649753650/icmobile"
}

Updates an existing trigger, changing any aspect of it.

HTTP Request

PUT /triggers/{triggerId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
triggerId The id of the Trigger being altered.

Request Parameters

Parameter Type Description
name String The name to give the trigger, ideally to help explain its purpose.
spec String Identifies the path to the resource(s) the trigger will monitor and report changes to. The wildcard character * can stand in for any resource id.
type String Options: sqs webhook. The mechanism the trigger should use to report changes to the resource it is monitoring.
url String The URL of the Amazon SQS queue or web application to which the trigger should post reports about changes to the monitored resource.

Response

The trigger response format is detailed here.

Remove a Trigger

# Continuing with the trigger object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/triggers/1a0a3e60-8a3b-11e4-bcc0-7e206b5b3fb6" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the trigger object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"Triggers\"} 1a0a3e60-8a3b-11e4-bcc0-7e206b5b3fb6"
}

Deletes a trigger, canceling any future reports about the resource it had been monitoring.

HTTP Request

DELETE /triggers/{triggerId}

Produces

application/json

Path Parameters

Parameter Description
triggerId The id of the Trigger that is to be cancelled. InformaCast Mobile will stop reporting changes to the resources described in that trigger’s spec.

Response

The deletion response format is detailed here.

Trigger Response

The JSON document used to represent a trigger resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this trigger was created.
id String The id of this specific trigger, allowing it to be manipulated or retrieved individually.
name String The name of the trigger.
permissions Array[String] Options: get put delete. What operations are possible on this trigger resource itself.
spec String Identifies the path to the resource(s) the trigger will monitor and report changes to.
type String Options: sqs webhook. The mechanism the trigger should use to report changes to the resource it is monitoring.
url String The URL of the Amazon SQS queue or web application to which the trigger should post reports about changes to the monitored resource.

Users

User resources serve two primary roles within InformaCast Mobile. They are both the recipients of Notifications (through their Distribution List Subscriptions and registration of Devices), and the agents of change, by logging in and obtaining access tokens, which grant access to features of the API through the user’s associations with Permissions and Security Groups.

List All Users

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 36,
  "partial": true,
  "previous": null,
  "next": "WyJhZHJpYW4gYWRzaGVhZCIsImZiNTA3YTMwLTAxNTktMTFlNC1iYzNkLTY4NWIzNThlYTg0NyJd",
  "data": [
    {
      "lock": false,
      "name": "Craig Smith",
      "securityGroups": [
        {
          "createdAt": "2014-05-16T14:50:23.126Z",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "id": "68a3db60-dd09-11e3-8c49-b8e856327746",
          "securityGroupId": "3aa5dec0-dd09-11e3-b17e-b8e856327746"
        }
      ],
      "passwordResetRequired": false,
      "tfaRemovalRequested": false,
      "createdAt": "2014-05-16T14:50:22.656Z",
      "email": "craig.smith@acme.com",
      "type": "regular",
      "idleTimeout": null,
      "permissions": ["delete", "put", "get"],
      "subscriptions": [
        {
          "createdAt": "2014-05-19T19:09:21.020Z",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
          "id": "152f93c0-df89-11e3-93bc-685b358ea847"
        },
        {
          "createdAt": "2014-07-22T19:15:42.057Z",
          "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
          "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
          "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
        }
      ],
      "id": "685c2400-dd09-11e3-8c49-b8e856327746",
      "providerIdpId": null,
      "isLicensed": true,
      "fromCloudUserLoader": false,
      "fromRegularUserLoader": false
    }
  ]
}

Retrieves the list of all Users. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /users

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 36 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally you can filter the results by matching on the User name or type, and find out the entire set of Domains to which each returned User belongs:

Parameter Type Description
includeDomains Boolean If true, include the list of Domains to which each User belongs.
includeIdp Boolean If true, include the User’s identity provider object. Note: in order to determine the value of passwordResetRequired or tfaRemovalRequested (when applicable), this parameter must be specified as true. Otherwise, passwordResetRequired and tfaRemovalRequested will not be included in the response.
name String Returns only Users whose names exactly match the supplied value.
type String Option: regular, application, anonymous. Return only Users whose type match the supplied value. Application users are for non-interactive use with permanent API tokens, such as with the InformaCast plugin; anonymous users cannot be created via the API, but are created when users register a phone anonymously to participate in a campaign.

Response

The user response format is detailed here.

Get a User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    user = JSON.parse(HTTParty.get(url, headers: headers))
    puts(user)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    user = requests.get(url, headers=headers).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
{
  "lock": false,
  "name": "Craig Smith",
  "securityGroups": [
    {
      "createdAt": "2014-05-16T14:50:23.126Z",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "id": "68a3db60-dd09-11e3-8c49-b8e856327746",
      "securityGroupId": "3aa5dec0-dd09-11e3-b17e-b8e856327746"
    }
  ],
  "passwordResetRequired": false,
  "tfaRemovalRequested": false,
  "createdAt": "2014-05-16T14:50:22.656Z",
  "email": "craig.smith@acme.com",
  "type": "regular",
  "permissions": ["delete", "put", "get"],
  "idleTimeout": null,
  "subscriptions": [
    {
      "createdAt": "2014-05-19T19:09:21.020Z",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
      "id": "152f93c0-df89-11e3-93bc-685b358ea847"
    },
    {
      "createdAt": "2014-07-22T19:15:42.057Z",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
      "id": "92bd3590-11d4-11e4-bdcd-685b358ea847"
    }
  ],
  "id": "685c2400-dd09-11e3-8c49-b8e856327746",
  "providerIdpId": null,
  "isLicensed": true,
  "fromCloudUserLoader": false,
  "fromRegularUserLoader": false
}

Retrieves a single user by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the user to retrieve.

Query Parameters

Parameter Type Description
includeDomains Boolean If true, include the entire list of Domains to which the User belongs.
includeIdp Boolean If true, include the User’s identity provider object. Note: in order to determine the value of passwordResetRequired or tfaRemovalRequested (when applicable), this parameter must be specified as true. Otherwise, passwordResetRequired and tfaRemovalRequested will not be included in the response.

Response

The user response format is detailed here.

Create a User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'email': 'craig.smith@acme.com'
,
    'name': 'Craig Smith'
,
    'lock': false

}

begin: 
    user = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(user)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"email": "craig.smith@acme.com", \
       "name": "Craig Smith", \
       "lock": false}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'email': 'craig.smith@acme.com',
    'name': 'Craig Smith',
    'lock': false
}

try: 
    user = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
{
  "lock": false,
  "name": "Craig Smith",
  "securityGroups": [ ],
  "passwordResetRequired": false,
  "tfaRemovalRequested": false,
  "createdAt": "2014-08-07T13:55:04.624Z",
  "email": "craig.smith@acme.com",
  "type": "regular",
  "permissions": ["delete", "put", "get"],
  "idleTimeout": null,
  "subscriptions": [ ],
  "id": "6ef1e300-1e3a-11e4-b08e-685b358ea847",
  "providerIdpId": null,
  "isLicensed": true,
  "fromCloudUserLoader": false,
  "fromRegularUserLoader": false
}

Create a new user.

HTTP Request

POST /users

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Request Parameters

Parameter Type Default Description
email String N/A The user’s email address. Maximum of 140 characters, and must be a valid email address; required for users whose type is regular. Anonymous and application users do not have email addresses.
lock Boolean false If true, the user will be locked (not allowed to access the system).
name String N/A The user’s name. Maximum of 140 characters.
idleTimeout Int N/A The user’s idle timeout override (between 15 and 120 minutes). null sets the user to the system default.
passwordReset­Required boolean N/A Whether the user will be forced to set a new password on next login (available only for Providers configured to use InformaCast’s own Identity Provider for login). Note that includeIdp=true must be passed as a query param for this value to be shown.
tfaRemoval­Requested boolean N/A Whether the user’s two factor authentication will be deactivated on next login (available only for Providers configured to use InformaCast’s own Identity Provider for login). Note that includeIdp=true must be passed as a query param for this value to be shown.
type String regular Option: regular, application, anonymous. Application users are for non-interactive use with permanent API tokens, such as with the InformaCast plugin; anonymous users cannot be created via the API, but are created when users register a phone anonymously to participate in a campaign.
providerIdpId String N/A The ID of the identity provider used for authenticating the user.
application String N/A Used only with users whose type is application; specifies the type of application. Application type cannot be changed after it is assigned to a new user. These are the types that are currently supported: mobile-plugin, user-loader, cloud-user-loader, desktop-registration, custom.

Response

The user response format is detailed here.

Update a User

# Continuing with the user object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body))))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/6ef1e300-1e3a-11e4-b08e-685b358ea847" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Craig Jacob Smith"}'
# Continuing with the user object from the
# previous example:
try:
    print(requests.put(url, headers=headers, data=json.dumps(data)).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "lock": false,
  "name": "Craig Jacob Smith",
  "securityGroups": [ ],
  "passwordResetRequired": false,
  "tfaRemovalRequested": false,
  "createdAt": "2014-08-07T13:55:04.624Z",
  "email": "craig.smith@acme.com",
  "type": "regular",
  "idleTimeout": 60,
  "permissions": ["delete", "put", "get"],
  "subscriptions": [ ],
  "id": "6ef1e300-1e3a-11e4-b08e-685b358ea847",
  "providerIdpId": null,
  "isLicensed": true,
  "fromCloudUserLoader": false,
  "fromRegularUserLoader": false
}

Updates an existing user.

HTTP Request

PUT /users/{userId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the user to update.

Request Parameters

Parameter Type Default Description
email String N/A The user’s email address. Maximum of 140 characters, and must be a valid email address; required for users whose type is regular. Anonymous and application users do not have email addresses.
name String N/A The user’s name. Maximum of 140 characters.
idleTimeout Int N/A The user’s idle timeout override (between 15 and 120 minutes). null sets the user to the system default.
lock Boolean false If true, the user will be locked (not allowed to access the system).
passwordReset­Required boolean N/A Whether the user will be forced to set a new password on next login (available only for Providers configured to use InformaCast’s own Identity Provider for login). Note that includeIdp=true must be passed as a query param for this value to be shown.
tfaRemoval­Requested boolean N/A Whether the user’s two factor authentication will be removed on next login (available only for Providers configured to use InformaCast’s own Identity Provider for login). Note that includeIdp=true must be passed as a query param for this value to be shown.
type String regular Option: regular, application, anonymous. Application users are for non-interactive use with permanent API tokens, such as with the InformaCast plugin; anonymous users cannot be created via the API, but are created when users register a phone anonymously to participate in a campaign.
providerIdpId String N/A The ID of the identity provider used for authenticating the user.

Response

The user response format is detailed here.

Remove a User

# Continuing with the user object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/6ef1e300-1e3a-11e4-b08e-685b358ea847" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the user object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted Users 6ef1e300-1e3a-11e4-b08e-685b358ea847"
}

Deletes an existing user.

HTTP Request

DELETE /users/{userId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the user to delete.

Response

The deletion response format is detailed here.

User Response

The JSON document used to represent a User resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this user 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 user belongs.
email String The user’s email address; will be missing for users whose type is anonymous or application.
id String The id of the user, for efficient retrieval, manipulation, or looking up sub-resources attached to the user.
idleTimeout Int The user’s idle timeout override (between 15 and 120 minutes). null sets the user to the system default.
loadSourceId String Reflects how the user was created. Contains a Load Definition id, if the user came from a batch load; omitted if the user was created individually.
lock boolean The user lock resource. If true, the user is in a locked state (not allowed to access the system).
name String The user’s name.
passwordReset­Required boolean Whether the user will be forced to set a new password on next login (available only for Providers configured to use InformaCast’s own Identity Provider for login). Note that includeIdp=true must be passed as a query param for this value to be shown.
tfaRemoval­Requested boolean Whether the user’s two factor authentication will be removed on next login (available only for Providers configured to use InformaCast’s own Identity Provider for login). Note that includeIdp=true must be passed as a query param for this value to be shown.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
providerIdpId String The ID of the identity provider used for authenticating the user.
providerIdp Object When includeIdp is true in your request, the user’s identity provider object will be included. This includes the following: id, name, isDefault (whether the user will use this IDP for authentication when no providerIdpId is specified), selfRegistrationEnabled (whether new users may use this identity provider for registering new accounts), type (e.g. google, azure, cirrus-idp, saml2), enabled.
securityGroups Array[SecurityGroup] The user’s security groups.
subscriptions Array[UserSubscription] The user’s subscriptions.
type String Option: regular, application, anonymous. Application users are for non-interactive use with permanent API tokens, such as with the InformaCast plugin; anonymous users cannot be created via the API, but are created when users register a phone anonymously to participate in a campaign.
isLicensed Boolean Whether the user is licensed to use the system; this value is changed exclusively by membership in SCIM groups.
fromCloud­UserLoader Boolean Whether the user’s source is the cloud user loader and is associated with a SCIM user.
fromRegular­UserLoader Boolean Whether the user’s source is a user loader, cloud or otherwise.
application String Used only with users whose type is application; specifies the type of application. These are the types that are currently supported: mobile-plugin, user-loader, cloud-user-loader, desktop-registration, custom.

User All Permissions

Provides a compact representation of all permissions granted to a user, including implicit permissions that would not be visible when listing User Permissions.

List All Permissions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/all-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/all-permissions" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/all-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
[
  {
    "spec": "/users",
    "verbs": ["get", "post"]
  },
  {
    "spec": "/users/*",
    "verbs": ["get", "put", "delete"]
  }
]

The full response has been abbreviated.

Retrieves the list of all the permissions assigned to a specified user, either directly or through membership in a Security Groups. If Domains are enabled, only the permissions that are relevant to the acting domain are returned.

HTTP Request

GET /users/{userId}/user-permissions

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose permissions are being looked up.

Response

The response is an array of objects with the following content:

Attribute Type Description
spec String Identifies the path to the resource(s) the user is permitted to act on.
verbs Array[String] Options: get put delete post patch. What operations are possible on the resource identified by spec.

User Devices

InformaCast Mobile Users may have up to five mobile devices registered to receive Notifications. The registration process allows the app running on the device to tell the API that the device is associated with the logged-in user, and to provide the platform-specific identifiers needed to send push notifications to that device. Currently, InformaCast Mobile supports Apple’s APNS, Google’s GCM, and SMS for push notifications.

List All Devices

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/e4e7860d-fb72-11e5-93a8-7b0393df5405/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    devices = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(devices)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/e4e7860d-fb72-11e5-93a8-7b0393df5405/devices?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/e4e7860d-fb72-11e5-93a8-7b0393df5405/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    devices = requests.get(url, headers=headers, params=params).json()
    print(devices)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "next": "WyJhZHJpYW4gYWRzaGVhZCIsImZiNTA3YTMwLTAxNTktMTFlNC1iYzNkLTY4NWIzNThlYTg0NyJd",
  "previous": null,
  "data": [
    {
      "deviceIdentifier": "3cab93ba8b953bccca6f877315d1f3760109ba49ccd6b492cf6ed5287b6459df",
      "permissions": [ "delete", "put", "get" ],
      "disabled": false,
      "presence": {
       "accuracyInM": 65,
       "updatedAt": "2016-05-26T21:04:07.129Z",
       "areaOfInterestIds": [ "53a05323-2384-11e6-a729-45e28217691a" ],
       "areasOfInterest": [
        {
         "id": "53a05323-2384-11e6-a729-45e28217691a",
         "name": "Clifton",
         "geometry_type": "circle",
         "radius_in_m": 1000,
         "latitude": 39.0,
         "longitude": -84.0,
         "synced_device_types": [ "mobile" ]
        }
       ],
       "areasOfInterestChecksum": "d9bd685e4e97a8c6c76fa85db9329d54"
      },
      "name": "6plus",
      "client": "",
      "createdAt": "2016-05-17T15:31:52.241Z",
      "type": "apns-sandbox",
      "build": "v2.9.0 D",
      "id": "7aa5aa10-1c44-11e6-8356-2d3985aff6cc",
      "userId": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
      "os": "9.3.2",
      "verified": true
    }
  ]
}

Retrieves the list of all devices registered to a particular user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. A user will generally be able to see all devices they registered, but ordinary users will not be able to see devices registered by other users.)

HTTP Request

GET /users/{userId}/devices

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose registered devices are to be retrieved.

Query Parameters

To make this example more concise, only the first device 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. If location information is not available or not supported on the device, the presence element will be null.

Response

The user device response format is detailed here.

Get a Device

Retrieves a single device registration based on the id values of the user to whom it is registered and the registration itself.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/e4e7860d-fb72-11e5-93a8-7b0393df5405/devices/2414af21-1859-11e6-8356-d91faee9f92b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    device = JSON.parse(HTTParty.get(url, headers: headers))
    puts(device)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/e4e7860d-fb72-11e5-93a8-7b0393df5405/devices/2414af21-1859-11e6-8356-d91faee9f92b" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/e4e7860d-fb72-11e5-93a8-7b0393df5405/devices/2414af21-1859-11e6-8356-d91faee9f92b"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    device = requests.get(url, headers=headers).json()
    print(device)
except RequestException as e:
    print('Unexpected error!', e)
{
  "deviceIdentifier": "d9zuUli33Rk:APA91bFt-4haXOuk9k5su_ritOG7qEygOmhfSlEgb_AbnZJtm4YQsiVn_eTy1nKOXBZ8b1yOv3oFto-VyF8p2_VQ7AP-6COBhLMdjgQJa_lIuj1rkTpWHAZYyL_ok3Z47r1dFITyORje",
  "permissions": [ "delete", "put", "get" ],
  "disabled": false,
  "presence": {
   "accuracyInM": 15,
   "updatedAt": "2016-05-26T18:09:38.097Z",
   "areaOfInterestIds": [],
   "areasOfInterest": [],
   "areasOfInterestChecksum": "8b01473620d610174ffa2c2255acc3c9"
  },
  "name": "dpi: samsung - GT-I9190",
  "client": "",
  "createdAt": "2016-05-12T15:49:41.787Z",
  "type": "Android",
  "build": "2.9.0 (217)",
  "id": "2414af21-1859-11e6-8356-d91faee9f92b",
  "userId": "e4e7860d-fb72-11e5-93a8-7b0393df5405",
  "os": "4.4.2",
  "verified": true
}

HTTP Request

GET /users/{userId}/devices/{deviceId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose registered devices are being examined.
deviceId The id of the specific device registration to retrieve.

Response

The user device response format is detailed here. If location information is not available or not supported on the device, the presence element will be null.

Register a Device

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'type': 'Android'
,
    'name': 'Nexus 7'
,
    'deviceIdentifier': 'BPA91bFpOikKATC523g5Z_4-1puPNa_oE8t1A7rsTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf2VMJ8h64OZfP9OgKotDtNis9Jwc7ZjmiJZWCNPy-hN-pSFKFPvJ3e2zfh8Sszb7ntGJYlbqrXw'
,
    'build': '2.9.0 (217)'
,
    'os': '4.4.2'

}

begin: 
    device = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(device)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"type": "Android", \
       "name": "Nexus 7", \
       "deviceIdentifier": "BPA91bFpOikKATC523g5Z_4-1puPNa_oE8t1A7rsTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf2VMJ8h64OZfP9OgKotDtNis9Jwc7ZjmiJZWCNPy-hN-pSFKFPvJ3e2zfh8Sszb7ntGJYlbqrXw", \
       "build": "2.9.0 (217)", \
       "os": "4.4.2"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'type': 'Android',
    'name': 'Nexus 7',
    'deviceIdentifier': 'BPA91bFpOikKATC523g5Z_4-1puPNa_oE8t1A7rsTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf2VMJ8h64OZfP9OgKotDtNis9Jwc7ZjmiJZWCNPy-hN-pSFKFPvJ3e2zfh8Sszb7ntGJYlbqrXw',
    'build': '2.9.0 (217)',
    'os': '4.4.2'
}

try: 
    device = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(device)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-07T18:09:42.118Z",
  "deviceIdentifier": "BPA91bFpOikKATC523g5Z_4-1puPNa_oE8t1A7rsTzEwlfWKE0jFH-TvjAmFL_1ZkSCq7VGNA6dGn3jDQ5BsdZAf2VMJ8h64OZfP9OgKotDtNis9Jwc7ZjmiJZWCNPy-hN-pSFKFPvJ3e2zfh8Sszb7ntGJYlbqrXw",
  "type": "Android",
  "presence": null,
  "name": "Nexus 7",
  "disabled": false,
  "client": "",
  "build": "2.9.0 (217)",
  "os": "4.4.2",
  "id": "010a7860-1e5e-11e4-b406-3c970e7ff560",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "verified": true
}

Registers a device as belonging to a particular user, so that when that user is supposed to receive a notification, a push can be sent to the device.

HTTP Request

POST /users/{userId}/devices

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to whom this device should be registered.

Request Parameters

Parameter Type Default Description
build String N/A The current build of the application.
client String N/A OAuth2 Client identifier used for push authentication. Defaults to Singlewire InformaCast Mobile Client appropriate for device type.
deviceIdentifier String N/A The device’s mobile number, APNS token, or GCM token (as determined by the value of the type parameter). This may be up to 4096 characters long.
disabled boolean false Should pushes to the device be suppressed? When disabled is true, this device will no longer be sent notifications. (For example, the API server will automatically disable a device with type apns if the APNS feebdack service informs it that the InformaCast Mobile app has been unistalled.)
name String N/A The device’s name. This may be up to 140 characters long.
os String N/A The version of the OS the application is running on.
presence­[accuracyInM] integer N/A The accuracy of area of interest calculations.
presence­[areaOfInterestIds] Array[uuid] N/A The area of interest ids containing the device.
presence­[areasOfInterest­Checksum] String N/A Aggregated current device location information with respect to monitored Areas of Interest for efficient validation.
type String N/A Options: Android, apns, apns-desktop, msteams-chat, phone-call, singlewire:email, SMS, WNS (see table for details)
verified boolean false (self) / true (others) Whether the user has confirmed ownership of this device

Response

The user device response format is detailed here.

Update a Device

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices/010a7860-1e5e-11e4-b406-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'type': 'phone-call'
,
    'name': 'Nexus Fire 2'
,
    'deviceIdentifier': '+12223334444'

}

begin: 
    device = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(device)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices/010a7860-1e5e-11e4-b406-3c970e7ff560" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"type": "phone-call", \
       "name": "Nexus Fire 2", \
       "deviceIdentifier": "+12223334444"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices/010a7860-1e5e-11e4-b406-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'type': 'phone-call',
    'name': 'Nexus Fire 2',
    'deviceIdentifier': '+12223334444'
}

try: 
    device = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(device)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "deviceIdentifier": "+12223334444",
  "createdAt": "2014-08-07T18:09:42.118Z",
  "type": "phone-call",
  "disabled": false,
  "presence": null,
  "client": null,
  "name": "Nexus Fire 2",
  "build": "",
  "os": "",
  "id": "010a7860-1e5e-11e4-b406-3c970e7ff560",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "verified": true
}

Update an existing user’s device within InformaCast Mobile.

HTTP Request

PUT /users/{userId}/devices/{deviceId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose device registration is being updated.
deviceId The id of the specific device registration to update.

Request Parameters

Parameter Type Default Description
build String N/A The current build of the application.
client String N/A OAuth2 Client identifier used for push authentication. Defaults to Singlewire InformaCast Mobile Client appropriate for device type.
deviceIdentifier String N/A The device’s mobile number, APNS token, or GCM token (as determined by the value of the type parameter). This may be up to 4096 characters long.
disabled boolean false Should pushes to the device be suppressed? When disabled is true, this device will no longer be sent notifications. (For example, the API server will automatically disable a device with type apns if the APNS feebdack service informs it that the InformaCast Mobile app has been unistalled.)
name String N/A The device’s name. This may be up to 140 characters long.
os String N/A The version of the OS the application is running on.
presence­[accuracyInM] integer N/A The accuracy of area of interest calculations.
presence­[areaOfInterestIds] Array[uuid] N/A The area of interest ids containing the device.
presence­[areasOfInterest­Checksum] String N/A Aggregated current device location information with respect to monitored Areas of Interest for efficient validation.
type String N/A Options: Android, apns, apns-desktop, msteams-chat, phone-call, singlewire:email, SMS, WNS (see table for details)
verified boolean false (self) / true (others) Whether the user has confirmed ownership of this device

Response

The user device response format is detailed here.

Remove a Device’s Registration

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices/010a7860-1e5e-11e4-b406-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices/010a7860-1e5e-11e4-b406-3c970e7ff560" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/devices/010a7860-1e5e-11e4-b406-3c970e7ff560"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"UserDevices\"} 010a7860-1e5e-11e4-b406-3c970e7ff560"
}

Removes a device from a user’s list of registered devices, so that it will no longer be contacted if that user receives a notification.

HTTP Request

DELETE /users/{userId}/devices/{deviceId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose device registration is being removed.
deviceId The id of the specific device registration to delete.

Response

The deletion response format is detailed here.

User Devices Response

The JSON document used to represent a user device resource has the following content:

Attribute Type Description
build String The current build of the application.
createdAt ISO 8601 date/time When this device registration was created.
updatedAt ISO 8601 date/time When this device registration was last updated.
client String The device name.
device­Identifier String The device’s mobile number, APNS token, or GCM token (as determined by the value of the type parameter).
disabled boolean Should pushes to the device be suppressed? When disabled is true, this device will no longer be sent notifications. (For example, the API server will automatically disable a device with type apns if the APNS feebdack service informs it that the InformaCast Mobile app has been unistalled.)
id String The id of this specific device registration, allowing it to be manipulated or retrieved individually.
name String The device name.
os String The OS version the application is running on.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
presence Presence Area of Interest information if location services were requested and are enabled. This value can be null if location services are not available or if no areas are being monitored.
type String N/A
userId String The id of the User to whom the device is registered.
verified boolean Whether the user has confirmed ownership of this device

Presence Response

The JSON document used to represent a Presence value has the following content:

Attribute Type Description
accuracyInM String The accuracy of area of interest calculations (in meters).
areasOfInterestIds Array[uuid] List of current Area of Interest ids containing the device.
areasOfInterest Array[AOI] Prefetched complete Area of Interest information.
areasOfInterest­Checksum String Aggregated current device location information with respect to monitored Areas of Interest for efficient validation.
updatedAt ISO 8601 date/time When this device registration was created.

User Domains

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 User Domains

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 2

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains?limit=2" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 2
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 6,
  "previous": null,
  "next": "2",
  "partial": true,
  "data": [
    {
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "name": "Grounds",
      "namePath": "/West Campus/Stadium/Grounds/",
      "createdAt": "2018-03-16T06:02:44.441Z",
      "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "userId": "42532c36-4478-11e6-9ba6-fb22bf89f89a"
    },
    {
      "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
      "permissions": [
        "delete",
        "put",
        "get"
      ],
      "name": "Vending",
      "namePath": "/West Campus/Stadium/Vending/",
      "createdAt": "2018-03-16T20:52:28.522Z",
      "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
      "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
      "userId": "42532c36-4478-11e6-9ba6-fb22bf89f89a"
    }
  ]
}

Retrieves the list of all Domains the User belongs to. (The permissions associated with the request, through the user attached to the access token, may limit the visibility of results.)

HTTP Request

GET /users/{userId}/domains

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose associated Domains 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 6 Domains assigned to the specified User when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Additionally, you can request the subdomains of any attached Domains, or the Domains the user can act in through one or more Security Groups, using query parameters. You can also filter the results by matching on the Domain 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 Domain appears in the response only once.
name string Returns only Domains whose names exactly match the supplied value.
recursive boolean If true, in addition to the Domains that are directly attached to the specified User, all their subdomains will be returned.
transitive boolean If true, in addition to Domains that are directly attached to the specified User, any Domains attached to Security Groups that are attached to the User, and all subdomains of any of these Domains will be returned (transitive takes precedence over recursive, so passing true for both is the same as just passing true for transitive).

Response

The Domain response format is detailed here. Additionally, the id of the user whose domains were requested is returned under the key userId inside each domain response.

If recursive is true, you get back the list of all Domains that are visible to the chosen User, because they are either a member of the Domain directly, or they are a member of one of its ancestors.

If transitive is true, you get back the list of all Domains in which the chosen User can act, 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 Domain response attributes, information explaining why the user is able to act in the Domain is added. The same Domain 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 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.

Check if a User belongs to a Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    domain = JSON.parse(HTTParty.get(url, headers: headers))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains/f04e3599-295b-11e8-b54b-abb9a309846e"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    domain = requests.get(url, headers=headers).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/f04e3599-295b-11e8-b54b-abb9a309846e/",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Vending",
  "namePath": "/West Campus/Stadium/Vending/",
  "createdAt": "2018-03-16T20:52:28.522Z",
  "id": "f04e3599-295b-11e8-b54b-abb9a309846e",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "userId": "42532c36-4478-11e6-9ba6-fb22bf89f89a"
}

Retrieves a single User Domain by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose membership in the Domain is being checked.
Id The id of the Domain whose Users are of interest.

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 the Domains that are directly attached to the specified User, all their subdomains will be considered.
transitive boolean If true, in addition to Domains that are directly attached to the specified User, any Domains attached to Security Groups that are attached to the User, and all their 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 Domain 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 Domain 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 User Domain

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'

}

begin: 
    domain = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(domain)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "a4e9e56c-28df-11e8-8c38-738c606ef19c"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'a4e9e56c-28df-11e8-8c38-738c606ef19c'
}

try: 
    domain = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(domain)
except RequestException as e:
    print('Unexpected error!', e)
{
  "path": "/90de0f6a-28df-11e8-8c38-e9fe0f3683de/9ca35dab-28df-11e8-8c38-235a5737f6bb/a4e9e56c-28df-11e8-8c38-738c606ef19c/",
  "permissions": [
    "delete",
    "put",
    "get"
  ],
  "name": "Grounds",
  "namePath": "/West Campus/Stadium/Grounds/",
  "createdAt": "2018-03-16T06:02:44.441Z",
  "id": "a4e9e56c-28df-11e8-8c38-738c606ef19c",
  "parentId": "9ca35dab-28df-11e8-8c38-235a5737f6bb",
  "userId": "42532c36-4478-11e6-9ba6-fb22bf89f89a"
}

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 /users/{userId}/domains

Produces

application/json

Path Parameters

Parameter Type Description
userId String The id of the User 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 User out of a parent Domain?
id String n/a The id of the Domain to which the User should be added.
promote Boolean false Allow this request to proceed even if it will promote the User out of one or more child Domains?

A User 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 User 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 User Domain

# Continuing with the domain object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/42532c36-4478-11e6-9ba6-fb22bf89f89a/domains/f04e3599-295b-11e8-b54b-abb9a309846e" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the domain object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted User Domain 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 /users/{userId}/domains/{id}

Produces

application/json

Path Parameters

Parameter Type Description
id String The id of the Domain from which the User should be removed.
userId 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.

User Extensions

User Extensions provide a mechanism for Extensions to store user-specific configuration information.

For example the “Do Not Disturb” device-filter extension allows each user to configure their own do-not-disturb window. In order to track those choices, the configuration information is stored under the id values of the user and the extension itself.

List All Extension Settings for a User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 3

}

begin: 
    extensions = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(extensions)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions?limit=3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 3
}

try: 
    extensions = requests.get(url, headers=headers, params=params).json()
    print(extensions)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 1,
 "partial": false,
 "previous": null,
 "next": null,
 "data": [
  {
   "permissions": [
    "put",
    "get"
   ],
   "extensionUrl": "http://localhost:8999/icm-dnd-service",
   "disabled": false,
   "config": {
    "type": "simple",
    "simple": {
     "start": "12:39Z",
     "end": "13:39Z"
    }
   },
   "name": "Do Not Disturb Notification Blocker",
   "createdAt": "2015-07-21T19:28:51.225Z",
   "type": "device-filter",
   "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
   "userId": "de7b51a0-5a1e-11e4-ab31-8a1d033dd637"
  }
 ]
}

Retrieves a list of all extensions configured for the specified user, along with the configuration information for that user and extension pair. (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 manipulate extensions.)

HTTP Request

GET /users/{userId}/extensions

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 three extensions were requested, there were only two available. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The user extension response format is detailed here.

Get Settings for a Single User Extension

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    settings = JSON.parse(HTTParty.get(url, headers: headers))
    puts(settings)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    settings = requests.get(url, headers=headers).json()
    print(settings)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "put",
  "get"
 ],
 "extensionUrl": "http://localhost:8999/icm-dnd-service",
 "disabled": false,
 "config": {
  "type": "simple",
  "simple": {
   "start": "12:39Z",
   "end": "13:39Z"
  }
 },
 "name": "Do Not Disturb Notification Blocker",
 "createdAt": "2015-07-21T19:28:51.225Z",
 "type": "device-filter",
 "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
 "userId": "de7b51a0-5a1e-11e4-ab31-8a1d033dd637"
}

Retrieves settings information for a single user extension by the id values of the user and extension. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/extensions/{extensionId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose extensions are being examined.
extensionId The id of the Extension of interest.

Response

The user extension response format is detailed here.

Update Settings for a User Extension

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'config': {
        'type': 'simple'
,
        'simple': {
            'start': '21:00Z'
,
            'end': '06:00Z'

}


}


}

begin: 
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"config": {"type": "simple", \
         "simple": {"start": "21:00Z", \
           "end": "06:00Z"}}}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/de7b51a0-5a1e-11e4-ab31-8a1d033dd637/extensions/b6d90e60-2a40-11e5-8134-9a9e6c05013a"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'config': {
        'type': 'simple',
        'simple': {
            'start': '21:00Z',
            'end': '06:00Z'
}

}

}

try: 
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
 "permissions": [
  "put",
  "get"
 ],
 "extensionUrl": "http://localhost:8999/icm-dnd-service",
 "disabled": false,
 "config": {
  "type": "simple",
  "simple": {
   "start": "21:00Z",
   "end": "06:00Z"
  }
 },
 "name": "Do Not Disturb Notification Blocker",
 "createdAt": "2015-07-21T19:28:51.225Z",
 "type": "device-filter",
 "id": "b77bb090-2fde-11e5-80c4-56847afe9799",
 "userId": "de7b51a0-5a1e-11e4-ab31-8a1d033dd637"
}

Updates the user-specific configuraton of an extension.

HTTP Request

PUT /users/{userId}/extensions/{extensionId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose extensions are being configured.
extensionId The id of the Extension being configured.

Request Parameters

Parameter Type Description
config JSON The configuration parameters for the extension. These will be sent to the extension itself for validation; the details are up to the extension, and you will need to consult the extension documentation to learn about them. In this example, the Do Not Disturb extension takes a “simple” configuration map which identifies the start and end of the do-not-disturb window in Coordinated Universal Time.

Response

The user extension response format is detailed here.

User Extension Response

The JSON document used to represent a extension resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this extension was created.
config JSON The configuration parameters for the extension for this user. These will be sent to the extension itself for validation; its details are up to the extension, and you will need to consult the extension documentation to learn about them.
deviceLimit integer For extensions of type device, identifies how many devices of the type provided by this extension may be associated with a single user.
deviceType String For extensions of type device, identifies the new type of device supported by the extension.
disabled boolean When true, the extension will no longer be used, and InformaCast Mobile will act as if it simply did not exist.
id String The id of this specific extension, allowing it to be manipulated or retrieved individually.
name String The name of the extension.
permissions Array[String] Options: get put. What operations are possible on this user extension resource itself.
type String Options: device device-filter. The kind of extension this is (as described in the Extensions section).
userId String The id of the user whose specific extension configuration information is being returned.

User Locations

InformaCast Mobile Users may store up to one hundred locations, and can then be searched for by queries based on those locations. Location-based queries use GeoJSON Linear Rings. For example, to find all users with locations in the polygon [[0,0],[-90,0],[-90,45],[0,43],[0,0]] you would append the URL-encoded version of that polygon after location.polygon: and use it as the q (search) parameter of a GET request to the Users resource.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'q': 'location.polygon%3A%5B%5B0%2C0%5D%2C%5B-90%2C0%5D%2C%5B-90%2C45%5D%2C%5B0%2C43%5D%2C%5B0%2C0%5D%5D'

}

begin: 
    user = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(user)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users?q=location.polygon%3A%5B%5B0%2C0%5D%2C%5B-90%2C0%5D%2C%5B-90%2C45%5D%2C%5B0%2C43%5D%2C%5B0%2C0%5D%5D" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'q': 'location.polygon%3A%5B%5B0%2C0%5D%2C%5B-90%2C0%5D%2C%5B-90%2C45%5D%2C%5B0%2C43%5D%2C%5B0%2C0%5D%5D'
}

try: 
    user = requests.get(url, headers=headers, params=params).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)

List All User Locations

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    locations = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(locations)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    locations = requests.get(url, headers=headers, params=params).json()
    print(locations)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
     "description": null,
     "permissions": [ "delete", "put", "get" ],
     "disabled": false,
     "deviceId": null,
     "name": "Home",
     "createdAt": "2015-06-15T20:27:50.435Z",
     "longitude": 43.034593,
     "id": "fe254730-139c-11e5-97be-ee186365dac3",
     "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
     "latitude": -89.421967
    }
  ]
}

Retrieves the list of all locations associated with a particular user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. A user will generally be able to see all locations they registered, but ordinary users will not be able to see locations registered by other users.)

HTTP Request

GET /users/{userId}/locations

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose locations are to be retrieved.

Query Parameters

To make this example more concise, only the first device was requested using the API’s pagination parameters. The response reflects this, as well as the fact that it was the only one available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The user location response format is detailed here.

Get a Location

Retrieves a single location based on the id values of the user to whom it is registered and the location itself.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations/fe254730-139c-11e5-97be-ee186365dac3"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    location = JSON.parse(HTTParty.get(url, headers: headers))
    puts(location)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations/fe254730-139c-11e5-97be-ee186365dac3" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations/fe254730-139c-11e5-97be-ee186365dac3"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    location = requests.get(url, headers=headers).json()
    print(location)
except RequestException as e:
    print('Unexpected error!', e)
{
  "description": null,
  "permissions": [ "delete", "put", "get" ],
  "disabled": false,
  "deviceId": null,
  "name": "Home",
  "createdAt": "2015-06-15T20:27:50.435Z",
  "longitude": 43.034593,
  "id": "fe254730-139c-11e5-97be-ee186365dac3",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "latitude": -89.421967
}

HTTP Request

GET /users/{userId}/locations/{locationId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose locations are being examined.
locationId The id of the specific location to retrieve.

Response

The user location response format is detailed here.

Add a Location

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'Home'
,
    'latitude': -89.421967
,
    'longitude': 43.034593

}

begin: 
    location = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(location)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "Home", \
       "latitude": -89.421967, \
       "longitude": 43.034593}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'Home',
    'latitude': -89.421967,
    'longitude': 43.034593
}

try: 
    location = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(location)
except RequestException as e:
    print('Unexpected error!', e)
{
  "description": null,
  "permissions": [ "delete", "put", "get" ],
  "disabled": false,
  "deviceId": null,
  "name": "Home",
  "createdAt": "2015-06-15T20:27:50.435Z",
  "longitude": 43.034593,
  "id": "fe254730-139c-11e5-97be-ee186365dac3",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "latitude": -89.421967
}

Associates a location with a particular user, so that when geographic searches are performed which match that location, the user is included.

HTTP Request

POST /users/{userId}/locations

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User with whom this location should be associated.

Request Parameters

Parameter Type Default Description
descripton String N/A The location’s description, to help the user recall its purpose.
deviceId String N/A The identifier of a device, if any, to associate with this location. The device will then presumably post updates to the location as it moves around.
disabled boolean false Should this location be suppressed? When disabled is true, this location will no longer cause the user to be included in geographic search results which cover it.
latitude float N/A The geographic latitude of the location, in decimal degrees.
longitude float N/A The geographic longitude of the location, in decimal degrees.
name String N/A The location’s name, to help the user identify its nature and purpose.

Response

The user location response format is detailed here.

Update a Location

# Continuing with the location object from
# the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations/fe254730-139c-11e5-97be-ee186365dac3" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"description": "Where the heart is."}'
# Continuing with the location object from
# the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "description": "Where the heart is.",
  "permissions": [ "delete", "put", "get" ],
  "disabled": false,
  "deviceId": null,
  "name": "Home",
  "createdAt": "2015-06-15T20:27:50.435Z",
  "longitude": 43.034593,
  "id": "fe254730-139c-11e5-97be-ee186365dac3",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "latitude": -89.421967
}

Update an existing user location within InformaCast Mobile.

HTTP Request

PUT /users/{userId}/locations/{locationId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose location is being updated.
locationId The id of the specific user location to update.

Request Parameters

Parameter Type Default Description
descripton String N/A The location’s description, to help the user recall its purpose.
deviceId String N/A The identifier of a device, if any, to associate with this location. The device will then presumably post updates to the location as it moves around.
disabled boolean false Should this location be suppressed? When disabled is true, this location will no longer cause the user to be included in geographic search results which cover it.
latitude float N/A The geographic latitude of the location, in decimal degrees.
longitude float N/A The geographic longitude of the location, in decimal degrees.
name String N/A The location’s name, to help the user identify its nature and purpose.

Response

The user location response format is detailed here.

Remove a User Location

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations/fe254730-139c-11e5-97be-ee186365dac3"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations/fe254730-139c-11e5-97be-ee186365dac3" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/locations/fe254730-139c-11e5-97be-ee186365dac3"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"UserLocations\"} fe254730-139c-11e5-97be-ee186365dac3"
}

Removes a location from a user’s list of associated locations, so that it will no longer cause the user to be found when geographic searches include that location.

HTTP Request

DELETE /users/{userId}/locations/{locationId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose device registration is being removed.
locationId The id of the specific location to delete.

Response

The deletion response format is detailed here.

User Locations Response

The JSON document used to represent a user location resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this location was created.
descripton String The location’s description, to help the user recall its purpose.
deviceId UUID The identifier of a device, if any, to associate with this location. The device will then presumably post updates to the location as it moves around.
disabled boolean Should this location be suppressed? When disabled is true, this location will no longer cause the user to be included in geographic search results which cover it.
id String The id of this specific location, allowing it to be manipulated or retrieved individually.
latitude float The geographic latitude of the location, in decimal degrees.
longitude float The geographic longitude of the location, in decimal degrees.
name String The location’s name, to help the user identify its nature and purpose.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
userId String The id of the User to whom the location is registered.

User Message Templates

A resource for users who have opted out of receiving available Message Templates. Note that not all message templates are available for opting out. An administrator must mark the message template appropriately.

List All User Message Template Settings

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    settings = JSON.parse(HTTParty.get(url, headers: headers))
    puts(settings)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/message-templates" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/message-templates"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    settings = requests.get(url, headers=headers).json()
    print(settings)
except RequestException as e:
    print('Unexpected error!', e)
{
 "total": 0,
 "previous": null,
 "next": null,
 "partial": false,
 "data": []
}

This never returns any values because message templates no longer support opting out.

HTTP Request

GET /users/{userId}/message-templates

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose message template settings are to be retrieved.

Response

The user message template response is always an emtpy list because this feature is no longer available for message templates.

User Notifications

This resource provides a view of all Notifications that were sent to a particular User. The user may never have viewed the notification, but it was sent to a distribution list that the user was subscribed to at the time.

The Notification resource may include sub-resources which contain audio, image, and Activities. Activities track how the User has interacted with the Notification, such as marking it read, responding to a Confirmation Request, etc.

List All Notifications for a Specific User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    messages = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(messages)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    messages = requests.get(url, headers=headers, params=params).json()
    print(messages)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 5,
  "partial": true,
  "next": "IjY5NTMyZDcwLTFlNjAtMTFlNC1iMDhlLTY4NWIzNThlYTg0NyI=",
  "previous": null,
  "data": [
    {
      "subject": "Please check your home. The temperature just reached 57ºF",
      "read": false,
      "distributionListIds": ["13b32cf0-df89-11e3-93bc-685b358ea847"],
      "initiatorId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "initiator": {
        "createdAt": "2014-05-16T14:50:22.656Z",
        "id": "685c2400-dd09-11e3-8c49-b8e856327746",
        "passwordResetRequired": false,
        "email": "craig.smith@singlewire.com",
        "name": "Craig Smith",
        "lock": { "start": "2014-03-16T14:00:00.000Z", "end": "2014-09-16T14:00:00.000Z" }
      },
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "imageMimeType": "image/png",
      "image": 15859,
      "audio": 12555,
      "confirmationRequestId": "4f599e70-df83-11e3-93bc-685b358ea847",
      "confirmationResponse": null,
      "createdAt": "2014-08-07T18:27:10.553Z",
      "dynamicReplyText": null,
      "messageTemplateId": "85a66790-df80-11e3-93bc-685b358ea847",
      "permissions": ["delete", "put", "get"],
      "body": "You are receiving this notification because your home has just reached a temperature of 57ºF which is outside your defined threshold.\n\nDo you need assistance?",
      "id": "71f4f490-1e60-11e4-b08e-685b358ea847",
      "confirmationRequest": {
        "expiration": "2014-08-07T23:27:10.571Z",
        "escalationRules": [],
        "dynamicReplies": [],
        "createdAt": "2014-05-19T18:28:01.623Z",
        "id": "4f599e70-df83-11e3-93bc-685b358ea847",
        "expirationPeriod": 18000,
        "options": ["Yes", "No"],
        "name": "Do you need assistance?"
      }
    }
  ]
}

Retrieves the list of all notifications which were sent to the specified user. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. A user will generally be able to see all notifications sent to them, but ordinary users will not be able to see notifications sent to other users.)

HTTP Request

GET /users/{userId}/notifications

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User

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 five available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The user notification response format is detailed here.

Get a Specific User’s Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/71f4f490-1e60-11e4-b08e-685b358ea847"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    message = JSON.parse(HTTParty.get(url, headers: headers))
    puts(message)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/71f4f490-1e60-11e4-b08e-685b358ea847" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/71f4f490-1e60-11e4-b08e-685b358ea847"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    message = requests.get(url, headers=headers).json()
    print(message)
except RequestException as e:
    print('Unexpected error!', e)
{
  "subject": "Please check your home. The temperature just reached 57ºF",
  "read": false,
  "distributionListIds": ["13b32cf0-df89-11e3-93bc-685b358ea847"],
  "initiatorId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "initiator": {
    "createdAt": "2014-05-16T14:50:22.656Z",
    "id": "685c2400-dd09-11e3-8c49-b8e856327746",
    "passwordResetRequired": false,
    "email": "craig.smith@singlewire.com",
    "name": "Craig Smith",
    "lock": { "start": "2014-03-16T14:00:00.000Z", "end": "2014-09-16T14:00:00.000Z" }
  },
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "imageMimeType": "image/png",
  "image": 15859,
  "audio": 12555,
  "confirmationRequestId": "4f599e70-df83-11e3-93bc-685b358ea847",
  "confirmationResponse": null,
  "createdAt": "2014-08-07T18:27:10.553Z",
  "dynamicReplyText": null,
  "messageTemplateId": "85a66790-df80-11e3-93bc-685b358ea847",
  "permissions": ["delete", "put", "get"],
  "body": "You are receiving this notification because your home has just reached a temperature of 57ºF which is outside your defined threshold.\n\nDo you need assistance?",
  "id": "71f4f490-1e60-11e4-b08e-685b358ea847",
  "confirmationRequest": {
    "expiration": "2014-08-07T23:27:10.571Z",
    "escalationRules": [],
    "dynamicReplies": [],
    "createdAt": "2014-05-19T18:28:01.623Z",
    "id": "4f599e70-df83-11e3-93bc-685b358ea847",
    "expirationPeriod": 18000,
    "options": ["Yes", "No"],
    "name": "Do you need assistance?"
  }
}

Retrieves a single user notification by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/notifications/{notificationId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User of interest.
notificationId The id of the specific notification to retrieve.

Response

The user notification response format is detailed here.

Remove a Notification from a Specific User’s List

# Continuing with the notification object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/71f4f490-1e60-11e4-b08e-685b358ea847" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the notification object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"UserNotifications\"} 71f4f490-1e60-11e4-b08e-685b358ea847"
}

Deletes a notification from the list associated with a particular user. When a user no longer wishes to see the notification in their “in box” this method is the appropriate way to remove it. The fact that the user was sent the notification will still be visible to administrators through the Notification Recipients resource.

HTTP Request

DELETE /users/{userId}/notifications/{notificationId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose notification is to be deleted.
notificationId The id of the specific notification to delete.

Response

The deletion response format is detailed here.

Get User Notification Audio

# Continuing with the notification object from
# the previous example:
begin:
    sound = HTTParty.get(url, headers: headers)
    puts(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/6ef1e300-1e3a-11e4-b08e-685b358ea847/notifications/71f4f490-1e60-11e4-b08e-685b358ea847/audio" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the notification object from
# the previous example:
try:
    sound = requests.get(url, headers=headers)
    print(sound.headers['content-type'])   # audio/wav
    f = open('audio.wav', 'w')
    f.write(sound.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Produces a binary stream of audio data, with the specific MIME type identified in the response header.

Retrieves the audio, if any, that was sent with the notification, as a binary stream. Typically this is μ-law encoded compressed audio.

Deprecation warning: Requesting conversion of the audio format by specifying a value of pcm for the convert request parameter is no longer necessary, because the content-type header returned now allows the audio to be used as-is. This query parameter will no longer cause the audio format to be converted in a future release.

HTTP Request

GET /users/{userId}/notifications/{notificationId}/audio

Produces

audio/wav, audio/u-law

Path Parameters

Parameter Description
userId The id of the User whose notification is being worked with.
notificationId The id of the specific notification for which the audio data is desired.

Request Parameters

Parameter Type Default Description
convert String null Deprecated: Specify a value of pcm to request that the server convert the audio to PCM (WAV) format from μ-law. This takes more network bandwidth, so should only be done if the client cannot handle μ-law compression.

Get User Notification Image

# Continuing with the notification object from
# the previous example:
begin:
    pic = HTTParty.get(url, headers: headers)
    puts(pic.headers['content-type'])   # e.g. image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/6ef1e300-1e3a-11e4-b08e-685b358ea847/notifications/71f4f490-1e60-11e4-b08e-685b358ea847/image" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
# Continuing with the notification object from
# the previous example:
try:
    pic = requests.get(url, headers=headers)
    print(pic.headers['content-type'])   # e.g. image/png
    f = open('picture.png', 'w')
    f.write(pic.content)
    f.close()
except RequestException as e:
    print('Unexpected error!', e)

Produces a binary stream of the image data, with the specific MIME type identified in the response header.

Retrieves the image, if any, that was sent with the notification, as a binary stream.

HTTP Request

GET /users/{userId}/notifications/{notificationId}/image

Produces

image/png image/jpeg image/gif

Path Parameters

Parameter Description
userId The id of the User whose notification is being worked with.
notificationId The id of the specific notification for which the image data is desired.

User Notification Response

The JSON document used to represent a user notification resource has the following content:

Attribute Type Description
audio Integer The size in bytes of the audio sent with this notification, or zero if there is none.
body String The body of text of the notification.
confirmation­Request ConfirmationRequest The Confirmation Request attached to the notification, if there was one.
confirmation­RequestId String The id of the Confirmation Request, above. This is what is actually stored; the expanded details about the Confirmation Request are returned as a convenience, to save clients from having to issue a separate request to look them up.
confirmation­Response String The response this user chose for the Confirmation Request, if they have responded already.
dynamic­Reply­Text String If a Dynamic Reply was sent in response to confirmation, the text will be listed here.
createdAt ISO 8601 date/time When this notification was sent.
distribution­ListIds Array[String] A list of the ids of all distribution lists this notification was sent to.
id String The id of this specific notification, allowing it to be manipulated or retrieved individually, and providing access to its audio, image, and Activities.
image Integer The size in bytes of the image sent with this notification, or zero if there is none.
image­MimeType String Options: image/png image/jpeg image/gif. The format in which the image data will be delivered, if there is an image associated with this notification.
initiator User Embeds information from the User record of the sender of the notification.
initiatorId String The id of the sender of the notification, above.
message­TemplateId String The id of the Message Template on which this Notification was based.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
read Boolean An indication of whether this user has seen this notification. Initially set to false, will become true if a readStatus activity with value true is posted (until a later one with value false is posted to mark it as unread again).
read­Timestamp ISO 8601 date/time The most recent time at which this notification was marked as read by this user. No value is returned if read is currently false.
subject String The subject text of this notification.
userId String The id of the User whose notification is being worked with.

User Notification Activities

The user notification activities resource provides a mechanism for tracking and reviewing interactions a User has had with a Notification, such as marking it read or unread, or responding to an associated Confirmation Request.

List All Activities for a User Notification

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    activities = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(activities)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    activities = requests.get(url, headers=headers, params=params).json()
    print(activities)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "next": "WyI2OTUzMmQ3MC0xZTYwLTExZTQtYjA4ZS02ODViMzU4ZWE4NDciLCJkYTY0ZDk1MC0xZTY1LTExZTQtYjA4ZS02ODViMzU4ZWE4NDciXQ==",
  "previous": null,
  "data": [
    {
      "readStatus": "read",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
      "confirmationOption": null,
      "notificationId": "69532d70-1e60-11e4-b08e-685b358ea847",
      "createdAt": "2014-08-07T19:04:35.917Z",
      "type": "set-read-status",
      "permissions": ["delete", "put", "get"],
      "id": "ac4c4fd0-1e65-11e4-b08e-685b358ea847"
    }
  ]
}

Retrieves the list of all activities recorded for the specified user and notification. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. A user will generally be able to see all activities performed by themselves, but non-administrative users will not be able to see the activities of other users.)

HTTP Request

GET /users/{userId}/notifications/{notificationId}/activities

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User of interest.
notificationId The id of the Notification to that User for which activity information is desired.

Query Parameters

To make this example more concise, only the first activity 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 user notification activity response format is detailed here.

Get a User Notification Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities/ac4c4fd0-1e65-11e4-b08e-685b358ea847"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    activity = JSON.parse(HTTParty.get(url, headers: headers))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities/ac4c4fd0-1e65-11e4-b08e-685b358ea847" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities/ac4c4fd0-1e65-11e4-b08e-685b358ea847"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    activity = requests.get(url, headers=headers).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "readStatus": "read",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "confirmationOption": null,
  "notificationId": "69532d70-1e60-11e4-b08e-685b358ea847",
  "createdAt": "2014-08-07T19:04:35.917Z",
  "type": "set-read-status",
  "permissions": ["delete", "put", "get"],
  "id": "ac4c4fd0-1e65-11e4-b08e-685b358ea847"
}

Retrieves a single user notification activity by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/notifications/{notificationId}/activities/{activityId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User of interest.
notificationId The id of the specific Notification whose activities are being examined.
activityId The id of the specific activity to retrieve.

Response

The user notification activity response format is detailed here.

Create a User Notification Activity

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'type': 'set-read-status'
,
    'readStatus': 'read'

}

begin: 
    activity = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(activity)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"type": "set-read-status", \
       "readStatus": "read"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/notifications/69532d70-1e60-11e4-b08e-685b358ea847/activities"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'type': 'set-read-status',
    'readStatus': 'read'
}

try: 
    activity = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(activity)
except RequestException as e:
    print('Unexpected error!', e)
{
  "readStatus": "read",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746",
  "confirmationOption": null,
  "notificationId": "69532d70-1e60-11e4-b08e-685b358ea847",
  "createdAt": "2014-08-07T19:22:41.073Z",
  "type": "set-read-status",
  "permissions": ["delete", "put", "get"],
  "id": "3319fa10-1e68-11e4-b08e-685b358ea847"
}

Record an interaction between a User and a Notification they received. Currently, two different kinds of interaction can be reported, and they are differentiated by the value sent in the type parameter.

HTTP Request

POST /users/{userId}/notifications/{notificationId}/activities

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose activity is being recorded.
notificationId The id of the Notification for which an activity is being reported.

Request Parameters

Parameter Type Default Description
type String N/A Options: set-read-status, confirmation. The type of activity to record. The type confirmation is only valid if the Notification was sent with a Confirmation Request and no response has yet been recorded for this user.
confir­mation­Option String N/A The confirmation request option chosen by the user as a response. Only valid when type is confirmation, and must be one of the values present in the options list of the associated Confirmation Request.
read­Status String N/A Options: read, unread. Only valid when type is set-read-status. Use the value read to mark the notification as read by this user, unread as yet-to-be-read. The message may be repeatedly marked as read and unread over time, the most recent activity is considered the current state.

Response

The user notification activity response format is detailed here.

User Notification Activities Response

The JSON document used to represent a user notification activity resource has the following content:

Attribute Type Description
confirmation­Option String When the type attribute is confirmation, this contains the Confirmation Request response the user has chosen. This will be a value from the options list of the confirmation request attached to the notification, and there will be at most one activity of this type recorded for this user and notification.
dynamic­Reply­Text String If a Dynamic Reply was sent in response to confirmation, the text will be listed here.
createdAt ISO 8601 date/time When this activity was created.
id String The id of this specific activity, allowing it to be manipulated or retrieved individually.
notificationId String The id of the Notification whose activities are being examined.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
readStatus String Present when the type attribute is set-read-status, and will have the value read or unread. Marks the notification as read or unread as of the time of this activity. The read status can be toggled multiple times; the value set by the most recent activity is considered the current state.
type String Options: set-read-status, confirmation sms-sent, sms-received, call-placed, call-answered, sms-failed, call-failed, email-queued, email-sent, email-failed, dynamic-reply. Identifies the type of activity that was recorded. Extensions may add more type values; this is where the email-related values came from. Such extension-defined types will not be present in the API Explorer documentation, since the API is not aware of them.
userId String The id of the User whose notification is being recorded.

User Permissions

Permissions are required to perform any action with the InformaCast Mobile API. User Permissions are a direct assignment of a permission to a specific User. These are often implicitly granted by the system, for example, to allow a user to view a notification that they sent, even if they lack the ability to see other notifications. Manual assignment of permissions is usually done through Security Groups, which provide a way to group permissions into a named, logical collection, which can then be tied to users.

When validating an action that a user is trying to perform through the API, the User Permissions assigned directly to the user (through the access token which accompanies all API requests) are combined with any that come from security groups to which the user belongs. Each permission is made up of two attributes: the spec which identifies the resource being controlled, and the verb which identifies the action (HTTP method) being permitted. For example, a permission granting the ability to read a particular User resource would use the spec /users/{userId} and a verb of get. To grant the ability to read every user, the spec would use the * wildcard character rather than a specific user id. This same pattern can also be applied with the verbs post (create), put (update), and delete. In the case of post permissions, a trailing /* is not required to give “create” access to a specific resource, because the id value is not assigned until after the post action is in progress.

When Domains are in use, Users are assigned to Domains, granting them the ability to act in those Domains and their subdomains (they may also have access to Domains through membership in Security Groups). Permissions that refer to Domain-enabled resources, unless their spec values tie them to a single resource by id, are Domain scoped and will be attached to the acting Domain that was in effect when the Permision was created. This means the permission will only operate within that Domain and its subdomains.

Implicit User Permissions

As noted above, in addition to explicitly granted permissions, all users are implicitly and automatically granted a set of permissions to enable basic use of the system. These implicit permissions are not stored, and will not show up when listing user permissions. They are:

Verb Spec
get /users/{userId}/notifications/*
delete /users/{userId}/notifications/*
get /session/*
get /session
delete /session/*
post /users/{userId}/notifications/*/activities
get /users/{userId}/notifications//activities/
get /users/{userId}/notifications/*/image
get /users/{userId}/notifications/*/audio
get /users/{userId}/subscriptions/*
get /users/{userId}/devices/*
delete /users/{userId}/devices/*
put /users/{userId}/devices/*
post /users/{userId}/devices
get /users/{userId}/security-groups/*
get /users/{userId}/user-permissions/*
get /users/{userId}/locations/*
put /users/{userId}/locations/*
delete /users/{userId}/locations/*
post /users/{userId}/locations
get /users/{userId}/extensions/*
put /users/{userId}/extensions/*

List All Permissions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    perms = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(perms)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    perms = requests.get(url, headers=headers, params=params).json()
    print(perms)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 99,
  "partial": true,
  "next": "IjY4NjM3NzAxLWRkMDktMTFlMy04YzQ5LWI4ZTg1NjMyNzc0NiI=",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "createdAt": "2014-05-16T14:50:22.704Z",
      "verb": "post",
      "spec": "/notifications",
      "id": "68637700-dd09-11e3-8c49-b8e856327746",
      "domainId": null,
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
    }
  ]
}

This permission means the user is able to create (send) Notifications.

Retrieves the list of all the permissions assigned directly to a specified user. They may have other permissions indirectly, through membership in Security Groups.

HTTP Request

GET /users/{userId}/user-permissions

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose permissions are being looked up.

Query Parameters

To make this example more manageable, only the first permission was requested using the API’s pagination parameters. The response reflects this, as well as the fact that there were a total of 99 available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The user permission response format is detailed here.

Get a Permission

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions/68637700-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    perm = JSON.parse(HTTParty.get(url, headers: headers))
    puts(perm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions/68637700-dd09-11e3-8c49-b8e856327746" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions/68637700-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    perm = requests.get(url, headers=headers).json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-05-16T14:50:22.704Z",
  "verb": "post",
  "spec": "/notifications",
  "id": "68637700-dd09-11e3-8c49-b8e856327746",
  "domainId": null,
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

Retrieves a single user permission by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/user-permissions/{userPermissionId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User of interest.
userPermissionId The id of the specific permission to retrieve.

Response

The user permission response format is detailed here.

Add Permissions to a User

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'spec': '/confirmation-requests/*'
,
    'verb': 'get'

}

begin: 
    perm = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(perm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"spec": "/confirmation-requests/*", \
       "verb": "get"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'spec': '/confirmation-requests/*',
    'verb': 'get'
}

try: 
    perm = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(perm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-08T16:25:11.538Z",
  "verb": "get",
  "spec": "/confirmation-requests/*",
  "id": "91e5a520-1f18-11e4-b784-685b358ea847",
  "domainId": null,
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

This permission grants the user the ability to view all Confirmation Requests.

Grants a user the permission to perform a specific action on a specified resource or list of resources.

Tied Extensions

There are two pairs of extensions which are now treated by the user interface as a single concept: the iOS and Android push extensions are jointly managed as InformaCast for iOS/Android, and the macOS and Windows push extensions are jointly managed as InformaCast for Mac/Windows. Because of this, granting a permission to one of either pair will automatically grant permission to the other.

HTTP Request

POST /users/{userId}/user-permissions

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to whom permission is being granted.

Request Parameters

Parameter Type Default Description
spec String N/A Identifies the path to the resource(s) the user is being permitted to act on.
verb String N/A Options: get post put delete. The action (HTTP method) which is to be permitted.
promote Boolean false Automatically delete any matching user permissions attached to subdomains of the current acting Domain when creating this one?

Response

The user permission response format is detailed here.

Update a Permission

# Continuing with the user permission object
# from the previous example:
begin:
    updated_perm = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated_perm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions/91e5a520-1f18-11e4-b784-685b358ea847" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"spec": "/confirmation-requests/*", \
       "verb": "delete"}'
# Continuing with the user permission object
# from the previous example:
try:
    updated_perm = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated_perm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "createdAt": "2014-08-08T16:25:11.538Z",
  "verb": "delete",
  "spec": "/confirmation-requests/*",
  "id": "91e5a520-1f18-11e4-b784-685b358ea847",
  "domainId": null,
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

This permission grants the user the ability to delete any Confirmation Request.

Updates an existing user permission, to change the spec or the verb, as needed.

Tied Extensions

There are two pairs of extensions which are now treated by the user interface as a single concept: the iOS and Android push extensions are jointly managed as InformaCast for iOS/Android, and the macOS and Windows push extensions are jointly managed as InformaCast for Mac/Windows. Because of this, granting or revoking a permission to one of either pair will automatically grant or revoke permission to the other.

HTTP Request

PUT /users/{userId}/user-permissions/{userPermissionId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose permission is being altered.
userPermissionId The id of the specific permission to change.

Request Parameters

Parameter Type Default Description
spec String N/A Identifies the path to the resource(s) the user is being permitted to act on.
verb String N/A Options: get post put delete. The action (HTTP method) which is to be permitted.
promote Boolean false Automatically delete any matching user permissions attached to subdomains of the current acting Domain when updating this one?

Response

The user permission response format is detailed here.

Revoke a Permission

# Continuing with the user permission object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/user-permissions/91e5a520-1f18-11e4-b784-685b358ea847" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the user permission object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"UserPermissions\"} 91e5a520-1f18-11e4-b784-685b358ea847"
}

Removes a previously granted permission from a user.

Tied Extensions

There are two pairs of extensions which are now treated by the user interface as a single concept: the iOS and Android push extensions are jointly managed as InformaCast for iOS/Android, and the macOS and Windows push extensions are jointly managed as InformaCast for Mac/Windows. Because of this, revoking a permission to one of either pair will automatically revoke permission to the other.

HTTP Request

DELETE /users/{userId}/user-permissions/{userPermissionId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose permission is being revoked.
userPermissionId The id of the specific permission to revoke.

Response

The deletion response format is detailed here.

User Permission Response

The JSON document used to represent a user permission resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this permission was created.
domainId String Limits the maximum scope at which the permission can be applied: will be null unless Domains are enabled and the permission is domain-scoped (that is, it can match more than one domain-enabled resource, rather than referring to a specific resource by id). In those cases, for Domain-enabled resources, only those belonging to the specified Domain or its subdomains are affected by the permission.
id String The id of this specific permission, allowing it to be manipulated or retrieved individually.
permissions Array[String] Options: get put delete. What operations are possible on this permission resource itself.
spec String Identifies the path to the resource(s) the user is being permitted to act on.
userId String The id of the User to whom this permission applies.
verb String Options: get post put delete. The action (HTTP method) which is permitted on the resource(s) identified by spec.

User Profile

The User Profile endpoint allows for greater customization of self-registered users in Self Service. This endpoint allows the User to change their name, preferred name, local timezone, and preferred language.

Get User Profile Information

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/profile"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    pro = JSON.parse(HTTParty.get(url, headers: headers))
    puts(pro)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/profile" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/profile"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    pro = requests.get(url, headers=headers).json()
    print(pro)
except RequestException as e:
    print('Unexpected error!', e)
{
"name": "Craig Smith",
  "preferredLanguage": "en-US",
  "preferredName": "name",
  "preferredTimezone": null,
  "permissions": [
    "put",
    "get"
  ]
}

Retrieves all User Profile information available for modification.

HTTP Request

GET /users/{userId}/profile

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose User Profile information is desired.

Response

The User Profile response format is detailed here.

Update a User Profile

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/profile"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '37dd9fa0-1e47-11e4-b08e-685b358ea847'
,
    'preferredName': 'Craig'
,
    'preferredLanguage': 'en-US'
,
    'preferredTimezone': 'America/Chicago'
,
    'name': 'Craig S.'

}

begin: 
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/profile" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "37dd9fa0-1e47-11e4-b08e-685b358ea847", \
       "preferredName": "Craig", \
       "preferredLanguage": "en-US", \
       "preferredTimezone": "America/Chicago", \
       "name": "Craig S."}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/profile"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '37dd9fa0-1e47-11e4-b08e-685b358ea847',
    'preferredName': 'Craig',
    'preferredLanguage': 'en-US',
    'preferredTimezone': 'America/Chicago',
    'name': 'Craig S.'
}

try: 
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "name": "Craig S.",
  "preferredLanguage": "en-US",
  "preferredName": "Craig",
  "preferredTimezone": "America/Chicago",
  "permissions": [
    "put",
    "get"
  ]
}

Update the User Profile information present on a user.

HTTP Request

PUT /users/{userId}/profile

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to update their User Profile.

Request Parameters

Parameter Type Default Description
id String N/A The id of the user to change the profile.
name String N/A The user’s name. Maximum of 140 characters.
preferredLanguage String N/A The user’s preferred language. Note en-US is the only language currently supported.
preferredName String N/A The user’s preferred name. Maximum of 140 characters.
preferredTimezone String N/A The user’s preferred timezone. Visit https://docs.oracle.com/middleware/12212/wcs/tag-ref/MISC/TimeZones.html for a list of available time zones.

Response

The User Profile response format is detailed here.

User Profile Response

The JSON document used to represent a User Profile resource has the following content:

Attribute Type Description
name String N/A
preferredLanguage String N/A
preferredName String N/A
preferredTimezone String N/A
permissions Array[String] Options: get put . Which operations are possible on this resource, given the authentication token being used to access the API.

User Roll Call Incidents

Roll Call Incidents for which the requesting user is a Roll Call administrator.

Get All User Roll Call Incidents

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "id": "7159d9c6-53d0-11ed-a668-2d0c7a8eaf4f",
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "incidentPlan": {"name": "Roll Call Incident"},
      "site": {"id": "c3a8c5a5-9f15-11ec-87e2-796d091c34fe", "name": "High School A"},
      "locations": ["Classroom", "Gym", "Reunification Zone"],
      "statuses": ["Safe", "Injured"],
      "createdAt": "2022-10-24T19:17:03.784Z",
      "endedAt": null
    }
  ]
}

Retrieves the list of all Roll Call Incidents for which the requesting user is a Roll Call administrator.

HTTP Request

GET /users/{userId}/rostering

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.

Query Parameters

Parameter Type Description
ongoingOnly Boolean If set to true, only active Roll Call Incidents (i.e. those which have not been ended) will be returned

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

The User Roll Call response format is detailed here.

Get a Specific User Roll Call Incident

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    user_roll_call = JSON.parse(HTTParty.get(url, headers: headers))
    puts(user_roll_call)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    user_roll_call = requests.get(url, headers=headers).json()
    print(user_roll_call)
except RequestException as e:
    print('Unexpected error!', e)
 {
  "id": "7159d9c6-53d0-11ed-a668-2d0c7a8eaf4f",
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "incidentPlan": {"name": "Roll Call Incident"},
  "site": {"id": "c3a8c5a5-9f15-11ec-87e2-796d091c34fe", "name": "High School A"},
  "locations": ["Classroom", "Gym", "Reunification Zone"],
  "statuses": ["Safe", "Injured"],
  "createdAt": "2022-10-24T19:17:03.784Z",
  "endedAt": null
}

Retrieves a specific Roll Call Incident based on the id value of the Incident. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/rostering/{incidentId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.
incidentId The id of the Incident for which Roll Call information is desired.

Response

The User Roll Call response format is detailed here.

User Roll Call Incident Response

Attribute Type Description
id UUID The id of the Roll Call data for the Incdent
incidentId UUID The id of the Incident
incidentPlan Object A JSON object containing the name of the Incident Plan from which this Incident was created
site Object A JSON object containing the name and ID of the Site assigned to this Incident
locations Array[string] A list of the locations that are selectable for this Roll Call Incident
statuses Array[string] A list of the statuses that are selectable for this Roll Call Incident
createdAt ISO 8601 date/time When this Incident was created.
endedAt ISO 8601 date/time When this Incident was ended. Will be null while the Incident is still active.

User Roll Call Members

User Roll Call members are the users who are in the list for a particular Roll Call Incident. The Roll Call members will have a status and location assigned, which will be updated by Roll Call administrators during the event.

Only users who are Roll Call administrators for the specified Incident will be able to retrieve Roll Call member data through this API.

Get All User Roll Call Members

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
        "name": "John Doe",
        "email": "john.doe@domain.com"
      },
      "status": "Safe",
      "location": "Classroom",
      "permissions": [
          "get", "put"
      ]
    },
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
        "name": "Jane Doe",
        "email": "jane.doe@domain.com"
      },
      "status": "Safe",
      "location": "Reunification Zone",
      "permissions": [
        "get", "put"
      ]
    }
  ]
}

Retrieves the list of all members of the Incident’s Roll Call list.

HTTP Request

GET /users/{userId}/rostering/{incidentId}/rostering-members

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.
incidentId The id of the Incident for which Roll Call member information is desired.

Query Parameters

Parameter Type Description
filterStatuses Array[string] A JSON-encoded array of statuses on which to filter Roll Call members. To filter on ‘Unknown’, include a status of null.
filterLocations Array[string] A JSON-encoded array of locations on which to filter Roll Call members. To filter on 'Unknown’, include a location of null.

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

The Roll Call member response format is detailed here.

Get a Specific User Roll Call Member

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    user_roll_call_member = JSON.parse(HTTParty.get(url, headers: headers))
    puts(user_roll_call_member)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    user_roll_call_member = requests.get(url, headers=headers).json()
    print(user_roll_call_member)
except RequestException as e:
    print('Unexpected error!', e)
 {
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "memberUser": {
    "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
    "name": "Jane Doe",
    "email": "jane.doe@domain.com"
  },
  "status": "Safe",
  "location": "Reunification Zone",
  "permissions": [
    "get", "put"
  ]
}

Retrieves a specific Roll Call member based on the id values of the Incident and Roll Call member. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/rostering/{incidentId}/rostering-members/{rollCallMemberId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.
incidentId The id of the Incident for which Roll Call information is desired.
rollCallMemberId The id of the specific user who is a member of the Roll Call list.

Response

The Incident Roll Call member response format is detailed here.

Bulk Update User Roll Call Member Statuses and Locations

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'rosterMemberUserIds': ['0a8f4841-11d2-11ed-87c6-11f85dd7497d'
, '7676808b-d5fa-11eb-aea1-a17da050c75a'
]
,
    'status': 'Safe'
,
    'location': 'Reunification Zone'

}

begin: 
    user_roll_call_member = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(user_roll_call_member)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"rosterMemberUserIds": ["0a8f4841-11d2-11ed-87c6-11f85dd7497d", "7676808b-d5fa-11eb-aea1-a17da050c75a"], \
       "status": "Safe", \
       "location": "Reunification Zone"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'rosterMemberUserIds': ['0a8f4841-11d2-11ed-87c6-11f85dd7497d', '7676808b-d5fa-11eb-aea1-a17da050c75a'],
    'status': 'Safe',
    'location': 'Reunification Zone'
}

try: 
    user_roll_call_member = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(user_roll_call_member)
except RequestException as e:
    print('Unexpected error!', e)
{
  "rosterMemberUsers": [
    {
      "memberUser": {
        "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
        "name": "John Doe",
        "email": "john.doe@domain.com"
      },
      "status": "Safe",
      "location": "Classroom"
    },
    {
      "memberUser": {
        "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
        "name": "Jane Doe",
        "email": "jane.doe@domain.com"
      },
      "status": "Safe",
      "location": "Reunification Zone",
    }
  ],
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "permissions": ["put", "get"],
}

Updates the status and/or location of all specified Roll Call members. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

POST /users/{userId}/rostering/{incidentId}/rostering-members

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.
incidentId The id of the Incident for which to update Roll Call member data.

Request Parameters

Parameter Type Required Description
rosterMemberUserIds Array[UUID] Yes List of ids of users in the Roll Call list for which to update status and/or location.
location String One or both of status or location required The new location to be set for the specified roll call members. To set location to 'Unknown’, pass null.
status String One or both of status or location required The new status to be set for the specified Roll Call members. To set status to 'Unknown’, pass null.

Response

The Roll Call Member response format is detailed here.

Update One User Roll Call Member Status and Location

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'status': 'Safe'
,
    'location': 'Reunification Zone'

}

begin: 
    rcm = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(rcm)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"status": "Safe", \
       "location": "Reunification Zone"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-members/0a8f4841-11d2-11ed-87c6-11f85dd7497d"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'status': 'Safe',
    'location': 'Reunification Zone'
}

try: 
    rcm = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(rcm)
except RequestException as e:
    print('Unexpected error!', e)
{
  "memberUser": {
    "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
    "name": "John Doe",
    "email": "john.doe@domain.com"
  },
  "status": "Safe",
  "location": "Classroom",
  "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
  "permissions": ["put", "get"]
}

Updates the status and/or location of the specified Roll Call member. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

PUT /users/{userId}/incidents/{incidentId}/rostering-members/{rollCallMemberId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.
incidentId The id of the Incident for which to update Roll Call member data.
rollCallMemberId The user id of the Roll Call member for which to update status and/or location

Request Parameters

Parameter Type Required Description
location String No The new location to be set for the specified roll call members. To set location to 'Unknown’, pass null.
status String No The new status to be set for the specified Roll Call members. To set status to 'Unknown’, pass null.

Response

The Roll Call member response format is detailed here.

User Roll Call Member Response

Attribute Type Description
incidentId UUID The Incident id for this Roll Call event.
memberUser Array[Object] A JSON object containing the user name, email and ID for the Roll Call list member
status String The status of the Roll Call member. null indicates status of 'Unknown’.
location String The location of the Roll Call member. null indicates location of 'Unknown’.

User Roll Call My List

Roll Call My List is specific to each individual Roll Call administrator. It is the list of all Roll Call members whose status and/or location have been updated by that particular Roll Call administrator. The user making the request determines the list of Roll Call members returned.

Only users who are Roll Call administrators for the specified Incident will be able to retrieve Roll Call My List data through this API.

Get User Roll Call My List

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-my-list"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-my-list" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-my-list"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": false,
  "next": null,
  "previous": null,
  "data": [
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "0a8f4841-11d2-11ed-87c6-11f85dd7497d",
        "name": "John Doe",
        "email": "john.doe@domain.com"
      },
      "status": "Safe",
      "location": "Classroom",
      "permissions": [
          "get"
      ]
    },
    {
      "incidentId": "da757132-bd82-11eb-a95c-75282fb7d651",
      "memberUser": {
        "id": "7676808b-d5fa-11eb-aea1-a17da050c75a",
        "name": "Jane Doe",
        "email": "jane.doe@domain.com"
      },
      "status": "Safe",
      "location": "Reunification Zone",
      "permissions": [
        "get"
      ]
    }
  ]
}

Retrieves the list of all Roll Call members whose status and/or location the requesting user has updated. If the requesting user has not updated any status or location of any Roll Call members, then an empty list will be returned. The requesting user can only get their own Roll Call My List, and will be unable to access any other user’s My List.

HTTP Request

GET /users/{userId}/rostering/{incidentId}/rostering-my-list

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.
incidentId The id of the Incident for which Roll Call My List information is desired.

Query Parameters

Parameter Type Description
filterStatuses Array[string] A JSON-encoded array of statuses on which to filter Roll Call members. To filter on ‘Unknown’, include a status of null.
filterLocations Array[string] A JSON-encoded array of locations on which to filter Roll Call members. To filter on 'Unknown’, include a location of null.

Pagination parameters can be found here. There were few enough results in this example that pagination was not required.

Response

Attribute Type Description
incidentId UUID The Incident id for this Roll Call event.
memberUser Array[Object] A JSON object containing the user name, email and ID for the Roll Call list member
status String The status of the Roll Call member. null indicates status of 'Unknown’.
location String The location of the Roll Call member. null indicates location of 'Unknown’.

User Roll Call Report

The Incident Roll Call report contains the number of users currently assigned to each status in the Roll Call event. This is used to help incident administrators with directing the incident response.

Only users who are Roll Call administrators for the specified Incident will be able to retrieve Roll Call report data through this API.

Get User Roll Call Report

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-report"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-report" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/rostering/da757132-bd82-11eb-a95c-75282fb7d651/rostering-report"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    print(requests.get(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "statusCounts": [
    {"status": "Safe", "count":  370},
    {"status": "Injured", "count":  3},
    {"status": null, "count":  23}
  ]
}

Retrieves the user counts for each status in the Roll Call event.

HTTP Request

GET /incidents/{incidentId}/rostering-report

Produces

application/json

Path Parameters

Parameter Description
userId The id of the requesting user. Must be a Roll Call administrator for the specified incident.
incidentId The id of the Incident for which Roll Call information is desired.

Query Parameters

N/A

Response

Attribute Type Description
statusCounts Array[Object] A list of JSON objects that contain the status label and assigned user count for each status in the Roll Call event. A status of null means ‘Unknown’

User Security Groups

A User may belong to any number of Security Groups, which are a convenient way of assigning a logical set of permissions to the User. Other than automatically-assigned direct user permissions, which grant users access to resources they create themselves, placing Users into Security Groups is the primary method of granting users the ability to perform actions in the system. Each permission assigned to the associated Security Group will be implicitly granted to the User.

List All User Security Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    groups = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(groups)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    groups = requests.get(url, headers=headers, params=params).json()
    print(groups)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "next": "IjU5MTQ4YmQwLTFlZmYtMTFlNC1iMDhlLTY4NWIzNThlYTg0NyI=",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "securityGroup": {
        "createdAt": "2014-05-16T14:49:05.964Z",
        "id": "3aa5dec0-dd09-11e3-b17e-b8e856327746",
        "name": "Administrators"
      },
      "createdAt": "2014-05-16T14:50:23.126Z",
      "securityGroupId": "3aa5dec0-dd09-11e3-b17e-b8e856327746",
      "id": "68a3db60-dd09-11e3-8c49-b8e856327746",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
    }
  ]
}

Retrieves the list of all the Security Groups to which the User belongs. (The Permissions and Security Groups associated with the request, through the User attached to the access token, may limit the resources returned. A user will generally be able to see all their own memberships, and administrative users will be able to see other users’ group memberships.)

HTTP Request

GET /users/{userId}/security-groups

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose Security Group list is desired.

Query Parameters

To make this example more manageable, only the first Security 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 User Security Group response format is detailed here.

Get a User Security Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups/68a3db60-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    group = JSON.parse(HTTParty.get(url, headers: headers))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups/68a3db60-dd09-11e3-8c49-b8e856327746" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups/68a3db60-dd09-11e3-8c49-b8e856327746"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    group = requests.get(url, headers=headers).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "securityGroup": {
    "createdAt": "2014-05-16T14:49:05.964Z",
    "id": "3aa5dec0-dd09-11e3-b17e-b8e856327746",
    "name": "Administrators"
  },
  "createdAt": "2014-05-16T14:50:23.126Z",
  "securityGroupId": "3aa5dec0-dd09-11e3-b17e-b8e856327746",
  "id": "68a3db60-dd09-11e3-8c49-b8e856327746",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

Retrieves a single User Security Group assignment by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/security-groups/{securityGroupId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User of interest.
securityGroupId The id of the specific User Security Group assignment to retrieve.

Response

The User Security Group response format is detailed here.

Place a User in a Security Group

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'securityGroupId': '5422d460-1eff-11e4-b08e-685b358ea847'

}

begin: 
    group = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(group)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"securityGroupId": "5422d460-1eff-11e4-b08e-685b358ea847"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'securityGroupId': '5422d460-1eff-11e4-b08e-685b358ea847'
}

try: 
    group = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(group)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "securityGroup": {
    "createdAt": "2014-08-08T13:24:30.502Z",
    "id": "5422d460-1eff-11e4-b08e-685b358ea847",
    "name": "Administrators"
  },
  "createdAt": "2014-08-08T13:30:57.390Z",
  "securityGroupId": "5422d460-1eff-11e4-b08e-685b358ea847",
  "id": "3abd40e0-1f00-11e4-b08e-685b358ea847",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

Assigns the specified User to the specified Security Group, implicitly granting the user all permissions assigned to the group.

HTTP Request

POST /users/{userId}/security-groups

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to be added to the Security Group.

Request Parameters

Parameter Type Default Description
securityGroupId String N/A The id of the Security Group to which the User is being added.

Response

The User Security Group response format is detailed here.

Remove a User from a Security Group

# Continuing with the security group object
# from the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/security-groups/3abd40e0-1f00-11e4-b08e-685b358ea847" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the security group object
# from the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"UserSecurityGroups\"} 3abd40e0-1f00-11e4-b08e-685b358ea847"
}

Removes the specified User from the specified Security Group, so that the group’s permissions are no longer implicitly available to the user.

HTTP Request

DELETE /users/{userId}/security-groups/{securityGroupId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to remove from the Security Group.
securityGroupId The id of the Security Group to which the User will no longer belong.

Response

The deletion response format is detailed here.

List All SCIM Security Groups

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/5972cc1c-8026-11eb-a543-c1a5d6a87b54/scim-security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    subs = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(subs)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/5972cc1c-8026-11eb-a543-c1a5d6a87b54/scim-security-groups?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/5972cc1c-8026-11eb-a543-c1a5d6a87b54/scim-security-groups"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    subs = requests.get(url, headers=headers, params=params).json()
    print(subs)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 3,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    {
      "id": "37e63af7-8031-11eb-a543-67f151212590",
      "userId": "5972cc1c-8026-11eb-a543-c1a5d6a87b54",
      "securityGroup": {
        "id": "37e63af7-8031-11eb-a543-67f151212590",
        "name": "C",
        "super_group": false
      },
      "scimGroupIds":["569a087f-8031-11eb-a543-2386a627ea5e","d80aa1de-8026-11eb-a543-53c5fa2d317e"],
      "scimGroups":[
        {
          "id": "569a087f-8031-11eb-a543-2386a627ea5e",
          "name": "SCIM Group 1"
        },
        {
          "id": "d80aa1de-8026-11eb-a543-53c5fa2d317e",
          "name": "SCIM Group 2"
        }
      ],
      "createdAt": "2021-03-08T17:10:44.452Z",
      "permissions": ["put","delete","get"]
    }
  ]
}

Retrieves the list of all security groups to which the specified user is included through associated SCIM Groups.

HTTP Request

GET /users/{userId}/scim-security-groups

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose security group information is desired.

User Security Group Response

The JSON document used to represent a User Security Group resource has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When this group membership was created.
domains Array[Domain] When Domains are in use, this response will list the Domains to which the Security Group belongs.
id String The id of this specific User/Security Group association.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
securityGroup SecurityGroup The Security Group whose permissions are granted to the User through this association.
securityGroupId String The id of the Security Group above. This is what is actually stored; the expanded details about the Security Group are returned as a convenience, to save clients from having to issue a separate request to look them up.
userId String The id of the User whose Security Group membership is being reported.

User Subscriptions

User Subscriptions connect Users to Distribution Lists. 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 Subscriptions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    subs = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(subs)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    subs = requests.get(url, headers=headers, params=params).json()
    print(subs)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "next": "WyJUZXN0IiwiMTNiMzJjZjAtZGY4OS0xMWUzLTkzYmMtNjg1YjM1OGVhODQ3Il0=",
  "previous": null,
  "data": [
    {
      "permissions": ["delete", "put", "get"],
      "user": {
        "createdAt": "2014-05-16T14:50:22.656Z",
        "id": "685c2400-dd09-11e3-8c49-b8e856327746",
        "passwordResetRequired": false,
        "email": "craig.smith@acme.com",
        "name": "Craig Smith",
        "lock": { "start": "2014-03-16T14:00:00.000Z", "end": "2014-09-16T14:00:00.000Z" }
      },
      "distributionList": {
        "createdAt": "2014-07-22T19:15:37.346Z",
        "id": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
        "name": "To Just Craig Smith"
      },
      "createdAt": "2014-07-22T19:15:42.057Z",
      "subscriptionEndDate": null,
      "id": "92bd3590-11d4-11e4-bdcd-685b358ea847",
      "distributionListId": "8fee5e20-11d4-11e4-bdcd-685b358ea847",
      "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
    }
  ]
}

Retrieves the list of all distribution lists to which the specified user is subscribed. (The Permissions and Security Groups associated with the request, through the user attached to the access token, may limit the resources returned. A user will generally be able to see all their own subscriptions.)

HTTP Request

GET /users/{userId}/subscriptions

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose subscription information is desired.

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 two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The user subscription response format is detailed here.

Get a Subscription

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions/152f93c0-df89-11e3-93bc-685b358ea847"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    sub = JSON.parse(HTTParty.get(url, headers: headers))
    puts(sub)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions/152f93c0-df89-11e3-93bc-685b358ea847" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions/152f93c0-df89-11e3-93bc-685b358ea847"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    sub = requests.get(url, headers=headers).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-05-16T14:50:22.656Z",
    "id": "685c2400-dd09-11e3-8c49-b8e856327746",
    "passwordResetRequired": false,
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "lock": { "start": "2014-03-16T14:00:00.000Z", "end": "2014-09-16T14:00:00.000Z" }
  },
  "distributionList": {
    "createdAt": "2014-05-19T19:09:18.527Z",
    "id": "13b32cf0-df89-11e3-93bc-685b358ea847",
    "name": "To Just Craig Smith"
  },
  "createdAt": "2014-05-19T19:09:21.020Z",
  "subscriptionEndDate": null,
  "distributionListId": "13b32cf0-df89-11e3-93bc-685b358ea847",
  "id": "152f93c0-df89-11e3-93bc-685b358ea847",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

Retrieves a single subscription by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/subscriptions/{subscriptionId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User of interest.
subscriptionId The id of the specific subscription to retrieve.

Response

The user subscription response format is detailed here.

Create a Subscription

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'distributionListId': '37dd9fa0-1e47-11e4-b08e-685b358ea847'

}

begin: 
    sub = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(sub)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"distributionListId": "37dd9fa0-1e47-11e4-b08e-685b358ea847"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'distributionListId': '37dd9fa0-1e47-11e4-b08e-685b358ea847'
}

try: 
    sub = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-05-16T14:50:22.656Z",
    "id": "685c2400-dd09-11e3-8c49-b8e856327746",
    "passwordResetRequired": false,
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "lock": { "start": "2014-03-16T14:00:00.000Z",
    "end": "2014-09-16T14:00:00.000Z" }
  },
  "distributionList": {
    "createdAt": "2014-08-07T15:26:35.674Z",
    "id": "37dd9fa0-1e47-11e4-b08e-685b358ea847",
    "name": "Acme Corp"
  },
  "createdAt": "2014-08-07T15:26:49.492Z",
  "distributionListId": "37dd9fa0-1e47-11e4-b08e-685b358ea847",
  "id": "401a1540-1e47-11e4-b08e-685b358ea847",
  "subscriptionEndDate": null,
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

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 /users/{userId}/subscriptions

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to be subscribed.

Request Parameters

Parameter Type Default Description
distributionListId String N/A The id of the Distribution List to be subscribed to.
subscription­EndDate ISO 8601 date/time N/A If specified, the time at which this subscription will become inactive.

Response

The user subscription response format is detailed here.

Update a Subscription

# Continuing with the subscription object from
# the previous example:
begin:
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions/401a1540-1e47-11e4-b08e-685b358ea847" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"subscriptionEndDate": "2015-09-16T14:00:00.000Z"}'
# Continuing with the subscription object from
# the previous example:
try:
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "permissions": ["delete", "put", "get"],
  "user": {
    "createdAt": "2014-05-16T14:50:22.656Z",
    "id": "685c2400-dd09-11e3-8c49-b8e856327746",
    "passwordResetRequired": false,
    "email": "craig.smith@acme.com",
    "name": "Craig Smith",
    "lock": { "start": "2014-03-16T14:00:00.000Z",
    "end": "2014-09-16T14:00:00.000Z" }
  },
  "distributionList": {
    "createdAt": "2014-08-07T15:26:35.674Z",
    "id": "37dd9fa0-1e47-11e4-b08e-685b358ea847",
    "name": "Acme Corp"
  },
  "createdAt": "2014-08-07T15:26:49.492Z",
  "distributionListId": "37dd9fa0-1e47-11e4-b08e-685b358ea847",
  "id": "401a1540-1e47-11e4-b08e-685b358ea847",
  "subscriptionEndDate": "2015-09-16T14:00:00.000Z",
  "userId": "685c2400-dd09-11e3-8c49-b8e856327746"
}

Updates an existing subscription’s subscriptionEndDate.

HTTP Request

PUT /users/{userId}/subscriptions/{subscriptionId}

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the user 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 user subscription response format is detailed here.

Remove a Subscription

# Continuing with the subscription object from
# the previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscriptions/401a1540-1e47-11e4-b08e-685b358ea847" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the subscription object from
# the previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "status": 200,
  "message": "deleted {:name \"UserSubscriptions\"} 401a1540-1e47-11e4-b08e-685b358ea847"
}

Deletes a subscription, removing that association between a User and a Distribution List.

HTTP Request

DELETE /users/{userId}/subscriptions/{subscriptionId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the user whose subscription is to be deleted.
subscriptionId The id of the specific subscription to delete.

Response

The deletion response format is detailed here.

List All SCIM Subscriptions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/5972cc1c-8026-11eb-a543-c1a5d6a87b54/scim-subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    subs = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(subs)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/5972cc1c-8026-11eb-a543-c1a5d6a87b54/scim-subscriptions?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/5972cc1c-8026-11eb-a543-c1a5d6a87b54/scim-subscriptions"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    subs = requests.get(url, headers=headers, params=params).json()
    print(subs)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 3,
  "previous": null,
  "next": null,
  "partial": false,
  "data": [
    { 
      "id": "c5928f66-8b21-11eb-b282-9babf743bf37",
      "userId": "5972cc1c-8026-11eb-a543-c1a5d6a87b54",
      "distributionList": { 
        "id": "c5928f66-8b21-11eb-b282-9babf743bf37",
        "name": "DL A"
      },
      "scimGroupIds": ["d80aa1de-8026-11eb-a543-53c5fa2d317e"],
      "scimGroups":[
        {
          "id":" d80aa1de-8026-11eb-a543-53c5fa2d317e",
          "name": "SCIMSGTEST"
        }
      ],
      "createdAt": "2021-03-22T15:17:52.983Z",
      "permissions": ["put","delete","get"]
    }
  ]
}

Retrieves the list of all distribution lists to which the specified user is subscribed through associated SCIM Groups.

HTTP Request

GET /users/{userId}/scim-subscriptions

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose subscription information is desired.

User Subscription Response

The JSON document used to represent a user subscription 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.

Self Service Subscriptions

Self Service Subscriptions connect Users to Distribution Lists they can subscribe to. The difference between Self Service Subscriptions and User Subscriptions is that Self Service Subscriptions are applied to any distribution lists that are marked as subscribable, whereas User Subscriptions can be applied to any Distribution List.

List All Self Service Subscriptions

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    subs = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(subs)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    subs = requests.get(url, headers=headers, params=params).json()
    print(subs)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "partial": true,
  "next": "WyJUZXN0IiwiMTNiMzJjZjAtZGY4OS0xMWUzLTkzYmMtNjg1YjM1OGVhODQ3Il0=",
  "previous": null,
  "data": [
    {
      "distributionListName": "Administrator Alerts",
      "distributionListId": "12163d67-f790-11ea-a5f1-8fe62d9fe6fe",
      "subscribed": false,
      "permissions": [
        "put",
        "get"
      ]
    }
  ]
}

Retrieves the list of all distribution lists Users may subscribe to and whether they are subscribed.

HTTP Request

GET /users/{userId}/subscribable-distribution-lists

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose self service subscription information is desired.

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 two available when the request was made. The Informacast Mobile API offers a standard pagination mechanism for list requests like this.

Response

The self service subscription response format is detailed here.

Add a Self Service Subscription

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': 'af94ef60-1d9a-11e4-a054-3c970e7ff560'
,
    'subscribe': true

}

begin: 
    updated = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(updated)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "af94ef60-1d9a-11e4-a054-3c970e7ff560", \
       "subscribe": true}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': 'af94ef60-1d9a-11e4-a054-3c970e7ff560',
    'subscribe': true
}

try: 
    updated = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(updated)
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListName": "Everyone",
  "distributionListId": "af94ef60-1d9a-11e4-a054-3c970e7ff560",
  "subscribed": true,
  "permissions": [
    "put",
    "get"
  ]
}

Create a link between a User and a Distribution List so that the User will receive Notifications sent to that Distribution List.

HTTP Request

PUT /users/{userId}/subscribable-distribution-lists

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to be subscribed.

Request Parameters

Parameter Type Default Description
id String N/A The id of the Distribution List to be subscribed to.
subscribe Boolean N/A Whether to subscribe to the Distribution List.

Response

The self service subscription response format is detailed here.

Remove a Self Service Subscription

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'id': '37dd9fa0-1e47-11e4-b08e-685b358ea847'
,
    'subscribe': false

}

begin: 
    sub = JSON.parse(HTTParty.put(url, headers: headers, body: JSON.dump(body)))
    puts(sub)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists" \
  -X PUT \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"id": "37dd9fa0-1e47-11e4-b08e-685b358ea847", \
       "subscribe": false}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/subscribable-distribution-lists"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'id': '37dd9fa0-1e47-11e4-b08e-685b358ea847',
    'subscribe': false
}

try: 
    sub = requests.put(url, headers=headers, data=json.dumps(data)).json()
    print(sub)
except RequestException as e:
    print('Unexpected error!', e)
{
  "distributionListName": "Administrator Alerts",
  "distributionListId": "37dd9fa0-1e47-11e4-b08e-685b358ea847",
  "subscribed": false,
  "permissions": [
    "put",
    "get"
]
}

Removes a self servie subscription and its association between a User and a Distribution List.

HTTP Request

PUT /users/{userId}/subscribable-distribution-lists

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User to be subscribed.

Request Parameters

Parameter Type Default Description
id String N/A The id of the Distribution List to be subscribed to.
subscribe Boolean N/A Whether to subscribe to the Distribution List.

Response

The self service subscription response format is detailed here.

Self Service Subscription Response

The JSON document used to represent a self service subscription resource has the following content:

Attribute Type Description
distribution­ListName String The name of the Distribution List available for subscription.
distribution­ListId String The id of the named Distribution List.
subscribed String Whether the User is subscribed to this Distribution List.
permissions Array[String] Options: get put . Which operations are possible on this resource, given the authentication token being used to access the API.

User Tokens

Authentication tokens are sent along with every request to the InformaCast Mobile API to associate the request with a particular User, and thereby control access to API resources and actions, as detailed in the Authentication section.

The User Tokens resource manages the tokens which grant access to InformaCast Mobile. Tokens are created or refreshed automatically when users log in through the normal authentication mechanism. Your client code may also manipulate this resource directly if it needs to create application tokens to distribute to components of itself (for example, permanent tokens for headless, unattended operation), or in order to revoke a user’s access.

List a User’s Tokens

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    tokens = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(tokens)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    tokens = requests.get(url, headers=headers, params=params).json()
    print(tokens)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 2,
  "next": null,
  "previous": null,
  "data": [
    {
      "refreshTokenUsed": false,
      "permissions": [ "get", "delete" ],
      "name": "My API Token",
      "tokenType": "access_token",
      "client": null,
      "createdAt": "2023-10-27T15:09:31.729Z",
      "type": "token",
      "scope": null,
      "expires": "2023-10-20T08:45:48.957Z",
      "id": "d4d204fb-74da-11ee-bba9-3512102fdbb9",
      "userId": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
      "originId": null,
      "subject": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
      "originCreatedAt": null,
      "object": null
    },
    {
      "refreshTokenUsed": false,
      "permissions": [ "get", "delete" ],
      "name": "IcMobile Web",
      "tokenType": "refresh_token",
      "client": "ios_secure_v2",
      "createdAt": "2023-11-06T15:46:39.144Z",
      "type": "token",
      "scope": null,
      "expires": "2023-11-07T03:46:39.000Z",
      "id": "ac981371-7cbb-11ee-a92e-c7524bc59845",
      "userId": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
      "originId": "ac975020-7cbb-11ee-a92e-3ddeaf4b6aa6",
      "subject": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
      "originCreatedAt": "2023-11-06T15:46:39.139Z",
      "object": null
    }
  ]
}

Retrieves the list of tokens associated with a particular user. (The Permissions and Security Groups associated with the request, through the user attached to its access token, may limit the resources returned. Generally only administrative users will be able to manipulate tokens.)

HTTP Request

GET /users/{userId}/tokens

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose access tokens are to be listed.

Query Parameters

To make this example more manageable, only the first token 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.

Response

The user token response format is detailed here.

Get One Token

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens/d4d204fb-74da-11ee-bba9-3512102fdbb9"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    t = JSON.parse(HTTParty.get(url, headers: headers))
    puts(t)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens/d4d204fb-74da-11ee-bba9-3512102fdbb9" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens/d4d204fb-74da-11ee-bba9-3512102fdbb9"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    t = requests.get(url, headers=headers).json()
    print(t)
except RequestException as e:
    print('Unexpected error!', e)
{
  "refreshTokenUsed": false,
  "permissions": [ "get", "delete" ],
  "name": "My API Token",
  "tokenType": "access_token",
  "client": null,
  "createdAt": "2023-10-27T15:09:31.729Z",
  "type": "token",
  "scope": null,
  "expires": "2023-10-20T08:45:48.957Z",
  "id": "d4d204fb-74da-11ee-bba9-3512102fdbb9",
  "userId": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
  "originId": null,
  "subject": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
  "originCreatedAt": null,
  "object": null
}

Retrieves a single user token by id. Since this is not a list request, there is no pagination wrapper around the result.

HTTP Request

GET /users/{userId}/tokens/{tokenId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose access tokens is being requested.
tokenId The id of the specific token to retrieve.

Response

The user token response format is detailed here.

Create a Token

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
body = {
    'name': 'My API Token'
,
    'expires': '2023-10-20T08:45:48.957Z'

}

begin: 
    t = JSON.parse(HTTParty.post(url, headers: headers, body: JSON.dump(body)))
    puts(t)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens" \
  -X POST \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Content-Type: application/json" \
  -d '{"name": "My API Token", \
       "expires": "2023-10-20T08:45:48.957Z"}'
import requests
from requests.exceptions import RequestException
import json

url = "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND=',
    'Content-Type': 'application/json'
}
data = {
    'name': 'My API Token',
    'expires': '2023-10-20T08:45:48.957Z'
}

try: 
    t = requests.post(url, headers=headers, data=json.dumps(data)).json()
    print(t)
except RequestException as e:
    print('Unexpected error!', e)
{
  "refreshTokenUsed": false,
  "permissions": [ "get", "delete" ],
  "name": "My API Token",
  "token": "6LMPV4G5BAI6HLOOXDUFMMTXIZUFYJAA3UERDY4MJG4OQVRSO5DO6UTSZW3PXD43P7OO3A46NJDBMVXE2Y2CTYCWZD55Y57WQ4DLPDY=",
  "tokenType": "access_token",
  "client": null,
  "createdAt": "2023-10-27T15:09:31.729Z",
  "type": "token",
  "scope": null,
  "expires": "2023-10-20T08:45:48.957Z",
  "id": "d4d204fb-74da-11ee-bba9-3512102fdbb9",
  "userId": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
  "originId": null,
  "subject": "bd6508ce-ef1c-11eb-b855-752b3cc63493",
  "originCreatedAt": null,
  "object": null
}

Create a new access token associated with a particular user.

HTTP Request

POST /users/{userId}/token

Consumes

multipart/form-data, application/x-www-form-urlencoded, application/json

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User for whom a new access token is to be created.

Request Parameters

Parameter Type Default Description
name String N/A The name to give the new token.
expires String ISO 8601 date/time When the token should expire and cease to be usable. If left blank will default to 1 year.

Response

The user token response format is detailed here.

Revoke a Token

# Continuing with the token object from the
# previous example:
begin:
    puts(JSON.parse(HTTParty.delete(url, headers: headers)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/users/685c2400-dd09-11e3-8c49-b8e856327746/tokens/18f80750-1e5c-11e4-b08e-685b358ea847" \
  -X DELETE \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
  -H "Accept: application/json"

# Continuing with the token object from the
# previous example:
try:
    print(requests.delete(url, headers=headers).json())
except RequestException as e:
    print('Unexpected error!', e)
{
    "status": 200,
    "message": "success",
    "resources": [
        {
            "id": "18f80750-1e5c-11e4-b08e-685b358ea847",
            "name": "Feh"
        }
    ]
}

Deletes a token, so that it will immediately cease to be valid for accessing the system.

HTTP Request

DELETE /users/{userId}/tokens/{tokenId}

Produces

application/json

Path Parameters

Parameter Description
userId The id of the User whose token is to be revoked.
tokenId The id of the specific token to revoke.

Query Parameters

Parameter Type Description
deleteEntireSession Boolean Whether to delete the entire session. This effectievly deletes all entries sharing the same originId.

Response

The deletion response format is detailed here.

User Token Response

The JSON document used to represent a security group resource has the following content:

Attribute Type Description
client String The id of the OAuth2 client with which the token is associated. This is an area of active development and the details are changing rapidly at the moment; once client records are available for external developers, this documentation will be updated.
createdAt ISO 8601 date/time When the token was created.
expires ISO 8601 date/time When the token will expire, and cease to provide access to the system.
id String The id of this specific token, allowing it to be manipulated or retrieved individually.
name String The name assigned this token.
permissions Array[String] Options: get put delete. Which operations are possible on this resource, given the authentication token being used to access the API.
scope String The OAuth2 scope for which the token applies. This is an area of active development, and in future might be used to provide access to subsets of the API. When such features become available, this documentation will be updated; for now, consider this a value used internally by the API.
subject String The OAuth2 subject associated with the token; currently the same as userId.
token String The special string which can be used to provide this token as an access_token for authenticating API requests, as discussed in the Authentication section. This value is present only in the response to a post request when the token is first created, and must be securely recorded at that point. It is important to protect this token because possession is enough to grant access to the API as the user associated with the token.
userId String The id of the User the token is associated with; use of this token in API requests allows access to the system with the identity and permissions of that user.
notValidAfter ISO 8601 date/time The time the session will be expired no matter what.
originId String The origin id. This will be the same throughout an entire session.
originCreatedAt ISO 8601 date/time The time the origin/session was created.
tokenType String One of refresh_token or access_token depending on if it is an API Token or a Session.
refreshTokenused Boolean Whether or not the refresh token has been used to exchange for a new token pair.

User Devices - Direct Access

Unlike the User Devices endpoint, which is used for accessing the devises of an individual InformaCast Mobile user, this endpoint provides an overall view of the devices registered to all users. As such, it can return a paginated list of all known devices. Additionally, client applications can request that the returned list of devices be filtered and sorted. The devices can also be selected by their type or by the category of the users they belong to.

List User Devices

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/user-devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    devices = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(devices)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/user-devices?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/user-devices"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    devices = requests.get(url, headers=headers, params=params).json()
    print(devices)
except RequestException as e:
    print('Unexpected error!', e)
{
    "total": 12,
    "previous": null,
    "next": "WyJhZHJpYW4gYWRzaGVhZCIsImZiNTA3YTMwLTAxNTktMTFlNC1iYzNkLTY4NWIzNThlYTg0NyJd",
    "partial": true,
    "data": [
        {
            "deviceIdentifier": "3cab93ba8b953bccca6f877315d1f3760109ba49ccd6b492cf6ed5287b6459df",
            "updatedAt": "2020-08-10T22:20:30.348Z",
            "permissions": [
                "get"
            ],
            "disabled": false,
            "name": "Microsoft Teams Device",
            "createdAt": "2020-08-10T22:20:30.348Z",
            "type": "msteams-chat",
            "build": null,
            "id": "b3356516-db57-11ea-bf4d-69bedc344aa1",
            "userId": "5339dc92-db57-11ea-bf4d-99c68d4d56f3",
            "os": null,
            "user": {
                "name": "Craig Smith",
                "type": "regular",
                "email": "craig.smith@acme.com"
            },
            "verified": true
        }
    ]
}

Retrieves the list of devices registered to InformaCast Mobile users.

HTTP Request

GET /user-devices

Produces

application/json

Request Parameters

Parameter Type Default Description
deviceTypes String N/A A comma separated list of types of the Devices to be retrieved.
userTypes String N/A A comma separated list of types of the Users whose devices are to be retrieved.
verified boolean false Whether or not only verified devices are to be retrieved.
deviceNames String asc Options: asc, desc. Sort devices by their names.
userNames String asc Options: asc, desc. Sort devices by the names of the users they are registered to.

Requests can also include pagination parameters that can be found here. There were few enough results in this example that pagination was not required.

The API has pseudo field names which combine the field name, updatedAt, with a comparison operation. The 4 pseudo field names are updatedAt__lt (less than), updatedAt__lte (less than or equals), updatedAt__gt (greater than) and updatedAt__gte (greater than or equals). When specifying one of these updatedAt filters the timestamp format must be in RFC3339 format, including the timezone offset.

Ex. updatedAt__gt=2019-07-29T01:53:00-05:00

Response

The user device response format is detailed here. Additionally, the individual device records in the response payload will include the user attribute with the following data regarding the device’s owner.

Attribute Type Description
name String The user’s name.
type String The type of the user. Options: regular, anonymous.
email String The user’s email address; will be missing for users whose type is anonymous.

Webex Teams Integration API

To allow you to programmatically 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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab/proxy/api/v1/spaces"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 1

}

begin: 
    puts(JSON.parse(HTTParty.get(url, headers: headers, query: query)))
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab/proxy/api/v1/spaces?limit=1" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab/proxy/api/v1/spaces"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 1
}

try: 
    print(requests.get(url, headers=headers, params=params).json())
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab//proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    space = JSON.parse(HTTParty.post(url, headers: headers))
    puts(space)
rescue StandardError => e
    puts e
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"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab//proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    space = requests.post(url, headers=headers).json()
    print(space)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab//proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

begin: 
    space = JSON.parse(HTTParty.delete(url, headers: headers))
    puts(space)
rescue StandardError => e
    puts e
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"

import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/extensions/299036d0-188a-11e7-a184-fd464c9fabab//proxy/api/v1/spaces/Y2lzY29zcGFyazovL3VzL1JPT00vZDJmZGUwOTAtOWQwYy0xMWU1LWFlZWQtMjE3NmZkY2Q4YTU4"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}

try: 
    space = requests.delete(url, headers=headers).json()
    print(space)
except RequestException as e:
    print('Unexpected error!', e)
{
  "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.

  

Common Responses

Status Codes

An example of a validation error response.

{
 "status": 400,
 "message": "Validation Failed",
 "reason": [
  {
   "field": "name",
   "type": "max-length-error",
   "message": "Maximum field length of 140 exceeded for field name"
  }
 ]
}

Here is a summary of the most common response codes that can be received from the API.

Response Code Meaning
200 Successful request. Celebration time!
400 Bad Request—The request failed validation; many times, more specific information about the validation failure will also appear (see the example in the right pane).
401 Unauthorized—Either the access token is invalid or user/customer is locked/expired.
403 Forbidden—The associated user does not have the right to perform the requested operation.
404 Not Found—The specified resource could not be found, e.g. the id is incorrect, the id has been deleted, etc.
429 Too Many Requests—The API is receiving too many requests; see Throttling for more information on handling this issue.
500 Internal Server Error—InformaCast Mobile has encountered an error in its own processing. If this error is due to load or transitory network problems, wait a few moments and try your request again. If this is a persistent error, submit an online support request. Singlewire Support will log the error and assist you in resolving it.
503 Service Unavailable—InformaCast Mobile is temporarily offline for maintenance. Please try your request again later.

Deleted Response

Any time a DELETE request is issued, the following JSON document will be produced:

Attribute Type Description
status Integer The response status code. Success is indicated by 200.
message String A more detailed description of the results of the operation.

Sync State Element

Fusion Only

The JSON object used to represent a syncState element in various other resources has the following content:

Attribute Type Description
createdAt ISO 8601 date/time When the sync process for the resource reached this state.
id UUID The id of this specific synchronization state detail, allowing it to be manipulated or retrieved individually.
name String The name of the endpoint (Fusion server) being synchronized with.
severity String Options: info error. Severity of this state.
activationGroupId Int Associated activation group id (when this is part of a activation group resource).
messageId Int Associated message id (when this is part of a message template resource).
recipientGroupId Int Associated recipient group id (when this is part of a device group or distribution list resource).
scheduledBroadcastId Int Associated broadcast id (when this is part of a scheduled broadcast resource).
bellScheduleId Int Associated bell schedule id (when this is part of a bell schedule resource).
ringListId Int Associated ring list id (when this is part of a ring list resource).
state String Options: complete failed pending. Current state of the sync.
value String Any associated id or extra information regarding this sync state.
errors Array[Object] Any errors related to the sync state.

Pagination and Search

The InformaCast Mobile API provides consistent methods for performing search and pagination for requests which return a list of resources. Unless otherwise specified, a request which lists a resource will return a maximum of 100 results. You need to be aware of this pagination mechanism in order to detect when you have received partial results, and to obtain the remaining results in such circumstances. You may also wish to choose more specific numbers of results to request, or to filter out specific resources in your query to improve network efficiency if you know what you are looking for.

Pagination

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/resource"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'limit': 10

}

begin: 
    resource = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(resource)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/resource?limit=10" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/resource"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'limit': 10
}

try: 
    resource = requests.get(url, headers=headers, params=params).json()
    print(resource)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 26,
  "partial": true,
  "previous": null,
  "next": "IjRlZTVkODUwLTI2ZjAtMTFlNC1hOWE3LWI4ZTg1NjMyNzc0NiI=",
  "data": [ "<ten items omitted to save space in the example…>" ]
}

Listing a resource will always return a JSON document as described in Pagination Results. If the response indicates that it is incomplete (has a true value for its partial attribute), you will need to issue a subsequent request in order to retrieve the next set of results. This is done by passing the next pointer (the value returned in the next attribute in your current result set) as a start query parameter in your next request, as described in Pagination Parameters. The example shown illustrates a partial response that can be paginated (again, this is indicated by the next attribute being present, as well as partial being set to true).

There is also a previous pointer which can be used to step backwards through the results. In this case, since we started at the beginning, its value is null.

The results themselves are in the data array. This has been omitted from the example in the interest of brevity. Try some list requests in the API Explorer to see these structures in their full glory.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/resource"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'start': 'IjRlZTVkODUwLTI2ZjAtMTFlNC1hOWE3LWI4ZTg1NjMyNzc0NiI%3D'
,
    'limit': 10

}

begin: 
    resource = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(resource)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/resource?start=IjRlZTVkODUwLTI2ZjAtMTFlNC1hOWE3LWI4ZTg1NjMyNzc0NiI%3D&limit=10" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/resource"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'start': 'IjRlZTVkODUwLTI2ZjAtMTFlNC1hOWE3LWI4ZTg1NjMyNzc0NiI%3D',
    'limit': 10
}

try: 
    resource = requests.get(url, headers=headers, params=params).json()
    print(resource)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 26,
  "partial": true,
  "next": "IjJhZDJjMDYwLTE5MTUtMTFlNC1iZWVhLWI4ZTg1NjMyNzc0NiI=",
  "previous": "ImM3MmZmZWIwLTI2ZjItMTFlNC05Y2ViLTY4NWIzNThlYTg0NyI=",
  "data": [ "<ten items omitted to save space in the example…>" ]
}

To continue the example, let’s fetch the next ten results. To do this, we would keep the limit query parameter of 10 and also send a start query parameter containing the URL encoded value of the next pointer we received in our first response, which was IjRlZTVkODUwLTI2ZjAtMTFlNC1hOWE3LWI4ZTg1NjMyNzc0NiI=.

The response now indicates that we can move both forward and backward due to the presence of the next and previous attributes. As with paginating in the forward direction, backwards pagination can be performed simply by passing the value of the previous attribute as the start query parameter (URL encoding the value, of course). In order to paginate backwards through the entire list of results, you need some way to start at the end of the list of resources. This can be done by providing the special value of end as the start query parameter.

In either case, once you have retrieved the last chunk of data in paginating through your resource query, the value of the the pointer for the direction in which you have been moving (next or previous) will become null. The value of partial attribute will only false if all values were returned in a single query.

The total number of resources available, whether or not all were present in the current data array, is reported in the total attribute. This may not represent all the resources which actually exist in the Provider, because the results may be limited by the Permissions and Security Groups attached to the user associated with the access token used to make the request. The number reported in total is the number that can be seen by the requesting user.

require 'httparty'
require 'json'

url = "https://api.icmobile.singlewire.com/api/v1/user"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
query = {
    'q': 'Craig%20Smith'

}

begin: 
    user = JSON.parse(HTTParty.get(url, headers: headers, query: query))
    puts(user)
rescue StandardError => e
    puts e
curl "https://api.icmobile.singlewire.com/api/v1/user?q=Craig%20Smith" \
  -H "Authorization: Bearer S35QCVBN6S6TUQKHOND=" \
import requests
from requests.exceptions import RequestException

url = "https://api.icmobile.singlewire.com/api/v1/user"
headers = {
    'Authorization': 'Bearer S35QCVBN6S6TUQKHOND='
}
params = {
    'q': 'Craig%20Smith'
}

try: 
    user = requests.get(url, headers=headers, params=params).json()
    print(user)
except RequestException as e:
    print('Unexpected error!', e)
{
  "total": 1,
  "partial": false,
  "previous": null,
  "next": null,
  "data": [
    {
      "lock": null,
      "name": "Craig Smith",
      "securityGroups": [ ],
      "passwordResetRequired": false,
      "createdAt": "2014-05-16T14:50:22.656Z",
      "email": "craig.smith@acme.com",
      "permissions": ["delete", "put", "get"],
      "subscriptions": [ ],
      "id": "685c2400-dd09-11e3-8c49-b8e856327746"
    }
  ]
}

Filtering a list of results can be performed by supplying the q query parameter as one of your Pagination Parameters. The example shows how you could search for a user named Craig Smith.

This example did not require pagination, because only one available result matched the filter. Even in such cases, the pagination wrapper is present in the response, and all results are embedded in the data array. If you are paginating through a filtered result set, remember to supply the same value for the q filter with each request.

If q does not contain a colon, then the search will be performed against all resource attributes which are of type String, as well as createdAt. If the value looks like a date (formatted as specified by ISO 8601), it will match records which were created at any time on that day; if it includes a time, then the resource must have been created at that exact date and time.

You can also restrict the search to a particular attribute of the resource by formatting q to contain the attribute name, a colon, and the value you want to search for, e.g. name:smith. The attribute name can contain lower and uppercase letters, underscores, and hyphens. The search value is matched loosely against the content of the attribute, with a bias towards returning more results rather than missing them.

You can perform geographic searches of User Locations using search queries of location.polygon: and a URL-encoded GeoJSON Linear Ring.

Logical Operators

You can perform searches with the simple logical operators and and or.

Operator Example
and q={"and":["name:craig","type:regular"]}
or q={"or":["name:craig","name:linda"]}

Pagination Parameters

The following optional query parameters are used to control the pagination of resource requests which return lists.

Parameter Type Default Description
start String beginning Tells the API which portion of the list of results to return. Omitting this parameter tells the API to start at the beginning of the list. The special value end indicates the API should start at the end of the list and return chunks in reverse order. All other values must come from a next or previous attribute in the pagination results of a prior API response, and instruct the API to continue from that point in its pagination.
limit Integer 100 The maximum number of resources to be returned in the response. The value must be between 1 and 1000.
q String n/a The search query with which to filter the result set.
include-total Boolean true Whether to compute the total key in the list response output. When this is false, total will be removed and previous/next will be null.
ids[] Array n/a Filters the list to only the supplied ids. Works for most resources. Example usage: ?ids[]=1&ids[]=2&ids[]=3.

Pagination Results

Any time a list request is made, the response will be wrapped in a pagination object. The array of resources making up the actual response will always be available as the data attribute of the JSON response document. The other attributes provide information about the pagination status of the response.

Attribute Type Description
total Integer The total number of resources available, not all of which may be present in the current response, due to pagination. When include-total is false, this will be omitted.
partial String Whether the results contains all of the available resources, or only a partial set, in which case further queries will be required to page through the remaining results.
previous String The value which can be passed as the start query parameter to retrieve the previous page of results, paginating backwards. When include-total is false, this will always be returned as null.
next String The value which can be passed as the start query parameter to retrieve the next page of results, paginating forward. When include-total is false, this will always be returned as null.
data Array The array of resources in the current response.

Throttling

The system rate-limits incoming requests to protect itself, your application and other users. A request that exceeds the rate-limit fails with an HTTP 429 Too Many Requests error status. All requests are subject to the same rate-limiting policy, including sending notifications, creating resources, etc. The policy itself is subject to change depending on system conditions.

Your application should be prepared to receive a 429. Every application should be set up to handle 429 responses. When you receive a 429, your application should only retry after waiting a random amount of time. That wait time should increase with each 429 you receive.

Examples of situations that can cause 429 responses are: when your application sends many requests in parallel or when your application sends thousands of requests in rapid succession.

Overriding the Request Method

For HTTPS clients that only know how to make GET requests, adding a query parameter of _method will allow you to override the request method. For instance GET /api/v1/session?_method=DELETE&access_token=CADDCD33... will delete the user’s session.

The other request parameters need to be query parameters, so it’s not an appropriate technique for uploading files or updating nested structures.