NAV
HTTP

API Reference

The DicksonOne REST API uses predictable resource-oriented URLs, accepts both JSON-encoded and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Please Note

Base URL

Code examples below assume that requests are being directed to endpoints for the application at a base URL. All listed request endpoints should be directed to the following domain:

https://www.dicksonone.com

Authentication

GET https://www.dicksonone.com/api/rest/users HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN

The DicksonOne API uses API keys to authenticate requests. Account Managers and Owners can manage the API keys available for their account via “Manage > API Keys”. Use of this API requires that your account have an active subscription with an appropriate level of features. If you’re interested in accessing the REST API and don’t currently have access to API Key management, please contact support@dicksonone.com to discuss upgrading your subscription.

In order to access the API, you’ll need to pass the token associated with an active API Key as a Bearer token in the Authorization header for each request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Pagination

Due to the large number of records that can be returned with each request, DicksonOne’s REST API uses pagination to pass back records in manageable chunks.

Request

GET https://www.dicksonone.com/api/rest/locations?page[number]=2&page[size]=3 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

For API endpoints that return a collection of results, you can control which page of results you’re fetching, as well as the number of results included on each page, using the following pagination parameters.

Parameters

Name Description
page[number] The number of the page you’re requesting.
page[size] The number of results you want to receive per-page. This defaults to 25, and has a maximum value of 100.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ 
  "data": [
    { "id": 4, "name": "Pharmaceutical Warehouse - West", "sublocation_ids": [5, 6] },
    { "id": 5, "name": "Vaccine Refrigerator A", "sublocation_ids": [] },
    { "id": 6, "name": "Vaccine Refrigerator B", "sublocation_ids": [] }
  ],
  "meta" : {
    "pagination": {
      "record_count": 7,
      "page_size": 3,
      "page_count": 3,
      "current_page": 2,
      "prev_page": 1,
      "next_page": 3
    }
  }
}

Each response for a paginated endpoint will include a set of metadata for the paginated results, in addition to the list of record data.

Fields

Name Description
data The list of record data for the current page of results.
meta[pagination][record_count] The total count of records in the collection.
meta[pagination][page_size] The number of results included per-page.
meta[pagination][page_count] The total number of results pages.
meta[pagination][current_page] The number of the current page of results.
meta[pagination][prev_page] The number of the previous page of results.
meta[pagination][next_page] The number of the next page of results.

Errors

DicksonOne uses conventional HTTP response codes to indicate the success or failure of an API request.

Success Codes

Code Description
200 The request was successful.
201 A record was created in response to the request.

Error Codes

Code Description
301 The request was made via HTTP, rather than HTTPS. You will need to attempt your request again using SSL.
400 The request’s format was invalid. This can be triggered by invalid pagination parameters.
401 No API token was supplied, or the supplied API token was invalid.
403 The user authenticated by the API token is not permitted to perform the requested action.
404 The requested record wasn’t found.
409 Your request caused a conflict with existing data. Review the list of error messages to determine how to resolve the error.
422 The requested change was rejected due to validation errors. Review the list of error messages to determine how to resolve the error.
500 A hard-error occurred on DicksonOne’s servers. If the problem persists, please report the issue to support@dicksonone.com, with as much detail as possible.
503 DicksonOne is experiencing a service outage. You can try your request again in a few moments.

Support

Dickson does not provide support for custom integrations. If you have general questions regarding access to or the functionality of the API, please email support@dicksonone.com. This code is provided “as is”, without warranty of any kind expressed or implied.

Alerts

View the alerts that have been triggered by devices on your account. Each Alert record represents a historical event that was caused by a Device tripping the warning or excursion condition for a configured Alarm.

Listing all alerts

