API Reference

The Application REST APIs allow system administrators and Application Providers to send downlinks and Register/Activate/Deactivate Devices for an Application. An API key is required to authenticate API usage. API keys are created and managed in the API Keys view.

Response messages are JSON-formatted.

Device uplink messages heard by one or more gateways are relayed to the network server which in turn server securely forwards the data to an IoT platform.

Application Payload

In addition to streaming the payload data (pdu), network information is included. Optionally, RF information about each transmission can be added by enabling "Include RF Data" in the notification target's configuration.

The Senet Network supports the standard JSON object model where each object contains one-to-many key/values pairs. The JSON object is in the following format:

{
   "Key":"String Value",
   "Key": Numeric Value
}

Note: Senet may add additional fields during future Portal updates. Please ensure that the Application ignores any unknown fields and continue to parse the notification data. Duplicate uplinks are also available on Production with a Contract.

All JSON-formatted data contains the following default fields:

Fields

FieldName DataType Category Description
devEui String Default 64-bit Extended Unique Identifier of the Device transmitting the message
gwEui String Default 64-bit Extended Unique Identifier of the receiving Gateway that processed the message
joinId Number Default Incrementing Integer used to Identify the last join
pdu String Default Protocol Data Unit or Customer Payload data
port Number Default 0 indicates that the FRMPayload contains MAC commands only and 1..223 are Application specific
seqno Number Default Incrementing Integer used to Identify an uplink
txtime String Default Time the message was received by the Network Server
channel Number RF Field Frequency Channel of the transmission
datarate Number RF Field Integer that maps to a spreading factor, bandwidth and bitrate
freq Number RF Field Transmit Frequency in MHz
rssi Number RF Field Received Signal Strength Indicator reported by receiving gateway
snr Number RF Field Average Signal to Noise Ratio reported by receiving gateway
ack Boolean Optional Flag indicating if the uplink was acknowledging the receipt of a downlink
ackDnMsgId Number Optional When present, indicates that a Device has acknowledged a specific downlink message ID
devClass String Optional LoRaWAN Class designation ("A", "B", "C") of the Device
devType String Optional The type of the Device
dup* Boolean Optional Flag indicating if the uplink was already forwarded because it was heard by multiple gateways
estLat* Number Optional Estimated latitude of the Device in decimal degrees
estLng* Number Optional Estimated longitude of the Device in decimal degrees
cfgLat Number Optional Configured latitude of the Device in decimal degrees
cfgLng Number Optional Configured longitude of the Device in decimal degrees
tags String Optional A comma separated list of tags configured on this Device
metadata String Optional The metadata value configured on this Device
devProfile String Optional The name of the Profile applied to this Device
fwVersion String Optional The firmware version of this Device

* Requires contractual agreement

Example:

{
   "ack":true,
   "ackDnMsgId": 100000,
   "devClass": "A" ,
   "devEui":"FFFFFFFFFFFFFFFF",
   "gwEui":"AAAAAAAAAAAAAAAA",
   "joinId":216,
   "pdu":"01000016D7011400060E06",
   "port":1,
   "seqno":1,
   "txtime":"2017-02-09T12:38:38.375Z"

}

Example with RF Fields:

{
   "ack":true,
   "channel":64,
   "datarate":4,
   "devEui":"FFFFFFFFFFFFFFFF",
   "freq":903,
   "gwEui":"AAAAAAAAAAAAAAAA",
   "joinId":209,
   "pdu":"01000016D7011400060E06",
   "port":1,
   "rssi":-77,
   "seqno":1,
   "snr":10,
   "txtime":"2017-02-09T11:35:44.384Z"
}

Batching

Batching is the process of delaying the forwarding of a notification to see if it can be grouped with other notifications going to the same endpoint. Batching is more efficient for both the Network Server and for the Customer's endpoint. Many messages can be transferred in the same time that it takes to transfer a single message.

JSON Format:

Example: Batching Disabled.
Each notification is forwarded northbound to the customer individually using the JSON object model.

