Introduction

Welcome to the SmartSense Developer Portal. Here you will find information about the APIs that we offer as well as how to use them.

We have provided example language bindings in Shell and Python. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Auth

Authentication

Sample /auth/oauth Request

curl --silent https://api.smartsense.co/auth/oauth \
  --data "grant_type=client_credentials" \
  --header "Accept: application/json"\
  --basic --user myclientid:myclientsecret

import json
import requests

client_id="myclientid"
client_secret="myclientsecret"
client_auth = (client_id, client_secret)
r = requests.post('https://api.smartsense.co/auth/oauth',
                  data = {'grant_type':'client_credentials'},
                  auth = client_auth,
                  headers={'Accept': 'application/json'}
                  )
print (r.json())

Sample /auth/oauth Response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Expires: -1
Date: Wed, 13 Jan 2016 17:46:54 GMT

{ 
  "access_token": "AW+kvNB8LR5Hqd60GNwY2MkkDooKvoGuQpHXoRm4DAYM", 
    "token_type": "Bearer", 
    "expires_in": 3600 
}

The SmartSense REST API uses the client credentials portion of the OAuth2 specification to perform authentication and authorization. This requires the client of the API to possess a client identifier and a client "secret" (the "secret" should be considered confidential). Both the client ID and "secret" together make up the client credentials.

SmartSense provides client credentials for clients of the API. Once you have acquired credentials, make a call to the SmartSense authorization endpoint (https://api.smartsense.co/auth/oauth) to obtain a token.

Client Credentials Scope

The client credentials are bound at creation time to a specific SmartSense account ID and user ID. Currently, client credentials have access to all data available to the SmartSense user ID.

Using API Client Credentials To Obtain an Access Token

As per the OAuth2 specification, client credentials can be used by the API client to obtain an AccessToken. This AccessToken can then be used for authorizing API calls (until the token expires). To obtain an AccessToken, the client makes a POST request to /auth/oauth, as described in https://tools.ietf.org/html/rfc6749#section-4.4.2.

To summarize section 4.4.2 of the OAuth2 specification: pass grant_type=client_credentials in the body of the request (form-urlencoded), and use HTTP Basic authentication to provide the client ID and client secret.

To use the sample code, you must replace myclientid and myclientsecret with your personal API client ID and secret.

Key	Value
Accept	application/json
Content-Type	application/x-www-form-urlencoded
Content-Length	calculated when request is sent
Host	domain name for which the request is being sent to the server

Authorization

To authorize with the SmartSense API you need to pass a Bearer token obtained using the Authentication process. The bearer token must be included in the Authorization header for all API requests and must look like the following:

Authorization: Bearer TOKEN_FROM_SMARTSENSE

You must replace TOKEN_FROM_SMARTSENSE with your personal API token from the Authorization process.

Global Types

All SmartSense APIs use the following custom types:

Numbers

Byte

Parameters of type byte can return or accept a whole number between 0 and 255 inclusive.

Integer (16 bit)

Parameters of type integer (16 bit) can return or accept a whole number between -32,768 and 32,767 inclusive.

Integer (32 bit)

Parameters of type integer (32 bit) can return or accept a whole number between -2,147,483,648 and 2,147,483,647 inclusive.

Integer (64 bit)

Parameters of type integer (64 bit) can return or accept a whole number between -9,223,372,036,854,775,808 and 9,223,372,036,854,775,807 inclusive.

Float (32 bit)

Parameters of type float (32 bit) can return or accept a 4-byte floating-point number.

Float (64 bit)

Parameters of type float (64 bit) can return or accept an 8-byte floating-point number.

Decimal

Parameters of type decimal may include a fractional portion separated by a point. The number of allowed digits on either side of the point may be specified.

Example: A parameter type specified as decimal (5.2) would have a maximum of 5 digits before the decimal point, and 2 after.

Date

Parameters of type date should be sent to (and are sent from) the service as a combined date and time in ISO 8601 format. Time zone information must be included, or the results of the API call are not defined.

All dates returned by the service are in UTC.

Time Zone

Time zones are returned as a human-readable string as described by IANA and stored in their Time Zone Database.

Enums

Fields that are enums are returned as strings in JSON. The string value will be limited to the possible enum values for the as defined for the type. All enum types have the possibility of being null.

GroupType

Specifies the type of a group. Values:

"Account"
"Organization"
"Location"
"Department"

Errors

The following error codes are returned by this API:

Error Code	Meaning
400	Bad Request -- The request contains an invalid payload.
401	Unauthorized -- The API key provided is not allowed to perform the operation.
403	Forbidden -- The API key provided is not allowed to perform the operation.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- The specified request is not allowed.
406	Not Acceptable -- The format of the request is not in an acceptable. Supported format is `json`.
409	Conflict - The request could not be completed due to a conflict with the current state of the target resource.
410	Gone -- The resource is no longer available.
422	Unprocessable Entity -- Logic conflicts in provided parameters.
429	Too Many Requests -- Too many requests have been made for this interval.
500	Internal Server Error -- The server had an unexpected error.
503	Service Unavailable -- The server is offline for maintenance. Please try again later.

Data API

SmartSense Data API

SmartSense provides a set of endpoints for gathering asset and sensor data programmatically.

Asset Model

SmartSense organizes Devices, Sensors, and their readings into logical units referred to as Assets.

Asset

An Asset is a logical abstraction of something that is being monitored. A common example is a fridge or a freezer.

Sensor Point

Assets have Sensor Points. A Sensor Point is a logical abstraction for what is being monitored. A fridge Asset, for example, could have a temperature and a humidity Sensor Point.

Sensor Points cannot be moved between Assets. A Sensor Point can only have one Sensor associated with it at a time.

Sensor

A Sensor is a physical thing that measures something, like the current temperature. In SmartSense a Sensor gets attached to a Sensor Point to link its data to an Asset.

A Sensor is also attached to one, and only one, Device.

Device

A Sensor must be connected to a Device. Devices are what communicate the data from the Sensors to SmartSense.

An Example

A store has a fridge and an Asset in SmartSense that represents it. The temperature and humidity in the fridge must be monitored, so the Asset has two Sensor Points, one for temperature, and one for humidity.

Inside the fridge there is a Device with a temperature and humidity Sensor attached to it. In SmartSense these Sensors get linked with the Asset's Sensor Points.

If the Device in the fridge gets replaced with a new Device and Sensors, the new Sensors would then be associated with the same Sensor Points on the Asset in SmartSense.

Querying the readings for the fridge's Sensor Points would show the readings from the first set of Sensors for the times when they were attached to the Sensor Points, and the new Sensors for the times after they were attached.

Results Paging

Sample Paging Response Fields

{
  "totalCount": 1555,
  "pageSize": 50,
  "count": 50,
  "pageNumber": 1
}

Many of the endpoints that return a list of data are subject to paging. Paged responses include the following paging information:

name	type	description
totalCount	integer (32 bit)	The total number of items found for the request.
pageSize	integer (32 bit)	The maximum number of items that could be returned in this response.
count	integer (32 bit)	The actual number of items that were returned in this response.
pageNumber	integer (32 bit)	The current page number. This number is 1 indexed.

If there is an additional page, a link to the next page is specified in the HTTP response header called next. This header may include default values for non-required GET parameters that were not specified in the original request, so this header should be preferred over manually creating the URI for your next page to guarantee correct results.

The default page size can be overriden by setting a pageSize query parameter:

name	location	type	required	description
pageSize	query string	integer (32 bit)	no	Set the desired page size for results. Default is `50`. The maximum is `1000`.
pageNumber	query string	integer (32 bit)	no	Set the desired page number. Default is `1`. As stated above, the recommendation is to use the `next` response header when pulling multiple pages.

Synchronizing Readings

Clients wishing to have their own copy of sensor or device readings can use the processedAfterDate query parameter to keep in sync with SmartSense. Whenever the last "page" of results is returned from a query containing a processedAfterDate value, a header (nextProcessedAfterDate) is included in the response specifying the processedAfterDate value to use on the next query.

Example: Client Alice wants all sensor readings since March 1st, 2021 (UTC), as well as any readings that arrive after that point. Alice will poll SmartSense every 15 minutes, using the processedAfterDate query parameter.

To begin, Alice makes the following request:

GET /v1/data/asset/4146/sensorpoint/55689?processedAfterDate="2021-03-01T00:00:00.00Z"

The response from the server may contain several "pages" of data. Each "page" (with the exception of the last "page") will have a header in the response with a link to the next "page". The final "page" will contain a nextProcessedAfterDate header with a datetime value. Alice saves this value as X.

After retrieving all "pages", Alice now has a copy of all sensor readings from the account up to and including the datetime X.

After 15 minutes have passed, Alice once again queries SmartSense for readings. This time, Alice uses a new value for processedAfterDate: specifically nextProcessedAfterDate value X from the last "page" of the previous request. SmartSense will then respond with any new readings that have arrived since Alice’s last query.

Alice continues to repeat this process every 15 minutes to stay in sync with SmartSense.

Data Specific Types

The SmartSense Data API defines the following types:

Dates

All dates returned by the service are in UTC.

readingDate

readingDate specifies the point in time at which a reading was captured by a sensor or device, e.g., a temperature sensor recorded a temperature of 32.45°F on Friday, January 15th at 3:17pm, UTC.

processedDate

processedDate specifies the point in time at which a reading was processed by SmartSense.

Example: An external temperature sensor, attached to a device, records a temperature of 32.45°F on Friday, January 15th at 3:17pm, UTC. Due to an interruption in cellular service, the device is not able to send the reading to SmartSense for five minutes. In this case the reading would have a readingDate of 3:17pm, but a processedDate of 3:22pm.

Applications using this API to capture all readings processed by SmartSense should use the processedAfterDate filter to request new readings since the last request. (see Synchronizing Readings)

lastActivityDate

lastActivityDate specifies the time a device or sensor last contacted SmartSense. If the device has never contacted SmartSense this field will be null.

Numbers

DeviceId

The deviceId field is a 20-digit number that is converted to string and transmitted. It is converted to string to ease interoperability.

Power Reading Values

A device reading type of Power indicates the status of a device's power source. Values range from 0 to 10 for battery only devices (e.g. ZPoint Wireless Sensor). For AC powered devices with battery backup, the values range from 16 to 26 when the device is plugged in and 0 to 10 when not plugged in. A value of 16 indicates AC power only, while a value higher than 16 would indicate AC power plus some battery backup.

Signal Strength Reading Values

A device reading type of Signal Strength is a normalized status of a device's wireless signal. Values range from 1-10.

IncidentSeverity

IncidentServerity describes how severe an Incident or Alarm is. An Incident's severity is always equal to the highest severity of any Alarm associated with the Incident. An Alarm's severity is always equal to the severity configured on the Configured Alarm that created it. This type has 5 values:

1: Lowest
2: Low
3: Medium
4: High
5: Highest

IncidentStatus

IncidentStatus describes the current status of an Incident. These values can be updated by the system as new Readings come in that resolve or retrigger Alarms, or by Users interacting with Incidents in the UI. This type has 4 values:

0: New
1: Active
2: On Hold
99: Closed

The New status means the system has created the Incident, but no User action has been taken. Active indicate a User has been assigned to the Incident. On Hold is functionally the same as Active, with the addition that a User has selected to put the Incident On Hold in the UI. And Closed means the Incident is resolved and will no longer be used by the System; this means that new reading violations will result in new incidents being created.

AlarmStatus

AlarmStatus describes the current status of an Alarm. An Incident can contain have many Alarms, so their status is tracked separately per Alarm. This type has 4 values:

0: Closed
1: Open
2: Acknowledged
3: Resolved

The Closed status means the system will no longer take any actions with the Alarm. New reading violations will result in new Alarms. The Open status means the Alarm is active. The current reading is out of range, and the Alarm is available for User action. Acknowledged is the same as Open, with the addition of indicating that a User acknowledged the Alarm in the UI. A Resolved alarm means the readings have come back in range.

ViolationOperator

ViolationOperator describes the relational operator used to compare an incoming reading against an Alarm threshold. All Incidents and Alarms are created by the system by comparing readings gathered by sensors to Configured Alarm Thresholds. These Thresholds consist of a value and comparison operator, which are also tracked in the Alarm instance. This type has 3 values:

-1: Less Than
0: Equal To
1: Greater Than

ThresholdType

ThresholdType describes the type of readings that an Alarm is setup or triggered for. Each Incident will only track Alarms for one type of reading. As an example, consider an Asset with both temperature and humidity sensors that has two Configured Alarms, one for temperature and one for humidity. If both sensors go out of range for their respective Configured Alarm, two Incidents (one per reading type) will be created. The type of reading that each Incident is responsible for is tracked with this ThresholdType enumeration. The possible values for this type are:

1: Temperature
2: Missed Report
3: Humidity
4: Power
5: Wind Speed
6: Soil Moisture
7: Flood
8: Voltage
9: Pressure
10: Pressure Pascal
11: Leaf Wetness
12: Rainfall
13: Percent CO2
14: Percent O2
15: OLPHC Pressure
16: Dry Contact
17: CentiPascal Pressure
18: Power Low Battery
20: Starwatch Pressure
21: Starwatch Level
23: Pressure KiloPascal
24: Current MilliAmp
25: Current Amp
26: Charge
27: Level
28: Capacitance PicoFarad
99: Validation

Enums

Fields that are enums are returned as strings in JSON. The string value will be limited to the possible enum values as defined for the type. All enum types have the possibility of being null.

ReadingType

Specifies the type of a reading. Values:

"Temperature"
"Humidity"
"Power"
"Signal Strength"

Unit

Specifies the unit of a reading. Values:

DeviceType

Specifies the type of a device. Values:

"Node"
"Repeater"
"Gateway"

SensorType

Specifies the type of a sensor. Values:

"Temperature"
"Humidity"

Asset

The /asset endpoints can be used to retrieve information about the assets in the user's account. The asset response includes information about what devices are attached to the assets.

Get One Asset

Sample Get One Asset Request

curl --silent \
  --get "https://api.smartsense.co/data/v1/asset/7746" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/data/v1/asset/7746',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    timeout=5
)

print(r.json())

Sample Get One Asset Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
strict-transport-security: max-age=15724800; includeSubDomains

{
  "assetId": 1436,
  "assetName": "Pharmacy",
  "groupId": "104",
  "groupName": "West",
  "environment": "Freezer",
  "lastActivityDate": "2021-01-25T18:54:34.5970000Z",
  "tags": [
    "Manager: Casey",
    "State: Oregon"
  ],
  "sensorPoints": [
    {
      "sensorPointId": 126,
      "sensorPointName": "Top Temperature",
      "devices": [
        "23004000080793070793",
        "74012807612084533500"
      ]
    },
    {
      "sensorPointId": 129,
      "sensorPointName": "Bottom Temperature",
      "devices": [
        "86004000080793070956"
      ]
    }
  ]
}

Get the asset identified by the provided asset ID.

GET /data/v1/asset/{assetId}

Parameters

name	location	type	required	description
assetId	path	integer (32 bit)	yes	Unique identifier of the asset.

Output Fields

name	type	description
assetId	integer (32 bit)	Unique identifier of the asset.
assetName	string (max 50)	The name of the asset.
groupId	integer (64 bit)	Unique ID of the group. Will be null if the device does not belong to a group.
groupName	string (max 255)	Name of the group to which the device belongs. Will be null if the device does not belong to a group.
environment	string (max 50)	Name of the environment the asset is assigned to.
lastActivityDate	date	The last time a device belonging to the asset communicated with SmartSense.
tags	array	Array of strings of tag data (string length max 255).
sensorPoints	array	Array of `sensorPoint data`.

The sensorPoint data structure is as follows:

name	type	description
sensorPointId	integer (32 bit)	Unique identifier of the sensor point.
sensorPointName	string (max 150)	The name of the sensor point.
devices	array	Array of DeviceIds.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
404	Not Found

Get All Assets

Sample Get All Assets Request

curl --silent \
  --get "https://api.smartsense.co/data/v1/asset" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/data/v1/asset',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    timeout=5
)

print(r.json())

Sample Get All Assets Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
next: https://api.smartsense.co/data/v1/asset?PageNumber=2&PageSize=50
strict-transport-security: max-age=15724800; includeSubDomains

{
  "assets": [
    {
      "assetId": 1436,
      "assetName": "Pharmacy",
      "groupId": "104",
      "groupName": "West",
      "environment": "Freezer",
      "lastActivityDate": "2021-01-25T18:54:34.5970000Z",
      "tags": [
        "Manager: Casey",
        "State: Oregon"
      ],
      "sensorPoints": [
        {
          "sensorPointId": 126,
          "sensorPointName": "Top Temperature",
          "devices": [
            "23004000080793070793",
            "74012807612084533500"
          ]
        },
        {
          "sensorPointId": 129,
          "sensorPointName": "Bottom Temperature",
          "devices": [
            "86004000080793070956"
          ]
        }
      ]
    },
    ...
  ],
  "totalCount": 352,
  "pageSize": 50,
  "count": 50,
  "pageNumber": 1
}

Get all the assets in the account to which the API client has access.

GET /data/v1/asset

Parameters

None.

Output Fields

name	type	description
assets	array	Array of asset data. The structure is the same as Get One Asset.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Unprocessable Entity

Device

The /device endpoints can be used to retrieve information about the devices in an account. The device response includes information about what assets the device is associated with, as well as what sensors are attached to the device.

Get One Device

Get the active device identified by the device ID.

GET /data/v1/device/{deviceId}

Sample Get One Device Request

