API

Introduction

The Registration request allows client applications to register on the SCS system with its callback information, including the callback URL.
To test if the defined application url and header fields are valid SCS posts the following request to your application url:

{
  	"reports":[],
    "registrations":[],
    "deregistrations":[],
    "updates":[],
    "expirations":[],
    "responses":[]
}

If the application isn't reachable or returns an HTTP status code not equal to 200 or 202 the register application request returns with an error and the defined url and header fields are not stored.

Reports Message

Uplink message payload of devices are reported to your registered application endpoint via an array of reports within the application notification message. 

{
    "reports": [
        {
            "serialNumber": "IMEI:351938100103239",
            "timestamp": 1654592153981,
            "subscriptionId": "2689b07b-b15c-40c4-82c2-c603abe99ebb",
            "resourcePath": "uplinkMsg/0/data",
            "value": "01015410ec9ab714000157ad0aca11fa042901",
            "customAttributes": {
                "deviceType": "IMBUILDING CO2"
            }
        }
    ],
    "registrations": [],
    "deregistrations": [],
    "updates": [],
    "expirations": [],
    "responses": []
}

serialNumber

The serial number of IMEI of the device for which the uplink payload is forwarded to the application. In case of UDP, CoAP, LoRA WAN devices the serial numbers are prefixed with the IMEI:.

timestamp

Timestamp in the Unix/epoch format when the message has been forwarded to the application endpoint.

subscriptionId

Id of the subscription which caused the message forwarding to the application endpoint.

resourcePath

Device resource path for which the uplink payload is reported. In case of UDP or CoAP devices the resourcePath is normally set to uplinkMsg/0/data automatically.

value

The uplink payload as it has been received from the device. The payload is device specific and it is NOT interpreted by the SCS platform.

customAttributes

As shown in the screenshot below it is possible to define Uplink Message Tags for each device while it is created. Those Uplink Message Tags are transfered along with each report message as customAttributes. The customAttributes is a dictionary of key/value pairs.

839