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. If you have not received an API key, please email your request to support@senetco.com or call the technical support phone number shown on support@senetco.com.

Response messages are JSON-formatted.

Downlink API

Send downlink messages to devices on the managed application.

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

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 access could not be found.

Curl Example

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

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

Downlink API - Multicast

Send multicast downlink messages to a multicast session allowing a user specified list of gateways 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
confirmed	The flag to tell the receiving device to acknowledge the reception of the PDU.	No	false	true or false
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 access could not be found.

Curl Example

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

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

Downlink API - Clear Downlinks

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.	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 access could not be found.

Curl Example

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

{  
   "clearedIds":[00001]}
}

Uplink API

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:

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.

{
   "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. All JSON-formatted data contains the following default fields:

Fields

FieldName	DataType	Description
ack	Boolean	Flag indicating if the uplink was acknowledging the receipt of a downlink
ackDnMsgId	Number	When present, indicates that a device has acknowledged a specific downlink message ID
devClass	String	LoRaWAN Class designation ("A", "B", "C") of the device
devEui	String	64-bit Extended Unique Identifier of the device transmitting the message
gwEui	String	64-bit Extended Unique Identifier of the receiving Gateway that processed the message
joinId	Number	Incrementing Integer used to Identify the last join
pdu	String	Protocol Data Unit or Customer Payload data
port	Number	0 indicates that the FRMPayload contains MAC commands only and 1..223 are application specific
seqNo	Number	Incrementing Integer used to Identify an uplink
txtime	String	Time the message was received by the gateway

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"

}

RF Fields

The following fields can be added to the payload by enabling "Include RF Data" in the the notification target editor. This is only available to a user with with administrative privileges.

FieldName	DataType	Description
channel	Number	Frequency Channel of the transmission
datarate	Number	Integer that maps to a spreading factor, bandwidth and bitrate
freq	Number	Transmit Frequency in MHz
rssi	Number	Received Signal Strength Indicator reported by receiving gateway
snr	Number	Average Signal to Noise Ratio reported by receiving gateway

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

Optional Fields

The following data fields are available on Production with contractual agreement:

FieldName	DataType	Description
estLat	Number	Estimated latitude of the device in decimal degrees
estLng	Number	Estimated longitude of the device in decimal degrees

Duplicate uplinks are also available on Production with a contract.

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.

Device Onboarding APIs

Senet offers a series of APIs that can be 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 have Joined the network and are 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, the Task Status API must be called to verify that the requested operation has completed 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 will complete in less than 5 seconds. Activation of 1,000 devices will take around 5 seconds and it should be expected that Activation of 10,000 devices will complete in under 40 seconds.

Please see Device Registration Overview for detailed information on the Device Registration LifeCycle along with associating contracts and other metadata to each device.

Device Registration API

Register new devices on the managed application. See Device Registration to learn how to request a token. Only one task can be running at a time per application. It is recommended for each operation, the Task Status API should be called to verify that the requested operation has completed successfully prior to initiating another job request. 

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 will be used.

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	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
devType	The type of the device.	No	Senet supported type String

Callback Object (Optional)

A callback URL can be specified in the request to receive results after a bulk operation is complete. The server will POST the results in JSON format to the callback URL.

Field	Description	Required	Default Value	Allowed Values
url	The callback URL.	Yes		Fully qualified URL String
headers	JSON object containing key-value pairs which will be added to the callback request as HTTP header fields.	No		Valid JSON object

{  
   "data":[  
      {  
         "devEui":"123000000000ABC0",
         "appKey":"123AAAAAAAAAAAAAAAA000000000ABC0",
         "lat":40.7484445,
         "lng":-73.9878584,
         "tags":"tag1",
         "devType":"WATER_SENSOR"
      },
      {  
         "devEui":"123000000000ABC1",
         "appKey":"123AAAAAAAAAAAAAAAA000000000ABC1"
      }
   ],
   "callback":{  
      "url":"https://example-callback.com/endpoint",
      "headers":{  
         "X-API-Key":"123456789abcdef"
      }
   }
}

Curl Example