curl --silent \
  --get "https://api.smartsense.co/data/v1/device/23004000080793070793" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/data/v1/device/23004000080793070793',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    timeout=5
)

print(r.json())

Sample Get One Device Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
strict-transport-security: max-age=15724800; includeSubDomains

{
  "deviceId": "23004000080793070793",
  "deviceType": null,
  "groupId": "104",
  "groupName": "West",
  "gatewayId": "40004000580363050801",
  "reportInterval": 5,
  "lastActivityDate": "2021-01-25T18:54:34.5970000Z",
  "assets": [
    {
      "assetId": 5424,
      "assetName": "West Cooler",
      "environment": "Cooler"
    }
  ],
  "sensors": [
    {
      "sensorId": 62531,
      "displayName": "West Cooler Temp",
      "serialNumber": null,
      "sensorType": "Temperature",
      "sensorTypeId": 2,
      "port": 1,
      "lastActivityDate": "2021-01-25T18:54:34.5970000Z"
    }
  ]
}

Parameters

name	location	type	required	description
deviceId	path	DeviceId	yes	Unique identifier of the device.

Output Fields

The device data structure is as follows:

name	type	description
deviceId	DeviceId	Unique identifier of the device.
deviceType	DeviceType	Indicates whether the device is a Node, Repeater, Gateway etc. May be null if the device has not contacted SmartSense yet.
groupId	integer (64 bit)	Unique ID of the group. Will be null if the device does not belong to a group.
groupName	string (max 255)	Name of the group to which the device belongs. Will be null if the device does not belong to a group.
gatewayId	string (max 20)	The gateway through which this device is communicating, if applicable.
reportInterval	integer (32 bit)	Number of minutes the device is configured to wait between taking readings.
lastActivityDate	date	The last time the device contacted SmartSense.
assets	array	Array of `asset data`.
sensors	array	Array of `sensor data`.

The asset data structure is as follows:

name	type	description
assetId	integer (32 bit)	Unique identifier of the asset.
assetName	string (max 50)	The name of the asset.
environment	string (max 50)	Name of the environment the asset is assigned to.

The sensor data structure is as follows:

name	type	description
sensorId	integer (32 bit)	Unique identifier for the sensor.
displayName	string (max 50)	The name of the sensor as displayed on SmartSense.
serialNumber	string (max 15)	The serial number of the sensor where supported.
sensorType	SensorType	The type of the sensor.
sensorTypeId	integer (32 bit)	Numerical representation of the sensor's type.
port	byte	The port number of the device this sensor is attached to (may be null).
lastActivityDate	date	The last time the sensor contacted SmartSense.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
404	Not Found
422	Unprocessable Entity

Get All Devices

Sample Get All Devices Request

curl --silent \
  --get "https://api.smartsense.co/data/v1/device" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/data/v1/device',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    timeout=5
)

print(r.json())

Sample Get All Devices Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
next: https://api.smartsense.co/data/v1/device?PageNumber=2&PageSize=50
strict-transport-security: max-age=15724800; includeSubDomains

{
   "devices": [
    {
      "deviceId": "23004000080793070793",
      "deviceType": null,
      "groupId": "104",
      "groupName": "West",
      "gatewayId": "40004000580363050801",
      "reportInterval": 5,
      "lastActivityDate": "2021-01-25T18:54:34.5970000Z",
      "assets": [
        {
          "assetId": 5424,
          "assetName": "West Cooler",
          "environment": "Cooler"
        }
      ],
      "sensors": [
        {
          "sensorId": 62531,
          "displayName": "West Cooler Temp",
          "serialNumber": null,
          "sensorType": "Temperature",
          "sensorTypeId": 2,
          "port": 1,
          "lastActivityDate": "2021-01-25T18:54:34.5970000Z"
        }
      ]
    },
    {
      "deviceId": "74012807612084533500",
      "deviceType": null,
      "groupId": "158",
      "groupName": "East",
      "gatewayId": "40004000580363080955",
      "reportInterval": 5,
      "lastActivityDate": "2021-01-25T18:56:38.5970000Z",
      "assets": [
        {
          "assetId": 5427,
          "assetName": "East Cooler",
          "environment": "Cooler"
        }
      ],
      "sensors": [
        {
          "sensorId": 62865,
          "displayName": "East Cooler Temp",
          "serialNumber": null,
          "sensorType": "Temperature",
          "sensorTypeId": 2,
          "port": 1,
          "lastActivityDate": "2021-01-25T18:56:38.5970000Z"
        }
      ]
    },
    {
      "deviceId": "11666000000010000990",
      "deviceType": null,
      "groupId": "1004",
      "groupName": "West",
      "gatewayId": "13004000580363078314",
      "reportInterval": 5,
      "lastActivityDate": "2021-01-22T20:50:22.5970000Z",
      "assets": [
        {
          "assetId": 5102,
          "assetName": "West Freezer",
          "environment": "Freezer"
        }
      ],
      "sensors": [
        {
          "sensorId": 74631,
          "displayName": "West Freezer Temp",
          "serialNumber": null,
          "sensorType": "Temperature",
          "sensorTypeId": 2,
          "port": 1,
          "lastActivityDate": "2021-01-22T20:50:22.5970000Z"
        }
      ]
    },
    ...
  ],
  "totalCount": 103,
  "pageSize": 50,
  "count": 50,
  "pageNumber": 1
}

Get all the active devices in the account to which the API client has access.

GET /data/v1/device

Parameters

None.

Output Fields

name	type	description
devices	array	Array of `device data`. The structure is the same as Get One Device.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Unprocessable Entity

Group

The /group endpoints can be used to retrieve information about the group hierarchy in an account.

Get One Group

Sample Get Group Request

curl --silent \
  --get "https://api.smartsense.co/data/v1/group/35286" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense/data/v1/group/35268',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    timeout=5
  )

print(r.json())

Sample Get Group Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
strict-transport-security: max-age=15724800; includeSubDomains

{
  "groupId": 35268,
  "address": "1776 Example Dr",
  "name": "Example Org",
  "parentId":  "35266",
  "timeZone": "Eastern Standard Time",
  "type": "Organization"
}

GET /data/v1/group/{groupId}

Get the group identified by the group ID.

Parameters

name	location	type	required	description
groupId	path	integer (64 bit)	yes	ID of the group to retrieve.

Output Fields

name	type	description
groupId	integer (64 bit)	Unique group identifier.
address	string (max 100)	The address associated with this group.
name	string (max 255)	Name of the group.
parentId	integer (64 bit)	ID of this group's parent, if any, in the group hierarchy.
timezone	string (max 50)	The time zone assigned to the group as a human readable string.
type	GroupType	This group's type.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
404	Not Found

Get All Groups

Sample Get All Groups Request

curl --silent \
  --get "https://api.smartsense.co/data/v1/group" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense/data/v1/group',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    timeout=5
  )

print(r.json())

Sample Get Groups Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
next: https://api.smartsense.co/data/v1/group?PageNumber=2&PageSize=50
strict-transport-security: max-age=15724800; includeSubDomains

{
   "groups" : [
    {
      "groupId": 35268,
      "address": "1776 Example Dr",
      "name": "Example Org",
      "parentId":  "35266",
      "timeZone": "Eastern Standard Time",
      "type": "Organization"
    },
    {
      "groupId": 35270,
      "address": "1776 Example Dr",
      "name": "Example Location",
      "parentId":  "35268",
      "timeZone": "Eastern Standard Time",
      "type": "Location"
    },
    ...
  ],
  "totalCount": 76,
  "pageSize": 50,
  "count": 50,
  "pageNumber": 1
}

This endpoint gets all the groups in the account to which the API client has access. Groups are returned as a flat list. The response may be broken up into pages, requiring multiple requests to retrieve all of the groups in the account.

GET data/v1/group

Parameters

None.

Output Fields

name	type	description
groups	array	Array of group data. The structure is the same as Get One Group.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Unprocessable Entity

Incident

The /incident endpoint can be used to retrieve information about the incidents in the user's account.

Get Incidents

Sample Get Incidents Request

curl --silent \
  --get "https://api.smartsense.co/data/v1/incident" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json" \
  --data "AssetId=1777" \
  --data "IncidentOpenedStartDate=2022-09-01T00:00:00Z" \
  --data "IncidentOpenedEndDate=2022-10-01T00:00:00Z"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/data/v1/incident',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    params={
      'AssetId': 1777
      'IncidentOpenedStartDate': '2022-09-01T00:00:00Z',
      'IncidentOpenedEndDate': '2022-10-01T00:00:00Z',
    }
    timeout=5
)

print(r.json())

Sample Get Incidents Response

HTTP/1.1 200 OK
date: Mon, 24 Oct 2022 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
next: https://api.smartsense.co/data/v1/incident?IncidentOpenedStartDate=2022-09-01%2012%3A00%3A00%20AM&IncidentOpenedEndDate=2022-09-27%206%3A06%3A56%20PM?PageNumber=2&PageSize=50
strict-transport-security: max-age=15724800; includeSubDomains

{
  "incidents": [
    {
      "incidentId": 1886,
      "assetId": 1777,
      "assignedUserId": null,
      "automaticallyClosed": false,
      "closedDate": null,
      "deviceId": "11666000000014001320",
      "openedDate": "2022-09-09T19:00:00.7730000",
      "resolvedDate": null,
      "severity": 4,
      "status": 0,
      "alarms": [
        {
          "dateResolved": null,
          "dateTriggered": "2022-09-09T19:00:15.4470000",
          "name": "Fridge Below 0",
          "readingDate": "2022-09-09T19:00:00.7730000",
          "readingUnit": "F",
          "readingValue": -3.52,
          "severity": 4,
          "status": 2,
          "thresholdValue": 0,
          "type": 1,
          "violationOperator": -1
        }
      ],
      "correctiveActions": [
        {
          "date": "2022-09-10T15:24:47.1370000",
          "details": "Fridge temperature was adjusted",
          "userId": 184
        }
      ]
    },
    ...
  ],
  "totalCount": 15,
  "pageSize": 50,
  "count": 15,
  "pageNumber": 1
}

Get all the Incidents in the account that satisfy the given query parameters.

GET /data/v1/incident

Parameters

name	location	type	required	description
assetId	query string	integer (32 bit)	no	Limit the result set to Incidents involving an Asset, given by its ID. The AssetId parameter is mutually exclusive with the GroupId parameter, both cannot be provided in a single request.
groupId	query string	integer (64 bit)	no	Limit the result set to Incidents involving Assets assigned to a Group, given by its ID, or any of its child Groups. The target Group must be a Location or Department Group. The GroupId parameter is mutually exclusive with the AssetId parameter, both cannot be provided in a single request.
incidentOpenedStartDate	query string	date	no	Limit the result set to Incidents that were opened after the given Date. Default is 1 hour prior to the request being received by the server. The value cannot be more than 90 days prior to `incidentOpenedEndDate`
incidentOpenedEndDate	query string	date	no	Limit the result set to Incidents that were opened before the given Date. Default is the time the request was received by the server. The value cannot be more than 90 days after the `incidentOpenedStartDate`

Output Fields

name	type	description
incidents	array	Array of `Incident Data`.

The Incident Data structure is as follows:

name	type	description
incidentId	integer (64 bit)	The ID of the Incident object.
assetId	integer (32 bit)	The ID of the Asset the Incident was created for.
assignedUserId	integer (32 bit)	The ID of the User currently assigned to the Incident.
automaticallyClosed	boolean	Indicates whether the Incident was automatically closed by the system.
closedDate	date	The Date the Incident was closed, or null if the Incident is still open.
deviceId	DeviceId	The ID of the Device the Incident was created for.
openedDate	date	The Date the Incident was Opened.
resolvedDate	date	The Date all Alarms for the Incident were resolved, or null if there are open Alarms.
severity	IncidentSeverity	The Severity of the Incident. The Incident's severity is always equal to the highest severity of its Alarms.
status	IncidentStatus	The current Status of the Incident.
alarms	array	Array of `Alarm Data` for the Incident.
correctiveActions	array	Array of `Corrective Action` data for the Incident.

The Alarm Data structure is as follows:

name	type	description
dateResolved	date	The Date the Alarm was resolved, or null if is not resolved yet.
dateTriggered	date	The Date the Alarm was triggered.
name	string	The name of the Configured Alarm that is responsible for triggering the Alarm.
readingDate	date	The Date of the Reading that triggered the Alarm.
readingUnit	Unit	Specifies the unit for the readingValue.
readingValue	float (64 bit)	The value of the Reading that triggered the Alarm.
severity	IncidentSeverity	The Severity of the Alarm.
status	AlarmStatus	The current Status of the Alarm.
thresholdValue	float (64 bit)	The value the Alarm was set to trigger at, above, or below.
type	ThresholdType	The type of Threshold that triggered the Alarm.
ViolationOperator	ViolationOperator	The operator used to compare incoming readings against the `thresholdValue`.

The CorrectiveAction Data structure is as follows:

name	type	description
date	date	The Date the CorrectiveAction was documented.
details	string	The message describing the CorrectiveAction.
userId	integer (32 bit)	The ID of the User who documented the CorrectiveAction.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
404	NotFound
422	Unprocessable Entity

Readings

Get Asset Sensor Point Readings

Sample Get Asset Sensor Point Readings Request

curl --silent \
  --get 'https://api.smartsense.co/data/v1/readings/asset/1464/sensorpoint/1686' \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json" \
  --data "ReadingStartDate=2021-05-01T00:00:00Z" \
  --data "ReadingEndDate=2021-06-01T00:00:00Z"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/data/v1/readings/asset/1464/sensorpoint/1686',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json',
    },
    params={
      'ReadingStartDate': '2021-05-01T00:00:00Z',
      'ReadingEndDate': '2021-06-01T00:00:00Z',
    }
    timeout=5
)

print(r.json())

Sample Get Asset Sensor Point Readings Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
strict-transport-security: max-age=15724800; includeSubDomains

{
  "assetId": 1464,
  "assetName": "East Freezer",
  "sensorPointId": 1686,
  "sensorPointName": "Top Shelf Temperature",
  "readings": [
      {
        "sensorId": 38003,
        "deviceId": "11666100000000000994",
        "port": 0,
        "readingType": "Temperature",
        "unit": "F",
        "readingValue": -10,
        "readingDate": "2021-05-17T15:02:46.3560000",
        "processedDate": "2021-05-17T15:03:45.8740000",
        "alarm": false
    },
    {
        "sensorId": 38003,
        "deviceId": "11666100000000000994",
        "port": 0,
        "readingType": "Temperature",
        "unit": "F",
        "readingValue": -11,
        "readingDate": "2021-05-17T15:03:29.7090000",
        "processedDate": "2021-05-17T15:04:29.1630000",
        "alarm": false
    }
    {
        "sensorId": 39057,
        "deviceId": "11666100000000000997",
        "port": 0,
        "readingType": "Temperature",
        "unit": "F",
        "readingValue": -10,
        "readingDate": "2021-05-17T15:03:29.7090000",
        "processedDate": "2021-05-17T15:04:29.1630000",
        "alarm": false
    },
    ...
  ],
  "totalCount": 10352,
  "pageSize": 50,
  "count": 50,
  "pageNumber": 1
}

This endpoint gets all readings for the sensors attached to the specified sensor point on the specified asset.

GET /data/v1/readings/asset/{assetId}/sensorpoint/{sensorpointId}

Parameters

name	location	type	required	description
assetId	path	integer (32 bit)	yes	Unique identifier of the target asset.
sensorPointId	path	integer (32 bit)	yes	Unique identifier of the target sensor point.
readingStartDate	query string	date	no	Limit the result set to readings with a readingDate greater than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is 1 hour prior to the request being received by the server.
readingEndDate	query string	date	no	Limit the result set to readings with a readingDate less than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is the time the request is received by the server.
processedAfterDate	query string	date	no	Limit the result set to readings that have been processed after the specified date. If not provided the results are not filtered by processedDate.

Output Fields

name	type	description
assetId	integer (32 bit)	Unique identifier of the asset.
assetName	string (max 50)	The name of the asset.
sensorPointId	integer (32 bit)	Unique identifier of the sensor point.
sensorPointName	string (max 150)	The name of the sensor point.
readings	array	Array of `readings data`.

The readings data structure is as follows:

name	type	description
sensorId	integer (32 bit)	Unique identifier for the sensor.
deviceId	DeviceId	Unique identifier of the device.
port	byte	Port number for the sensor (may be null).
readingType	ReadingType	Specifies the type of reading.
unit	Unit	Specifies what unit the reading is being reported in.
readingValue	decimal(9.4)	Reading value.
readingDate	date	Date at which the reading was made.
processedDate	date	Date at which the reading was processed by SmartSense.
alarm	boolean	Indicates if this reading violated an alert threshold configured in SmartSense.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
404	Not Found
422	Unprocessable Entity

Get Asset Devices' Readings

Sample Get Devices' Readings Request

curl --silent \
  --get 'https://api.smartsense.co/data/v1/readings/asset/1464/devices' \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json" \
  --data "ReadingStartDate=2021-05-01T00:00:00Z" \
  --data "ReadingEndDate=2021-06-01T00:00:00Z"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/data/v1/readings/asset/1464/devices',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json',
    },
    params={
      'ReadingStartDate': '2021-05-01T00:00:00Z',
      'ReadingEndDate': '2021-06-01T00:00:00Z',
    }
    timeout=5
)

print(r.json())

Sample Get Devices' Readings Response

