In 2 minutes you will be logged out due to inactivity.

PLEASE NOTE: This code is provided “AS IS” without warranty of any kind expressed or implied. Dickson does not provide support for custom integrations.

PLEASE NOTE: The V2 API will be deprecated at some point in the future, so we encourage you to move your integration to the new REST API.

Developers

Getting Started with the v2 API

The V2 API provides a RESTful interface to the DicksonOne data service.

API Basics

Base API URL

http://www.dicksonone.com/api/v2

Accounts

You must Sign Up for an account before you can authenticate with the API.

Format

All requests and responses should be JSON encoded.

Authentication

In order to use the DicksonOne API, you must first authenticate using your email and password. Upon successful authentication, you will be provided with an API Token to be sent along in the header of each subsequent API request.

Resource URL

POST /sessions

Request Body
{
  "credentials":
    {
      "email": "YOUR_EMAIL",
      "password": "YOUR_PASSWORD"
    }
}
Response
HTTP 200
{ "token": "YOUR_API_TOKEN" }
Using the API Token

For each API request, send along your token in the X-API-KEY header:

"X-API-KEY:YOUR_API_TOKEN"

User

Details for the currently logged in user can be viewed and updated.

Get User

GET /user

Response
HTTP 200
{
  "id": 1,
  "email": "user_email@gmail.com",
  "full_name": "Anon User",
  "first_name": "Anon",
  "last_name": "User",
  "last_login_at": null,
  "phone": null,
  "time_zone": "Central Time (US & Canada)",
  "admin": true,
  "manager": true
}

Update User

PUT /user

Request Body

{ "email": "new_email@gmail.com" }

Successful Response
HTTP 204
Error Response
HTTP 422
{
  errors: {
    email: [
      "should look like an email address."
    ]
  }
}

Account

Get Account Information

GET /account

Response
HTTP 200
{
  "id": 1,
  "name": "Account 1",
  "devices": 5,
  "users": 3,
  "subscription":
    {
      "name": "Enterprise+",
      "expiration": "2013-12-04T23:59:59Z",
      "sku": "SAS1H",
      "max_devices": null,
      "sample_limit_seconds": 300,
      "max_storage_days": null,
      "alarms_enabled": false
    }
}

Null values for max_devices and max_storage_days represent "unlimited"

Locations

Listing All Locations

GET /locations

Response
HTTP 200
[
   {
      "id":1,
      "name":"newco",
      "num_locations":1,
      "num_devices":1,
      "locations":[
         { "id":2, "name": "fridge", ... },
      ],
      "devices":[
         { "token":"186424100012791312", ...  },
         { "token":"186424100012791312", ...  }
      ]
   },
   {
      "id":2,
      "name":"fridge",
      "num_locations":0,
      "num_devices":0,
      "locations":[],
      "devices":[]
   }
]

If the user does not have read access to the account's root location, the location will not have an ID or any devices, but will contain a list of the locations the user does have access to.

GET /locations/home

Response
HTTP 200

If the user has read access to account's root location, the user will see the full information of Location#show

{
  "id": null,
  "name": "Home",
  "num_devices": 0,
  "num_locations": 2,
  "locations": [
    {
      "id": 147,
      "name": "Location 1",
      "num_devices": 1,
      "num_locations": 0
    },
    {
      "id": 148,
      "name": "Location 2",
      "num_devices": 2,
      "num_locations": 1
    }
  ],
  "devices": []
}

If the user has read access to account's root location, the user will see the full information of Location#show

See Location#show

Viewing a Single Location

GET /locations/:id