curl -H "authorization: <API KEY>" -H "Content-Type: application/json" --insecure -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. Only one task can be running at a time per application. It is recommended for each operation, the Task Status API should be called to verify that the requested operation has completed 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 that will be assigned to the activated devices.	No		Integer
profId	The Device Profile Id that will be assigned to the activated devices.	No		Integer
tags	Informational tags that will be added to the activated devices.	No		Comma separated Strings

Data Object

Field	Description	Required	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
devType	The type of the device.	No	Senet supported type String

Callback Object (Optional)

A callback URL can be specified in the request to receive results after a bulk operation is complete. The server will POST the results in JSON format to the callback URL.

Field	Description	Required	Default Value	Allowed Values
url	The callback URL.	Yes		Fully qualified URL String
headers	JSON object containing key-value pairs which will be added to the callback request as HTTP header fields.	No		Valid JSON object

{  
   "data":[  
      {  
         "devEui":"123000000000ABC0",
         "lat":40.7484445,
         "lng":-73.9878584,
         "tags":"tag1",
         "devType":"WATER_SENSOR"
      },
      {  
         "devEui":"123000000000ABC1"
      }
   ],
   "callback":{  
      "url":"https://example-callback.com/endpoint",
      "headers":{  
         "X-API-Key":"123456789abcdef"
      }
   }
}

Curl Example

curl -H "authorization: <API KEY>" -H "Content-Type: application/json" --insecure -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 that will be assigned to the activated device.	No		Integer
profId	The Device Profile Id that will be assigned to the activated device.	No		Integer
tags	Informational tags that will be added to the activated device.	No		Comma separated Strings
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" --insecure -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 can continue uplinking if it previously joined the network. Deactivated devices cannot join or rejoin the network. A device that is administratively deactivated but continues to communicate on the network is in an active billing state. To avoid billing for deactivated devices, they must not be heard by the network for the entire billing cycle. Only one task can be running at a time per application. It is recommended for each operation, the Task Status API should be called to verify that the requested operation has completed 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

Data Object

Field	Description	Required	Default Value	Allowed Values
devEui	The IEEE EUI-64 identifier for the device.	Yes		Hexadecimal String

Callback Object (Optional)

A callback URL can be specified in the request to receive results after a bulk operation is complete. The server will POST the results in JSON format to the callback URL.

Field	Description	Required	Default Value	Allowed Values
url	The callback URL.	Yes		Fully qualified URL String
headers	JSON object containing key-value pairs which will be added to the callback request as HTTP header fields.	No		Valid JSON object

{  
   "data":[  
      {  
         "devEui":"123000000000ABC0"
      },
      {  
         "devEui":"123000000000ABC1"
      }
   ],
   "callback":{  
      "url":"https://example-callback.com/endpoint",
      "headers":{  
         "X-API-Key":"123456789abcdef"
      }
   }
}

Curl Example

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

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 can be running at a time per application. 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	Allowed Values
appEui	The IEEE EUI-64 identifier for the application.	Yes	Hexadecimal String
profId	The Device Profile Id that will be asigned to the devices.	No	Integer
tagsOperation	The action performed against the existing device tags (only required if tags are being updated).	Yes	APPEND, REPLACE or DELETE
tags	Informational tags that will be applied to the devices.	No	Comma separated list of Strings

Data Object

Field	Description	Required	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
devType	The type of the device.	No	Senet supported type String

{  
   "data":[  
      {  
         "devEui":"123000000000ABC0",
         "lat":43.0775992,
         "lng":-70.7596765,
         "tags":"tag1;tag2",
         "devType":"WATER_SENSOR"
      },
      {  
         "devEui":"123000000000ABC1",
         "lat":40.7484445,
         "lng":-73.9878584,
         "tags":"tag1",
         "devType":"WATER_SENSOR"
      }
   ]
}

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"},{"devEui":"123000000000ABC1","lat":40.7484445,"lng":-73.9878584,"tags":"tag1"}]}' --insecure -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"
}

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 has completed prior to initiating a subsequent request. The status is available for 15 minutes after the task is complete.

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>" --insecure "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.