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 data loggers, 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"
          }
        }
      ]
    },
    ...
  ]
}

Data Loggers

Listing All Data Loggers

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 Data Logger

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, ... }
    ]
 }

Data Logger 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"
  }
}

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

Alerts

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 data logger 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, Calibration, Contact, Dashboard, Device, Equipment, EscalationPolicy, Export, Floorplan, 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.