HTTP/1.1 200 OK
date: Mon, 24 May 2021 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
next: https://api.smartsense.co/data/v1/readings/asset/1464/devices?ReadingStartDate=2021-05-01T00:00:00Z&ReadingEndDate=2021-06-01T00:00:00Z&PageNumber=2&PageSize=50
strict-transport-security: max-age=15724800; includeSubDomains

{
  "assetId": 1464,
  "assetName": "East Freezer",
  "readings": [
    {
        "deviceId": "11666000000010000994",
        "readingType": "Power",
        "unit": null,
        "readingValue": 5,
        "readingDate": "2021-05-22T14:34:51.9260000",
        "processedDate": "2021-05-22T14:35:55.9290000",
        "alarm": true
    },
    {
        "deviceId": "11666000000010000997",
        "readingType": "Power",
        "unit": null,
        "readingValue": 8,
        "readingDate": "2021-05-22T14:34:51.9260000",
        "processedDate": "2021-05-22T14:35:55.9290000",
        "alarm": true
    },
    {
        "deviceId": "11666000000010000994",
        "readingType": "Signal Strength",
        "unit": null,
        "readingValue": 7,
        "readingDate": "2021-05-22T14:34:51.9260000",
        "processedDate": "2021-05-22T14:35:55.9290000",
        "alarm": true
    },
    ...
  ],
  "totalCount": 56431,
  "pageSize": 50,
  "count": 50,
  "pageNumber": 1
}

This endpoint gets all readings for all the devices attached to the specified specified asset.

GET /data/v1/readings/asset/{assetId}/devices

Parameters

name	location	type	required	description
assetId	path	integer (32 bit)	yes	Unique identifier of the target asset.
readingStartDate	query string	date	no	Limit the result set to readings with a readingDate greater than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is 1 hour prior to the request being received by the server.
readingEndDate	query string	date	no	Limit the result set to readings with a readingDate less than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is the time the request is received by the server.
processedAfterDate	query string	date	no	Limit the result set to readings that have been processed after the specified date. If not provided the results are not filtered by processedDate.

Output Fields

name	type	description
assetId	integer (32 bit)	Unique identifier of the asset.
assetName	string (max 50)	The name of the asset.
readings	array	Array of `readings data`.

The readings data structure is as follows:

name	type	description
deviceId	DeviceId	Unique identifier of the device.
readingType	ReadingType	Specifies the type of reading.
unit	Unit	Specifies what unit the reading is being reported in.
readingValue	decimal(9.4)	Reading value.
readingDate	date	Date at which the reading was made.
processedDate	date	Date at which the reading was processed by SmartSense.
alarm	boolean	Indicates if this reading violated an alert threshold configured in SmartSense.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Unprocessable Entity

Report API

SmartSense Report API

SmartSense provides a set of endpoints for generating report information.

Report Specific Types

The SmartSense Report API defines the following types:

Numbers

TaskSelectionType

TaskSelectionType describes the type of task selection. This type has four values:

0: None
1: Fixed
2: Randomized
3: Dynamic

The Fixed type means that all tasks in the checklist must be completed by the designated type. The Randomized type is a Fixed-type checklist with the items in a random order. The _Dynamic_type means that a specified number of tasks must be completed. E.g., if there are 12 listed tasks, the user may only have to complete 6 of the 12.

TaskType

TaskType describes the task. This type has 10 values:

0: Manual Temperature
1: Sensor Temperature
2: Probe Temperature
3: Manual Number
4: Manual Text
5: Select Single
6: Select Many
7: Picture
8: Checkbox
9: Asset Sensor Reading

Enums

Fields that are enums are returned as strings in JSON. The string value will be limited to the possible enum values as defined for the type. All enum types have the possibility of being null.

AnswerStatus

Specifies the type of a reading. Values:

"Incomplete"
"Complete"
"CompletedNotApplicable"
"RequiresFollowUp"
"CompletedWithCorrectiveAction"

The Incomplete status means that the user has not yet provided a response to the task. The Complete status means that the user provided a response to a task and that the task has a value associated, e.g., the user used a temperature probe to take a temperature or inputed in the temperature manually. The CompletedNotApplicable status means that the user provided a response to a task, but it was not necessary to provide a value. The RequiresFollowUp status means that the user has missed follow-up tasks which still need to be completed. The CompletedWithCorrectiveAction status means that the task was completed and performed at least one associated corrective action.

TaskClass

Specifies the class of a task. Values:

"FoodStep"
"Task"

The FoodStep class indicates that the task relates to a specific food item, e.g., checking the temperature of cooked chicken. The Task class indicates that the task does not relate to a specific food item, e.g., checking the SmartSense web application for any new incidents.

Above Store Report

The /abovestore endpoint can be used to retrieve checklist/task completion information for a given group as well as summary information for descendent groups.

Get Above Store Report

Sample Get Above Store Report Request

curl --silent \
  --get "https://api.smartsense.co/report/v1/abovestore/group/1" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json" \
  --data "ReportDate=2022-09-01T00:00:00Z"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/report/v1/abovestore/group/1',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    params={
      'ReportDate': '2022-09-01T00:00:00Z',
    }
    timeout=5
)

print(r.json())

Sample Get Above Store Report Response

HTTP/1.1 200 OK
date: Mon, 24 Oct 2022 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding

{
  "groupId": 3589,
  "day": "2023-02-07T00:00:00",
  "overallCompletionPercentage": 0.9431321084864393,
  "totalAvailableTasks": 254,
  "totalMissedFollowUpTasks": 0,
  "totalCompletedTasks": 189,
  "totalCorrectiveActions": 4,
  "totalIncompleteOrMissedTasks": 65,
  "results": [
    {
      "groupId": 4291,
      "completionPercentage": 0.4881889763779528,
      "incompleteOrMissedTasks": 65,
      "availableTasks": 127,
      "missedFollowUpTasks": 0,
      "completedTasks": 62,
      "correctiveActions": 1
    },
    {
      "groupId": 4292,
      "completionPercentage": 1.0,
      "incompleteOrMissedTasks": 0,
      "availableTasks": 127,
      "missedFollowUpTasks": 0,
      "completedTasks": 127,
      "correctiveActions": 3
    }
  ]
}

Get the Above Store report for the given group as well as summary information for descendant groups.

GET /report/v1/abovestore/group/{groupId}

Parameters

name	location	type	required	description
groupId	path	integer (64 bit)	yes	ID of the group to retrieve. Any group type can be used, but usage is typically limited to `Location` and `Department` groups.
reportDate	query string	date	no	Pull report for a given date. Default is the current date. Value cannot be in the future.

Output Fields

name	type	description
groupId	integer (64 bit)	Unique group identifier.
day	date	The date of the report.
overallCompletionPercentage	float (64 bit)	Returns `totalCompletedTasks` divided by `totalAvailableTasks` as a number between 0 and 1. Will be `null` when `totalAvailableTasks` is zero.
totalAvailableTasks	integer (32 bit)	Total number of available tasks.
totalMissedFollowUpTasks	integer (32 bit)	Total number of missed or follow-up tasks.
totalCompletedTasks	integer (32 bit)	Total number of completed tasks.
totalCorrectiveActions	integer (32 bit)	Total number of corrective actions.
totalIncompleteOrMissedTasks	integer (32 bit)	Total number of incomplete or missed tasks.
results	array	Array of `Results Data` for each descendant group. May be empty.

The Results Data structure is as follows:

name	type	description
groupId	integer (64 bit)	Unique group identifier.
completionPercentage	float (64 bit)	Returns `completedTasks` divided by `availableTasks` as a number between 0 and 1. Will be `null` when `availableTasks` is zero.
availableTasks	integer (32 bit)	The number of available tasks.
missedFollowUpTasks	integer (32 bit)	The number of missed follow-up tasks.
completedTasks	integer (32 bit)	The number of completed tasks.
correctiveActions	integer (32 bit)	The number of corrective actions.
incompleteOrMissedTasks	integer (32 bit)	The number of incomplete or missed tasks.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized

Scheduled Checklist Report

The /ScheduledChecklist endpoint can be used to retrieve a daily scheduled checklist report including checklist details.

Get Scheduled Checklist Report

Sample Get Scheduled Checklist Report Request

curl --silent \
  --get "https://api.smartsense.co/report/v1/scheduledchecklist/group/1" \
  --header "Authorization: Bearer $TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json" \
  --data "ReportDate=2022-09-01T00:00:00Z"

import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/report/v1/scheduledchecklist/group/1',
    headers={
      'Authorization': 'Bearer ' + credential_token,
      'Accept': 'application/json'
    },
    params={
      'ReportDate': '2022-09-01T00:00:00Z',
    }
    timeout=5
)

print(r.json())

Sample Get Scheduled Checklist Response

HTTP/1.1 200 OK
date: Mon, 24 Oct 2022 17:09:42 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding

{
  "groupId": 0,
  "reportDate": "2023-02-07T16:38:38.824Z",
  "summary": {
    "completionPercentage": 0.4881889763779528,
    "incompleteOrMissedTasks": 0,
    "availableTasks": 127,
    "missedFollowUpTasks": 0,
    "completedTasks": 62,
    "correctiveActions": 2
  },
  "details": [
    {
      "checklistTemplateId": 147,
      "checklistName": "AM Equipment Review",
      "timeZone": "America/New_York",
      "startDate": "2023-02-09T15:00:00+00:00",
      "endDate": "2023-02-09T17:59:59.999+00:00",
      "gracePeriodEndDate": "2023-02-09T17:59:59.999+00:00",
      "taskSelectionType": 1,
      "dynamicallyRequiredItemCount": 0,
      "checklistAnswers": [
        {
          "taskId": "task-2496",
          "taskName": "Cooking - Walk In Temperature",
          "taskType": 2,
          "incidentId": null,
          "low": 36.0,
          "high": 38.0,
          "unit": "fahrenheit",
          "priority": 8,
          "status": "Complete",
          "answerDate": "2023-02-09T15:25:22.048",
          "taskClass": "Task",
          "result": "34",
          "manager": "10183747",
          "comments": null,
          "correctiveActions": [
            "Corrected Immediately"
          ],
          "followUps": []
        }
      ]
    }
  ]
}

Get the Scheduled Checklist report for the given group.

GET /report/v1/scheduledchecklist/group/{groupId}

Parameters

name	location	type	required	description
groupID	path	integer (64 bit)	yes	ID of the group to retrieve. Any group type can be used, but usage is typically limited to `Location` and `Department` groups.
reportDate	query string	date	no	Pull report for a given date. Default is the current date. Value cannot be in the future.

Output Fields

name	type	description
groupID	integer (64 bit)	Unique group identifier.
reportDate	date	The date of the report.
summary	object	Single object of `Summary Data`.
details	array	Array of `Details Data`.

The Summary Data structure is as follows:

name	type	description
completionPercentage	float (64 bit)	Returns `completedTasks` divided by `availableTasks` as a number between 0 and 1. Will be `null` when `availableTasks` is zero.
availableTasks	integer (32 bit)	The number of available tasks.
missedFollowUpTasks	integer (32 bit)	The number of missed follow-up tasks.
completedTasks	integer (32 bit)	The number of completed tasks.
correctiveActions	integer (32 bit)	The number of corrective actions.
incompleteOrMissedTasks	integer (32 bit)	The number of incomplete or missed tasks.

The Details Data structure is as follows:

name	type	description
checklistName	string	The name of the checklist.
timeZone	time zone	The time zone assigned to the group as a human readable string.
startDate	date	The start date of the checklist.
endDate	date	The end date of the checklist.
gracePeriodEndDate	date	The end date of the grace period. If there is no grace period, it will be the same as `endDate`.
taskSelectionType	TaskSelectionType	Describes the type of task selection.
dynamicallyRequiredItemCount	integer (32 bit)	The number of required items for checklists with a "Dynamic" `taskSelectionType`. Will be zero otherwise.
checklistAnswers	array	Array of `Checklist Answers Data`.

The Checklist Answers Data structure is as follows:

name	type	description
taskId	string	The ID of the task.
taskName	string	The name of the task.
taskType	TaskType	Describes the type of task.
incidentId	integer (64 bit)	The ID of the incident, if triggered by an incident otherwise will be `null`.
low	float (64 bit)	The lower range limit of acceptable values, if relevant.
high	float (64 bit)	The upper range limit of acceptable values, if relevant.
unit	string	The unit type for `low` and `high` values, if relevant.
priority	integer (32 bit)	A number indicating priority.
status	AnswerStatus	The status of the checklist answer.
answerDate	date	The date the checklist item was answered.
taskClass	TaskClass	The class of the task.
result	string	The result of the checklist item.
manager	string	The login username of the manager, if applicable.
comments	string	Any related comments.
correctiveActions	string array	A list of corrective actions, if any.
followUps	array	Array of `Checklist Answers Data` containing follow-up actions, if any.

Responses

Code	Description
200	Success
400	Bad Request
401	Unauthorized

SCIM API v2

SmartSense Identity Management with SCIM v2

To ease managing of SmartSense users, SmartSense provides a set of endpoints that conform to the SCIM version 2 standard.

Results Paging

Sample Paging Response Fields

{
  "totalResults": 1555,
  "startIndex": 1,
  "itemsPerPage": 100,
}

Per SCIM RFC 7644 any endpoint that returns a list of data is subject to paging. Paging information is included in all paged responses as follows.

name	type	description
totalResults	integer (32 bit)	The total number of results matching the client query.
startIndex	integer (32 bit)	The 1-based index of the first result in the current page.
itemsPerPage	integer (32 bit)	The number of results returned in the current page.

SCIM Specific Types

SCIM objects and their attributes are defined by SCIM RFC 7643. Listed here is a description of the SCIM types used in SmartSense's SCIM implementation and how they are used.

name	type	mutability	description
resourceType	string	ReadOnly	The name of the containing resource's type.
location	string	ReadOnly	A URL that can be used to GET the object.

SmartSenseEnterpriseUser

SmartSenseEnterpriseUser is an extension of the basic SCIM Enterprise User schema. SmartSenseEnterpriseUser consists of two attributes.

name	type	mutability	description
managedExternally	boolean	ReadWrite	A boolean marking how the user can be managed. If set to true, the User is not editable through the SmartSense application and can only be managed through SCIM.
defaultContactRoleId	string	ReadWrite	A ContactRoleId that will be used when assigning the User to a Group.

Name

name	type	mutability	description
givenName	string	ReadWrite	The User's first name.
familyName	string	ReadWrite	The User's last name.

Email

name	type	mutability	description
value	string	ReadWrite	The User's email address.
type	string	ReadWrite	The type of the email address. Should always be "work".
primary	boolean	ReadWrite	A boolean indicating if this email is the primary email for the User. Should always be "true".

PhoneNumber

SmartSense Users can be configured with two phone numbers: one for voice calls and one for SMS. An SMS phone number should have its "type" set to "SMS". A voice call phone number should have its "type" set to "voice".

name	type	mutability	description
value	string	ReadWrite	The User's phone number. ¹
type	string	ReadWrite	The type of the phone number address. Should either be "SMS" or "voice".
primary	boolean	ReadWrite	A boolean indicating if this email is the primary phone number for the User. Should always be "true".

¹ Must be in international format. May begin with '+', followed by digits; other characters will be discarded. 10-digit-long values not starting with '+' will have the characters '+1' appended at the beginning, e.g. '2015551234' -> '+12015551234'. Other values not starting with '+' will have a single '+' character appended at the beginning, e.g. '59812345678' -> '+59812345678'

Errors

SCIM RFC 7644 defines error handling for SCIM implementations.

Access Role

The Access Role endpoint is used to get all SmartSense Access Roles. A User's assigned Access Role defines what access and permissions they have in the SmartSense application.

Get all Access Roles

Sample Get All AccessRole Request


curl --silent "https://api.smartsense.co/scim/v2/accessRole" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/accessRole',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get All AccessRole Response:

{
  "Owner": "Owns the account. This value cannot be set via the API.",
  "Super Administrator": "An unrestricted user with access to all features.",
  "Administrator": "A limited administrative user with access to all features for the Locations set for the user.",
  "ApiUser": "Can access this API, but cannot log into SmartSense. Contact us to get an access token.",
  "Responder": "Can respond to incidents and checklists, but cannot modify assets, alerts or checklists.",
  "Viewer": "Read only access to all features."
}

Get all supported roles

GET /scim/v2/accessRole

Parameters

None.

Output Fields

Property	Type	Description
key	`string`	The Role's Name.
Value	`string`	A description of the Role.

Contact Role

The Contact Role endpoints are used to create and update ContactRoles from the SmartSense system. Contact Roles define the relationship the User has with a Group. When a User is assigned to a Group, they must also be assigned a Contact Role. These ContactRoles are used to determine who should be notified when an Asset enters an alarm state.

A single Contact Role can be assigned to a User for all the Groups they are assigned to by setting the DefaultContactRoleId field in the SmartSenseEnterpriseUser object.

ContactRole Object Model

name	type	mutability	description
id	string	ReadOnly	A globally unique identifier of the ContactRole.
name	string	Immutable	The name of the ContactRole that is displayed in the SmartSense application.

Get One Contact Role

Sample Get ContactRole Request


curl --silent "https://api.smartsense.co/scim/v2/contactRole/TLLVUX43HR-829" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/contactRole/TLLVUX43HR-829',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print (r.json())

Sample Get ContactRole Response:

{
  "id": "TLLVUX43HR-829",
  "name": "Primary Store Tech"
}

Get a single ContactRole identified by the given ContactRoleId.

GET /scim/v2/contactRole/{contactRoleId}

Parameters