{"snr": 9.25, "devEui": "000000000000000A", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.721Z", "joinId": 10, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -57, "value1": 239, "value2": 18, "port": 1, "freq": 913.3, "pdu": "01080100EF020012", "channel": 55, "seqno": 74503}

Example: Batching Enabled.
A set of notifications received by the Network Server (within a few milliseconds of each other) are forward to the customer in a JSON Array.

[
{"snr": 9.25, "devEui": "000000000000000A", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.721Z", "joinId": 10, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -57, "value1": 239, "value2": 18, "port": 1, "freq": 913.3, "pdu": "01080100EF020012", "channel": 55, "seqno": 74503}, 
{"snr": 8.75, "devEui": "000000000000000B", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.722Z", "joinId": 1, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -61, "value1": 239, "value2": 18, "port": 1, "freq": 907.9, "pdu": "01080100EF020012", "channel": 28, "seqno": 23423}, 
{"snr": 9.25, "devEui": "000000000000000C", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.723Z", "joinId": 2, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -55, "value1": 239, "value2": 18, "port": 1, "freq": 913.5, "pdu": "01080100EF020012", "channel": 56, "seqno": 34532}, 
{"snr": 8.75, "devEui": "000000000000000E", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.724Z", "joinId": 1, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -61, "value1": 247, "value2": 18, "port": 1, "freq": 907.7, "pdu": "01080100F7020012", "channel": 27, "seqno": 76453}, 
{"snr": 10.75, "devEui": "000000000000000F", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.725Z", "joinId": 1, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -60, "value1": 247, "value2": 18, "port": 1, "freq": 902.5, "pdu": "01080100F7020012", "channel": 1, "seqno": 18743}
]

When batching is enabled, if only one message is available to be forwarded, it will still be forwarded using the batch format.

[
{"snr": 9.25, "devEui": "000000000000000A", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.721Z", "joinId": 10, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -57, "value1": 239, "value2": 18, "port": 1, "freq": 913.3, "pdu": "01080100EF020012", "channel": 55, "seqno": 74503}
]

Senet provides a simple API for sending downlinks to devices on the Senet Network using HTTP POST. The Downlink API can be leveraged by a Notifier endpoint where in response to receiving uplinks, downlinks are automatically submitted to the downlink queue. All API requests require an authorization key passed either as a parameter or in an authorization header of a Curl command. Senet API keys are 44-character alpha-numeric strings with a prefix of either “AK2:” or “AK3:”. See API Key Management for more information about acquiring API Authorization Keys.

Resource URL

https://api.senetco.io/rest/integration/device/sendmsg

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the LoRa Device. Yes Hexadecimal String
pdu The PDU to send to the Device. Yes Hexadecimal String
port The port (fport) to send to the Device. No 1 1-254
confirmed The flag to tell the receiving Device to acknowledge the reception of the PDU. No false true or false
timeoutMinutes The amount of time in minutes to allow the transaction to be sent prior to timing out the request. No 5 Positive Integer
clear A flag to clear the downlink queue prior to sending a message No false true or false
immediate The flag to request sending the downlink only if can be sent immediately. No false true or false

Response

Field Description
message Message indicating the status or error of the API request in plaintext.
msgId Message Id of the downlink being processed, only present on successful responses.
Code Reason Description
200 Success Request was successfully processed.
403 Authorization failure Access to this resource was rejected due to an authorization issue.
400 Bad Request Invalid request due to insufficient or malformed parameters.
404 Device EUI was not found The Device being accessed could not be found.

Curl Example

curl -H "authorization: <API_KEY>" -X POST "https://api.senetco.io/rest/integration/device/sendmsg?eui=AAAAAAAAAAAAAAAA&pdu=0102030405060708090a0b0c0d0e0f&confirmed=true&port=88&timeoutMinutes=2"

{  
   "message":"Success!",
   "msgId":119
}

Send multicast downlink messages to a multicast session allowing a user specified list of Base Stations to transmit on.

Resource URL

https://api.senetco.io/rest/integration/device/sendmcastmsg

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
addr The IEEE Device address identifier for the LoRa Device that holds the session keys. Yes Hexadecimal String
pdu The PDU to multicast to the Device(s). Yes Hexadecimal String
port The port (fport) to send to the Device. No 1 1-254
bstnEuis The comma separated list of gateway EUIs to have broadcasting the multicast PDU. Yes Comma Separated Hexadecimal String

Response

Field Description
message Message indicating the status or error of the API request in plaintext.
msgId Message Id of the downlink being processed, only present on successful responses.
Code Reason Description
200 Success Request was successfully processed.
403 Authorization failure Access to this resource has been rejected due to an authorization issue.
400 Bad Request Invalid request due to insufficient or malformed parameters.
404 Device EUI was not found The Device being accessed could not be found.

Curl Example

curl -H "authorization: <API_KEY>" -X POST "https://api.senetco.io/rest/integration/device/sendmcastmsg?addr=12FFFFFF&pdu=0102030405060708090a0b0c0d0e0f&bstnEuis=AAAAAAAAAAAAAAAA,AAAAAAAAAAAAAAAB"

{  
   "message":"Success!",
   "msgId":119
}

Clears queued downlink messages. If a specific message ID is supplied, only that downlink will be cleared, otherwise all queued messages are cleared.

Resource URL

https://api.senetco.io/rest/integration/device/clearmsgs

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the LoRa Device. Yes Hexadecimal String
msgId Optional message ID of the downlink to clear. If not specified, all will be cleared. No Positive Integer

Response

Field Description
msgId List of the message IDs cleared from the downlink queue.
Code Reason Description
200 Success Request was successfully processed.
403 Authorization failure Access to this resource has been rejected due to an authorization issue.
400 Bad Request Invalid request due to insufficient or malformed parameters.
404 Device EUI was not found The Device being accessed could not be found.

Curl Example

curl -H "authorization: AK2:APIKEY" -X POST "https://api.senetco.io/rest/integration/device/clearmsgs?devEui=AAAAAAAAAAAAAAAA&msgId=00001"

{  
   "clearedIds":[00001]}
}

Device Onboarding APIs

Senet offers a series of APIs that are used to automate the process of onboarding Devices onto the Senet Network, and facilitate the management of these Devices throughout their lifecycle.  The onboarding process encompasses the Registration of Devices (loading the DevEUI/RootKey(s) onto the Join Server), followed by the Activation of those Devices (authorizing the DevEUIs to Join the network). Devices may be Deactivated once they have Joined the network or prior to Joining the network, in which case a Join attempt will be prevented. Devices that Joined the network in a Deactivated state and continue to communicate on the network, remain in a billable state until the Device is no longer communicating or is forced to re-Join the network.

The APIs were architected with the expectation the onboarding workflows are used for bulk transactions, such that the Registration, Activation and Deactivation calls would apply to a large number of Devices. To validate the completion of the workflow, calling the Task Status API is required to verify that the requested operation completes successfully prior to initiating another job request.  Only one job request can run at a time per Application.  Additional API calls initiated prior to the completion of a running job will result in a failure.

The Registration of 1,000 Devices would typically take around 1 second, while Registration of 10,000 Devices completes in less than 5 seconds. Activation of 1,000 Devices will take around 5 seconds and it is expected that Activation of 10,000 Devices will complete in under 40 seconds.

Device Registration API

Register new Devices on the managed Application. See Device Registration to learn how to request a token.  

Note: Registration of a Device does not transition it to an active billing state.

Note: If "Do Not Set" is selected during registration, a value can be assigned during activation. If no Contract or profile is selected during both operations, the default value configured for the Application is used.

Only one task can run per Application. For each operation, calling the Task Status API before initiating another job request is recommended to verify that the requested operation completes successfully.

Resource URL

https://api.senetco.io/rest/integration/device/register

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
token The randomly generated token used for multi-factor authentication. Yes Six digit number
appEui The IEEE EUI-64 identifier for the Application. No Application associated with the API key Hexadecimal String
joinEui The IEEE EUI-64 identifier for the Join Server. No Default Join Server for the Application Hexadecimal String
contractId The Contract Id that will be assigned to the registered Devices. No Integer
profId The Device Profile Id that will be assigned to the registered Devices. No Integer
tags Informational tags that will be added to the registered Devices. No Comma separated Strings

Data Object

Field Description Required Default Value Allowed Values
devEui The IEEE EUI-64 identifier for the Device. Yes Hexadecimal String
appKey The Device's AES-128 root key used to derive session keys (Application Key). Yes Hexadecimal String
lat The Device's latitude in decimal degrees. No Float
lng The Device's longitude in decimal degrees. No Float
tags Informational tag(s) for the Device. No Comma separated list of Strings
metadata Custom information for the Device. No String
devType The type of the Device. No Senet supported type String 
{  
   "data":[  
      {  
         "devEui":"123000000000ABC0",
         "appKey":"123AAAAAAAAAAAAAAAA000000000ABC0",
         "lat":40.7484445,
         "lng":-73.9878584,
         "tags":"tag1",
         "devType":"WATER_SENSOR"
      },
      {  
         "devEui":"123000000000ABC1",
         "appKey":"123AAAAAAAAAAAAAAAA000000000ABC1"
      }
   ]
}

Curl Example

curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -d '{"data":[{"devEui":"0A00000012000001","appKey":"0ABCDEF0120000010A00000012000001","lat":42.356959, "lng":-71.053271},{"devEui":"0A00000012000002","appKey":"0ABCDEF0120000010A00000012000002","lat":42.356779, "lng":-71.065271}]}' "https://api.senetco.io/rest/integration/device/register?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>&profId=<devProfile>&token=<token>&tags=test1,test2"

Response Example

{  
   "statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
}

Device Activation API

Activate registered or deactivated Devices on the managed Application. An Activated Device may join the network and start uplinking.

Note: Activating a Device transitions it to an active billing state.

Only one task can be running at a time per Application. Calling the Task Status API is recommended to verify that the requested operation completes successfully prior to initiating another job request. 

Bulk Activation

Resource URL

https://api.senetco.io/rest/integration/device/activate

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
appEui The IEEE EUI-64 identifier for the Application. No Application associated with the API key Hexadecimal String
joinEui The IEEE EUI-64 identifier for the Join Server. No Default Join Server for the Application Hexadecimal String
contractId The Contract Id assigned to the Activated Devices. No Integer
profId The Device Profile Id assigned to the Activated Devices. No Integer
tags Informational tags added to the Activated Devices. No Comma separated Strings

Data Object

Field Description Required Default Value Allowed Values
devEui The IEEE EUI-64 identifier for the Device. Yes Hexadecimal String
lat The Device's latitude in decimal degrees. No Float
lng The Device's longitude in decimal degrees. No Float
tags Informational tag(s) for the Device. No Comma separated list of Strings
metadata Custom information for the Device. No String
devType The type of the Device. No Senet supported type String 
{  
   "data":[  
      {  
         "devEui":"123000000000ABC0",
         "lat":40.7484445,
         "lng":-73.9878584,
         "tags":"tag1",
         "devType":"WATER_SENSOR"
      },
      {  
         "devEui":"123000000000ABC1"
      }
   ]
}

Curl Example

curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -d '{"data":[{"devEui":"0A00000012000001","appKey":"0ABCDEF0120000010A00000012000001","lat":42.356959, "lng":-71.053271},{"devEui":"0A00000012000002","appKey":"0ABCDEF0120000010A00000012000002","lat":42.356779, "lng":-71.065271}]}' "https://api.senetco.io/rest/integration/device/activate?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>&profId=<devProfile>&token=<token>&tags=test1,test2"

Response Example

{  
   "statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
}

Individual Activation

Resource URL

https://api.senetco.io/rest/integration/device/activateOne

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
appEui The IEEE EUI-64 identifier for the Application. No Application associated with the API key Hexadecimal String
joinEui The IEEE EUI-64 identifier for the Join Server. No Default Join Server for the Application Hexadecimal String
contractId The Contract Id assigned to the Activated Device. No Integer
profId The Device Profile Id assigned to the Activated Device. No Integer
tags Informational tags added to the Activated Device. No Comma separated Strings
metadata Custom information for the Device. No String
lat The Device's latitude in decimal degrees. No Float
lng The Device's longitude in decimal degrees. No Float
devType The type of the Device. No Senet supported type String

Curl Example

curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -X POST "https://api.senetco.io/rest/integration/device/activateOne?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>&devEui=0A00000012000002&devType=WATER_SENSOR&tags=test1,test2&lat=42.356959&lng=-71.053271"

Response Example

{
   "message":"Device successfully Activated"
}

Device Deactivation API

Deactivate Activated or registered Devices on the managed Application. A deactivated Device continues uplinking if it previously joined the network. Deactivated Devices cannot join or rejoin the network.

Note: A deactivated Device that continues to communicate on the network is in an active billing state. To prevent billing for a deactivated Device, the network must not hear it for a complete billing cycle.

Only one task can run per Application. Calling the Task Status API is recommended to verify that the requested task completes successfully prior to initiating another job request.  

Resource URL

https://api.senetco.io/rest/integration/device/deactivate

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
appEui The IEEE EUI-64 identifier for the Application. No Application associated with the API key Hexadecimal String
joinEui The IEEE EUI-64 identifier for the Join Server. No Default Join Server for the Application Hexadecimal String
contractId The Contract Id assigned to the deactivated Devices. No Integer
profId The Device Profile Id assigned to the Activated Device. No Integer

Data Object

Field Description Required Default Value Allowed Values
devEui The IEEE EUI-64 identifier for the Device. Yes Hexadecimal String 
{  
   "data":[  
      {  
         "devEui":"123000000000ABC0"
      },
      {  
         "devEui":"123000000000ABC1"
      }
   ]
}

Curl Example

curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -d '{"data":[{"devEui":"0A00000012000001"},{"devEui":"0A00000012000002"}]}' "https://api.senetco.io/rest/integration/device/deactivate?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>"

Response Example

{  
   "statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
}

Device Update API

Update fields of Devices that have joined on the managed Application. The Devices' latitude, longitude and tags fields can be edited. Tags in the update can append, replace or delete existing tags based on the selected operation. The tags can be specified for individual Devices in the JSON data or for the full set of Devices in the request by using the tags parameter. The latitude and longitude values in the JSON will always replace the existing Device data.

Only one task per Application is allowed to run at the same time. The response of a successful request is a URL to GET the status of the update task. See Task Status API for more information.

Resource URL

https://api.senetco.io/rest/integration/device/update

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
appEui The IEEE EUI-64 identifier for the Application. Yes Hexadecimal String
profId The Device Profile Id assigned to the Devices. No Integer
tagsOperation The action performed against the existing Device tags (only required if tags are updated). Yes APPEND, REPLACE or DELETE
tags Informational tags applied to the Devices. No Comma separated list of Strings

Data Object

Field Description Required Default Value Allowed Values
devEui The IEEE EUI-64 identifier for the Device. Yes Hexadecimal String
lat The Device's latitude in decimal degrees. No Float
lng The Device's longitude in decimal degrees. No Float
tags Informational tag(s) for the Device. No Comma separated list of Strings
metadata Custom information for the Device. No String
devType The type of the Device. No Senet supported type String
devClass The classification of the Device, either Class A, B, or C. No CLASS_A or CLASS_B or CLASS_C
fwVer The firmware version of the Device. No String 
{  
   "data":[  
      {  
         "devEui":"123000000000ABC0",
         "lat":43.0775992,
         "lng":-70.7596765,
         "tags":"tag1;tag2",
         "devType":"WATER_SENSOR",
        "devClass":"CLASS_B",
        "fwVer" : "1.0.0"
      },
      {  
         "devEui":"123000000000ABC1",
         "lat":40.7484445,
         "lng":-73.9878584,
         "tags":"tag1",
         "devType":"WATER_SENSOR",
        "devClass":"CLASS_C",
        "fwVer" : "1.0.0"
      }
   ]
}

Curl Example

curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -d {"data":[{"devEui":"123000000000ABC0","lat":43.0775992,"lng":-70.7596765,"tags":"tag1;tag2","devType":"WATER_SENSOR","devClass":"CLASS_B","fwVer":"1.0.0"},{"devEui":"123000000000ABC1","lat":40.7484445,"lng":-73.9878584,"tags":"tag1","devType":"WATER_SENSOR","devClass":"CLASS_C","fwVer":"1.0.0"}]}' -X POST "https://api.senetco.io/rest/integration/device/update?appEui=00000000000100E0&tagsOperation=APPEND"

Response Example

{  
   "statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevUpdateJobReq:00000000000100E0"
}

Device Export API

Export Device data from the managed Application. The data returned from the API is formatted for a CSV file.

Resource URL

https://api.senetco.io/rest/integration/device/csvExport

HTTP Method

GET

Parameters

Parameter Description Required Default Value Allowed Values
appEui The IEEE EUI-64 identifier for the Application No Application used to generate API key Hexadecimal String
fields A filter to limit the columns in the exported data No devEui, contract, tags, state, lastHeardFrom Comma separated list of Device fields
state A filter to export Devices based on their current state No ALL ALL, REGISTERED, ACTIVATED, DEACTIVATED, or JOINED
psrDays The number of days to export PSR data No No PSR data Integer value between 1 and 31
contractId A filter to export Devices for a specific contract ID No None Long value
devEuis A list of comma separated Device EUIs to retrieve No None Comma separated list of Hexadecimal Strings

Device Fields

The following Device fields can be used with the 'fields' parameter:

devEui, contract, tags, metadata, state, registrationDate, activationDate, deactivationDate, lastHeardFrom, lastJoinTime, firstJoinTime, yestBstns, yestPsr, yestAvgRssi, yestAvgSnr, lat, lng, profId,devType, devAddr, estLat, estLng, txPeriod, txPower, curDr, adrChg, fwVer, serviceMetrics, metricA, metricB, metricC, joinEui

Curl Example

curl -H "authorization: <API_KEY>" "https://api.senetco.io/rest/integration/device/csvExport?fields=devEui,contract,tags,state,registrationDate,activationDate,deactivationDate,lastHeardFrom" > device_export.csv

Response Example

Dev EUI,Contract,Tags,State,Registration Date,Activation Date,Deactivation Date,Last Heard From
123000000000ABC0,99,,ACTIVATED,03/31/2017 11:37:30 PM UTC,03/31/2017 11:37:30 PM UTC,,04/03/2018 01:54:02 PM UTC
123000000000ABC1,99,,ACTIVATED,03/31/2017 11:25:49 PM UTC,03/31/2017 11:25:49 PM UTC,,04/03/2018 00:27:38 PM UTC
123000000000ABC2,99,,ACTIVATED,03/31/2017 11:04:48 PM UTC,03/31/2017 11:04:48 PM UTC,,09/25/2019 09:38:10 AM UTC

Service Metric Data Curl Example

curl -H "authorization: <API_KEY>" "https://api.senetco.io/rest/integration/device/csvExport?appEui=00250C000001BEEF&contractId=2&fields=devEui,contract,tags,state,registrationDate,activationDate,deactivationDate,lastHeardFrom,serviceMetrics" > service_metric_data.csv

Service Metric Data Response Example

Dev EUI,Contract,Tags,State,Registration Date,Activation Date,Deactivation Date,Last Heard From,Metric A,Metric B,Metric C
00250C0100000302,2,"Test,tag1,tag22",ACTIVATED,10/22/2017 04:00:00 AM UTC,09/03/2019 09:04:37 PM UTC,09/03/2019 09:04:07 PM UTC,07/07/2020 02:39:46 PM UTC,80,100,100

Device Transfer API

Devices may be transferred between Accounts, specifically between Applications. Transfer between Applications belonging to the same Account is also supported.

The response to a successful Device Transfer request contains a job status URL which in turn can be used to check the progress of the transfer task. Task Status API for more information.

All Transfers are constrained by or require the following:

Resource URL

https://api.senetco.io/rest/integration/device/transfer

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
fromAppEui The IEEE EUI-64 identifier for the current Application. Yes Hexadecimal String
toAppEui The IEEE EUI-64 identifier for the new Application. Yes Hexadecimal String
contractId The contract ID to assign to the Devices when they are moved to the new Application. Yes Positive Integer
profId The Device Profile ID to assign to the Devices when they are moved to the new Application. No Application Default Positive Integer

Data Object

Field Description Required Default Value Allowed Values
devEui The IEEE EUI-64 identifier for the Device. Yes Hexadecimal String 
{
   "data":[
      {
         "devEui":"123000000000ABC0"
      },
      {
         "devEui":"123000000000ABC1"
      }
   ]
}

Response

Field Description
message Message indicating the status or error of the API request in plaintext.
Code Reason Description
200 Success Request was successfully processed.
403 Authorization failure Access to this resource was rejected due to an authorization issue.
400 Bad Request Invalid request due to insufficient or malformed parameters.
404 Device or Application EUI was not found The Device being transfered or the Application it is being transfered to could not be found.

Curl Example

curl -H "authorization: <CUR_APP_API_KEY>" -H "authorization2: <NEW_APP_API_KEY>" -H "Content-Type: application/json" -d '{"data":[{"devEui":"0A00000012000001"},{"devEui":"0A00000012000002"}]}' -X POST "https://api.senetco.io/rest/integration/device/transfer?fromAppEui=A1A1A1A1A1A1A1A1&toAppEui=A2A2A2A2A2A2A2A2&contractId=123456"

{  
   "statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevTransferJobReq:A1A1A1A1A1A1A1A1-A2A2A2A2A2A2A2A2"
}

Task Status API

Get the status of an ongoing Device Registration, Activation or Deactivation task. The Task Status API is used to confirm the preceding operation completes prior to initiating a subsequent request. The status is available for 15 minutes after the task completes.

Resource URL

https://api.senetco.io/rest/integration/device/status

HTTP Method

GET

Parameters

Parameter Description Required Default Value Allowed Values
reqId Identifier of the ongoing task. Yes Id String

Curl Example

curl -H "authorization: <API_KEY>" "https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"

Response Example

{  
   "state":"DONE_SUC",
   "result":{  
      "status":"Device activation on App EUI: 00000000000100E0 completed. Activated: 0 Updated: 0 Not Changed: 0 Errors: 1",
      "msgs":[  
         "DevEUI: 1230000000000ABC has not been registered. The Device cannot be Activated on JoinEUI: 00000000000100E0."
      ],
      "stats":{
         "activated":0,
         "updated":0,
         "notChanged":0,
         "errors":1
      }
   },
   "pctDone":100
}

Status Codes

200 The task specified was successfully found. The latest status is returned.

400 The reqId parameter is missing or invalid.

403 The API key is not authorized to get the status of the task.

404 No task could be found with the requested reqId.

Response Details

pctDone

Current status of the task expressed as a percentage (0 to 100).

state

Current state of the task.

DONE_SUC The task finished successfully.
DONE_FAIL An internal server exception occurred while running the task.
INITIAL The task has been created and is waiting to be queued.
QUEUED The task has been queued and is waiting to be run.
RUNNING The task is running.

status

Summary of the task after completion.

Registered Number of Devices successfully registered.
Activated Number of Devices successfully Activated.
Deactivated Number of Devices successfully deactivated.
Updated Number of Device appKeys updated.
Not Changed Number of Devices in the request that did not change.
Errors Number of errors that occurred.

msgs

Messages describing any errors that occurred while running the task.

Registration Messages
An internal server error occurred while registering Devices. <NUM_SKIPPED> Devices were skipped.
Activation Messages
The AppKey for DevEUI: <DEV_EUI> has been updated. Old AppKey: <APP_KEY> New AppKey: <APP_KEY>.
DevEUI: <DEV_EUI> has not been registered. The Device cannot be Activated on JoinEUI: <JOIN_EUI>.
An internal server error occurred while activating DevEUI: <DEV_EUI>.
DevEUI: <DEV_EUI> has already joined on AppEUI: <APP_EUI>. The Device cannot be Activated on AppEUI: <APP_EUI>.
DevEUI: <DEV_EUI> was already Activated on AppEUI: <APP_EUI>. The Device cannot be Activated on AppEUI: <APP_EUI>.
An internal server error occurred while activating Devices.
Deactivation Messages
DevEUI: <DEV_EUI> has not been registered. The Device cannot be deactivated.
An internal server error occurred while deactivating Devices.

FUOTA API

Initiate a firmware update over the air for a set of Devices on an Application.

Resource URL

https://api.senetco.io/rest/integration/mcastTransfer

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
appEui The IEEE Application EUI identifier for the Devices to initiate the FUOTA transfer for. Yes Hexadecimal String
devEuis The list of IEEE Device EUIs to initiate the FUOTA transfer for. Yes Comma Separated Hexadecimal String
startDelaySecs The delay in seconds before initiating the file transfer.  This should include enough time for the network server to configure all Devices for the FUOTA transfer. Yes Positive Integer
txChnl The channel to use when transmitting the multicast fragments to the Devices. No RX2 Channel Positive Integer, Valid Channel For Regional ISM Band
txDr The datarate to use when transmitting the multicast fragments to the Devices. No RX2 DR Positive Integer, Valid Datarate For Regional ISM Band
contractId The Contract ID to use for billing when transferring the multicast fragments to the Devices. Yes Positive Integer, Valid Contract ID for Application
fragAlg The algorithm to use to fragment the file. Yes FWD_ERR_CORR
devClass The class of the multicast session. No C C
redundancy The amount of file redundancy to use when building the fragments to send.  1.0 = 100%. Yes Double value from 0 – 1.0.
millisBetweenPkts The number of milliseconds to force to wait between packet sends.  This is here for Devices that take longer to write fragments. No 5000 Positive Integer
descriptor The 4 byte file descriptor field required by FUOTA to describe the firmware image to the Device receiving it. No 00000000 Hexadecimal String
The binary file to multicast to all the Devices. Yes A firmware file to send to Devices.

Curl Example

    curl -H "authorization: <API_KEY>" --insecure -X POST -F "file=@patch-to_new.bin" "https://api.senetco.io/rest/integration/mcastTransfer?appEui=00250C0000010001&devEuis=0080000004003996,00800000040088F8&devClass=C&txChnl=7&txDr=13&startDelaySecs=120&fragAlg=FWD_ERR_CORR&redundancy=1.0&millisBetweenPkts=4000&contractId=20"

Response Example

{ 
   "jobId":"MCastXferJobReq:00250C0000010001",
   "responseMsg":"MCastXferJobReq job starting in: 00:01:59",
   "statusCode":200
}

Network Management Notification API

Network Management Notifications are administered by Operators and require their assistance to set up for use. This is a unique Notifier type that forwards alert status events for owned assets with alerting enabled. The type of the message determines the body of the message:

Field Descriptions

Field Description Values
type The Type of message being sent. APPLICATION
subType The format of the message body ALERT
data One or more messages of the subType format

Alert Type Field Descriptions

Alert type messages contain detailed information about the alert that was either raised or cleared.

Field Description
count The number of times the alert has been raised.
latestSystemInfo The most recent information about why the alert was raised.
identifier The identifier for the alert, this is usually the entity that is being alerted on i.e. Application EUI.
lastOccurrence A timestamp in ISO format when the alert was last triggered.
status The current status of the alert; Open, Cleared, and Closed.
severity The severity of the alert; Low, Moderate, High, Urgent.
name The name of the alert type, some Examples: Low Notification Count, High Notification Error Count, High Notification Count, etc. For the full list of alerts, see Application Alerts
notes Optional notes provided by the system or Senet Operations.
firstOccurrence A timestamp in ISO format when the alert was first triggered.

Example

{
   "type":"APPLICATION",
   "subType":"ALERT",
   "data":[
      {
         "count":"3",
         "latestystemInfo":"Notifications: 0.0 Threshold: 3000000",
         "identifier":"XXXXXXXXXXXXXXXX",
         "lastOccurrence":"2019-05-09T19:01:56.765Z",
         "status":"cleared",
         "severity":"Moderate",
         "name":"Low Notification Count",
         "notes":"",
         "firstOccurrence":"2019-05-09T18:55:16.887Z"
      }
   ]
}

Senet Packet Format

In addition to the above JSON payload types, Senet also offers an extended payload if the Device implements the standard Senet Packet Format. See the Senet Packet format documentation for more details.