Files Thru The Air API Guide

Transcription

1 Files Thru The Air API Guide Contents Part 1: Introduction... 4 Part 2: Connection / Use Examples... 5 Connecting to the API... 5 JQuery / JSON GET Example Get current readings for a device... 6 JQuery / JSON POST Example Update User Password... 7 Part 3: Common Objects... 8 user... 8 permissions... 8 location... 8 channel... 9 alarmsettings... 9 session... 9 unit device Part 4: Reference Locations.svc UserLocations LocationName Devices NewDevices Users.svc Login AccountSummary UpdatePassword UpdateDateTimeFormats UpdateGroupAlertFrequency UpdateUserPermissions UpdateUserLocations AccountUsers AddUser EditUser DeleteUser Favourites Page 1 of 156

2 AddToFavourites RemoveFromFavourites DevicesInAlarm Alarms Devices.svc Device AddDevice DeviceName UpdateDeviceName SampleRate UpdateSampleRate TransmissionPeriod UpdateTransmissionPeriod ChannelLabels UpdateChannelLabels Units UpdateUnits ProbeTypes UpdateProbeTypes AlarmSettings UpdateAlarmSettings AlertSettings UpdateAlertSettings DeviceLocation UpdateDeviceLocation AuditChecksEnabled UpdateAuditChecks ApplySettings ResetAlarm CurrentReadings Sessions SessionsByDate CurrentSession Events CloseEvent OpenEvent AddEventNote Page 2 of 156

3 AuditChecks AllDevicesSummary Sessions.svc SessionInfo Readings ReadingsRaw Events CloseEvent OpenEvent AddEventNote AuditChecks CreateSession... Error! Bookmark not defined. AddEvent... Error! Bookmark not defined. ImportReadings... Error! Bookmark not defined. Lookups.svc Units ProbeTypes SampleRates TransmissionPeriods AlarmDelays GroupAlertFrequencies DateFormats TimeFormats TimeZones AlertEvents Status Part 5: Change Log Page 3 of 156

4 Part 1: Introduction Files Thru The Air provides a complete API for developers to use within their own applications. The API is hosted on a secure server. SSL encryption is mandatory for all connections. The resources are REST compatible and are grouped into 5 services: Users, Locations, Devices, Sessions and Lookups. Every resource requires an APIToken. You must obtain a valid APIToken from Corintech prior to attempting to use the API. The current userguid will be checked in each resource to ensure that the logged in user has the required permissions to perform the update/retrieve the data requested. Users do not have to be logged in each time they access the API, but their GUID must be passed to every resource except those in the Lookups service (these do not access customer specific data). The userguid can be obtained from the Users.svc/Login resource. Various other parameters are required for the various resources. None of the parameters are optional and each will be checked for validity prior to the requested action being executed. Some connection / use examples are in Part 2, common objects are described in Part 3, the resources are listed in Part 4 and Part 5 contains the version history detailing all the updates. Page 4 of 156

5 Part 2: Connection / Use Examples Connecting to the API The 5 services are hosted at: Connections using any protocol other than https (such as http) will be rejected. Requests for data should use the GET method with parameters supplied in a query string whereas data submissions/updates should use the POST method with parameters supplied in a JSON object. Examples of each of these methods are on the next pages. Page 5 of 156