name	location	type	required	description
contactRoleId	path	string	yes	Unique identifier of the requested ContactRole.

Output Fields

name	type	description
	ContactRole	A ContactRole object for the requested Contact Role.

Get All Contact Roles

Sample Get All ContactRole Request


curl --silent "https://api.smartsense.co/scim/v2/contactRole?startIndex=1&count=50&filter=id%20eq%20829" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/contactRole?startIndex=1&count=50&filter=id%20eq%20829',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get All ContactRole Response:

{
    "totalResults": 2,
    "resources": [
        {
            "id": "TLLVUX43HR-1001",
            "name": "Grocery Administrator"
        }
        {
            "id": "TLLVUX43HR-829",
            "name": "Primary Store Tech"
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 50
}

Gets all the ContactRoles within the Account, one page at a time.

GET scim/v2/contactRole

Parameters

name	location	type	required	description
startIndex	query string	integer (32 bit)	no	1-based index of where to start the page. Defaults to 1.
count	query string	integer (32 bit)	no	The maximum number of objects to return.
filter	query string	string	no	A SCIM filter expression to filter the results with.

The accepted filter fields are id and name.

name	type	description
resources	array	A list of ContactRoles objects.

Create a Contact Role

Sample Create ContactRole Request


curl --silent "https://api.smartsense.co/scim/v2/contactRole" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request POST \
  --data '{
    "name": "ContactRoleName"
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = { "name": "ContactRoleName" }

r = requests.post('https://api.smartsense.co/scim/v2/contactRole',
                   headers={
                     'Accept': 'application/json',
                     'Authorization': 'Bearer ' + credential_token,
                   },
                   json=payload,
                   timeout=5
                 )

print(r.json())

Sample Create ContactRole Response:


HTTP/1.1 201 Created
Location: https://api.smartsense.co/scim/v2/contactRole/TLLVUX43HR-241

{
  "contactRoleId": "TLLVUX43HR-241"
}

Create a new ContactRole.

POST /scim/v2/contactRole

Parameters

name	location	type	required	description
	body	ContactRole	yes	The ContactRole to create.

Output Fields

name	type	description
	ContactRole	A ContactRole object for the newly created ContactRole.

Replace a Contact Role

Sample Update ContactRole Request


curl --silent "https://api.smartsense.co/scim/v2/contactRole/TLLVUX43HR-241" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request PUT \
  --data '{
    "name": "UpdatedContactRoleName"
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = { "name": "UpdatedContactRoleName" }

r = requests.put('https://api.smartsense.co/scim/v2/contactRole/TLLVUX43HR-241',
                  headers={
                    'Accept': 'application/json',
                    'Authorization': 'Bearer ' + credential_token,
                  },
                  json=payload,
                  timeout=5
                )

print(r.json())

Sample Create ContactRole Response:

{
  "id": "TLLVUX43HR-241",
  "name": "UpdatedContactRoleName"
}

Update a ContactRole by entirely replacing the existing ContactRole.

PUT /scim/v2/contactRole/{contactRoleId}

Parameters

name	location	type	required	description
userId	path	string	yes	Unique identifier of the ContactRole to replace.
	body	ContactRole	yes	The ContactRole to assign to the given ContactRoleId.

Output Fields

name	type	description
	ContactRole	A ContactRole object for the modified ContactRole.

Group Type

Query SmartSense Group Types. A Group's GroupType defines the Group's place in the group hierarchy.

There are four GroupTypes defined in the SmartSense system:

Account - The root of the hierarchy. There can only be one account level group per account.
Organization - Organization level groups are used as abstractions to logically divide the hierarchy. Organizations typically represent regions, divisions, states, or similar. Organizations can contain child organization groups under them. Organizations cannot contain Assets.
Location - Location level groups are used to define a physical location and hold Assets.
Department - Department level groups are used to define subsections of a Location. Department level groups must have a Location as their parent, and can contain Assets. Departments cannot have any child groups.

Get All Group Types

Sample Get All GroupType Request


curl --silent "https://api.smartsense.co/scim/v2/GroupType" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/GroupType',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get All GroupType Response:

{
  "Account": "The Root Group. There is only one root 'Account' which cannot be deleted by the user (nor can a group of this type be created).",
  "Organization": "Any level above the location level of a hierarchy (Multiple organization groups allowed within a single account. Assets and checklists are not able to be assigned to this type, e.g. Region, Area, District, etc.)",
  "Location": "This is typically a site that has an address associated with it and can contain assets and can have checklists performed.",
  "Department": "This is typically an area within a location that can contain assets and can have checklists performed."
}

Get all the available GroupTypes

GET /scim/v2/groupType

Parameters

None.

Output Fields

name	Type	Description
key	string	The GroupType's name.
value	string	A description of the GroupType.

Group Type Attribute

Create and Retrieve the Group Type Attributes configured for your Account. Groups in SmartSense can have Attributes defined for them. Different GroupTypes will have different required and non-required attributes depending on their assigned GroupTemplate. These Attributes are used for organization in the SmartSense application.

GroupTypeAttribute Object Model

name	type	mutability	description
attributeId	string	ReadOnly	A unique identifier for the attribute.
attributeName	string	ReadOnly	The name of the Attribute that is displayed in the SmartSense application.
attributeType	string	ReadOnly	The name of the data type for the Attribute.
isRequired	boolean	ReadOnly	A boolean indicating whether Groups of this type must provide a value for this Attribute.
groupType	string	ReadOnly	The GroupType the Attribute belongs to.

Get All Group Type Attributes

Sample Get All GroupTypeAttributes Request


curl --silent "https://api.smartsense.co/scim/v2/groupTypeAttribute" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/groupTypeAttribute',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get All GroupTypeAttributes Response:

[
  {
    "groupType": "Location",
    "attributeId": "DQRXATU9MD-295",
    "attributeName": "Mailing Address",
    "isRequired": false,
    "attributeType": "String"
  },
  {
    "groupType": "Organization",
    "attributeId": "DQRXATU9MD-599",
    "attributeName": "Email",
    "isRequired": true,
    "attributeType": "String"
  }
]

Get all the Attributes for all the GroupTypes in the system.

GET /scim/v2/groupTypeAttribute

Parameters

None.

Output Fields

name	type	description
	array	A list of GroupTypeAttributes for the account.

Get Group Type Attributes for a Single GroupType

Sample Get By GroupType GroupTypeAttributes Request


curl --silent "https://api.smartsense.co/scim/v2/groupTypeAttribute/Location" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/groupTypeAttribute/Location',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get By GroupType GroupTypeAttributes Response:

[
  {
    "groupType": "Location",
    "attributeId": "DQRXATU9MD-295",
    "attributeName": "Mailing Address",
    "isRequired": false,
    "attributeType": "String"
  },
  {
    "groupType": "Location",
    "attributeId": "DQRXATU9MD-1470",
    "attributeName": "Floors",
    "isRequired": true,
    "attributeType": "String"
  }
]

Get all the Attributes in the system for a single GroupType.

GET /scim/v2/groupTypeAttribute/{groupType}

Parameters

name	location	type	required	description
groupType	path	string	yes	The name of the GroupType to fetch attributes for.

OutputFields

name	type	description
	array	A list of GroupTypeAttributes for the given GroupType.

Create a Group Type Attribute

Sample Create GroupTypeAttribute Request


curl --silent "https://api.smartsense.co/scim/v2/groupTypeAttribute" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request POST \
  --data '{
    "groupType":"Location",
    "name":"TestAttribute",
    "isRequired":true,
    "attributeType":"String"
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = {
    "groupType": "Location",
    "name": "TestAttribute",
    "isRequired": True,
    "attributeType": "String",
}

r = requests.post('https://api.smartsense.co/scim/v2/groupTypeAttribute',
                   headers={
                     'Accept': 'application/json',
                     'Authorization': 'Bearer ' + credential_token,
                   },
                   json=payload,
                   timeout=5
                 )

print(r.text)

Sample Create GroupTypeAttribute Response:


HTTP/1.1 200 OK

DQRXATU9MD-1516

Create a new Attribute for a GroupType.

POST /scim/v2/groupTypeAttribute

Parameters

name	location	type	required	description
	body	GroupTypeAttribute	yes	The GroupTypeAttribute to Create.

Output Fields

name	type	description
	GroupTypeAttribute	A GroupTypeAttribute object for the newly created Attribute.

Groups

The Groups endpoints are used to create, update, and delete Groups from the SmartSense system, as well as manage the Users associated with them. Groups in SmartSense are organized into a hierarchical tree by their GroupType. Groups are used to organize Assets, and Users are assigned to Groups with a ContactRole. The SCIM Group schema is defined by RFC 7643 Section 4.2.

Group Object Model

SmartSense uses all the attributes of the SCIM Group model, and extends it.

name	type	mutability	description
id	string	ReadOnly	A globally unique identifier for the group.
externalId	string	ReadWrite	An identifier provided by the client. This attribute is not used by the SmartSense application and is for external tracking only.
parentId	string	Immutable	The Id of the Group's Parent Group.
displayName	string	ReadWrite	A name for the Group as displayed in the SmartSense application.
type	GroupType	Immutable	The type of the Group.
attributes	array	ReadWrite	A list of attributes associated with the Group.
members	array	ReadWrite	A list of Users that belong to the Group. See Members
meta	Meta	ReadOnly	The meta info for the Group.

Members Object Model

name	type	mutability	description
value	string	Immutable	The Id of the Member. It must be a valid UserId.
contactRoleId	string	Immutable	The ContactRoleId of for the Member of the Group.
type	string	Immutable	The type of the member object.
$ref	string	Immutable	A URL reference that can be used to GET the member.

Get One Group

Sample Get Group Request


curl --silent "https://api.smartsense.co/scim/v2/Groups/RSDS64O4Q0-34397" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/Groups/RSDS64O4Q0-34397',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  },
                  timeout=5
                )

print(r.json())

Sample Get Group Response:

{
  "members": [
    {
      "contactRoleId": "TLLVUX43HR-6",
      "value": "XH02IN10JG-3896",
      "type": "User Membership",
      "$ref": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-3896"
    },
    {
      "contactRoleId": "TLLVUX43HR-6",
      "value": "XH02IN10JG-6943",
      "type": "User Membership",
      "$ref": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-6943"
    }
  ],
  "displayName": "Account",
  "type": "Account",
  "attributes": [],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:SmartSense4:1.0:Group"
  ],
  "id": "RSDS64O4Q0-34397",
  "externalID": "3",
  "meta": {
    "resourceType": "Group",
    "location": "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-34397"
  }
}

Get a single Group identified by the given GroupId.

GET /scim/v2/groups/{groupId}

Parameters

name	location	type	required	description
groupId	path	string	yes	Unique identifier of the requested Group.

Output Fields

name	type	description
	SCIM Group	A SCIM Group representation of the requested Group.

Get All Groups

Sample Get All Groups Request


curl --silent "https://api.smartsense.co/scim/v2/groups" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/groups',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  },
                  timeout=5
                )

print (r.json())

Sample Get All Groups Response

{
  "totalResults": 2,
  "resources": [
    {
      "members": [
        {
          "contactRoleId": "TLLVUX43HR-6",
          "value": "XH02IN10JG-3896",
          "type": "User Membership",
          "$ref": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-3896"
        },
        {
          "contactRoleId": "TLLVUX43HR-6",
          "value": "XH02IN10JG-6943",
          "type": "User Membership",
          "$ref": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-6943"
        }
      ],
      "displayName": "Account",
      "type": "Account",
      "attributes": [],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:SmartSense4:1.0:Group"
      ],
      "id": "RSDS64O4Q0-34397",
      "externalID": "3",
      "meta": {
        "resourceType": "Group",
        "location": "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-34397"
      }
    },
    {
      "members": [],
      "displayName": "Deli ",
      "parentID": "RSDS64O4Q0-525",
      "type": "Department",
      "attributes": [
        {
          "value": "15",
          "type": "Personal assigned",
          "$ref": "https://api.smartsense.co/scim/v2/groupTypeAttribute/department"
        }
      ],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:SmartSense4:1.0:Group"
      ],
      "id": "RSDS64O4Q0-526",
      "meta": {
        "resourceType": "Group",
        "location": "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-526"
      },
      "externalID": "3"
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 100
}

Gets all the Groups within the Account, one page at a time.

GET /scim/v2/groups

Parameters

name	location	type	required	description
startIndex	query string	integer (32 bit)	no	1-based index of where to start the page. Defaults to 1.
count	query string	integer (32 bit)	no	The maximum number of objects to return.
filter	query string	string	no	A SCIM filter expression to filter the results with.

The accepted filter fields are id, externalId, displayname, and type.

Output Fields

name	type	description
resources	array	A list of SCIM Groups objects.

Create a Group

Sample Create Group Request


curl --silent "https://api.smartsense.co/scim/v2/groups" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request POST \
  --data '{
    "displayName":"GroupName",
    "type":"Department",
    "parentID":"RSDS64O4Q0-67162",
    "externalID":"abcd123",
    "attributes": [
      {
        "type": "Address",
        "value": "1234 Main St. Boston, MA 00000"
      }
    ],
    "members": [
      {
        "contactRoleId": "TLLVUX43HR-6",
        "value": "XH02IN10JG-6943"
      }
    ]
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = {
    "displayName": "GroupName",
    "type": "Department",
    "parentID": "RSDS64O4Q0-67162",
    "externalID": "abcd123",
    "attributes": [
        {
            "type": "Address",
            "value": "1234 Main St. Boston, MA 00000",
        },
    ],
    "members": [
        {
            "contactRoleId": "TLLVUX43HR-6",
            "value": "XH02IN10JG-6943",
        },
    ],
}

r = requests.post('https://api.smartsense.co/scim/v2/groups',
                   headers={
                     'Accept': 'application/json',
                     'Authorization': 'Bearer ' + credential_token,
                   },
                   json=payload,
                   timeout=5
                 )

print(r.text)

Sample Create Group Response:


HTTP/1.1 201 Created
Location: https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161