Response
HTTP 200
{
  "id": 1,
  "name": "Root Location",
  "num_devices": 5,
  "num_locations": 2,
  "locations": [
    {
      "id": 147,
      "name": "Test Location",
      "num_devices": 1,
      "num_locations": 0
    },
    {
      "id": 148,
      "name": "Test Location 2",
      "num_devices": 0,
      "num_locations": 0
    }
  ],
  "devices": [
    {
      "token": 112233,
      "name": "Dual Temperature Device",
      "model_number": "12345",
      "serial": "12345",
      "channels": [
        {
          "channel": 1,
          "name": "Temperature",
          "color": "aa4643",
          "recent_reading": {
            "at": "2013-10-17T16:51:55Z",
            "timestamp": 1382028715,
            "value": 174.5,
            "value_with_unit": "174.5°F"
          }
        },
        {
          "channel": 2,
          "name": "Temperature",
          "color": "aa4642",
          "recent_reading": {
            "at": "2013-10-17T16:51:55Z",
            "timestamp": 1382028715,
            "value": 119.5,
            "value_with_unit": "119.5°F"
          }
        },
        {
          "channel": 9,
          "name": "Battery",
          "color": "aa4641",
          "recent_reading": {
            "at": "2013-10-17T16:51:55Z",
            "timestamp": 1382028715,
            "value": 4.0,
            "value_with_unit": "Battery"
          }
        }
      ]
    },
    ...
  ]
}

Devices

Listing All Devices

GET /devices

Response
HTTP 200
[
  {
     "token":"186424100012791312",
     "name":"tempone",
     "battery":null,
     "model_number":"ENH20",
     "serial_number":"12223143",
     "channels":[
        { "channel":1, ... },
        { "channel":2, ... },
        { "channel":99, ... }
     ]
  },
  {
     "token":"186424100012791313",
     "name":"temptwo",
     "battery":null,
     "model_number":"ENH20",
     "serial_number":"12223144",
     "channels":[
        { "channel":1, ... },
        { "channel":2, ... },
        { "channel":99, ... }
     ]
  }
]
Viewing a Single Device

GET /devices/:token

Response
HTTP 200
 {
    "token":"186424100012791312",
    "name":"tempone",
    "battery":null,
    "model_number":"ENH20",
    "serial_number":"12223143",
    "channels":[
       {
          "channel":1,
          "name":"Temperature",
          "channel_unit":"f",
          "color": "aa4643",
          "display_unit":null,
          "value":82.3,
          "value_at":1363921528000,
          "min":74.9,
          "min_at":1363920295000,
          "max":82.7,
          "max_at":1363921378000
       },
       { "channel":2, ... },
       { "channel":99, ... }
    ]
 }

Device Channels and Datapoints

Resource URL

GET /devices/:token/channels/:channel

URL Parameters
resolution
the time resolution (in seconds) for the datapoint set
start_at
the time for the earliest datapoint in the time range
end_at
the time for the last datapoint in the time range
Response
HTTP 200
{
  "device_token":"186424100012791312",
  "channel":1,
  "name":"Temperature",
  "channel_unit":"f",
  "resolution":1,
  "datapoints":[
     {
        "at":1363920265000,
        "value":75.0,
        "min":null,
        "max":null
     }
  ]
}

Annotations

Creating an Annotation

Resource URL

POST /devices/:token/annotations

Request Body
{
  "annotation": {
    "at": "2013-12-27T17:01:45Z",
    "channel": "1",
    "content": "new annotation"
  }
}
"at" can be either a UNIX timestamp or ISO-8601 formatted string
Successful Response
HTTP 200
{
  "id": 12345,
  "channel": 1,
  "content": "new annotation",
  "at": "2013-12-27T17:05:01Z"
}
Error Response
HTTP 422
{
  "errors": {
    "content": [ "can't be blank" ]
  }
}

Updating an Annotation

Resource URL

PUT /devices/:token/annotations/:id

Request Body
{
  "annotation": {
    "content": "new annotation"
  }
}
Successful Response
HTTP 200
{
  "id": 12345,
  "channel": 1,
  "content": "new annotation",
  "at": "2013-12-27T17:05:01Z"
}
Error Response
HTTP 422
{
  "errors": {
    "content": [ "can't be blank" ]
  }
}

Deleting an Annotation

