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.

To get started with the Application APIs, see the Swagger API Documentation.


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.

For mor information on the data streaming endpoint implementation, see the Swagger Data Stream Documentation.

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
gwRxTime String Optional Time the message was received by the gateway

* 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 Application downlinks to devices. In addition to the Application Payload, users can specify the LoRa-level FPort and Confirmed settings, as well as a timeout threshold for how long the Network waits until foregoing transmission or receiving acknowledgement when expected. Downlink queues support up to 3 downlinks and are cleared in one of the following ways: transmission, timeout, a newer downlink request with the 'clear' parameter set 'True', or a separate request to the Clear Downlinks API.

Notifier endpoint implementations can leverage the Downlink API in numerous ways. For example, a downlink POST request is automatically triggered in response to an uplink notification. With low-enough round-trip time between the Notifier and its endpoint, including the 'immediate' parameter set to 'True' in the downlink request ensures the Network will send it against one of the current uplink's receive windows.

When Downlink requests are successful, the response will include a unique-, numeric message identifier ('msgId'). This is distinct from the sequence number (FCntDn) allocated when a downlink is sent, allowing traceability of specific downlink Application payloads.

All Downlink API requests require an authorization key passed either as a URL parameter or in an authorization header. 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 Device's IEEE EUI-64 identifier. Yes Hexadecimal String
pdu Application payload to send. Yes Hexadecimal String
port LoRaWAN FPort to use in Downlink's MACPayload. No 1 1-254
confirmed Flag indicating Device must acknowledge receipt of this downlink. No false true or false
timeoutMinutes Minutes the Network waits until foregoing downlink transmission or receiving acknowledgement when expected. No 5 Positive Integer
clear Flag to forego previously queued downlinks and service this downlink request. No false true or false
immediate Flag indicating downlink should be sent against current uplink and not queued for the next. 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

The first step in the onboarding process, Registration accomplishes the following: - Provisions the Device EUI to Root Key(s) mappings to the appropriate Join Server. - Initial Customer Contract association for and billing. - Initial assignment of the Device Profile for LoRaWAN management.   Note: Registration of a Device does not transition it to an active billing state.

Note: If "Do Not Set" is selected for either Contract or Device Profile during Registration, these may set during Activation.

Note: Registration requests must be submitted with a security token. Refer to Device Registration for information about obtaining a token.

Because Registration may involve large amounts of data, this API works in conjunction with the Task Status API: responses to successful Registration requests contain a Task Job ID that can be used to monitor the progress of the Registration task. Although only one task can run per Application, Senet recommends ensuring previous operations are complete prior to initiating a new Device Management job.

Resource URL

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

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
token Value required to authenticate the Registration request. Yes Six digit number
appEui Application's IEEE EUI-64 identifier. No Application associated with the API key Hexadecimal String
joinEui Join Server's IEEE EUI-64 identifier. No Default Join Server for the Application Hexadecimal String
contractId Contract ID to be associated with the Devices being registered. No Integer
profId Device Profile assigned to the Devices being registered. No Integer
tags One or more human-readable strings - separated by commas - used to identify and organize the Devices being registered. 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.

Because Activation may involve large amounts of data, this API works in conjunction with the Task Status API: responses to successful Activation requests contain a Task Job ID that can be used to monitor the progress of the Activation task. Although only one task can run per Application, Senet recommends ensuring previous operations are complete prior to initiating a new Device Management job.

Bulk Activation

Resource URL

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

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
appEui Application's IEEE EUI-64 identifier. No Application associated with the API key Hexadecimal String
joinEui Join Server's IEEE EUI-64 identifier. No Default Join Server for the Application Hexadecimal String
contractId Contract ID to be associated with the Devices being activated. No Integer
profId Device Profile assigned to the Devices being activated. No Integer
tags One or more human-readable strings - separated by commas - used to identify and organize the Devices being registered. 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

Deactivated Devices cannot join or rejoin the Network. Previously joined Devices that are Deactivated will continue uplinking in the context of their previously established security session

Note: Deactivated Devices that continue communicating on the Network are in an active billing state. The Network must not hear Deactivated Devices for a complete billing cycle to prevent billing.

Because Deactivation may involve large amounts of data, this API works in conjunction with the Task Status API: responses to successful Deactivation requests contain a Task Job ID that can be used to monitor the progress of the Deactivation task. Although only one task can run per Application, Senet recommends ensuring previous operations are complete prior to initiating a new Device Management job.

Resource URL

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

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
appEui Application's IEEE EUI-64 identifier. No Application associated with the API key Hexadecimal String
joinEui Join Server's IEEE EUI-64 identifier. No Default Join Server for the Application Hexadecimal String
contractId Contract ID to be associated with the Devices being Deactivated. No Integer
profId Device Profile assigned to the Devices being Deactivated. 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. No Comma Separated Hexadecimal String
devTags The list of Device Tags used to initiate the FUOTA transfer for (devEuis must be empty). No Comma Separated Tag Names
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 B/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
"Request Body" 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=00000000000100E0&devEuis=123000000000ABC0,123000000000ABC1&devClass=C&txChnl=7&txDr=13&startDelaySecs=120&fragAlg=FWD_ERR_CORR&redundancy=1.0&millisBetweenPkts=4000&contractId=20"

Response Example

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