{
  "members": [
    {
      "contactRoleId": "TLLVUX43HR-6",
      "value": "XH02IN10JG-6943",
      "type": "User Membership",
      "$ref": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-6943"
    }
  ],
  "displayName": "GroupName",
  "parentID": "RSDS64O4Q0-67162",
  "type": "Department",
  "attributes": [
    {
      "type": "Address",
      "value": "1234 Main St. Boston, MA 00000",
      "$ref": "https://api.smartsense.co/scim/v2/groupTypeAttribute/Department"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:SmartSense4:1.0:Group"
  ],
  "id": "RSDS64O4Q0-1161",
  "externalID": "abcd123",
  "meta": {
    "resourceType": "Group",
    "location": "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161"
  }
}

Create a new Group.

POST /scim/v2/groups

Parameters

name	location	type	required	description
	body	SCIM Group	yes	The Group to create.

Output Fields

name	type	description
	SCIM Group	A SCIM Group representation of the newly created Group.

Replace a Group

Sample PUT Group Request


curl --silent "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request PUT \
  --data '{
    "displayName":"New Group Name",
    "externalID":"abcd123",
    "attributes": [
      {
        "type": "Address",
        "value": "1234 Main St. Boston, MA 00000"
      }
    ],
    "members": [
      {
        "contactRoleId": "TLLVUX43HR-6",
        "value": "XH02IN10JG-6943"
      }
    ]
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = {
    "displayName":"New Group Name",
    "externalID":"abcd123",
    "attributes": [
        {
            "type": "Address",
            "value": "1234 Main St. Boston, MA 00000",
        },
    ],
    "members": [
        {
            "contactRoleId": "TLLVUX43HR-6",
            "value": "XH02IN10JG-6943",
        },
    ],
}

r = requests.put('https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161',
                  headers={
                    'Accept': 'application/json',
                    'Authorization': 'Bearer ' + credential_token,
                  },
                  json=payload,
                  timeout=5
                )

print(r.json())

Sample PUT Group Response:

{
  "members": [
    {
      "contactRoleId": "TLLVUX43HR-6",
      "value": "XH02IN10JG-6943",
      "type": "User Membership",
      "$ref": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-6943"
    }
  ],
  "displayName": "New Group Name",
  "parentID": "RSDS64O4Q0-67162",
  "type": "Department",
  "attributes": [
    {
      "type": "Address",
      "value": "1234 Main St. Boston, MA 00000",
      "$ref": "https://api.smartsense.co/scim/v2/groupTypeAttribute/Department"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:SmartSense4:1.0:Group"
  ],
  "id": "RSDS64O4Q0-1161",
  "externalID": "abcd123",
  "meta": {
    "resourceType": "Group",
    "location": "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161"
  }
}

Update a Group by entirely replacing the existing Group.

PUT /scim/v2/groups/{groupId}

Parameters

name	location	type	required	description
groupId	path	string	yes	Unique identifier of the Group to replace.
	body	SCIM Group	yes	The Group to assign to the given GroupId.

Output Fields

name	type	description
	SCIM Group	A SCIM Group representation of the modified Group.

Update a Group

Sample PATCH Group Request


curl --silent "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request PATCH \
  --data '{
    "operations": [
      {
        "op": "replace",
        "path": "displayName",
        "value": "New Group Name"
      }
    ]
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = {
    "operations": [
        {
            "op": "replace",
            "path": "displayName",
            "value": "New Group Name",
        },
    ],
}

r = requests.patch('https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161',
                    headers={
                      'Accept': 'application/json',
                      'Authorization': 'Bearer ' + credential_token,
                    },
                    json=payload,
                    timeout=5
                )

print(r.text)

Sample PATCH Group Response:


HTTP/1.1 204 No Content

No Content

Modify an existing Group in place.

PATCH /scim/v2/groups/{groupId}

Parameters

name	location	type	required	description
groupId	path	string	yes	Unique identifier of the Group to modify.
operations	body	array	yes	A list of SCIM PATCH operations.

Output Fields

HTTP 204 No Content

Remove a Group

Sample Delete Group Request


curl --silent "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request DELETE


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.delete('https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-1161',
                     headers={
                       'Accept': 'application/json',
                       'Authorization': 'Bearer ' + credential_token,
                     },
                     timeout=5
                   )

print (r.text)

Sample Delete Group Response


HTTP/1.1 204 No Content

No Content

Delete a Group from the System. This cannot be undone.

DELETE /scim/v2/groups/{groupId}

Parameters

name	location	type	required	description
groupId	path	string	yes	Unique identifier of the Group to delete.

Output Fields

*HTTP 204 No Content

Resource Type

Get the SCIM Resource Types for SmartSense's defined resources. SCIM Resource Types are defined and required by RFC 7643 Section 6.

ResourceType Object Model

name	type	mutability	description
id	string	ReadOnly	An ID for the ResourceType.
name	string	ReadOnly	The name of the Resource.
description	string	ReadOnly	A description for the Resource.
endpoint	string	ReadOnly	The primary endpoint to retrieve resources of this ResourceType.
schema	string	ReadOnly	The ResourceTypes base schema.
schemaExtensions	SchemaExtension	ReadOnly	A list of schemas that extend the base schema for the ResourceType.
meta	Meta	ReadOnly	The meta info for the ResourceType.

SchemaExtension Object Model

name	type	mutability	description
schema	string	ReadOnly	The schema extension that is being applied.
required	boolean	ReadOnly	Whether applying the extension is required when interacting with the system.

Get One Resource Type

Sample Get ResourceType Request


curl --silent "https://api.smartsense.co/scim/v2/resourceType/user" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/resourceType/user',
                 headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get ResourceType Response:

{
  "name": "User",
  "description": "User Account",
  "endpoint": "/Users",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [
    {
      "schema": "urn:ietf:params:scim:schemas:SmartSense4:1.0:User",
      "required": false
    }
  ],
  "id": "User",
  "meta": {
    "resourceType": "ResourceType",
    "location": "https://api.smartsense.co/scim/v2/resourceType/users"
  }
}

Get the Resource definition for the Resource identified by the given name.

GET /scim/v2/resourceType/{resourceName}

Parameters

name	location	type	required	description
resourceName	path	string	yes	The name of the Resource to fetch.

OutputFields

name	type	description
	ResourceType	The resource definition for the given Resource name.

Get All Resource Types

Sample Get All ResourceType Request


curl --silent "https://api.smartsense.co/scim/v2/resourceType" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/resourceType',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get All ResourceType Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "itemsPerPage": 5,
  "startIndex": 1,
  "resources": [
    {
      "name": "User",
      "description": "User Account",
      "endpoint": "/Users",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:SmartSense4:1.0:User",
          "required": false
        }
      ],
      "id": "User",
      "meta": {
        "resourceType": "ResourceType",
        "location": "https://api.smartsense.co/scim/v2/resourceType/users"
      }
    },
    {
      "name": "Group",
      "description": "Location",
      "endpoint": "/Groups",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "id": "Group",
      "meta": {
        "resourceType": "ResourceType",
        "location": "https://api.smartsense.co/scim/v2/resourceType/groups"
      }
    },
    {
      "name": "ContactRole",
      "description": "Contact Roles are Roles that can be applied to Locations/Groups for User Accounts",
      "endpoint": "/ContactRole",
      "schema": "urn:ietf:params:scim:schemas:SmartSense4:1.0:ContactRole",
      "id": "ContactRole",
      "meta": {
        "resourceType": "ResourceType",
        "location": "https://api.smartsense.co/scim/v2/resourceType/contactRole"
      }
    },
    {
      "name": "AccessRole",
      "description": "Lookup list of supported user Access Roles",
      "endpoint": "/AccessRole",
      "schema": "urn:ietf:params:scim:schemas:SmartSense4:1.0:AccessRole",
      "id": "AccessRole",
      "meta": {
        "resourceType": "ResourceType",
        "location": "https://api.smartsense.co/scim/v2/resourceType/accessRole"
      }
    },
    {
      "name": "ServiceProviderConfiguration",
      "description": "A schema for representing the service provider's configuration",
      "endpoint": "/ServiceProviderConfiguration",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig",
      "id": "ServiceProviderConfiguration",
      "meta": {
        "resourceType": "ResourceType",
        "location": "https://api.smartsense.co/scim/v2/resourceType/serviceProviderConfiguration"
      }
    }
  ]
}

Get all the ResourceTypes in the system.

GET /scim/v2/resourceType

Parameters

None.

Output Fields

name	type	description
	array	A list of ResourceTypes in the system.

Schema

Get the documented SmartSense SCIM schemas. SCIM schemas are defined by RFC 7643 Section 7.

Get One Schema

Sample Get Schema Request


curl --silent "https://api.smartsense.co/scim/v2/Schema/urn%3Aietf%3Aparams%3Ascim%3Aschemas%3ASmartSense4%3A1.0%3AUser" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/Schema/urn%3Aietf%3Aparams%3Ascim%3Aschemas%3ASmartSense4%3A1.0%3AUser',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get Schema Response:

{
  "id": "urn:ietf:params:scim:schemas:SmartSense4:1.0:User",
  "name": "User",
  "description": "SmartSense4 User Account",
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
  "meta": {
    "location": "scim/v2/Schemas/urn:ietf:params:scim:schemas:SmartSense4:1.0:User",
    "resourceType": "Schema"
  },
  "attributes": [
    {
      "name": "ManagedExternally",
      "type": "boolean",
      "description": "Enterprise Users flagged with ManagedExternally as true are not editable from within SmartSense.",
      "required": false,
      "caseExact": false,
      "mutability": "readWrite",
      "returned": "default"
    }
  ]
}

Get a single SCIM Schema definition by the given Schema ID.

GET /scim/v2/schema/{schemaId}

name	location	type	required	description
schemaId	path	string	yes	A unique URI for the Schema.

Output Fields

name	type	description
	Schema	A Schema definition as defined by RFC 7643 Section 7.

Get All the Schemas

Sample Get All Schema Request


curl --silent "https://api.smartsense.co/scim/v2/schema" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/schema',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get All Schema Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "itemsPerPage": 2,
  "startIndex": 1,
  "resources": [
    {
      "id": "urn:ietf:params:scim:schemas:SmartSense4:1.0:ContactRole",
      "name": "ContactRole",
      "description": "SmartSense 4 Contact Role",
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
      "meta": {
        "location": "scim/v2/Schemas/urn:ietf:params:scim:schemas:SmartSense4:1.0:ContactRole",
        "resourceType": "Schema"
      },
      "attributes": [
        {
          "name": "Id",
          "type": "int",
          "description": "ID of contact role.",
          "required": true,
          "caseExact": true,
          "mutability": "readOnly",
          "returned": "default"
        },
        {
          "name": "Name",
          "type": "string",
          "description": "Display name of contact role.",
          "required": true,
          "caseExact": true,
          "mutability": "readOnly",
          "returned": "default"
        }
      ]
    },
    {
      "id": "urn:ietf:params:scim:schemas:SmartSense4:1.0:AccessRole",
      "name": "AccessRole",
      "description": "SmartSense 4 Access Roles",
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
      "meta": {
        "location": "scim/v2/Schemas/urn:ietf:params:scim:schemas:SmartSense4:1.0:AccessRole",
        "resourceType": "Schema"
      },
      "attributes": [
        {
          "name": "Access Role Name",
          "type": "string",
          "description": "Display name of Access Role",
          "required": true,
          "caseExact": true,
          "mutability": "readOnly",
          "returned": "default"
        },
        {
          "name": "Description",
          "type": "int",
          "description": "Description of the Access Role",
          "required": true,
          "caseExact": true,
          "mutability": "readOnly",
          "returned": "default"
        }
      ]
    }
  ]
}

Get all the SCIM Schemas defined by the system.

GET /scim/v2/schema

Parameters

None.

Output Fields

name	type	description
resources	array	A list of Schema objects.

Service Provider Configuration

Gets the SmartSense SCIM Service Provider Configuration. The SCIM service provider configuration is defined and required by RFC 7643 Section 5.

Get The Configuration

Sample Get All ServiceProviderConfiguration Request


curl --silent "https://api.smartsense.co/scim/v2/serviceProviderConfiguration" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/serviceProviderConfiguration',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  }
                )

print(r.json())

Sample Get All ServiceProviderConfiguration Response:

{
  "documentationURI": "https://developer.smartsense.co",
  "patch": { "supported": false },
  "bulk": { "supported": false, "maxOperations": 0, "maxPayloadSize": 0 },
  "filter": { "supported": false, "maxResults": 0 },
  "changePassword": { "supported": false },
  "sort": { "supported": false },
  "eTag": { "supported": false },
  "authenticationSchemes": [
    {
      "type": "oauthbearertoken",
      "name": "OAuth Bearer Token",
      "description": "Authentication Scheme using the OAuth Bearer Token Standard",
      "specURI": "http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-01",
      "primary": true,
      "documentationURI": "https://developer.smartsense.co/#authentication"
    }
  ],
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "meta": {
    "resourceType": "ServiceProviderConfiguration",
    "created": "2020-03-01T00:00:00",
    "lastModified": "2020-03-01T00:00:00",
    "location": "/scim/v2/ServiceProviderConfiguration",
    "version": "1"
  }
}

Get our Service Provider Configuration as defined by the SCIM specification.

GET /scim/v2/servicesProviderConfiguration

Parameters

None.

Output Fields

name	type	description
	ServiceProviderConfig	A SCIM ServiceProviderConfig for this SCIM Service.

Users

The Users endpoints are used to create, update, and delete Users from the SmartSense system. SmartSense Users created through the SCIM API can only login to the SmartSense system through a SAML SSO integration. SmartSense only uses a subset of the available SCIM User attributes. The full SCIM User schema is defined by RFC 7643 Section 4.1

User Object Model

name	type	mutability	description
id	string	ReadOnly	A globally unique identifier of the User.
externalId	string	ReadWrite	An identifier provided by the client. This attribute is not used by the SmartSense application and is for external tracking only.
username	string	Immutable	A unique string identifier of the user.
active	boolean	ReadWrite	A boolean marking if the user is allowed to access the system.
userType	AccessRole	ReadWrite	A string identifying the User's permissions in the system.
name	Name	ReadWrite	A complex object containing the User's first and last names.
smartSenseEnterpriseUser	SmartSenseEnterpriseUser	ReadWrite	A complex attribute holding SmartSense's SCIM extension attributes.
emails	array	ReadWrite	A list of Emails. SmartSense only accepts and returns one email in this list.
phoneNumbers	array	ReadWrite	A list of PhoneNumbers. SmartSense accepts two types of phone numbers: SMS and voice.
groups	array	ReadOnly	A list of Groups the User belongs to.
meta	Meta	ReadOnly	The meta info for the User.

Get One User

Sample Get User Request


curl --silent "https://api.smartsense.co/scim/v2/users/XH02IN10JG-7422" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/users/XH02IN10JG-7422',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  },
                  timeout=5
                )

print(r.json())

Sample Get User Response:

{
  "smartSenseEnterpriseUser": {
    "managedExternally": false,
    "defaultContactRoleId": "XH02IN10JG-94"
  },
  "userName": "jsmith",
  "name": {
    "givenName": "John",
    "familyName": "Smith"
  },
  "userType": "Viewer",
  "active": true,
  "emails": [
    {
      "value": "john.smith@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+19525551011",
      "type": "voice",
      "primary": true
    },
    {
      "value": "+19525551011",
      "type": "sms",
      "primary": true
    }
  ],
  "groups": [
    {
      "contactRoleId": "XH02IN10JG-94",
      "value": "RSDS64O4Q0-35272",
      "type": "Group membership",
      "$ref": "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-35272"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:user",
    "urn:ietf:params:scim:schemas:SmartSense4:1.0:User"
  ],
  "id": "XH02IN10JG-7422",
  "externalID": "FBF6F63E-73A3-4912-A339-68681BE18A8A",
  "meta": {
    "resourceType": "User",
    "location": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-7422"
  }
}

Get a single User identified by the given UserId.

GET /scim/v2/users/{userId}

Parameters

name	location	type	required	description
userId	path	string	yes	Unique identifier of the requested User.

Output Fields

name	type	description
	SCIM User	A SCIM User representation of the requested user.

Get All Users

Sample Get All Users Request


curl --silent "https://api.smartsense.co/scim/v2/users" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.get('https://api.smartsense.co/scim/v2/users',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                  },
                  timeout=5
                )

print (r.json())

Sample Get All Users Response

{
  "totalResults": 2,
  "resources": [
    {
      "smartSenseEnterpriseUser": {
        "managedExternally": false,
        "defaultContactRoleId": "XH02IN10JG-123"
      },
      "userName": "janesmith",
      "name": {
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "userType": "Viewer",
      "active": true,
      "emails": [
        {
          "value": "jane.smith@example.com",
          "type": "work",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "+19525551020",
          "type": "voice",
          "primary": true
        },
        {
          "value": "+19525551020",
          "type": "sms",
          "primary": true
        }
      ],
      "groups": [],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:user",
        "urn:ietf:params:scim:schemas:SmartSense4:1.0:User"
      ],
      "id": "XH02IN10JG-72963",
      "externalID": "external",
      "meta": {
        "resourceType": "User",
        "location": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-72963"
      }
    },
    {
      "smartSenseEnterpriseUser": {
        "managedExternally": false,
        "defaultContactRoleId": "XH02IN10JG-914"
      },
      "userName": "",
      "name": {
        "givenName": "Nomen",
        "familyName": "Nescio"
      },
      "userType": "Viewer",
      "active": true,
      "emails": [
        {
          "value": "n.n@example.com",
          "type": "work",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "+19525551022",
          "type": "voice",
          "primary": true
        },
        {
          "value": "+19525551022",
          "type": "sms",
          "primary": true
        }
      ],
      "groups": [],
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:user",
        "urn:ietf:params:scim:schemas:SmartSense4:1.0:User"
      ],
      "id": "XH02IN10JG-72964",
      "externalID": "external",
      "meta": {
        "resourceType": "User",
        "location": "https://api.smartsense.co/scim/v2/users/XH02IN10JG-72964"
      }
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 100
}

Gets all the Users within the Account, one page at a time.

GET /scim/v2/users

Parameters

name	location	type	required	description
startIndex	query string	integer (32 bit)	no	1-based index of where to start the page. Defaults to 1.
count	query string	integer (32 bit)	no	The maximum number of objects to return.
filter	query string	string	no	A SCIM filter expression to filter the results with.

The accepted filter fields are id, externalId, username, name.familyName, and name.givenName.

Output Fields

name	type	description
resources	array	A list of SCIM Users objects.

Create a User

Sample Create User Request


curl --silent 'https://api.smartsense.co/scim/v2/users' \
  --header 'Authorization: Bearer TOKEN_FROM_SMARTSENSE' \
  --header 'Content-Type: application/json' \
  --request POST \
  --data '{
    "enterpriseUser": {
      "managedExternally": false,
      "defaultContactRoleId": "TLLVUX43HR-221"
    },
    "userName": "lskywalker",
    "userType": "Viewer",
    "name": {
      "givenName": "Luke",
      "familyName": "Skywalker"
    },
    "phoneNumbers": [
      {
        "value": "59899123456",
        "type": "sms",
        "primary": true
      },
      {
        "value": "+19525551066",
        "type": "voice",
        "primary": true
      }
    ],
    "emails": [
      {
        "value": "lskywalker@yahoo.com",
        "type": "Home",
        "primary": true
      }
    ],
    "groups": [
      {
        "contactRoleId": "TLLVUX43HR-96",
        "value": "RSDS64O4Q0-803",
        "type": "Group membership",
        "$ref": "https://api.smartsense.co/scim/v2/groups/RSDS64O4Q0-803"
      }
    ],
    "externalID": "123456789"
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = {
  "enterpriseUser": {
    "managedExternally": False,
    "defaultContactRoleId": "TLLVUX43HR-221"
  },
  "userName": "lskywalker",
  "userType": "Viewer",
  "name": {
    "givenName": "Luke",
    "familyName": "Skywalker"
  },
  "phoneNumbers": [
    {
      "value": "59899123456",
      "type": "sms",
      "primary": True
    },
    {
      "value": "+19525551066",
      "type": "voice",
      "primary": True
    }
  ],
  "emails": [
    {
      "value": "lskywalker@yahoo.com",
      "type": "Home",
      "primary": True
    }
  ],
  "groups": [],
  "externalID": "123456789"
}

r = requests.post('https://api.smartsense.co/scim/v2/users',
                   headers={
                     'Accept': 'application/json',
                     'Authorization': 'Bearer ' + credential_token,
                   },
                   json=payload,
                   timeout=5
                 )

print(r.text)

Sample Create User Response:


HTTP/1.1 201 Created
Location: https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162

{
  "smartSenseEnterpriseUser": {
    "managedExternally": false
  },
  "userName": "lskywalker",
  "name": {
    "givenName": "Luke",
    "familyName": "Skywalker"
  },
  "userType": "Viewer",
  "active": true,
  "emails": [
    {
      "value": "lskywalker@yahoo.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+59899123456",
      "type": "voice",
      "primary": true
    },
    {
      "value": "+19525551066",
      "type": "sms",
      "primary": true
    }
  ],
  "groups": [],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:user",
    "urn:ietf:params:scim:schemas:SmartSense4:1.0:User"
  ],
  "id": "XH02IN10JG-74162",
  "externalID": "123456789",
  "meta": {
    "resourceType": "User",
    "location": "http://ss4apiqa.devalertlist.com/scim/v2/users/XH02IN10JG-74162"
  }
}