Resource URL

DELETE /devices/:token/annotations/:id

Successful Response
HTTP 204

Alarm Events

Listing All Alarm Events

Resource URL

GET /alarm_events

URL Parameters
limit
how many alarm events to return
offset
the offset to start retreiving results
Response
[
  {
    "id": 48,
    "alarm_id": 300,
    "token": 123,
    "device_name": "Device",
    "channel": 1,
    "channel_name": "Temperature",
    "condition": "0",
    "value": 5,
    "unit": "min",
    "created_at": "2013-10-22T17:52:52Z",
    "returned_to_normal_at": null,
    "acknowledger_first_name": "Test",
    "acknowledger_last_name": "User",
    "acknowledger_id": 123,
    "acknowledged_at": "2013-10-22T17:52:52Z",
    "text": "not reporting for 5.0 minutes",
    "current_datapoint": {
      "at": "2013-10-22T17:43:28Z",
      "value": "92.5°F"
    }
  }

...
]

Acknowledging an Alarm

PUT /alarm_events/:id/acknowledge

Request Body
{}

Successful Response
HTTP 200
{
  "id": 48,
  "alarm_id": 300,
  "token": 123,
  "device_name": "Device",
  "channel": 1,
  "channel_name": "Temperature",
  "condition": "0",
  "value": 5,
  "unit": "min",
  "created_at": "2013-10-22T17:52:52Z",
  "returned_to_normal_at": null,
  "acknowledger_first_name": "Test",
  "acknowledger_last_name": "User",
  "acknowledger_id": 123,
  "acknowledged_at": "2013-10-22T17:52:52Z",
  "text": "not reporting for 5.0 minutes",
  "current_datapoint": {
    "at": "2013-10-22T17:43:28Z",
    "value": "92.5°F"
  }
}
Error Response
HTTP 406
{
  "error": "The alarm was already acknowledged"
}

Viewing Comments On an Alarm

GET /alarm_events/:id/comments

Response
HTTP 200
[
  {
    "id": 1,
    "text": "This is a comment.",
    "created_at": "2013-10-30T14:26:19Z",
    "user_id": 1,
    "user_name": "Anon User"
  }
]
Commenting On an Alarm

POST /alarm_events/:id/comments

Request Body
{
  "comment": {
    "text": "This is a new comment."
  }
}

Successful Response
HTTP 200
{
  "id": 2,
  "text": "This is a new comment.",
  "created_at": "2013-10-30T14:34:04Z",
  "user_id": 2,
  "user_name": "Anon User2"
}
Error Response
HTTP 422
{
  "errors": {
    "text": [
      "can't be blank"
    ]
  }
}

Audit Logs (Events)

Listing Audit Logs

Resource URL

GET /audit_logs

URL Parameters
limit
How many events to return. Defaults to 50.
search[:token]
A single token or an array of device tokens
search[:user_id]
A single user id or array of user ids
search[type]
A single type or array of types. Valid options: Account, Alarm, Annotation, ApiKey, Contact, Device, EscalationPolicy, Export, Location, Report, Subscription, TemplateGroup
search[start_date], search[end_date]
Range of datetimes to search for. If start_date is blank, there is no minimum. If end_date is blank, there is no maximum.
Request
\/audit_logs?search[token]=584250303398082829&search[user_id]=123&search[type][]=Annotation&search[type][]=User
Response
[
  {
    "id": 6341,
    "message": "Annotation added channel:1, message:Test Annotation, time:11/06/2013 02:00:00 PM CST",
    "created_at": "2013-11-12T23:00:09Z",
    "user_id": 123,
    "first_name": "User",
    "last_name": "User",
    "device_token": 584250303398082829,
    "device_name": "Testing Device",
    "type": "Annotation"
  },

...
]

This code is provided "AS IS" without warranty of any kind expressed or implied. Dickson does not provide support for custom integrations. If you have general questions regarding the API or about creating a custom integration, please email support@dicksonone.com.