6 JQuery / JSON GET Example Get current readings for a device var MACAddress = "11:11:11:11:11:11"; var datetime; var channel1; var channel2; var channel3; var channel4; $.ajax( type: "GET", datatype: "json", contenttype: "application/json; charset=utf-8", url: " data: "APIToken= &UserGUID= &MACAddress=" + MACaddress + "&localtime=true", timeout: 5000, success: function (data) datetime = new Date(parseInt(data.datetime.substring(6))); channel1 = data.channels[0]; if (data.channels.length > 1) channel2 = data.channels[1]; if (data.channels.length > 2) channel3 = data.channels[2]; if (data.channels.length > 3) channel4 = data.channels[3]; error: function (xhr) if (xhr.status!= 500) alert("error: Could not connect to data service"); else alert("error: " + JSON.parse(xhr.responseText).Message); ); Page 6 of 156

7 JQuery / JSON POST Example Update User Password var newpassword = "P "; $.ajax( type: "POST", datatype: "json", contenttype: "application/json; charset=utf-8", url: " data: ' "APIToken":" ", "userguid":" ", "password":"' + newpassword + '" ', timeout: 5000, success: function (response) if (response) alert("password changed"); else alert("could not change password"); error: function (xhr) if (xhr.status!= 500) alert("error: Could not connect to data service"); else alert("error: " + JSON.parse(xhr.responseText).Message); ); Page 7 of 156

8 Part 3: Common Objects user user GUID name dateformat timeformat groupalertfrequency permissions Unique identifier for the user User s name User s preferred date format eg. dd/mm/yyyy User s preferred time format eg. HH:mm:ss Group alerts so that s are received at most once every x seconds Permissions object permissions permissions accountadministrator administrator managedevices viewdata exportdata dailysummaryofevents closeevents True/False user has account administrator permission True/False user has administrator permission True/False user has manage devices permission True/False user has view data permission True/False user has export data permission True/False user receives the daily summary of events True/False user can close events in the event log location location GUID name archived access timezone timezoneoffset sublocations Unique identifier for the location Name of the location True if the location is archived True if the selected user has access to this location TimeZone of location eg. GMT Standard Time Number of minutes from UTC Iteration of location object for sub locations within the tree Page 8 of 156

9 channel channel label Channel label eg. Temperature 1 typeid Channel type identifier eg. 1 type Channel type label eg. Temperature decimalplaces Number of decimal places to display readings in eg. 2 unit Unit object probetype Probe Type for channel null if no probe id Probe type identifier text Probe type label alarmsettings AlarmSettings object alarmsettings alarmsettings lowalarmon highalarmon lowalarmlevel highalarmlevel alarmtriggerdelay alarmhold True/False is low alarm enabled True/False is high alarm enabled Low alarm level eg. 1.5 Null if not set High alarm level eg Null if not set Delay before alarm is triggered in seconds True/False alarm hold is enabled session session GUID noofreadings firstreading lastreading MACAddress devicename timezone timezoneoffset samplerate channels Unique identifier for the session Number of readings in the session DateTime of the first reading DateTime of the last reading MAC Address of device Name of device Time zone of device s location Number of minutes from UTC Period between readings in seconds Collection of channel object Page 9 of 156

10 unit unit id symbol text Unit identifier Unit symbol eg. C Label for the unit eg. Celcius device device GUID MACaddress Unique identifier for the device Unique MAC Address of device name Device name eg. Fridge 2B type locationguid Device type eg. TP+ Unique identifier for device s location RSSI Device s WiFi signal level (0 5) permanentlypowered batterylevel inalarm SSID firmwareversion archived samplerate transmissionperiod lastreadingsreceived timezone timezoneoffset currentreadings datetime True/False device is permanently powered Device s battery level (1 5, 0 = critical, 11 = charging, 12 = full, 13 = battery error, 20 = permanently powered but disconnected, 21 = permanently powered and ok) Alarm state of device (0=none, 1=primary, 2=secondary, 3=both) SSID string of network device is communicating with Version string of device firmware True/False device is archived (not sending data to the cloud) Period between readings in seconds Period between data transmissions to the cloud in seconds DateTime of last readings received by cloud TimeZone of the location of the device Offset in minutes of device s timezone from UTC DateTime of readings channels Collection of formatted readings for each channel eg. 5.7 C, 35%RH received channels infavourites connectionlost auditchecksenabled DateTime of reading received by the cloud Collection of channel objects for each channel True/False device is in user s favourites True/False device is not currently transmitting to the cloud True/False audit checks are currently enabled for the device Page 10 of 156

11 Part 4: Reference Locations.svc The Locations service is for retrieving lists of locations and devices within a specified location. UserLocations LocationName Devices NewDevices Returns all locations for an account with indication whether the selected user has access to each one Returns the name of a location for a specified GUID Returns all the devices within a specified location Returns the devices within New Devices for the user s account Page 11 of 156

12 UserLocations UserLocations Service Locations.svc Returns all locations for an account with indication whether the selected user has access to each one Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid selecteduserguid includedisabledbranches Unique identifier for the logged in user Unique identifier for the selected user If true all locations will be returned, otherwise only those which the selected user has access to and parent branches thereof will be returned Returns GUID Unique identifier for the location name archived access timezone timezoneoffset sublocations GUID name archived access sublocations Name of the location True if the location is archived True if the selected user has access to this location TimeZone of location eg. GMT Standard Time Number of minutes from UTC Iteration of self for sub locations within the tree Unique identifier for the location Name of the location True if the location is archived True if the selected user has access to this location Iteration of self for sub locations within the tree Example GET /Locations.svc/UserLocations?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&selectedUserGUID=c3575a34-b372-11e3-9bd a0254 Data Returned "GUID":"a246c6fe-b35e-11e3-9bd a0254", "access":true, Page 12 of 156

13 "archived":false, "name":"test Api", "sublocations":[], "timezone": GMT Standard Time, "timezoneoffset":60 Page 13 of 156

14 LocationName LocationName Service Locations.svc Returns the name of a location for a specified GUID Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user locationguid Unique identifier for the selected location Returns Name of the location Example GET /Locations.svc/LocationName?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&locationGUID=a b35e-11e3-9bd a0254 Data Returned "New Devices" Page 14 of 156

15 Devices Devices Service Locations.svc Returns all devices within a specified location Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid selecteduserguid locationguid localtime includearchived Unique identifier for the logged in user Unique identifier for the selected user Unique identifier for the selected location If true returns reading datetime in timezone of device, otherwise UTC will be used If true archived devices will be included Returns Collection of device objects: [ GUID MACaddress Unique identifier for the device Unique MAC Address of device name Device name eg. Fridge 2B type locationguid Device type eg. TP+ Unique identifier for device s location RSSI Device s WiFi signal level (0 5) batterylevel inalarm SSID firmwareversion archived samplerate transmissionperiod lastreadingsreceived infavourites timezone timezoneoffset connectionlost Device s battery level (1 5, 11 = charging, 12 = full) Alarm state of device (0=none, 1=primary, 2=secondary, 3=both) SSID string of network device is communicating with Version string of device firmware True/False device is archived (not sending data to the cloud) Period between readings in seconds Period between data transmissions to the cloud in seconds DateTime of last readings received by cloud True/False device is in user s favourites TimeZone of the location of the device Offset in minutes of device s timezone from UTC True/False device is not currently transmitting to the cloud Page 15 of 156

16 ] currentreadings datetime channels received channels DateTime of readings Collection of formatted readings for each channel eg. 5.7 C, 35%RH DateTime of reading received by the cloud Collection of channel objects for each channel typeid Channel type identifier eg. 1 Type Channel type label eg. Temperature decimalplaces Number of decimal places to display readings in eg. 2 unit id symbol text probetype id text alarmsettings lowalarmon highalarmon lowalarmlevel highalarmlevel Unit object Unit identifier Unit symbol eg. C Label for the unit eg. Celcius Probe Type for channel null if no probe Probe type identifier Probe type label True/False is low alarm enabled True/False is high alarm enabled Low alarm level eg. 1.5 Null if not set High alarm level eg Null if not set alarmtriggerdelay Delay before alarm is triggered in seconds alarmhold True/False alarm hold is enabled Example GET /Locations.svc/Devices?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&locationGUID=a b35e-11e3-9bd a0254&localTime=true Data Returned [ "GUID":"9b2256f e ", "MACAddress":"98:8B:AD:00:00:64", "RSSI":5, "SSID":"bmc belkin", "archived":false, "batterylevel":4, "channels":[ "decimalplaces":1, "highalarmlevel":30, "lowalarmlevel":10, "probetype":null, Page 16 of 156

17 "type":"temperature", "typeid":1, "unit": "id":1, "symbol":" C", "text":"celcius" "decimalplaces":0, "highalarmlevel":80, "lowalarmlevel":20, "probetype":null, "type":"humidity", "typeid":4, "unit": "id":6, "symbol":"%rh", "text":"percent Relative Humidity" ], "connectionlost":false, "currentreadings": "channels":["26.8 C","34%RH"], "datetime":"\/date( )\/", "received":"\/date( )\/" "firmwareversion":"2.3.8 \/ \/ \/ R3.32", "inalarm":0, "infavourites":false, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"new Device Name", "samplerate":70, "timezone":"utc", "timezoneoffset":0, "transmissionperiod":170, "type":"wifi-th" "GUID":"9b2256f e ", "MACAddress":"98:8B:AD:00:0B:1B", "RSSI":5, "SSID":"bmc belkin", "archived":false, "batterylevel":0, "channels":[ "decimalplaces":1, "highalarmlevel":null, "lowalarmlevel":null, "probetype": "id":2, "text":"2" "type":"temperature", "typeid":1, "unit": "id":1, "symbol":" C", "text":"celcius" Page 17 of 156

18 ] ], "currentreadings": "channels":["25.5 C"], "datetime":"\/date( )\/", "received":"\/date( )\/" "firmwareversion":"2.3.8 \/ \/ \/ R3.31", "inalarm":0, "infavourites":false, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"wifi P Sensor", "samplerate":60, "timezone":"utc", "timezoneoffset":0, "transmissionperiod":300, "type":"wifi-tp" Page 18 of 156

19 NewDevices NewDevices Service Locations.svc Returns all devices in the New Devices location for the selected user s account Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid selecteduserguid localtime includearchived Unique identifier for the logged in user Unique identifier for the selected user If true returns reading datetime in timezone of device, otherwise UTC will be used If true archived devices will be included Returns Collection of device objects [ GUID MACaddress Unique identifier for the device Unique MAC Address of device name Device name eg. Fridge 2B type locationguid Device type eg. TP+ Unique identifier for device s location RSSI Device s WiFi signal level (0 5) batterylevel inalarm SSID firmwareversion archived samplerate transmissionperiod lastreadingsreceived infavourites timezone timezoneoffset connectionlost currentreadings Device s battery level (1 5, 11 = charging, 12 = full) Alarm state of device (0=none, 1=primary, 2=secondary, 3=both) SSID string of network device is communicating with Version string of device firmware True/False device is archived (not sending data to the cloud) Period between readings in seconds Period between data transmissions to the cloud in seconds DateTime of last readings received by cloud True/False device is in user s favourites TimeZone of the location of the device Offset in minutes of device s timezone from UTC True/False device is not currently transmitting to the cloud Page 19 of 156

20 ] datetime DateTime of readings channels Collection of formatted readings for each channel eg. 5.7 C, 35%RH received channels DateTime of reading received by the cloud Collection of channel objects for each channel typeid Channel type identifier eg. 1 type Channel type label eg. Temperature decimalplaces Number of decimal places to display readings in eg. 2 unit id symbol text probetype id text alarmsettings lowalarmon highalarmon lowalarmlevel highalarmlevel Unit object Unit identifier Unit symbol eg. C Label for the unit eg. Celcius Probe Type for channel null if no probe Probe type identifier Probe type label True/False is low alarm enabled True/False is high alarm enabled Low alarm level eg. 1.5 Null if not set High alarm level eg Null if not set alarmtriggerdelay Delay before alarm is triggered in seconds alarmhold True/False alarm hold is enabled Example GET /Locations.svc/NewDevices?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&selectedUserGUID=c3575a34-b372-11e3-9bd a0254&localTime=true Data Returned [ "GUID":"9b2256f e ", "MACAddress":"98:8B:AD:00:00:64", "RSSI":5, "SSID":"bmc belkin", "archived":false, "batterylevel":4, "channels":[ "decimalplaces":1, "highalarmlevel":30, "lowalarmlevel":10, "probetype":null, "type":"temperature", Page 20 of 156

21 "typeid":1, "unit": "id":1, "symbol":" C", "text":"celcius" "decimalplaces":0, "highalarmlevel":80, "lowalarmlevel":20, "probetype":null, "type":"humidity", "typeid":4, "unit": "id":6, "symbol":"%rh", "text":"percent Relative Humidity" ], "connectionlost":false, "currentreadings": "channels":["26.8 C","33%RH"], "datetime":"\/date( )\/", "received":"\/date( )\/" "firmwareversion":"2.3.8 \/ \/ \/ R3.32", "inalarm":0, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"new Device Name", "samplerate":70, "transmissionperiod":170, "type":"wifi-th" "firmwareversion":"2.3.8 \/ \/ \/ R3.32", "inalarm":0, "infavourites":false, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"new Device Name", "samplerate":70, "timezone":"utc", "timezoneoffset":0, "transmissionperiod":170, "type":"wifi-th" "GUID":"9b2256f e ", "MACAddress":"98:8B:AD:00:0B:1B", "RSSI":5, "SSID":"bmc belkin", "archived":false, "batterylevel":0, "channels":[ "decimalplaces":1, "highalarmlevel":null, "lowalarmlevel":null, "probetype": "id":2, "text":"2" Page 21 of 156

22 ] "type":"temperature", "typeid":1, "unit": "id":1, "symbol":" C", "text":"celcius" ], "connectionlost":false, "currentreadings": "channels":["25.5 C"], "datetime":"\/date( )\/", "received":"\/date( )\/" "firmwareversion":"2.3.8 \/ \/ \/ R3.31", "inalarm":0, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"wifi P Sensor", "samplerate":60, "timezone":"utc", "timezoneoffset":0, "transmissionperiod":300, "type":"wifi-tp" Page 22 of 156

23 Users.svc The Users service is for adding and editing users and returning favourite devices and alarms. Login AccountSummary UpdatePassword UpdateDateTimeFormats UpdateGroupAlertFrequency UpdateUserPermissions UpdateUserLocations AccountUsers AddUser EditUser DeleteUser Favourites AddToFavourites RemoveFromFavourites DevicesInAlarm Alarms Takes an address and password and returns the user object Returns account level permissions/options Updates the logged in user s password Updates the logged in user s date and time format preferences Updates group alert frequency setting for the logged in user Updates permissions for a specified user Updates locations a specified user can access Lists users within the account (assuming logged in user has admin privilege) Creates a new user and returns the userguid Updates name, and password for a specified user Disables selected user account Lists user s favourite devices Adds a device to user s favourites Removes a device from user s favourites Lists devices currently in alarm that the user can access Count of alarms for the user Page 23 of 156

24 Login Login Service Users.svc Takes an address and password and returns the user object Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech password User s login address User s password Returns GUID Unique identifier for the user name dateformat timeformat groupalertfrequency permissions accountadministrator administrator managedevices viewdata exportdata dailysummaryofevents closeevents User s name User s preferred date format eg. dd/mm/yyyy User s preferred time format eg. HH:mm:ss Group alerts so that s are received at most once every x seconds Permissions object True/False user has account administrator permission True/False user has administrator permission True/False user has manage devices permission True/False user has view data permission True/False user has export data permission True/False user receives the daily summary of events True/False user can close events in the event log Example GET /Users.svc/Login?APIToken=fbdff288-98b5-11e3-811f b054& =testapi@filesthrutheair.com&password=Testbiomedical7 Data Returned "GUID":"a2458cf8-b35e-11e3-9bd a0254", "dateformat":"dd\/mm\/yyyy", "timeformat":"hh:mm:ss", "groupalertfrequency":0, "name":"george Smith", "permissions": Page 24 of 156

25 "accountadministrator":true, "administrator":true, "exportdata":true, "managedevices":true, "viewdata":true, "dailysummaryofevents":true, "closeevents":true, Page 25 of 156

26 AccountSummary AccountSummary Service Users.svc Returns account level permissions/options Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user Returns GUID Unique identifier for the account name Account name type Account type eg. Professional tier 3 multilocationenabled True/False are multiple locations allowed for this account multiuserenabled True/False are multiple users allowed for this account Example GET /Users.svc/AccountSummary?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=a2458cf8-b35e-11e3-9bd a0254 Data Returned "GUID":"a2433b74-b35e-11e3-9bd a0254", "multilocationenabled":true, "multiuserenabled":true, "name":"test Api", "type":"professional tier 5" Page 26 of 156

27 UpdatePassword UpdatePassword Service Users.svc Updates the logged in user s password Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user password User s new password Returns True if successful, false otherwise Example POST /Users.svc/UpdatePassword POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"a2458cf8-b35e-11e3-9bd a0254", "password":"testbiomedical77" Page 27 of 156

28 UpdateDateTimeFormats UpdateDateTimeFormats Service Users.svc Updates the logged in user s date and time format preferences Method POST Parameters APIToken API Access token provided by Corintech userguid dateformat timeformat Unique identifier for the logged in user User s preferred date format must be one of the formats returned by Lookups.svc/DateFormats User s preferred time format must be one of the formats returned by Lookups.svc/TimeFormats Returns True if successful, false otherwise Example POST /Users.svc/UpdateDateTimeFormats POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"a2458cf8-b35e-11e3-9bd a0254", "dateformat":"yyyy\/mm\/dd", "timeformat":"hh:mm:ss" Page 28 of 156

29 UpdateGroupAlertFrequency UpdateGroupAlertFrequency Service Users.svc Updates group alert frequency setting for the logged in user Method POST Parameters APIToken API Access token provided by Corintech userguid groupalertfrequency Unique identifier for the logged in user User s preferred group alert frequency must be one of the formats returned by Lookups.svc/GroupAlertFrequencies Returns True if successful, false otherwise Example POST /Users.svc/UpdateGroupAlertFrequency POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"a2458cf8-b35e-11e3-9bd a0254", "groupalertfrequency":"1", Page 29 of 156

30 UpdateUserPermissions UpdateUserPermissions Service Users.svc Updates permissions for a specified user Method POST Parameters APIToken API Access token provided by Corintech userguid selecteduserguid userpermissions Unique identifier for the logged in user GUID of selected user can be the same as userguid to edit own account Permissions object Returns True if successful, false otherwise Example POST /Users.svc/UpdateUserPermissions POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "selecteduserguid":"c3575a34-b372-11e3-9bd a0254", "userpermissions": "accountadministrator":true, "administrator":true, "exportdata":true, "managedevices":true, "viewdata":true, "dailysummaryofevents":true, "closeevents":true Page 30 of 156

31 UpdateUserLocations UpdateUserLocations Service Users.svc Updates locations a specified user can access Method POST Parameters APIToken API Access token provided by Corintech userguid selecteduserguid locationguids Unique identifier for the logged in user GUID of selected user can be the same as userguid to edit own account Collection of locationguid strings note location access will be reset for the user so this parameter has to contain all the locations the user should have access to, not just any new ones. The one exception to this is the New Devices location for the user s account (if account is a Professional tier). All active users within an account will always have access to this location. Returns True if successful, false otherwise Example POST /Users.svc/UpdateUserLocations POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "selecteduserguid":"c3575a34-b372-11e3-9bd a0254", "locationguids":["a b35e-11e3-9bd a0254"] Page 31 of 156

32 AccountUsers AccountUsers Service Users.svc Lists users within the account (assuming logged in user has admin privilege) Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user Returns Collection of user objects [ GUID ] name dateformat timeformat groupalertfrequency permissions accountadministrator administrator managedevices viewdata exportdata dailysummaryofevents closeevents Unique identifier for the user User s name User s preferred date format eg. dd/mm/yyyy User s preferred time format eg. HH:mm:ss Group alerts so that s are received at most once every x seconds Permissions object True/False user has account administrator permission True/False user has administrator permission True/False user has manage devices permission True/False user has view data permission True/False user has export data permission True/False user receives the daily summary of events True/False user can close events in the event log Example GET /Users.svc/AccountUsers?apitoken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254 Data Returned [ "GUID":"c3575a34-b372-11e3-9bd a0254", "dateformat":"yyyy\/mm\/dd", "timeformat":"hh:mm:ss", "groupalertfrequency":0, "name":"george Smith", "permissions": Page 32 of 156

33 ] "accountadministrator":true, "administrator":true, "exportdata":true, "managedevices":true, "viewdata":true, "dailysummaryofevents":true, "closeevents":true Page 33 of 156

34 AddUser AddUser Service Users.svc Creates a new user and returns the userguid Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user name Name of new user address of new user password Password for new user Returns userguid for new user Example POST /Users.svc/AddUser POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "name":"holly Smith", " ":"apitesths@filesthrutheair.com", "password":"testbiomedical7" Data Returned "c3575a34-b372-11e3-9bd a0254" Page 34 of 156

35 EditUser EditUser Service Users.svc Updates name, and password for a specified user Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user selecteduserguid Unique identifier for the selected user name Name of new user address of new user password Password for new user Returns True if successful, false otherwise Example POST /Users.svc/EditUser POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "selecteduserguid":"a2458cf8-b35e-11e3-9bd a0254", "name":"ben Smith", " ": "apitestbs1@filesthrutheair.com", "password": "Testbiomedical7" Page 35 of 156

36 DeleteUser DeleteUser Service Users.svc Disables selected user account Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user selecteduserguid Unique identifier for the selected user Returns True if successful, false otherwise Example POST /Users.svc/DeleteUser POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "selecteduserguid":"c3575a34-b372-11e3-9bd a0254" Page 36 of 156

37 Favourites Favourites Service Users.svc Lists user s favourite devices Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid localtime Unique identifier for the logged in user If true returns reading datetime in timezone of device, otherwise UTC will be used Returns Collection of device objects [ GUID MACaddress Unique identifier for the device Unique MAC Address of device name Device name eg. Fridge 2B type locationguid Device type eg. TP+ Unique identifier for device s location RSSI Device s WiFi signal level (0 5) batterylevel inalarm SSID firmwareversion archived samplerate transmissionperiod lastreadingsreceived infavourites timezone timezoneoffset connectionlost currentreadings datetime channels received Device s battery level (1 5, 11 = charging, 12 = full) Alarm state of device (0=none, 1=primary, 2=secondary, 3=both) SSID string of network device is communicating with Version string of device firmware True/False device is archived (not sending data to the cloud) Period between readings in seconds Period between data transmissions to the cloud in seconds DateTime of last readings received by cloud True/False device is in user s favourites TimeZone of the location of the device Offset in minutes of device s timezone from UTC True/False device is not currently transmitting to the cloud DateTime of readings Collection of formatted readings for each channel eg. 5.7 C, 35%RH DateTime of reading received by the cloud Page 37 of 156

38 channels Collection of channel objects for each channel typeid Channel type identifier eg. 1 Type Channel type label eg. Temperature decimalplaces Number of decimal places to display readings in eg. 2 unit id symbol text Unit object Unit identifier Unit symbol eg. C Label for the unit eg. Celcius probetype id text Probe Type for channel null if no probe Probe type identifier Probe type label ] alarmsettings lowalarmon highalarmon lowalarmlevel highalarmlevel alarmtriggerdelay alarmhold True/False is low alarm enabled True/False is high alarm enabled Low alarm level eg. 1.5 Null if not set High alarm level eg Null if not set Delay before alarm is triggered in seconds True/False alarm hold is enabled Example GET /Users.svc/Favourites?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&localTime=true Data Returned [ "GUID":"9b2256f e ", "MACAddress":"98:8B:AD:00:00:64", "RSSI":5, "SSID":"bmc belkin", "archived":false, "batterylevel":4, "channels":[ "decimalplaces":1, "highalarmlevel":20, "lowalarmlevel":10, "probetype":null, "type":"temperature", "typeid":1, "unit": "id":1, "symbol":" C", "text":"celcius" Page 38 of 156

39 ] "decimalplaces":0, "highalarmlevel":80, "lowalarmlevel":20, "probetype":null, "type":"humidity", "typeid":4, "unit": "id":6, "symbol":"%rh", "text":"percent Relative Humidity" ], "connectionlost":false, "currentreadings": "channels":["27.5 C","34%RH"], "datetime":"\/date( )\/", "received":"\/date( )\/" "firmwareversion":"2.3.8 \/ \/ \/ R3.32", "inalarm":1, "infavourites":true, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"new Device Name", "samplerate":70, "transmissionperiod":170, "type":"wifi-th" Page 39 of 156

40 AddToFavourites AddToFavourites Service Users.svc Adds a device to user s favourites Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user sensorguid Unique identifier for the selected device Returns True if successful, false otherwise Example POST /Users.svc/AddToFavourites POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "sensorguid":"9b2256f e " Page 40 of 156

41 RemoveFromFavourites RemoveFromFavourites Service Users.svc Removes a device from user s favourites Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user sensorguid Unique identifier for the selected device Returns True if successful, false otherwise Example POST /Users.svc/RemoveFromFavourites POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "sensorguid":"9b2256f e " Page 41 of 156

42 DevicesInAlarm DevicesInAlarm Service Users.svc Lists devices currently in alarm that the user can access Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid localtime Unique identifier for the logged in user If true returns reading datetime in timezone of device, otherwise UTC will be used Returns Collection of device objects [ GUID MACaddress Unique identifier for the device Unique MAC Address of device name Device name eg. Fridge 2B type locationguid Device type eg. TP+ Unique identifier for device s location RSSI Device s WiFi signal level (0 5) batterylevel inalarm SSID firmwareversion archived samplerate transmissionperiod lastreadingsreceived infavourites timezone timezoneoffset connectionlost currentreadings datetime channels received Device s battery level (1 5, 11 = charging, 12 = full) Alarm state of device (0=none, 1=primary, 2=secondary, 3=both) SSID string of network device is communicating with Version string of device firmware True/False device is archived (not sending data to the cloud) Period between readings in seconds Period between data transmissions to the cloud in seconds DateTime of last readings received by cloud True/False device is in user s favourites TimeZone of the location of the device Offset in minutes of device s timezone from UTC True/False device is not currently transmitting to the cloud DateTime of readings Collection of formatted readings for each channel eg. 5.7 C, 35%RH DateTime of reading received by the cloud Page 42 of 156

43 channels Collection of channel objects for each channel typeid Channel type identifier eg. 1 Type Channel type label eg. Temperature decimalplaces Number of decimal places to display readings in eg. 2 unit id symbol text Unit object Unit identifier Unit symbol eg. C Label for the unit eg. Celcius probetype id text Probe Type for channel null if no probe Probe type identifier Probe type label ] alarmsettings lowalarmon highalarmon lowalarmlevel highalarmlevel alarmtriggerdelay alarmhold True/False is low alarm enabled True/False is high alarm enabled Low alarm level eg. 1.5 Null if not set High alarm level eg Null if not set Delay before alarm is triggered in seconds True/False alarm hold is enabled Example GET /Users.svc/DevicesInAlarm?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&localTime=true Data Returned [ "GUID":"9b2256f e ", "MACAddress":"98:8B:AD:00:00:64", "RSSI":5, "SSID":"bmc belkin", "archived":false, "batterylevel":4, "channels":[ "decimalplaces":1, "highalarmlevel":20, "lowalarmlevel":10, "probetype":null, "type":"temperature", "typeid":1, "unit": "id":1, "symbol":" C", "text":"celcius" Page 43 of 156

44 ] "decimalplaces":0, "highalarmlevel":80, "lowalarmlevel":20, "probetype":null, "type":"humidity", "typeid":4, "unit": "id":6, "symbol":"%rh", "text":"percent Relative Humidity" ], "connectionlost":false, "currentreadings": "channels":["27.7 C","39%RH"], "datetime":"\/date( )\/", "received":"\/date( )\/" "firmwareversion":"2.3.8 \/ \/ \/ R3.32", "inalarm":1, "infavourites":false, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"new Device Name", "samplerate":70, "timezone":"utc", "timezoneoffset":0, "transmissionperiod":170, "type":"wifi-th" Page 44 of 156

45 Alarms Alarms Service Users.svc Count of alarms for the user Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user Returns Number of devices currently in alarm Example GET /Users.svc/Alarms?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254 Data Returned 0 Page 45 of 156

46 Devices.svc The Devices service is for retrieving and updating the settings and listing the sessions of a device. Device AddDevice DeviceName UpdateDeviceName SampleRate UpdateSampleRate TransmissionPeriod UpdateTransmissionPeriod ChannelLabels UpdateChannelLabels Units UpdateUnits ProbeTypes UpdateProbeTypes AlarmSettings UpdateAlarmSettings AlertSettings UpdateAlertSettings DeviceLocation UpdateDeviceLocation AuditChecksEnabled UpdateAuditChecks ApplySettings ResetAlarm CurrentReadings Sessions SessionsByDate CurrentSession Events CloseEvent OpenEvent AddEventNote AuditChecks AllDevicesSummary Readings Device summary Adds a device to the New Devices location of the current user s account Name of the selected device Updates the name of the selected device Sample rate setting for a device (in seconds) Updates sample rate setting for a device Transmission period setting for a device (in seconds) Updates transmission period setting for a device Labels for each channel of a device Updates labels for each channel of a device Units settings for each channel of a device Updates unit settings for each channel of a device Probe type for each channel of a device Updates probe type for each channel of a device Returns object containing alarm settings for a device Updates alarm settings for a device Returns personal alert settings for a device Updates personal alert settings for a device Returns location identifier for a device Updates location of a device Indicates whether audit checks are enabled for a device Updates audit checks setting for a device Applies all updated settings and sends them to the device when it next communicates with the cloud Resets alarm for a device that is in alarm Pre-formatted latest reading for each channel and DateTime of reading List of sessions for a device List of sessions for a device, within specified date range Session identifier of current (latest) session for a device List of events for a device Closes an event Re-opens a closed event Adds a note to an event List of audit checks for a device Returns a summary of all the devices for the specified user Returns readings for a device within a date range Page 46 of 156

47 Device Device Service Devices.svc Returns device summary Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid sensorguid includeunappliedsettings localtime Unique identifier for the logged in user Unique identifier for the selected device If true, pending settings will be returned (if applicable), otherwise the actual device setting will be returned If true returns reading datetime in timezone of device, otherwise UTC will be used Returns GUID Unique identifier for the device MACaddress Unique MAC Address of device name Device name eg. Fridge 2B type locationguid Device type eg. TP+ Unique identifier for device s location RSSI Device s WiFi signal level (0 5) batterylevel inalarm SSID firmwareversion archived samplerate transmissionperiod lastreadingsreceived infavourites timezone timezoneoffset connectionlost auditchecksenabled currentreadings datetime channels Device s battery level (1 5, 11 = charging, 12 = full) Alarm state of device (0=none, 1=primary, 2=secondary, 3=both) SSID string of network device is communicating with Version string of device firmware True/False device is archived (not sending data to the cloud) Period between readings in seconds Period between data transmissions to the cloud in seconds DateTime of last readings received by cloud True/False device is in user s favourites TimeZone of the location of the device Offset in minutes of device s timezone from UTC True/False device is not currently transmitting to the cloud True/False audit checks are enabled for the device DateTime of readings Collection of formatted readings for each channel eg. 5.7 C, 35%RH Page 47 of 156

48 received DateTime of reading received by the cloud channels Label Collection of channel objects for each channel Channel label typeid Channel type identifier eg. 1 type Channel type label eg. Temperature decimalplaces Number of decimal places to display readings in eg. 2 unit id symbol text Unit object Unit identifier Unit symbol eg. C Label for the unit eg. Celcius probetype id text Probe Type for channel null if no probe Probe type identifier Probe type label alarmsettings lowalarmon highalarmon lowalarmlevel highalarmlevel alarmtriggerdelay alarmhold True/False is low alarm enabled True/False is high alarm enabled Low alarm level eg. 1.5 Null if not set High alarm level eg Null if not set Delay before alarm is triggered in seconds True/False alarm hold is enabled Example GET /Devices.svc/Device?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&sensorGUID=9b2256f e a0254&localTime=true Data Returned "GUID":"9b2256f e ", "MACAddress":"98:8B:AD:00:00:64", "RSSI":5, "SSID":"bmc belkin", "archived":false, "batterylevel":4, "channels":[ "alarmsettings": "alarmhold":false, "alarmtriggerdelay":0, "highalarmlevel":15.0, "highalarmon":true, "lowalarmlevel":5.0, "lowalarmon":true "decimalplaces":1, "label":"temperature", Page 48 of 156

49 "probetype":null, "type":"temperature", "typeid":1, "unit": "id":1, "symbol":" C", "text":"celcius" "alarmsettings": "alarmhold":false, "alarmtriggerdelay":0, "highalarmlevel":null, "highalarmon":false, "lowalarmlevel":null, "lowalarmon":false "decimalplaces":0, "label":"humidity", "probetype":null, "type":"humidity", "typeid":4, "unit": "id":6, "symbol":"%rh", "text":"percent Relative Humidity" ], "connectionlost":false, "auditchecksenabled":false, "currentreadings": "channels":["26.8 C","34%RH"], "datetime":"\/date( )\/", "received":"\/date( )\/" "firmwareversion":"2.3.8 \/ \/ \/ R3.32", "inalarm":0, "infavourites":false, "lastreadingsreceived":"\/date( )\/", "locationguid":"a b35e-11e3-9bd a0254", "name":"new Device Name", "samplerate":70, "timezone":"utc", "timezoneoffset":0, "transmissionperiod":170, "type":"wifi-th" Page 49 of 156

50 AddDevice AddDevice Service Devices.svc Adds a new device to the New Devices location of the user s account Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user MACaddress Unique MAC Address of device devicename Device name eg. Fridge 2B devicetype Device type eg. TP+ samplerate Period between readings in seconds transmissionperiod Period between data transmissions to the cloud in seconds SSID SSID string of network device is communicating with firmwareversion Version string of device firmware favourite True if device is in user s favourites auditchecksenabled True if audit checks are enabled permanentlypowered True if device is permanently powered, false if battery powered channels [ Collection of newdevicechannel object (1 per channel) label Channel label eg. Temperature typeid Channel type identifier eg. 1 unitid Unit identifier probetypeid Probe type identifier maxprobetype Maximum probe type number from device alarmsettings lowalarmon True/False is low alarm enabled highalarmon True/False is high alarm enabled lowalarmlevel Low alarm level eg. 1.5 Null if not set highalarmlevel High alarm level eg Null if not set alarmtriggerdelay Delay before alarm is triggered in seconds alarmhold True/False alarm hold is enabled ] Returns GUID (unique identifier) of device successful, empty string otherwise Example POST /Devices.svc/AddDevice Page 50 of 156

51 POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "MACAddress":"98:8B:AD:00:00:64", "devicename":"new Device Name", "devicetype":"wifi-th", "samplerate":70, "transmissionperiod":170, "SSID":"bmc belkin", "firmwareversion":"2.3.8 \/ \/ \/ R3.32", "favourite":false, "auditchecksenabled":false, "permanentlypowered":true, "channels":[ "label":"temperature", "typeid":1, "unitid":1, "probetypeid":0, "maxprobetype":0, "alarmsettings": "alarmhold":false, "alarmtriggerdelay":0, "highalarmlevel":null, "highalarmon":false, "lowalarmlevel":null, "lowalarmon":false "label":"humidity", "typeid":4, "unitid":6, "probetypeid":0, "maxprobetype":0, "alarmsettings": "alarmhold":false, "alarmtriggerdelay":0, "highalarmlevel":null, "highalarmon":false, "lowalarmlevel":null, "lowalarmon":false ], Page 51 of 156

52 DeviceName DeviceName Service Devices.svc Returns the name of selected device Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid sensorguid includeunappliedsettings Unique identifier for the logged in user Unique identifier for the device If true, pending settings will be returned (if applicable), otherwise the actual device setting will be returned Returns Device name Example GET /Devices.svc/DeviceName?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&sensorGUID=9b2256f e &includeUnappliedSettings=false Data Returned WiFi Sensor Page 52 of 156

53 UpdateDeviceName UpdateDeviceName Service Devices.svc Updates the name of the selected device Method POST Parameters APIToken API Access token provided by Corintech userguid Unique identifier for the logged in user sensorguid Unique identifier for the device devicename New name for the device Returns True if successful, false otherwise Example POST /Devices.svc/UpdateDeviceName POST Data "APIToken":"fbdff288-98b5-11e3-811f b054", "userguid":"c3575a34-b372-11e3-9bd a0254", "sensorguid":"9b2256f e ", "devicename":"new Device Name" Page 53 of 156

54 SampleRate SampleRate Service Devices.svc Sample rate setting for a device (in seconds) Method GET Data Format JSON Parameters APIToken API Access token provided by Corintech userguid sensorguid includeunappliedsettings Unique identifier for the logged in user Unique identifier for the device If true, pending settings will be returned (if applicable), otherwise the actual device setting will be returned Returns Number of seconds between samples Example GET /Devices.svc/SampleRate?APIToken=fbdff288-98b5-11e3-811f b054&userGUID=c3575a34-b372-11e3-9bd a0254&sensorGUID=9b2256f e a0254&includeUnappliedSettings Data Returned 30 Page 54 of 156