Create a new User.

POST /scim/v2/users

Parameters

name	location	type	required	description
	body	SCIM User	yes	The user to create.

Output Fields

name	type	description
	SCIM User	A SCIM User representation of the newly created User.

Replace a User

Sample Replace User Request


curl --silent 'https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162' \
  --header 'Authorization: Bearer TOKEN_FROM_SMARTSENSE' \
  --header 'Content-Type: application/json' \
  --request PUT \
  --data '{
    "smartSenseEnterpriseUser": {
      "managedExternally": true
    },
    "userName": "dfahrenheit",
    "name": {
      "givenName": "Daniel",
      "familyName": "Fahrenheit"
    },
    "userType": "Viewer",
    "active": true,
    "emails": [
      {
        "value": "danial.g.fahrenheit@gmail.com",
        "type": "work",
        "primary": true
      }
    ],
    "phoneNumbers": [
      {
        "value": "1235551099",
        "type": "voice",
        "primary": true
      },
      {
        "value": "+11235551099",
        "type": "sms",
        "primary": true
      }
    ],
    "groups": [],
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:user",
      "urn:ietf:params:scim:schemas:SmartSense4:1.0:User"
    ],
    "id": "XH02IN10JG-74162",
    "externalID": "111111123",
    "meta": {
      "resourceType": "User",
      "location": "https://api.smartsense.co/scim/v2/Users/XH02IN10JG-74162"
    }
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = {
  "smartSenseEnterpriseUser": {
    "managedExternally": True
  },
  "userName": "dfahrenheit",
  "name": {
    "givenName": "Daniel",
    "familyName": "Fahrenheit"
  },
  "userType": "Viewer",
  "active": True,
  "emails": [
    {
      "value": "danial.g.fahrenheit@gmail.com",
      "type": "work",
      "primary": True
    }
  ],
  "phoneNumbers": [
    {
      "value": "1235551099",
      "type": "voice",
      "primary": True
    },
    {
      "value": "+11235551099",
      "type": "sms",
      "primary": True
    }
  ],
  "groups": [],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:user",
    "urn:ietf:params:scim:schemas:SmartSense4:1.0:User"
  ],
  "id": "XH02IN10JG-74162",
  "externalID": "111111123",
  "meta": {
    "resourceType": "User",
    "location": "https://api.smartsense.co/scim/v2/Users/XH02IN10JG-74162"
  }
}

r = requests.put('https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162',
                   headers={
                     'Accept': 'application/json',
                     'Authorization': 'Bearer ' + credential_token,
                   },
                   json=payload,
                   timeout=5
                 )

print(r.text)

Sample Replace User Response:


HTTP/1.1 200 OK
Location: https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162

{
  "smartSenseEnterpriseUser": {
    "managedExternally": true
  },
  "userName": "dfahrenheit",
  "name": {
    "givenName": "Deniel",
    "familyName": "Fahrenheit"
  },
  "userType": "Viewer",
  "active": true,
  "emails": [
    {
      "value": "danial.g.fahrenheit@gmail.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+11235551099",
      "type": "voice",
      "primary": true
    },
    {
      "value": "+11235551099",
      "type": "sms",
      "primary": true
    }
  ],
  "groups": [],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:user",
    "urn:ietf:params:scim:schemas:SmartSense4:1.0:User"
  ],
  "id": "XH02IN10JG-74162",
  "externalID": "111111123",
  "meta": {
    "resourceType": "User",
    "location": "https://api.smartsense.co/scim/v2/Users/XH02IN10JG-74162"
  }
}

Update a User by entirely replacing the existing User.

PUT /scim/v2/users/{userId}

Parameters

name	location	type	required	description
userId	path	string	yes	Unique identifier of the User to be replaced.
	body	SCIM User	yes	The User to assign to the given UserId.

Output Fields

name	type	description
	SCIM User	A SCIM User representation of the modified user.

Update a User

Sample PATCH User Request


curl --silent "https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request PATCH \
  --data '{
    "operations": [
      {
        "op": "replace",
        "path": "name.familyName",
        "value": "patched value"
      }
    ]
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = {
  "operations": [
    {
      "op": "replace",
      "path": "name.familyName",
      "value": "patched value"
    }
  ]
}

r = requests.patch('https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162',
                    headers={
                      'Accept': 'application/json',
                      'Authorization': 'Bearer ' + credential_token,
                    },
                    json=payload,
                    timeout=5
                )

print(r.text)

Sample PATCH User Response:


HTTP/1.1 204 No Content

No Content

Modify an existing User in place.

PATCH /scim/v2/users/{userId}

Parameters

name	location	type	required	description
userId	path	string	yes	Unique identifier of the User to be modified.
operations	body	array	yes	A list of SCIM PATCH operations.

Output Fields

HTTP 204 No Content

Remove a User

Sample Delete User Request


curl --silent "https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request DELETE


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"

r = requests.delete('https://api.smartsense.co/scim/v2/users/XH02IN10JG-74162',
                     headers={
                       'Accept': 'application/json',
                       'Authorization': 'Bearer ' + credential_token,
                     },
                     timeout=5
                   )

print (r.text)

Sample Delete User Response


HTTP/1.1 204 No Content

No Content

Delete a User from the System. This cannot be undone. For a reversible delete action see the "active" field of the SCIM User.

DELETE /scim/v2/users/{userId}

Parameters

name	location	type	required	description
userId	path	string	yes	Unique identifier of the User to delete.

Output Fields

HTTP 204 No Content

Deprecated APIs

Deprecated APIs listed below this header are not intended for use and are for historical purposes only. They should not be used for new integrations.

SmartSense reserves the right to discontinue support for these APIs at anytime. Contact us at support@smartsense.co for more information.

🛑 SCIM API v1

SmartSense User Management With SCIM

This API has been deprecated. Please use our SCIM API v2 for any new integrations.

To ease managing of SmartSense users, SmartSense provides a set of endpoints that conform to the SCIM standard.

The SCIM User Resource is mapped directly to a SmartSense login.

Anatomy of a User

SmartSense supports the following portion of the SCIM User schema:

Attribute	Sub Attribute	Type	Description
id	--	`int`	The ID of the SmartSense User
externalID	--	`string`	An optional field that can represent the user ID in the your system, if left blank a random unique identifier will be set.
userName	--	`string`	The name the user will use to log into SmartSense
name	--	`object`	The components of the user's name.
	givenName	`string`	The user's first (given) name
	familyName	`string`	The user's last (family) name
groups	--	`array[multiValueAttribute]`	The user's groups.
emails	--	`array[multiValueAttribute]`	List of this user's email addresses. Currently only the first or `primary` address is saved.
phoneNumbers	--	`array[phoneNumberType]`	List of this user's phone/mobile numbers. There are 2 types of phone numbers in SmartSense, `voice` and `sms`. Currently only the first or `primary` number is saved for each type.
urn:ietf:params:scim:schemas:SmartSense:1.0:User	--	`object`	The attributes set on from the SmartSenseUser enterprise user schema extension
roles	--	`array[multiValueAttribute]`	The roles that the user has. Default: Viewer

SmartSense Enterprise User

SmartSense provides the following schema extension for the Core User Schema:

Attribute	Required	Type	Default	Description
managedExternally	No	`boolean`	`false`	If "Managed Externally" is `true` the user will not support edits from inside SmartSense.

PhoneNumberType

Attribute	Type	Description
value	`string`	The phone number. Should begin with `+` followed by only digits.
type	`string`	There are 2 types of phone numbers in SmartSense, we currently only store one number of each type per user. For voice phone numbers, the type can be either `voice` or `work`. For text numbers the type can be either `sms` or `mobile`.
primary	`bool`	When set, we will save the first number listed for each type that is marked `primary`. If not set, we will save the first number listed for each type.
extension	`string`	For `voice` or `work` numbers, use this to specify a phone extension if needed. (Optional).
smsCarrierId	`int`	For `sms` or `mobile` numbers, use this to specify the SmsCarrierId. (Optional) See the `SmsCarrierId` api endpoint for a list of available carriers.

Roles

SCIM Users can be assigned a single access role when they are created. If roles are not passed in, the default Viewer access role is assigned. Please see the chart below for more information about access roles (also available at the AccessRole api endpoint):

Role Name	Description
Super Administrator	An unrestricted user with access to all features
Administrator	A limited administrative user with access to all features for the Groups set for the User. Not available for all accounts.
ApiUser	Can access this API, but cannot log into SmartSense. Contact us to get an access token
Owner	Owns the account. This value cannot be set via the API
Responder	Can respond to incidents and checklists, but cannot modify devices, alerts, or checklists
Viewer	Read only access to all features

Paging

For API calls that may return large amounts of data, the results are broken up into "pages". Each "page" contains a unique subset of the data.

The StartIndex parameter is an optional 1-based index of the first query result. Defaults to 1. The Count parameter is an optional non-negative number of items to retrieve. Defaults to 50 and has a maximum value of 50. The TotalResults response field returns the total number of results and indicates if there is additional data beyond the page returned.

AccessRoles

/scim/accessRole endpoint allows retrieving SmartSense Access Roles supported by the server.

Access Roles define the user's overall access to the account.

Get All

Sample Get All AccessRole Request


curl --silent "https://api.smartsense.co/scim/accessRole" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/accessRole',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All AccessRole Response:


{
  "Owner": "Owns the account. This value cannot be set via the API.",
  "Super Administrator": "An unrestricted user with access to all features.",
  "ApiUser": "Can access this API, but cannot log into SmartSense. Contact us to get an access token.",
  "Responder": "Can respond to incidents and checklists, but cannot modify assets, alerts or checklists.",
  "Viewer": "Read only access to all features."
}

🛑 GET `scim/accessRole`

This endpoint returns all access roles supported by the server.

Parameters

None.

Responses

Status Codes

Code	Description
200	Success

Contact Roles

The following endpoints allow API clients to perform CRUD operations on SmartSense Contact Roles.

Contact Roles, or Location Roles, define the relationship between a user and a location type group.

Get All

Sample Get All ContactRole Request


curl --silent "https://api.smartsense.co/scim/contactrole?StartIndex=1&Count=50" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/contactrole?StartIndex=1&Count=50',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All ContactRole Response:


{
    "totalResults": 2,
    "resources": [
        {
            "id": 1001,
            "name": "Grocery Administrator"
        }
        {
            "id": 829,
            "name": "Primary Store Tech"
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 50
}

🛑 GET `scim/contactrole`

This endpoint returns all contact roles in the account to which the API client has access.

Parameters

Name	Location	Type	Required	Description
startIndex	querystring	`int`	No	optional 1-based index of the first query result. Defaults to 1.
count	querystring	`int`	No	optional non-negative number of items to retrieve. Defaults to 50.

Responses

Response Body

Property	Type	Description
totalResults	`int`	Total number of items that matched the query criteria
itemsPerPage	`int`	Number of items returned per page
startIndex	`int`	The starting index of this query
schemas	`array[string]`	The schema(s) of the response
resources	`array[contactRole]`	Array of the contact roles requested

Response Headers

Code	Description
200	Success
404	Not Found

Get One

Sample Get ContactRole Request


curl --silent "https://api.smartsense.co/scim/contactrole/829" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/contactrole/829',
                 headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get ContactRole Response:

{
    "id": 829,
    "name": "Primary Store Tech"
}

🛑 GET `/scim/contactrole/{contactRoleID}`

This endpoint returns a single contact role.

GET Parameters

Name	Location	Type	Required	Description
contactRoleID	path	`int` `(64 bit)`	Yes	Contact role to retrieve

GET Responses

Response Body

Property	Type	Description
id	`int` `(64 bit)`	Id of the contact role
name	`string`	Name of the contact role

Response Header

Code	Description
200	Success
404	Not Found

Create ContactRole

Sample Create ### Create ContactRole Request


curl --silent "https://api.smartsense.co/scim/contactrole" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request POST \
  --data '{
    "name":"ContactRoleName"
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = { "name" : "ContactRoleName"
          }

r = requests.post('https://api.smartsense.co/scim/contactrole',
                 headers={
                   'Accept': 'application/json',
                   'Authorization': 'Bearer ' + credential_token
                 },
                 json = payload,
                 timeout=5
                 )

print (r.text)

Sample Create ContactRole Response:


HTTP/1.1 201 Created
Location: /scim/contactrole/1

No Content

🛑 POST `/scim/contactrole`

This endpoint creates a new ContactRole in SmartSense. Upon success, the path to the new ContactRole is passed in the Location header of the response.

Parameters

Name	Location	Type	Required	Description
name	body	`string` `(max 50)`	Yes	Name of the group to create.

Responses

Headers

Name	Location	Type	Description
Location	response header	URI	Path to the newly created ContactRole.

Status Codes

Code	Description
201	Success
400	Bad request -- required fields missing
403	Forbidden - User does not have access to perform the task
404	Not Found - The specified ContactRole does not exist

PUT `/scim/contactrole/{contactRoleId}`

This endpoint allows an existing ContactRole to be updated. When using this endpoint, any new values specified are updated, while any values omitted are removed. Send all fields, not just the ones you wish to change.

Parameters

Name	Location	Type	Required	Description
name	body	`string` `(max 50)`	Yes	New name of the group.

Responses

Status Codes

Code	Description
204	Success - No Content
400	Bad request - required fields missing
403	Forbidden - User does not have access to perform the task
404	Not Found - The contactrole with the specified ID does not exist

Group

Definition

Smart Sense Groups

There are four different group types in SmartSense, defined as

Account - Top group in the account hierarchy
Organization - Any level above the location level of a hierarchy (Multiple organization groups allowed within a single account. Assets and checklists are not able to be assigned to this type, e.g. Region, Area, District, etc.)
Location - This is typically a site that has an address associated with it and can contain assets and can have checklists performed
Department - This is typically an area within a location that can contain assets and can have checklists performed

There is only one root 'Account' group which cannot be deleted by the user (nor can a group of this type be created). Organization groups can be children of either the Account group or another Organization. Location groups can be children of either the Account group or an Organization group. Department groups can only be the child of a Location group. The group type cannot be changed after group is created.

The following endpoints allow API clients to perform CRUD operations on SCIM [groups]

The GroupMember type

The GroupMember represents membership of a user in a group. The following properties are supported:

Name	Type	Required	Description
value	`int` `(64 bit)`	Yes	ID of user and roles
operation	`string`	No	If `delete`, user will be removed from the roles specified for this groups. Otherwise, the user will be added. This property serves no practical purpose for POST or PUT requests, but is useful for PATCH requests.

The GroupMemberID type

The GroupMemberID type represents the user ID and roles they hold in a group.

Name	Type	Required	Description
userId	`int`	Yes	ID of user
contactRoleIDs	`array[int]`	Yes	Contact roles held by user. Note that at least one role is required.

Create Group

Sample Create Group Request


curl --silent "https://api.smartsense.co/scim/group" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request POST \
  --data '{
    "name":"GroupName",
    "type":"Location",
    "parentID":1234,
    "externalID":"abcd123"
    "attributes":{
      "Address":"1234 Main St. Boston, MA 00000"
    },
    "members": [{"value": {"userID": 382, "contactRoleIDs": [2, 3]} }]
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = { "name" : "GroupName",
            "type" : "Location",
            "parentID" : 1234,
            "externalID" : "abcd123",
            "attributes" : {"Address" : "1234 Main St. Boston, MA 00000"},
            "members" : [{"value": {"userID": 382, "contactRoleIDs": [2, 3]} }]
          }

r = requests.post('https://api.smartsense.co/scim/group',
                 headers={
                   'Accept': 'application/json', 
                   'Authorization': 'Bearer ' + credential_token
                 },
                 json = payload,
                 timeout=5
                 )

print (r.text)

Sample Create Group Response:


HTTP/1.1 201 Created
Location: /scim/group/1

No Content

🛑 POST `/scim/group`

This endpoint creates a new group in SmartSense. Upon success, the path to the new group is passed in the Location header of the response.

Parameters

Name	Location	Type	Required	Description
name	body	`string` `(max 255)`	Yes	Name of the group to create.
parentID	body	`int` `(64 bit)`	Yes	The newly created group will be a subgroup of this parent group. Creating a root group is not supported. Cannot be changed after group is created.
type	body	`string` `(max 50)`	Yes	Type of group. Permissible values are: Account, Organization, Location, and Department. There is only one root 'Account' group which cannot be deleted by the user (nor can a group of this type be created). Organization groups can be children of either the Account group or another Organization. Location groups can be children of either the Account group or an Organization group. Department groups can only be the child of a Location group. Cannot be changed after group is created.
attributes	body	`dictionary`	No	A dictionary of string key/value pairs. The set of valid key names is determined by the group type. Note that, depending on your account configuration, some attributes may be required.
externalID	body	`string` `(max 512)`	No	Optional client specified identifier for a group.
members	body	`array[GroupMember]`	No	Users which are part of this group

Responses

Headers

Name	Location	Type	Description
Location	response header	URI	Path to the newly created group.

Status Codes

Code	Description
201	Success
400	Bad request -- required fields missing, group type does not exist, group type does not conform to hierarchy specification, etc.
403	Forbidden - User does not have access to the specified parent group ID
404	Not Found - The specified group type does not exist or the specified parent group does not exist or the role or user ID of one of the members does not exist.

Get All

Sample Get All Groups Request


curl --silent "https://api.smartsense.co/scim/group" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/scim/group',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  },
                  timeout=5
                )
print (r.json())

Sample Get All Groups Response


HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Content-Length: 2841


{
    "totalResults": 169,
     "resources": [
    ... groups
    ],
    "startIndex": 1,
    "itemsPerPage": 50
}

🛑 GET `/scim/group`

This endpoint gets all of the groups in the account to which the API client has access. Groups are returned as a flat list. The response may be broken up into pages, requiring multiple requests to retrieve all of the groups in the account.

Parameters

Name	Location	Type	Required	Description
groupIDs	querystring	`int` `(64 bit)`	No	Optional query parameter to filter groups by ID. If specified, only groups whose ID matches the parameter value are returned. Multiple values, separated by commas, may be specified.
groupTypes	querystring	`string`	No	Optional query parameter to filter groups by type. If specified only groups whose type matches the parameter value are returned. Multiple values, separated by commas, may be specified.
groupExternalIDs	querystring	`string`	No	Optional query parameter to filter groups by externalID. If specified only groups whose external IDs matches the parameter value will be returned. Multiple values, separated by commas, may be specified.
startIndex	querystring	`int`	No	optional 1-based index of the first query result. Defaults to 1.
count	querystring	`int`	No	optional non-negative number of items to retrieve. Defaults to 50.

Responses

Status Code

Code	Description
200	Success
404	Not Found

Response Body

Property	Type	Description
id	`int` `(64 bit)`	Unique group identifier.
name	`string` `(max 255)`	Name of the group.
parentID	`int` `(64 bit)`	ID of this group's parent, if any, in the group hierarchy.
type	`string` `(max 50)`	This group's type. The group type determines what attributes are available for this group as well as what group types may be children.
attributes	`dictionary`	A dictionary of string key/value pairs. The set of valid key names is determined by the group type.
externalID	`string` (max 512)	Client specified identifier for a group.

Get One

Sample Get Group Request


curl --silent "https://api.smartsense.co/scim/group/1" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/scim/group/1',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  },
                  timeout=5
                )