Retrieve a list of all historical alerts for your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/alerts HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/alerts

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 1,
      "description": "Temperature CH:1 is above 69.0°F",
      "type": "excursion",
      "escalation_started_at": "2020-08-10T20:40:34.000Z",
      "entered_at": "2020-08-10T21:10:34.000Z",
      "excursion_at": "2020-08-10T21:40:34.000Z",
      "returned_to_normal_at": null,
      "acknowledged_at": "2020-08-10T21:25:34.000Z",
      "acknowledger": {
        "id": 2,
        "email": "clinton_wunsch@ledner-price.biz",
        "full_name": "Clinton Wunsch",
        "first_name": "Clinton",
        "last_name": "Wunsch",
        "current_login_at": "2020-08-10T21:10:35.000Z",
        "last_login_at": "2020-08-10T20:10:34.000Z",
        "last_request_at": "2020-08-10T22:05:35.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      },
      "location": {
        "id": 1,
        "name": "Marvin-Hilll",
        "sublocation_ids": [

        ]
      },
      "device": {
        "name": "Evaporative cooler 1",
        "token": "544223957733959814",
        "sku": "B000JKKCMW",
        "serial": "e468c3cd4e12d5f6",
        "is_replaced": false
      },
      "channel": {
        "id": 1,
        "name": "Temperature CH:1",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2020-07-20T22:10:34.000Z",
        "last_datapoint_at": "2020-08-10T21:44:34.000Z"
      }
    },
    {
      "id": 2,
      "description": "Temperature CH:1 is above 69.0°F",
      "type": "warning",
      "escalation_started_at": "2020-08-10T20:10:35.000Z",
      "entered_at": "2020-08-10T20:40:35.000Z",
      "excursion_at": null,
      "returned_to_normal_at": "2020-08-10T21:10:35.000Z",
      "acknowledged_at": null,
      "acknowledger": null,
      "location": {
        "id": 1,
        "name": "Marvin-Hilll",
        "sublocation_ids": [

        ]
      },
      "device": {
        "name": "Evaporative cooler 1",
        "token": "544223957733959814",
        "sku": "B000JKKCMW",
        "serial": "e468c3cd4e12d5f6",
        "is_replaced": false
      },
      "channel": {
        "id": 1,
        "name": "Temperature CH:1",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2020-07-20T22:10:34.000Z",
        "last_datapoint_at": "2020-08-10T21:44:34.000Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The unique identifier for this Alert record.
description
The condition which resulted in the alert.
type
The type of alert. Either `warning` or `excursion`.
escalation_started_at
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert.
entered_at
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert.
excursion_at
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion.
returned_to_normal_at
An ISO-8601 timestamp representing the time that the alert was resolved.
acknowledged_at
An ISO-8601 timestamp representing the time that the alert was acknowledged.
acknowledger
The data for the user that acknowledged the alert.
location
The data for the location in which this alert took place.
device
The data for the device related to this alert.
channel
The data for the channel related to this alert. This will be null for device-level (not reporting) alerts.

Listing filtered alerts

Retrieve a list of historical alerts for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/alerts?search[tokens][]=824030898858204942&search[type]=excursion&search[started_after]=2020-08-10T19%3A10%3A36Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/alerts

Parameters

Name Description
search[tokens] A list of tokens for the devices to which you want to restrict your search.
search[location_ids] A list of IDs for the locations to which you want to restrict your search.
search[type] The type of alerts to which you want to restrict your search. Acceptable values are `all` (default), `excursion`, or `warning`.
search[started_after] An ISO-8601 timestamp. Results will be filtered to alerts triggered after this time.
search[started_before] An ISO-8601 timestamp. Results will be filtered to alerts triggered prior to this time.
search[ended_after] An ISO-8601 timestamp. Results will be filtered to alerts resolved after this time.
search[ended_before] An ISO-8601 timestamp. Results will be filtered to alerts resolved prior to this time.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 3,
      "description": "Temperature CH:2 is above 9.0°F",
      "type": "excursion",
      "escalation_started_at": "2020-08-10T20:40:36.000Z",
      "entered_at": "2020-08-10T21:10:36.000Z",
      "excursion_at": "2020-08-10T21:40:36.000Z",
      "returned_to_normal_at": null,
      "acknowledged_at": "2020-08-10T21:25:36.000Z",
      "acknowledger": {
        "id": 4,
        "email": "bryce.klein@gulgowski-gorczany.info",
        "full_name": "Bryce Klein",
        "first_name": "Bryce",
        "last_name": "Klein",
        "current_login_at": "2020-08-10T21:10:36.000Z",
        "last_login_at": "2020-08-10T20:10:36.000Z",
        "last_request_at": "2020-08-10T22:05:36.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      },
      "location": {
        "id": 2,
        "name": "Robel and Sons",
        "sublocation_ids": [

        ]
      },
      "device": {
        "name": "Blender 2",
        "token": "824030898858204942",
        "sku": "B000N5FYO4",
        "serial": "4f27dcde1523ecb4",
        "is_replaced": false
      },
      "channel": {
        "id": 2,
        "name": "Temperature CH:2",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2020-07-27T22:10:36.000Z",
        "last_datapoint_at": "2020-08-10T21:44:36.000Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The unique identifier for this Alert record.
description
The condition which resulted in the alert.
type
The type of alert. Either `warning` or `excursion`.
escalation_started_at
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert.
entered_at
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert.
excursion_at
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion.
returned_to_normal_at
An ISO-8601 timestamp representing the time that the alert was resolved.
acknowledged_at
An ISO-8601 timestamp representing the time that the alert was acknowledged.
acknowledger
The data for the user that acknowledged the alert.
location
The data for the location in which this alert took place.
device
The data for the device related to this alert.
channel
The data for the channel related to this alert. This will be null for device-level (not reporting) alerts.

Acknowledging an alert

Mark an alert as acknowledged. The acknowledger for the alert will be set to the User associated with the API token, and the acknowledged_at timestamp will be set to the time that the request was received by the server. Attempting to acknowledge an alert that has already been acknowledged will result in a 409 Conflict response.

Request

POST /api/rest/alerts/5/acknowledgements HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

POST /api/rest/alerts/:alert_id/acknowledgements

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "data": {
    "id": 5,
    "description": "Temperature CH:3 is above 31.0°F",
    "type": "excursion",
    "escalation_started_at": "2020-08-10T20:40:36.000Z",
    "entered_at": "2020-08-10T21:10:36.000Z",
    "excursion_at": "2020-08-10T21:40:36.000Z",
    "returned_to_normal_at": null,
    "acknowledged_at": "2020-08-10T22:10:36.000Z",
    "acknowledger": {
      "id": 5,
      "email": "jacquetta.kiehn@lockman.net",
      "full_name": "Jacquetta Kiehn",
      "first_name": "Jacquetta",
      "last_name": "Kiehn",
      "current_login_at": "2020-08-10T21:10:36.000Z",
      "last_login_at": "2020-08-09T22:10:36.000Z",
      "last_request_at": "2020-08-10T22:05:36.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    },
    "location": {
      "id": 3,
      "name": "Prohaska, Blanda and Hudson",
      "sublocation_ids": [

      ]
    },
    "device": {
      "name": "Oven 3",
      "token": "621700428653451639",
      "sku": "B000HB4DU0",
      "serial": "8d12540519e0d2ef",
      "is_replaced": false
    },
    "channel": {
      "id": 3,
      "name": "Temperature CH:3",
      "type": "Temperature",
      "unit": "fahrenheit",
      "first_datapoint_at": "2020-07-27T22:10:36.000Z",
      "last_datapoint_at": "2020-08-10T22:07:36.000Z"
    }
  }
}

Fields

Name Description
id
The unique identifier for this Alert record.
description
The condition which resulted in the alert.
type
The type of alert. Either `warning` or `excursion`.
escalation_started_at
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert.
entered_at
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert.
excursion_at
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion.
returned_to_normal_at
An ISO-8601 timestamp representing the time that the alert was resolved.
acknowledged_at
An ISO-8601 timestamp representing the time that the alert was acknowledged.
acknowledger
The data for the user that acknowledged the alert.
location
The data for the location in which this alert took place.
device
The data for the device related to this alert.
channel
The data for the channel related to this alert. This will be null for device-level (not reporting) alerts.

Listing comments for an alert

Retrieve a list of comments that have been submitted for a particular alert. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/alerts/6/comments HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/alerts/:alert_id/comments

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 2,
      "text": "Error et molestiae. Mollitia autem odit.",
      "created_at": "2020-08-10T22:10:37.000Z",
      "user": {
        "id": 7,
        "email": "stamm_gwen@olson-keeling.biz",
        "full_name": "Gwen Stamm",
        "first_name": "Gwen",
        "last_name": "Stamm",
        "current_login_at": "2020-08-10T21:10:37.000Z",
        "last_login_at": "2020-08-09T22:10:37.000Z",
        "last_request_at": "2020-08-10T22:05:37.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    },
    {
      "id": 3,
      "text": "Quis quia et. Consequuntur excepturi quasi.",
      "created_at": "2020-08-10T22:10:37.000Z",
      "user": {
        "id": 7,
        "email": "stamm_gwen@olson-keeling.biz",
        "full_name": "Gwen Stamm",
        "first_name": "Gwen",
        "last_name": "Stamm",
        "current_login_at": "2020-08-10T21:10:37.000Z",
        "last_login_at": "2020-08-09T22:10:37.000Z",
        "last_request_at": "2020-08-10T22:05:37.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    },
    {
      "id": 4,
      "text": "Eveniet quia sunt. Animi perferendis sapiente.",
      "created_at": "2020-08-10T22:10:37.000Z",
      "user": {
        "id": 7,
        "email": "stamm_gwen@olson-keeling.biz",
        "full_name": "Gwen Stamm",
        "first_name": "Gwen",
        "last_name": "Stamm",
        "current_login_at": "2020-08-10T21:10:37.000Z",
        "last_login_at": "2020-08-09T22:10:37.000Z",
        "last_request_at": "2020-08-10T22:05:37.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The unique identifier for this Comment record.
text
The text content of the Comment.
created_at
An ISO-8601 timestamp representing the time that the Comment was made.
user
The data for the user that submitted the Comment.

Adding a comment to an alert

Add a comment to a specified Alert. If the Alert was not previously acknowledged, this action will also acknowledge the alert and mark the commenter as the acknowledger.

Request

POST /api/rest/alerts/7/comments HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "comment": {
    "text": "Magni sit dolores. Officia deserunt commodi. Ut voluptatem sed."
  }
}

Endpoint

POST /api/rest/alerts/:alert_id/comments

Parameters

Name Description
comment[text] The text content for the new Comment.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "id": 5,
    "text": "Magni sit dolores. Officia deserunt commodi. Ut voluptatem sed.",
    "created_at": "2020-08-10T22:10:37.000Z",
    "user": {
      "id": 8,
      "email": "satterfield_ira@frami-ruecker.biz",
      "full_name": "Ira Satterfield",
      "first_name": "Ira",
      "last_name": "Satterfield",
      "current_login_at": "2020-08-10T21:10:37.000Z",
      "last_login_at": "2020-08-09T22:10:37.000Z",
      "last_request_at": "2020-08-10T22:05:37.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    }
  }
}

Fields

Name Description
id
The unique identifier for the new Comment record.
text
The text content of the Comment.
created_at
An ISO-8601 timestamp representing the time that the Comment was made.
user
The data for the user that submitted the Comment.

Channels

View the channels reporting for the devices on your account. Each Channel record represents a single stream of data coming in from a sensor plugged in to one of your environmental loggers. One sensor can potentially report multiple Channels’ worth of data to DicksonOne.

Fetching channel data

Readings data for DicksonOne is served out of a separate Datapoint Service. When you fetch information for a channel, the response includes the URLs necessary to fetch the data for that channel.

All readings data is normalized to a single unit for storage purposes (e.g., all temperature readings are stored in Fahrenheit). When you view your data in exports, reports, or the DicksonOne interface, we perform a conversion from the stored unit to the display unit configured for your device. If you’re building a custom integration and want to see the readings values in a different unit, you’ll need to convert the raw readings data yourself.

Summary data

GET https://dps.dicksonone.com/datapoints/036390d0-f790-4cf6-b903-cc0ee63f49b7/1566364361/1566450761/summary HTTP/1.1

The summary_url for a channel gives a full summary of the data for the channel over its reporting lifetime.

Summary response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "summary":{
    "count": 289,
    "min": 13.9,
    "max": 15.1,
    "avg": 14.5764705882353,
    "mkt": 14.5800856751846,
    "min_ts": 1566385361,
    "max_ts": 1566447761,
    "unit":"f"
  }
}

Fields

Name Description
count The total number of readings submitted for the channel.
min The minimum reading value recorded for the channel.
min_ts An integer epoch timestamp representing the time of the minimum reading value.
max The maximum reading value recorded for the channel.
max_ts An integer epoch timestamp representing the time of the maximum reading value.
avg The average reading value recorded for the channel.
mkt An estimated Mean Kinetic Temperature for the channel. This is included in every summary, but only valid for Temperature channels.
unit The unit in which the readings are stored.

Readings data

GET https://dps.dicksonone.com/datapoints/036390d0-f790-4cf6-b903-cc0ee63f49b7/1566364361/1566365561 HTTP/1.1

The readings_urls for a channel lists a series of URLs for segments of data. Fetching the data at these URLs will yield all of the readings that have been recorded for the channel over its reporting lifetime.

Readings response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "records":[
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364361, "value": 14.5, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364661, "value": 14.6, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364961, "value": 14.8, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566365261, "value": 14.9, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566365561, "value": 14.5, "unit": "f"}
  ]
}

Fields

Name Description
channel A unique identifier used to store the readings for the channel.
ts An integer epoch timestamp representing the time that the reading was recorded.
value The reading value that was recorded by the logger.
unit The unit in which the reading is stored.

Listing account channels

Retrieve a list of all channels reporting for devices belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/channels HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 4,
      "name": "Temperature CH:4",
      "type": "Temperature",
      "unit": "fahrenheit",
      "first_datapoint_at": "2020-07-13T22:10:37.000Z",
      "last_datapoint_at": "2020-08-10T21:59:37.000Z"
    },
    {
      "id": 5,
      "name": "Relative Humidity CH:5",
      "type": "RelativeHumidity",
      "unit": "rh",
      "first_datapoint_at": "2020-07-20T22:10:37.000Z",
      "last_datapoint_at": "2020-08-10T21:55:37.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The channel's unique identifier.
name
The channel's name.
type
The type of channel, e.g., Temperature or RelativeHumidity.
unit
The unit for readings reported to the channel, e.g., Fahrenheit or Celsius.
first_datapoint_at
The ISO-8601 timestamp of the first reading submitted to the channel.
last_datapoint_at
The ISO-8601 timestamp of the most recent reading submitted to the channel.

Listing channels by device

Retrieve a list of the channels reporting for a specific device. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/devices/180238386445495629/channels HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/devices/:token/channels

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 6,
      "name": "Temperature CH:6",
      "type": "Temperature",
      "unit": "fahrenheit",
      "first_datapoint_at": "2020-07-06T22:10:37.000Z",
      "last_datapoint_at": "2020-08-10T22:09:37.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The channel's unique identifier.
name
The channel's name.
type
The type of channel, e.g., Temperature or RelativeHumidity.
unit
The unit for readings reported to the channel, e.g., Fahrenheit or Celsius.
first_datapoint_at
The ISO-8601 timestamp of the first reading submitted to the channel.
last_datapoint_at
The ISO-8601 timestamp of the most recent reading submitted to the channel.

Fetching a specific channel

By requesting details for a single channel, you can see more information, including URLs from which you can fetch readings and summary data for the device.

Request

GET /api/rest/channels/7?readings[after]=2020-08-05T22%3A10%3A38Z&readings[before]=2020-08-06T22%3A10%3A38Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels/:id

Parameters

Name Description
readings[after] An ISO-8601 timestamp. Summary and readings URLs will reflect readings captured after this time.
readings[before] An ISO-8601 timestamp. Summary and readings URLs will reflect readings captured prior to this time.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "id": 7,
    "name": "Differential Pressure CH:7",
    "type": "DifferentialPressure",
    "unit": "inches_h2o",
    "first_datapoint_at": "2020-07-20T22:10:38.000Z",
    "last_datapoint_at": "2020-08-10T21:44:38.000Z",
    "summary_url": "https://dps.dicksonone.com/datapoints/45761a1d-0882-416b-8eaa-3b4e67bdaa04/1596665438/1596751838/summary",
    "readings_urls": [
      "https://dps.dicksonone.com/datapoints/45761a1d-0882-416b-8eaa-3b4e67bdaa04/1596665438/1596751838"
    ]
  }
}

Fields

Name Description
id
The channel's unique identifier.
name
The channel's name.
type
The type of channel, e.g., Temperature or RelativeHumidity.
unit
The unit for readings reported to the channel, e.g., Fahrenheit or Celsius.
first_datapoint_at
The ISO-8601 timestamp of the first reading submitted to the channel.
last_datapoint_at
The ISO-8601 timestamp of the most recent reading submitted to the channel.
summary_url
A URL from which to fetch a summary of the recent readings data for the channel.
readings_urls
A list of URLs from which to fetch readings data.

Listing annotations for a channel

Retrieve a list of all annotations added to a specific channel. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/channels/8/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels/:channel_id/annotations

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 1,
      "content": "Expedita in ipsa. Non et sequi.",
      "at": "2020-07-10T22:10:38.000Z",
      "user": {
        "id": 13,
        "email": "hilll.samira@fritsch.name",
        "full_name": "Samira Hilll",
        "first_name": "Samira",
        "last_name": "Hilll",
        "current_login_at": "2020-08-10T21:10:38.000Z",
        "last_login_at": "2020-08-09T22:10:38.000Z",
        "last_request_at": "2020-08-10T22:05:38.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    },
    {
      "id": 2,
      "content": "Sit culpa qui. Aliquid omnis explicabo.",
      "at": "2020-07-27T22:10:38.000Z",
      "user": {
        "id": 14,
        "email": "camellia.hoppe@hamill.com",
        "full_name": "Camellia Hoppe",
        "first_name": "Camellia",
        "last_name": "Hoppe",
        "current_login_at": "2020-08-10T21:10:38.000Z",
        "last_login_at": "2020-08-09T22:10:38.000Z",
        "last_request_at": "2020-08-10T22:05:38.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The annotation's unique identifier.
content
The text content of the annotation.
at
The ISO-8601 timestamp for the annotation's place on the channel's timeline.
user
The data for the user that added the annotation.

Listing filtered annotations

Retrieve a list of annotations for the channel matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/channels/11/annotations?search[after]=2020-07-06T22%3A10%3A39Z&search[before]=2020-07-20T22%3A10%3A39Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels/:channel_id/annotations

Parameters

Name Description
search[after] An ISO-8601 timestamp. Results will be filtered to annotations added after this time.
search[before] An ISO-8601 timestamp. Results will be filtered to annotations added prior to this time.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 3,
      "content": "Quo ullam nihil. Quibusdam officia eum.",
      "at": "2020-07-10T22:10:39.000Z",
      "user": {
        "id": 16,
        "email": "wehner_roman@wuckert.io",
        "full_name": "Roman Wehner",
        "first_name": "Roman",
        "last_name": "Wehner",
        "current_login_at": "2020-08-10T21:10:39.000Z",
        "last_login_at": "2020-08-09T22:10:39.000Z",
        "last_request_at": "2020-08-10T22:05:39.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The annotation's unique identifier.
content
The text content of the annotation.
at
The ISO-8601 timestamp for the annotation's place on the channel's timeline.
user
The data for the user that added the annotation.

Adding a channel annotation

Add an annotation to the specified channel, at the specified time. Any added annotations will show up when the relevant time period is rendered on a Device Overview graph.

Request

POST /api/rest/channels/14/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "annotation": {
    "content": "Quae sed facilis. Laborum est similique. Aut sit velit.",
    "at": "2020-08-03T22:10:39Z"
  }
}

Endpoint

POST /api/rest/channels/:channel_id/annotations

Parameters

Name Description
annotation[content] The text content to set for the new annotation.
annotation[at] An ISO-8601 timestamp for the time relevant to the annotation.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "id": 5,
    "content": "Quae sed facilis. Laborum est similique. Aut sit velit.",
    "at": "2020-08-03T22:10:39.000Z",
    "user": {
      "id": 18,
      "email": "langosh_alexandria@goodwin.io",
      "full_name": "Alexandria Langosh",
      "first_name": "Alexandria",
      "last_name": "Langosh",
      "current_login_at": "2020-08-10T21:10:39.000Z",
      "last_login_at": "2020-08-09T22:10:39.000Z",
      "last_request_at": "2020-08-10T22:05:39.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    }
  }
}

Fields

Name Description
id
The new annotation's unique identifier.
content
The text content of the new annotation.
at
The ISO-8601 timestamp for the new annotation's place on the channel's timeline.
user
The data for the user that added the annotation.

Updating a channel annotation

Update the specified annotation with new content or a modified timestamp.

Request

PATCH /api/rest/channels/15/annotations/6 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "annotation": {
    "content": "Ducimus enim consectetur. Molestiae nihil quas. Voluptatem esse ut."
  }
}

Endpoint

PATCH /api/rest/channels/:channel_id/annotations/:id

Parameters

Name Description
annotation[content] The new text content to set for the new annotation.
annotation[at] An updated ISO-8601 timestamp for the annotation.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "id": 6,
    "content": "Ducimus enim consectetur. Molestiae nihil quas. Voluptatem esse ut.",
    "at": "2020-08-10T22:10:40.000Z",
    "user": {
      "id": 20,
      "email": "manuel.jerde@beahan-beatty.name",
      "full_name": "Manuel Jerde",
      "first_name": "Manuel",
      "last_name": "Jerde",
      "current_login_at": "2020-08-10T21:10:40.000Z",
      "last_login_at": "2020-08-09T22:10:40.000Z",
      "last_request_at": "2020-08-10T22:05:40.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": null
    }
  }
}

Fields

Name Description
id
The annotation's unique identifier.
content
The updated text content of the annotation.
at
The updated ISO-8601 timestamp for the annotation.
user
The data for the user that added the annotation.

Removing a channel annotation

Delete the specified annotation.

Request

DELETE /api/rest/channels/17/annotations/7 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

DELETE /api/rest/channels/:channel_id/annotations/:id

Devices

View the devices configured for your account. Each Device record represents the current status of a particular environmental logger. Instead of integer IDs, Devices are thus accessed using a string token, which is maintained across device replacements.

Listing account devices

Retrieve a list of all devices belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/devices HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/devices

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "name": "Paper shredder 17",
      "token": "145854325589985701",
      "sku": "B000MLA1UQ",
      "serial": "416cd671663e8139",
      "is_replaced": false
    },
    {
      "name": "Futon dryer 18",
      "token": "743307548888823787",
      "sku": "B000B7CDX4",
      "serial": "585af57bb8027432",
      "is_replaced": false
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
token
The device's unique identifier. This value is maintained across device replacements.
name
The device's name.
sku
The device's model/SKU.
serial
The device's serial number.

Listing replaced devices

Retrieve a list of all devices belonging to your account, including older device serials that have been replaced. This list is paginated.

Request

GET /api/rest/devices?search[include_replacements]=true HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/devices

Parameters

Name Description
search[include_replacements] A boolean. Results will be expanded to include replaced devices if true. Defaults to false.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "name": "Solar water heater 19",
      "token": "957913688369990190",
      "sku": "B0002TJ4JM",
      "serial": "1733b99676541421",
      "is_replaced": false
    },
    {
      "name": "Water cooker 20",
      "token": "247974666660174956",
      "sku": "B000IATH6K",
      "serial": "46c639b192993602",
      "is_replaced": false
    },
    {
      "name": "Sump pump 21",
      "token": "957913688369990190",
      "sku": "B000A2NZFK",
      "serial": "ec2275fcae0debd5",
      "is_replaced": true
    },
    {
      "name": "Paper shredder 22",
      "token": "957913688369990190",
      "sku": "B00097DN12",
      "serial": "4b03f297bf22eb9f",
      "is_replaced": true
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 4,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
token
The device's unique identifier. This value is maintained across device replacements.
name
The device's name.
sku
The device's model/SKU.
serial
The device's serial number.
is_replaced
A boolean indicating whether or not the device has been replaced.

Listing devices by location

Retrieve a list of the devices attached to a specific location. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/locations/25/devices HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/locations/:location_id/devices

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "name": "Steam mop 23",
      "token": "841571473027972049",
      "sku": "B000Q6Y34W",
      "serial": "524380f5eb2fc34c",
      "is_replaced": false
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
token
The device's unique identifier. This value is maintained across device replacements.
name
The device's name.
sku
The device's model/SKU.
serial
The device's serial number.

Fetching a specific device

By requesting details for a single device, you can see more information, including the channel metadata for that device.

Request

GET /api/rest/devices/956417932903350777 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/devices/:token

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "name": "Tie press 24",
    "token": "956417932903350777",
    "sku": "B000PIIXBA",
    "serial": "ee65da5297e4fa25",
    "is_replaced": false,
    "channels": [
      {
        "id": 19,
        "name": "Temperature CH:19",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2020-07-13T22:10:41.000Z",
        "last_datapoint_at": "2020-08-10T21:51:41.000Z"
      },
      {
        "id": 20,
        "name": "Temperature CH:20",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2020-08-03T22:10:41.000Z",
        "last_datapoint_at": "2020-08-10T21:57:41.000Z"
      }
    ]
  }
}