print (r.json())

Sample Get Group Response:


HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Content-Length: 2841

🛑 GET `/scim/group/{groupID}`

This endpoint gets a single group.

Parameters

Name	Location	Type	Required	Description
groupID	path	`int` `(64 bit)`	yes	ID of group to retrieve.

Responses

Response Body

Name	Type	Description
groupID	`int` `(64 bit)`	Unique group identifier.
name	`string` `(max 255)`	Name of the group.
parentID	`int` `(64 bit)`	ID of this group's parent, if any, in the group hierarchy.
type	`string` `(max 50)`	This group's type. The group type determines what attributes are available for this group as well as what group types may be children.
attributes	`dictionary`	A dictionary of string key/value pairs. The set of valid key names is determined by the group type.
externalID	`string` (max 512)	Client specified identifier for a group. Unique per account.

Status Codes

Code	Description
200	Success
404	Not Found

Update Group (PUT)

Sample PUT Group Request


curl --silent "https://api.smartsense.co/scim/group/2" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request PUT \
  --data '{ "name" : "New Group Name", 
              "members": [{ "value": { "userID": 382, "contactRoleIDs": [2, 3] } }],
              "attributes" : {"Custom Time Zone" : "W. Central Africa Standard Time"}'


import json
import requests

parameters= { "name" : "New Group Name",
              "members": [{"value": {"userID": 382, "contactRoleIDs": [2, 3]} }],
              "attributes" : {"Custom Time Zone" : "W. Central Africa Standard Time"}
   }
credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.put('https://api.smartsense.co/scim/group/2',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                    'Content-Type': 'application/json'
                  },
                  json=parameters,
                  timeout=5
                )
print (r.json())

Sample PUT Group Response:


HTTP/1.1 204 No Content

No Content

🛑 PUT `/scim/group/{groupID}`

This endpoint allows an existing group to be replaced. When using this endpoint any new values specified are updated, while any values omitted are removed. Send all fields, not just the ones you wish to change.

Parameters

Name	Location	Type	Required	Description
name	body	`string` `(max 255)`	Yes	New name of the group.
attributes	body	`dictionary`	No	A dictionary of string key/value pairs. Valid key names are determined by the group type. Note that, depending on account configuration, some attributes may be required.
externalID	body	`string` `(max 512)`	No	Optional client specified identifier for a group.
members	body	`array[GroupMember]`	No	Users which are part of this group

Responses

Status Codes

Code	Description
204	Success - No Content
400	Bad request - required fields missing, group type does not exist, group type does not conform to hierarchy specification, etc.
403	Forbidden - You do not have permission to perform the task
404	Not Found - The group with the specified ID does not exist or the role or user ID of one of the members does not exist.

Update Group (PATCH)

Sample PATCH Group Request


curl --silent "https://api.smartsense.co/scim/group/2" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request PATCH \
  --data '{ "name" : "New Group Name", 
  "members": [{ "value": {"userID": 3434, "contactRoleIDs": [3, 4]}, operation: "delete" }]}'


import json
import requests

parameters= { "name" : "New Group Name",
              "members": [{ "value": {"userID": 3434, "contactRoleIDs": [3, 4]}, operation: "delete" }]}
credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.patch('https://api.smartsense.co/scim/group/2',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                    'Content-Type': 'application/json'
                  },
                  json=parameters,
                  timeout=5
                )
print (r.json())

Sample PATCH Group Response:


HTTP/1.1 204 No Content

No Content

🛑 PATCH `/scim/group/{groupID}`

This endpoint allows an existing group to be updated. When using this endpoint any new values specified are updated, but any values omitted are not changed.

Parameters

Name	Location	Type	Required	Description
name	body	`string` `(max 255)`	No	New name of the group.
attributes	body	`dictionary`	No	A dictionary of string key/value pairs. Valid key names are determined by the group type. Note that, depending on account configuration, some attributes may be required.
externalID	body	`string` `(max 512)`	No	Optional client specified identifier for a group.
members	body	`array[groupMember]`	No	Users which are part of this group

Responses

Status Codes

Code	Description
204	Success - No Content
400	Bad request - required fields missing, group type does not exist, group type does not conform to hierarchy specification, etc.
403	Forbidden - You do not have permission to perform the task
404	Not Found - The group with the specified ID does not exist or the role or user ID of one of the members does not exist.

Delete Group

Sample Delete Group Request


curl --silent "https://api.smartsense.co/scim/group/12" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request DELETE


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.delete('https://api.smartsense.co/scim/group/12',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                    'Content-Type': 'application/json'
                  },
                  timeout=5
                )
print (r.json())

Sample Delete Group Response


HTTP/1.1 204 No Content

No Content

🛑 DELETE `/scim/group/{groupID}`

This endpoint deletes a group. The group must not contain any devices or subgroups.

Parameters

Name	Location	Type	Required	Description
groupID	path	`int` `(64 bit)`	Yes	ID of group to be deleted

Responses

Status Codes

Code	Description
204	Success - No Content
403	Forbidden - You do not have permission to perform the task
404	Not Found - The group with the specified ID does not exist

GroupTypes

/scim/groupType endpoint allows retrieving SmartSense Group Types supported by the server.

Group types define a group's place in the group hierarchy and the types of custom group attributes available to set for it.

Get All

Sample Get All GroupType Request


curl --silent "https://api.smartsense.co/scim/groupType" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/groupType',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All GroupType Response:


{
    "Account": "The Root Group. There is only one root 'Account' which cannot be deleted by the user (nor can a group of this type be created).",
    "Organization": "Any level above the location level of a hierarchy (Multiple organization groups allowed within a single account. Assets and checklists are not able to be assigned to this type, e.g. Region, Area, District, etc.)",
    "Location": "This is typically a site that has an address associated with it and can contain assets and can have checklists performed.",
    "Department": "This is typically an area within a location that can contain assets and can have checklists performed."
}

GET 🛑 `scim/groupType`

This endpoint returns all group types supported by the server.

Parameters

None.

Responses

Response Body

Property	Type	Description
key	`string`	GroupType name
value	`string`	Description of the GroupType

Status Codes

Code	Description
200	Success

GroupTypeAttributes

/scim/groupTypeAttribute endpoint allows retrieving SmartSense Group Type Attributes configured for the account.

Group Type Attributes define additional configurable properties of a group.

Get All

Sample Get All GroupTypeAttributes Request


curl --silent "https://api.smartsense.co/scim/groupTypeAttribute" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/groupTypeAttribute',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All GroupTypeAttributes Response:


[
    {
        "groupType": "Organization",
        "attributeID": 1,
        "attributeName": "Address,
        "attributeType": "String",
        "isRequired": "true"
    },
    ... groupTypeAttributes
]

GET 🛑 `scim/groupTypeAttribute`

This endpoint returns all group type attributes configured for the account.

Parameters

None.

Responses

Response Body

Property	Type	Description
groupType	`string`	The Type of the Group
attributeID	`int` `(64 bit)`	The ID of the Attribute
attributeName	`string`	The Name of the Attribute
attributeType	`string`	The date type of the Attribute
isRequired	`bool`	Is this Attribute required for the GroupType. Making an attribute required means that you cannot create a group of that type unless the attribute is specified.

Status Codes

Code	Description
200	Success

Get By GroupType

Sample Get By GroupType GroupTypeAttributes Request


curl --silent "https://api.smartsense.co/scim/groupTypeAttribute/Location" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/groupTypeAttribute/Location',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get By GroupType GroupTypeAttributes Response:


[
    {
        "groupType": "Organization",
        "attributeID": 1,
        "attributeName": "Address,
        "attributeType": "String",
        "isRequired": "true"
    },
    ... groupTypeAttributes
]

GET 🛑 `scim/groupTypeAttribute/{groupType}`

This endpoint returns all group type attributes configured for the account for a given GroupType.

Parameters

Name	Location	Type	Required	Description
groupType	path	`string`	yes	GroupType of the attributes to retrieve

Responses

Response Body

Property	Type	Description
groupType	`string`	The Type of the Group
attributeID	`int` `(64 bit)`	The ID of the Attribute
attributeName	`string`	The Name of the Attribute
attributeType	`string`	The date type of the Attribute
isRequired	`bool`	Is this Attribute required for the GroupType. Making an attribute required means that you cannot create a group of that type unless the attribute is specified.

Status Codes

Code	Description
200	Success
400	Bad Request
404	Not Found

Create GroupType Attribute

Sample Create GroupTypeAttribute Request


curl --silent "https://api.smartsense.co/scim/groupTypeAttribute" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request POST \
  --data '{
    "groupType":"Location",
    "name":"TestAttribute",
    "isRequired":true,
    "attributeType":"String"    
  }'


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
payload = { "groupType" : "Location",
            "name" : "TestAttribute",
            "isRequired" : true,
            "attributeType" : "String"
          }

r = requests.post('https://api.smartsense.co/scim/groupTypeAttribute',
                 headers={
                   'Accept': 'application/json',
                   'Authorization': 'Bearer ' + credential_token
                 },
                 json = payload,
                 timeout=5
                 )

print (r.text)

Sample Create GroupTypeAttribute Response:


HTTP/1.1 200 Ok

1

🛑 POST `/scim/groupTypeAttribute`

This endpoint creates a new group type attribute in SmartSense.

Parameters

Name	Location	Type	Required	Description
groupType	body	`string`	Yes	The group type to create the attribute for.
name	body	`string` `(64 bit)`	Yes	Name of the group type attribute.
isRequired	body	`bool`	No	Is this Attribute required for the GroupType. Making an attribute required means that you cannot create a group of that type unless the attribute is specified.
attributeType	body	`string`	No	The data type of the new attribute. Only 'String' attributes are currently supported.

Responses

Response Body

Property	Type	Description
id	`int (64 bit)`	The ID of the GroupTypeAttribute that was created.

Status Codes

Code	Description
200	Success
400	Bad request - required fields missing, group type does not exist, group type does not conform to hierarchy specification, etc.
403	Forbidden - User does not have access to the specified account
404	Not Found - The specified group type does not exist, the specified parent group does not exist, or the attribute type does not exist.

ResourceTypes

/scim/resourceType endpoints allow retrieving SCIM resource types supported by the server.

Get All

Sample Get All ResourceType Request


curl --silent "https://api.smartsense.co/scim/resourceType" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/resourceType',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All ResourceType Response:


[
  {
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 5,
  "itemsPerPage": 5,
  "startIndex": 1,
  "resources": [
    {
      "name": "User",
      "description": "User Account",
      "endpoint": "/User",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:SmartSense4:1.0:User",
          "required": false
        }
      ],
      "id": "User",
      "meta": {
        "resourceType": "ResourceType",
        "location": "/ResourceType/User"
      }
    },
    {
      "name": "Group",
      "description": "Location",
      "endpoint": "/Group",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "id": "Group",
      "meta": {
        "resourceType": "ResourceType",
        "location": "/ResourceType/Group"
      }
    },
    {
      "name": "ContactRole",
      "description": "Contact Roles are Roles that can be applied to Locations/Groups for User Accounts",
      "endpoint": "/ContactRole",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:ContactRole",
      "id": "ContactRole",
      "meta": {
        "resourceType": "ResourceType",
        "location": "/ResourceType/ContactRole"
      }
    },
    {
      "name": "SmsCarrier",
      "description": "Lookup list of supported SMS Carrier Ids",
      "endpoint": "/SmsCarrier",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:SmsCarrier",
      "id": "SmsCarrier",
      "meta": {
        "resourceType": "ResourceType",
        "location": "/ResourceType/SmsCarrier"
      }
    },
    {
      "name": "AccessRole",
      "description": "Lookup list of supported user Access Roles",
      "endpoint": "/AccessRole",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:AccessRole",
      "id": "AccessRole",
      "meta": {
        "resourceType": "ResourceType",
        "location": "/ResourceType/AccessRole"
      }
    },
    {
      "name": "SystemInfo",
      "description": "Display application and system information",
      "endpoint": "/SystemInfo",
      "schema": "urn:ietf:params:scim:schemas:SmartSense:1.0:SystemInfo",
      "id": "SystemInfo",
      "meta": {
        "resourceType": "ResourceType",
        "location": "/ResourceType/SystemInfo"
      }
    }
  ]
}
]

🛑 GET `scim/resourceType`

This endpoint returns all resource types supported by the server.

Parameters

None.

Responses

Status Codes

Code	Description
200	Success

Get One

Sample Get ResourceType Request


curl --silent "https://api.smartsense.co/scim/resourceType/User" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/resourceType/User',
                 headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get ResourceType Response:


{
  "name": "User",
  "description": "User Account",
  "endpoint": "/User",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [
    {
      "schema": "urn:ietf:params:scim:schemas:SmartSense4:1.0:User",
      "required": false
    }
  ],
  "id": "User",
  "meta": {
    "resourceType": "ResourceType",
    "location": "/ResourceType/User"
  }
}

🛑 GET `/scim/resourceType/{resourceName}`

This endpoint returns a single resource type.

Parameters

Name	Location	Type	Required	Description
resourceName	path	`string`	Yes	Resource type to retrieve

Supported Parameter Values

ResourceName
User
Group
ContactRole
SmsCarrier
AccessRole

Responses

Status Codes

Code	Description
200	Success
404	Not Found

Service Provider Configuration

/scim/ServiceProviderConfiguration endpoint allows retrieving SCIM Service Provider Configuration Schema supported by the server.

Get All

Sample Get All ServiceProviderConfiguration Request


curl --silent "https://api.smartsense.co/scim/ServiceProviderConfiguration" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/ServiceProviderConfiguration',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All ServiceProviderConfiguration Response:


{
    "documentationURI": "https://developer.smartsense.co",
    "patch": {
        "supported": false
    },
    "bulk": {
        "supported": false,
        "maxOperations": 0,
        "maxPayloadSize": 0
    },
    "filter": {
        "supported": false,
        "maxResults": 0
    },
    "changePassword": {
        "supported": false
    },
    "sort": {
        "supported": false
    },
    "eTag": {
        "supported": false
    },
    "authenticationSchemes": [
        {
            "type": "oauthbearertoken",
            "name": "OAuth Bearer Token",
            "description": "Authentication Scheme using the OAuth Bearer Token Standard",
            "specURI": "http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-01",
            "primary": true,
            "documentationURI": "https://developer.smartsense.co"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "meta": {
        "resourceType": "ServiceProviderConfiguration",
        "created": "2020-03-01T00:00:00",
        "lastModified": "2020-03-01T00:00:00",
        "location": "/scim/ServiceProviderConfiguration",
        "version": "1"
    }
}

🛑 GET `scim/ServiceProviderConfiguration`

This endpoint returns all ServiceProviderConfiguration supported by the server.

Parameters

None.

Responses

Status Codes

Code	Description
200	Success

SMS Carrier

/scim/smsCarrier endpoint allows retrieving SmartSense SMS Carriers supported by the server.

Get All

Sample Get All SMS Carriers Request


curl --silent "https://api.smartsense.co/scim/smsCarrier" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/smsCarrier',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All SMS Carriers Response:


{
  "Alltel": 1,
  "AT&T": 2,
  "Boost": 3,
  "Nextel": 4,
  "Sprint PCS": 5,
  "T-Mobile": 6,
  "US Cellular": 7,
  "Verizon": 8,
  "Virgin Mobile": 9,
  "Element Mobile": 10,
  "Ntelos": 11,
  "Metro PCS": 12,
  "Emtel": 13,
  "Movistar": 14,
  "Telus": 15,
  "Entel": 17,
  "Cricket Wireless": 18,
  "O2": 20,
  "Cincinnati Bell Wireless": 21,
  "Orange": 22,
  "SFR": 23,
  "Bell Mobility": 25,
  "ESMS Rogers": 26,
  "ATT MMS": 28,
  "Telstra": 29,
  "Alaska Communications": 30,
  "TracFone": 32,
  "Inland Cellular": 33,
  "Straight Talk": 34,
  "Rogers PCS": 35,
  "Clear Talk": 36,
  "CSpire Wireless": 37,
  "Consumer Cellular": 38,
  "TempAlert": 39,
  "Google fi": 40
}

🛑 GET `scim/smsCarrier`

This endpoint returns all SMS Carriers supported by the server.

Parameters

None.

Responses

Status Codes

Code	Description
200	Success

User

The following endpoints allow API clients to perform CRUD operations on SCIM users:

Create User

Sample Create User Request


curl --silent "https://api.smartsense.co/scim/user" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request POST \
  --data '{
   "userName": "apiUser",
   "name": {
      "givenName": "John",
      "familyName": "Doe"
   },
   "emails":[
      {
         "type": "work",
         "value": "jdoe@SmartSense.io",
         "primary": true
      }
   ],
   "phoneNumbers": [
      {
         "type": "voice",
         "value": "+1235551234",
         "extension": "x12",
         "primary": true
      },
      {
         "type": "sms",
         "value": "+1235550000",
         "smsCarrierId": 1,
         "primary": true
      }
   ],
   "roles": [
        {
            "value": "Viewer",
            "type": "Role",
            "primary": true
        }
    ],
   "externalID": "abcd123",
   "urn:ietf:params:scim:schemas:SmartSense:1.0:User": {
      "managedExternally": false
   }
}'


import json
import requests

user= {
   "userName": "apiUser",
   "name": {
      "givenName": "John",
      "familyName": "Doe"
   },
   "emails":[
      {
         "type": "work",
         "value": "jdoe@SmartSense.io",
         "primary": true
      }
   ],
   "phoneNumbers": [
      {
         "type": "voice",
         "value": "+1235551234",
         "extension": "x12",
         "primary": true
      },
      {
         "type": "sms",
         "value": "+1235550000",
         "smsCarrierId": 1,
         "primary": true
      }
   ],
   "roles": [
        {
            "value": "Viewer",
            "type": "Role",
            "primary": true
        }
    ],
   "externalID": "abcd123",
   "urn:ietf:params:scim:schemas:SmartSense:1.0:User": {
      "managedExternally": false
   }
}
credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.post('https://api.smartsense.co/scim/user',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                    'Content-Type': 'application/json'
                  },
                  json=user,
                  timeout=5
                )
print (r.json())

Sample Create User Response:


HTTP/1.1 201 Created
Location: /scim/users/1

No Content

🛑 POST `/scim/user`

This endpoint creates a new user in SmartSense. The username must be unique. On success, the SCIM API path of the new user is passed in the Location header of the response.

Parameters

Name	Location	Type	Required	Description
user	body	user	Yes	The user to create

Responses

Status Codes

Code	Description
201	Success - User Created
403	Forbidden - You do not have permission to create the user
409	Conflict - Username already exists

Get All

Sample Get All Users Request


curl --silent "https://api.smartsense.co/scim/user?startIndex=1&count=5" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/scim/user?startIndex=1&count=5',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  },
                  timeout=5
                )
print (r.json())

Sample Get All Users Response

{
    "totalResults": 234,
    "resources": [
        ... users
    ],
    "startIndex": 1,
    "itemsPerPage": 50
}

🛑 GET `/scim/user`

This endpoint returns all users in your account. This call returns a paginated response of users.

Parameters

Name	Location	Type	Required	Description
username	querystring	`string`	No	optional username filter. if provided, only users with this username will be returned.
givenName	querystring	`string`	No	optional first/given name filter. if provided, only users with this given name will be returned.
familyName	querystring	`string`	No	optional last/family filter. if provided, only users with this family name will be returned.
email	querystring	`string`	No	optional email filter. if provided, only users with this email will be returned.
roles	querystring	`string`	No	optional comma separated list of role names. if provided, only users with a role in the list will be returned.
SSOUsersOnly	querystring	`bool`	No	optional boolean, when true the list of users returned will only include SSO users
startIndex	querystring	`int`	No	optional 1-based index of the first query result. Defaults to 1.
count	querystring	`int`	No	optional non-negative number of items to retrieve. Defaults to 50.

Responses

Status Codes

Code	Description
200	Success
404	Not Found

Response Body

Property	Type	Description
totalResults	`int`	Total number of items that matched the query criteria
itemsPerPage	`int`	Number of items returned per page
startIndex	`int`	The starting index of this query
schemas	`array[string]`	The schema(s) of the response
resources	`array[`user`]`	Array of the users requested

Get One

Sample Get User Request


curl --silent "https://api.smartsense.co/scim/user/1" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

user_id='1'
credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.get('https://api.smartsense.co/scim/user/' + user_id,
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  },
                  timeout=5
                )
print (r.json())

Sample Get User Response:


{
    "enterpriseUser": {
        "managedExternally": false
    },
    "userName": "apiUser",
    "name": {
        "givenName": "John",
        "familyName": "Doe"
    },
    "emails": [
        {
            "value": "jdoe@SmartSense.io",
            "type": "work",
            "primary": true
        }
    ],
    "phoneNumbers": [
        {
            "extension": "x12",
            "value": "+1235551234",
            "type": "voice",
            "primary": true
        },
        {
            "smsCarrierId": 1,
            "value": "+1235550000",
            "type": "sms",
            "primary": true
        }
    ],
    "groups": [],
    "roles": [
        {
            "value": "Viewer",
            "type": "Role",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:SmartSense:1.0:User"
    ],
    "id": "1",
    "externalID": "abcd123",
    "meta": {
        "resourceType": "User",
        "location": "/scim/user/1"
    }
}

🛑 GET `/scim/user/{userId}`

This endpoint retrieves a single user.

Parameters

Name	Location	Type	Required	Description
userId	path	`int`	ID of the user to retrieve	Yes

Responses

Status Codes

Code	Description
200	Success
404	Not Found

Response Body

Body	Description
user	The user requested

Update User

Sample Update User Request


curl --silent "https://api.smartsense.co/scim/user/1" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request PUT \
  --data '{
   "userName": "apiUser",
   "name": {
      "givenName": "John",
      "familyName": "Doe"
   },
   "emails":[
      {
         "type": "work",
         "value": "jdoe@SmartSense.io",
         "primary": true
      }
   ],
   "phoneNumbers": [
      {
         "type": "voice",
         "value": "+1235551234",
         "extension": "x12",
         "primary": true
      },
      {
         "type": "sms",
         "value": "+1235550000",
         "smsCarrierId": 1,
         "primary": true
      }
   ],
   "roles": [
        {
            "value": "Viewer",
            "type": "Role",
            "primary": true
        }
    ],
   "externalID": "abcd123",
   "urn:ietf:params:scim:schemas:SmartSense:1.0:User": {
      "managedExternally": false
   }'


import json
import requests

user_id='1'
user= {
   "userName": "apiUser",
   "name": {
      "givenName": "John",
      "familyName": "Doe"
   },
   "emails":[
      {
         "type": "work",
         "value": "jdoe@SmartSense.io",
         "primary": true
      }
   ],
   "phoneNumbers": [
      {
         "type": "voice",
         "value": "+1235551234",
         "extension": "x12",
         "primary": true
      },
      {
         "type": "sms",
         "value": "+1235550000",
         "smsCarrierId": 1,
         "primary": true
      }
   ],
   "roles": [
        {
            "value": "Viewer",
            "type": "Role",
            "primary": true
        }
    ],
   "externalID": "abcd123",
   "urn:ietf:params:scim:schemas:SmartSense:1.0:User": {
      "managedExternally": false
   }

credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.put('https://api.smartsense.co/scim/user/' + user_id,
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json',
                    'Content-Type': 'application/json'
                  },
                  json=user,
                  timeout=5
                )
print (r.json())

Sample Update User Response:


HTTP/1.1 204 No Content

No Content

🛑 PUT `/scim/user/{userId}`

This endpoint updates (replaces) a user with the new information in the request. Send all fields, not just the ones you wish to change.

Parameters

Name	Location	Type	Required	Description
user	body	user	Yes	New value for user
userId	path	`int`	Yes	ID of the user to update

Responses

Status Codes

Code	Description
204	Success - No Content
403	Forbidden - You do not have permission to create the user
404	Not Found

Delete User

Sample Delete User Request


curl --silent "https://api.smartsense.co/scim/user/1"
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"\
  --request DELETE


import json
import requests

user_id='1'
credential_token = "TOKEN_FROM_SMARTSENSE"
r = requests.delete('https://api.smartsense.co/scim/user/' + user_id,
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json', 
                    'Content-Type': 'application/json'
                  },
                  json=user,
                  timeout=5
                )
print (r.json())

Sample Delete User Response


HTTP/1.1 204 No Content

No Content

🛑 DELETE `/scim/user/{userId}`

This endpoint deletes a user.

Parameters

Name	Location	Type	Required	Description
userId	path	`int`	Yes	ID of the user to delete

Delete Responses

Status Codes

Code	Description
204	No Content
403	Forbidden - You do not have permission to delete the user
404	Not Found

SystemInfo

/scim/systeminfo endpoint allows retrieving SmartSense System Information including: Description of API service, current release version.

Get All

Sample Get All SystemInfo Request


curl --silent "https://api.smartsense.co/scim/systeminfo" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/systeminfo',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All SystemInfo Response:


{
    "Service Description": "Digi SmartSense SCIM API",
    "Release": "1.6.0"
}

🛑 GET `scim/systeminfo`

This endpoint returns the available service and system information such as current release version.

Parameters

None.

Responses

Response Body

Property	Type	Description
key	`string`	Key
value	`string`	Value of Key

Status Codes

Code	Description
200	Success

Schema

The /scim/schema endpoints allow retrieving the SCIM schemas supported by the server.

Get All

Sample Get All Schema Request


curl --silent "https://api.smartsense.co/scim/schema" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/schema',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get All Schema Response:


{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 10,
    "itemsPerPage": 10,
    "startIndex": 1,
    "resources": [
            ... schemas
            ]
        }
    ]
}

🛑 GET `/scim/schema`

This endpoint retrieves all the schema supported by the server.

Parameters

None.

Responses

Status Codes

Code	Description
200	Success

Get One

Sample Get Schema Request


curl --silent "https://api.smartsense.co/scim/schema/urn:ietf:params:scim:schemas:core:2.0:User" \
  --header "Authorization: Bearer TOKEN_FROM_SMARTSENSE" \
  --header "Accept: application/json"


import json
import requests

credential_token = "TOKEN_FROM_SMARTSENSE"           
r = requests.get('https://api.smartsense.co/scim/schema/urn:ietf:params:scim:schemas:core:2.0:User',
                  headers={
                    'Authorization': 'Bearer ' + credential_token,
                    'Accept': 'application/json'
                  }
                )
print (r.json())

Sample Get Schema Response:


{
    "id": "urn:ietf:params:scim:schemas:core:2.0:User",
    "name": "User",
    "description": "User Account",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
    ],
    "meta": {
        "resourceType": "Schema",
        "location": "scim/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    },
    "attributes": [
        {
            "name": "userName",
            "type": "string",
            "multiValued": false,
            "description": "Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. REQUIRED.",
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "server"
        },
        {
            "name": "name",
            "type": "complex",
            "multiValued": false,
            "description": "The components of the user's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined.",
            "required": true,
            "caseExact": false,
            "returned": "default",
            "uniqueness": "none",
            "subAttributes": [
                {
                    "name": "familyName",
                    "type": "string",
                    "multiValued": false,
                    "description": "The family name of the User, or last name in most Western languages (e.g., 'Jensen' given the full name 'Ms. Barbara J Jensen, III').",
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "givenName",
                    "type": "string",
                    "multiValued": false,
                    "description": "The given name of the User, or first name in most Western languages (e.g., 'Barbara' given the full name 'Ms. Barbara J Jensen, III').",
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                }
            ]
        },
        {
            "name": "emails",
            "type": "complex",
            "multiValued": true,
            "description": "Email addresses for the user.The value SHOULD be canonicalized by the service provider, e.g., 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical type values of 'work', 'home', and 'other'.",
            "required": true,
            "subAttributes": [
                {
                    "name": "value",
                    "type": "string",
                    "multiValued": false,
                    "description": "Email addresses for the user.The value SHOULD be canonicalized by the service provider, e.g., 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical type values of 'work', 'home', and 'other'.",
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "type",
                    "type": "string",
                    "multiValued": false,
                    "description": "A label indicating the attribute's function, e.g., ' work ' or ' home '.",
                    "required": false,
                    "caseExact": false,
                    "canonicalValues": [
                        "work",
                        "home",
                        "other"
                    ],
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                }
            ],
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "none"
        },
        {
            "name": "phoneNumbers",
            "type": "complex",
            "multiValued": true,
            "description": "Phone Numbers for the user. ",
            "required": true,
            "subAttributes": [
                {
                    "name": "value",
                    "type": "string",
                    "multiValued": false,
                    "description": "Phone Numbers for the user. Format should begin with '+' followed by only digits, e.g. '+12015551234'. Canonical type values of 'work', 'voice', 'sms' and 'mobile' MUST be set. See description.",
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "type",
                    "type": "string",
                    "multiValued": false,
                    "description": "A label indicating the attribute's function. 'work' or 'voice' indicate this is a regular phone number. 'sms' or 'mobile' indicate this is a phone number that can recieve SMS text messages.",
                    "required": false,
                    "caseExact": false,
                    "canonicalValues": [
                        "voice",
                        "work",
                        "sms",
                        "mobile"
                    ],
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "extension",
                    "type": "string",
                    "multiValued": false,
                    "description": "Optional field for a PBX extension for a 'voice' or 'work' phone number.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "smsCarrierId",
                    "type": "int",
                    "multiValued": false,
                    "description": "Optional field for a SMS Carrier Id for a 'sms' or 'mobile' phone number. GET '/scim/smscarrier' for supported carriers and values. SMS messaging will still work if this is left blank.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "primary",
                    "type": "bool",
                    "multiValued": false,
                    "description": "Optional field to indicate preferred phone number. If omitted, the first number listed for the type will be used.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                }
            ],
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "none"
        },
        {
            "name": "entitlements",
            "type": "complex",
            "multiValued": true,
            "description": "A list of entitlements for the User that represent a thing the User has.",
            "required": false,
            "subAttributes": [
                {
                    "name": "value",
                    "type": "string",
                    "multiValued": false,
                    "description": "The value of an entitlement.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "type",
                    "type": "string",
                    "multiValued": false,
                    "description": "A label indicating the attribute's function.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                }
            ],
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default"
        },
        {
            "name": "roles",
            "type": "complex",
            "multiValued": true,
            "description": "A list of roles for the User that collectively represent who the User is, e.g., 'Administrator', 'Viewer'.",
            "required": false,
            "subAttributes": [
                {
                    "name": "value",
                    "type": "string",
                    "multiValued": false,
                    "description": "The value of a role.",
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "display",
                    "type": "string",
                    "multiValued": false,
                    "description": "A human-readable name, primarily used for display purposes. READ-ONLY.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "type",
                    "type": "string",
                    "multiValued": false,
                    "description": "A label indicating the attribute's function.",
                    "required": false,
                    "caseExact": false,
                    "canonicalValues": [],
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "primary",
                    "type": "boolean",
                    "multiValued": false,
                    "description": "A Boolean value indicating the 'primary' or preferred attribute value for this attribute. The primary attribute value 'true' MUST appear no more than once.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "default"
                }
            ],
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default"
        }
    ],
    "caseExact": false,
    "mutability": "readWrite",
    "returned": "default"
}

🛑 GET `/scim/schema/{schemaName}`

This endpoint retrieves a single schema.

Parameters

Name	Location	Type	Required	Description
schemaName	path	`string`	Yes	Schema type to retrieve

Supported Parameter Values

Name	Description
urn:ietf:params:scim:schemas:core:2.0:ResourceType	The supported ResourceType schema
urn:ietf:params:scim:schemas:core:2.0:User	The supported User schema
urn:ietf:params:scim:schemas:SmartSense:1.0:User	SmartSense User schema extension
urn:ietf:params:scim:schemas:core:2.0:Group	SmartSense Group schema
urn:ietf:params:scim:schemas:SmartSense:1.0:ContactRole	SmartSense Contact Roles schema
urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig	The supported ServiceProviderConfig schema
urn:ietf:params:scim:api:messages:2.0:ListResponse	Specifies the schema that describes a SCIM List Response message
urn:ietf:params:scim:schemas:SmartSense:1.0:SmsCarrier	SmartSense SMS Carriers schema
urn:ietf:params:scim:schemas:SmartSense:1.0:AccessRole	SmartSense Access Roles schema
urn:ietf:params:scim:schemas:SmartSense:1.0:SystemInfo	SmartSense Application Information schema
urn:ietf:params:scim:schemas:core:2.0:Schema	The supported Schema schema

Responses

Code	Description
200	Success
404	Not Found