Fields

Name Description
token
The device's unique identifier. This value is maintained across device replacements.
name
The device's name.
sku
The device's model/SKU.
serial
The device's serial number.
channels
A list of channels reporting for the device.

Events

View the event logs for your account. Each record represents an event that took place on the account. Events can take multiple formats.

Supported event types

There are multiple types of activity captured in the event logs for an account. The type of activity is exposed in the type field in each response, and the list of events can be filtered by supplying one of these values for the search[type] parameter.

Name Description
Account Activity tied to registration of an account, or settings updates.
Alarm Activity tied to the creation, update, or triggering of alarms.
Annotation Activity tied to the creation, update, or removal of channel annotations.
ApiKey Activity tied to the generation and revocation of API keys.
Contact Activity tied to the creation or modification of user/contact information.
Device Activity tied to the registration of a device or update of device settings.
EscalationPolicy Activity tied to the creation or update of notification policies on the account.
Export Activity tied to generation of account or device exports for the account.
Location Activity tied to the management of Locations on the account.
Report Activity tied to the creation, update, or generation of a report.
Subscription Activity tied to redemption or update of a Subscription for the account.
TemplateGroup Activity tied to the creation or update of an alarm template.

Listing all events

Retrieve a list of all events for your account, in reverse chronological order. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/events HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/events

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 7,
      "message": "Device setting(s) updated:\n  - Temperature Display Unit changed to \"°C\" from \"°F\"",
      "created_at": "2020-08-10T21:40:42.000Z",
      "type": "Device",
      "user": {
        "id": 27,
        "email": "troy.deckow@glover.info",
        "full_name": "Troy Deckow",
        "first_name": "Troy",
        "last_name": "Deckow",
        "current_login_at": "2020-08-10T21:10:42.000Z",
        "last_login_at": "2020-08-09T22:10:42.000Z",
        "last_request_at": "2020-08-10T22:05:42.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": {
        "name": "Clothes dryer 25",
        "token": "175526956932789694",
        "sku": "B000A6LR6K",
        "serial": "3bd042aec070be8c",
        "is_replaced": false
      },
      "location": {
        "id": 27,
        "name": "Dicki, Reinger and Fahey",
        "sublocation_ids": [

        ]
      }
    },
    {
      "id": 6,
      "message": "Logged In",
      "created_at": "2020-08-10T21:20:42.000Z",
      "type": "User",
      "user": {
        "id": 27,
        "email": "troy.deckow@glover.info",
        "full_name": "Troy Deckow",
        "first_name": "Troy",
        "last_name": "Deckow",
        "current_login_at": "2020-08-10T21:10:42.000Z",
        "last_login_at": "2020-08-09T22:10:42.000Z",
        "last_request_at": "2020-08-10T22:05:42.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    },
    {
      "id": 5,
      "message": "Failed Login Attempt",
      "created_at": "2020-08-10T21:10:42.000Z",
      "type": "User",
      "user": {
        "id": 27,
        "email": "troy.deckow@glover.info",
        "full_name": "Troy Deckow",
        "first_name": "Troy",
        "last_name": "Deckow",
        "current_login_at": "2020-08-10T21:10:42.000Z",
        "last_login_at": "2020-08-09T22:10:42.000Z",
        "last_request_at": "2020-08-10T22:05:42.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The unique identifier for this Event record.
message
A description of the event that took place.
type
The type of event.
created_at
An ISO-8601 timestamp representing the time that the event took place.
user
The data for the user responsible for this event.
device
The data for the device related to this event.
location
The data for the location related to this event.

Listing filtered events

Retrieve a list of all events for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/events?search[user_ids][]=28&search[type][]=Contact HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/events

Parameters

Name Description
search[tokens] A list of tokens for the devices to which you want to restrict your search.
search[user_ids] A list of IDs for the users to which you want to restrict your search.
search[location_ids] A list of IDs for the locations containing devices to which you want to restrict your search.
search[type] The type(s) of event to which you want to restrict your search. See above for acceptable values.
search[after] An ISO-8601 timestamp. Results will be filtered to events that took place after this time.
search[before] An ISO-8601 timestamp. Results will be filtered to events that took place prior to this time.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 9,
      "message": "Logged In",
      "created_at": "2020-08-10T21:20:42.000Z",
      "type": "User",
      "user": {
        "id": 28,
        "email": "dare.forest@strosin.name",
        "full_name": "Forest Dare",
        "first_name": "Forest",
        "last_name": "Dare",
        "current_login_at": "2020-08-10T21:10:42.000Z",
        "last_login_at": "2020-08-09T22:10:42.000Z",
        "last_request_at": "2020-08-10T22:05:42.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    },
    {
      "id": 8,
      "message": "Failed Login Attempt",
      "created_at": "2020-08-10T21:10:42.000Z",
      "type": "User",
      "user": {
        "id": 28,
        "email": "dare.forest@strosin.name",
        "full_name": "Forest Dare",
        "first_name": "Forest",
        "last_name": "Dare",
        "current_login_at": "2020-08-10T21:10:42.000Z",
        "last_login_at": "2020-08-09T22:10:42.000Z",
        "last_request_at": "2020-08-10T22:05:42.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The unique identifier for this Event record.
message
A description of the event that took place.
type
The type of event.
created_at
An ISO-8601 timestamp representing the time that the event took place.
user
The data for the user responsible for this event.
device
The data for the device related to this event.
location
The data for the location related to this event.

Searching for an invalid event type

Attempting to filter the list of results with an unsupported search[type] (see above for the list of supported types) will result in a 400 error.

Request

GET /api/rest/events?search[type]=Other HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/events

Parameters

Name Description
search[tokens] A list of tokens for the devices to which you want to restrict your search.
search[user_ids] A list of IDs for the users to which you want to restrict your search.
search[location_ids] A list of IDs for the locations containing devices to which you want to restrict your search.
search[type] The type(s) of event to which you want to restrict your search. See above for acceptable values.
search[after] An ISO-8601 timestamp. Results will be filtered to events that took place after this time.
search[before] An ISO-8601 timestamp. Results will be filtered to events that took place prior to this time.

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "errors": [
    "The requested type (Other) is not supported."
  ]
}

Fields

Name Description
errors
A description of the error that prevented the search.

Locations

View the location hierarchy for your account. Locations are structured with one root location attached directly to your account, and potentially multiple sublocations for every location.

[
  {"id": 1, "name": "Account (Root)", "sublocation_ids": [2]},
  {"id": 2, "name": "Warehouse", "sublocation_ids": []}
]

The following list might represent a simple location hierarchy for an organization monitoring a single warehouse:

In order to reconstruct the full location hierarchy from the response, you can start with the root location element (the first element in the list), and follow the sublocation_ids for that location, nesting the locations with the specified IDs beneath the root. You can then repeat this process for each sublocation, stopping when you reach a location with no sublocation_ids. Let’s look at an example for a slightly more complicated organization.

[
  {"id": 1, "name": "Account (Root)", "sublocation_ids": [2]},
  {"id": 2, "name": "Region", "sublocation_ids": [3, 4]},
  {"id": 3, "name": "Office #1", "sublocation_ids": []},
  {"id": 4, "name": "Office #2", "sublocation_ids": []}
]

The following list might represent an organization with a deeper location hierarchy, due to a high density of sensors, or sensors used for multiple purposes or applications throughout the organization:

As above, you can follow the sublocation_ids starting with the root location to reconstruct the proper hierarchy for your organization.

Listing account locations

Retrieve a list of locations belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/locations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/locations

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 30,
      "name": "Purdy, Kozey and Parker",
      "sublocation_ids": [
        31,
        32
      ]
    },
    {
      "id": 31,
      "name": "Ensuite Bathroom 2",
      "sublocation_ids": [

      ]
    },
    {
      "id": 32,
      "name": "Loft 3",
      "sublocation_ids": [

      ]
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The locations's unique identifier.
name
The location's name.
sublocation_ids
A list of IDs for the locations nested beneath this one.

Fetching a specific location

By requesting details for a single location, you can see more information, including the device metadata for that location.

Request

GET /api/rest/locations/33 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/locations/:id

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "id": 33,
    "name": "Stracke LLC",
    "sublocation_ids": [

    ],
    "devices": [
      {
        "name": "Micathermic heater 28",
        "token": "193556464197964713",
        "sku": "B0000VF9C8",
        "serial": "b0416ea3077bd0ed",
        "is_replaced": false
      },
      {
        "name": "Sump pump 29",
        "token": "277522012029384492",
        "sku": "B000HW20EA",
        "serial": "7ae7a6e8b390fe39",
        "is_replaced": false
      }
    ]
  }
}

Fields

Name Description
id
The location's unique identifier.
name
The location's name.
devices
A list of devices attached to this location.
sublocation_ids
A list of IDs for the locations nested beneath this one.

Users

View and update the users that have access to your account.

Listing account users

Retrieve a list of users belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/users HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/users

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "id": 32,
      "email": "willard.hane@langosh.biz",
      "full_name": "Willard Hane",
      "first_name": "Willard",
      "last_name": "Hane",
      "current_login_at": "2020-08-10T21:10:43.000Z",
      "last_login_at": "2020-08-09T22:10:43.000Z",
      "last_request_at": "2020-08-10T22:05:43.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    },
    {
      "id": 33,
      "email": "collier.loise@wiegand-reichert.info",
      "full_name": "Loise Collier",
      "first_name": "Loise",
      "last_name": "Collier",
      "current_login_at": "2020-08-10T21:10:43.000Z",
      "last_login_at": "2020-08-03T22:10:43.000Z",
      "last_request_at": "2020-08-10T22:05:43.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": null
    },
    {
      "id": 34,
      "email": "jerde_millie@johns.info",
      "full_name": "Millie Jerde",
      "first_name": "Millie",
      "last_name": "Jerde",
      "current_login_at": "2020-08-10T21:10:43.000Z",
      "last_login_at": "2020-08-03T22:10:43.000Z",
      "last_request_at": "2020-08-10T22:05:43.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": null
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Name Description
id
The user's unique identifier.
email
The user's email address.
full_name
The user's full name.
first_name
The user's first name.
last_name
The user's last name.
current_login_at
The timestamp of the user's current login to DicksonOne.
last_login_at
The timestamp of the user's prior login to DicksonOne.
last_request_at
The timestamp of the user's most recent request to DicksonOne.
time_zone
The user's configured time zone.
role
The user's assigned role in DicksonOne.

Updating an existing user

The User’s contact attributes can be updated.

Request

PATCH /api/rest/users/36 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "user": {
    "email": "alessandra.vandervort@lesch.biz",
    "first_name": "Alessandra",
    "last_name": "Vandervort"
  }
}

Endpoint

PATCH /api/rest/users/:id

Parameters

Name Description
user[email] The new email address for the user.
user[first_name] The new first name for the user.
user[last_name] The new last name for the user.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "id": 36,
    "email": "alessandra.vandervort@lesch.biz",
    "full_name": "Alessandra Vandervort",
    "first_name": "Alessandra",
    "last_name": "Vandervort",
    "current_login_at": "2020-08-10T21:10:44.000Z",
    "last_login_at": "2020-08-08T22:10:43.000Z",
    "last_request_at": "2020-08-10T22:05:44.000Z",
    "time_zone": "Central Time (US & Canada)",
    "role": null
  }
}

Fields

Name Description
id
The user's unique identifier.
email
The user's updated email address.
first_name
The user's updated first name.
last_name
The user's updated last name.

Updating with invalid attributes

Email addresses must be properly formatted, and no blank values are allowed. Attempting to set any of a user’s attributes to an invalid value will result in an error response.

Request

PATCH /api/rest/users/38 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "user": {
    "email": "not.an.email",
    "first_name": ""
  }
}

Endpoint

PATCH /api/rest/users/:id

Parameters

Name Description
user[email] The new email address for the user.
user[first_name] The new first name for the user.
user[last_name] The new last name for the user.

Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{
  "errors": [
    "Email should look like an email address.",
    "First name can't be blank"
  ]
}

Fields

Name Description
errors
A list of the errors that prevented the record from being updated.