Sigfox Cloud Integration

To understand the main difference between the Callbacks API and the REST API, you need to understand how the Sigfox Cloud works. 

On Sigfox Cloud, a company is usually represented by a "Group", which contains at least one "Device type". Each device type can be attributed to a "family" of devices. A device type regroups all units of the same product, to allow them to behave exactly in the same way when the Sigfox network receives a message. This is called a same-device behavior. 

A Callback-based integration is defined on a per-device type basis. 

Subscription management is assigned on a per-device basis too. 

All this is represented in the diagram below:  

Callbacks

Callback queries are HTTP requests which are notification messages (one-way only) and are tied to a device type: your server can only obtain data through callbacks, not manage devices through the Cloud. 

When Sigfox Cloud receives a message from an emitting device, it instantly generates a callback message and sends it to your platform's servers. This way, you don't have to regularly check for new data: the system sends any new content your way when it receives it. 

 

REST API

REST API queries are HTTP requests which are bi-directional and work at the Group level: your server can request and receive data from Sigfox Cloud through the API. The Sigfox REST API follows a “fair use” policy: you can make requests as long as you follow the API rate limits and you agree to never use more resources than is nominally required by your application (see the Terms and Conditions).

The REST API allows you to automatically register and manage all your devices on the Sigfox Cloud, including their subscription lifecycles. This way, you don't have to connect to the Sigfox Backend website to perform recurring operations, such as callback declaration, device management, etc. You should use the REST API to handle your registered devices directly from your platform. 

Callbacks are available through device types, as they will be triggered every time any device of this device type sends a message. 

They are used to deliver data and information to your platform, which can then rework into a proper dashboard. 

Callbacks can be of three types: Data, Service, and Error. 

Callback type		Description
DATA	UPLINK	Send uplink messages to a customer platform.
	BIDIR	Send uplink messages to a customer platform and waits for a downlink message from the same platform.
SERVICE	STATUS	To retrieve device battery and temperature information provided by service messages (e.g. keep-alive messages).
	ACKNOWLEDGE	To retrieve the network acknowledgement, confirming the downlink message transmission.
	DATA_ADVANCED	To retrieve optional data, such as geolocation, as well as metadata information. The list of available variables is displayed on the backend upon creation. Some variables are computed over the different base stations which received the messages. This callback is therefore delayed by approximately 30s.
ERROR		In case of communication failure, it informs on whether it is a device issue (based on the keep-alive value defined in the device edition page) or a network issue
EVENT		To be alerted upon device event occurrence. This can be configured at the Group, Device Type or Device level.

Data callbacks are the most immediate use of Callbacks when approaching Sigfox data retrieval. You can create an uplink or a bidirectional callback: 

• UPLINK: Used to deliver uplink messages to a customer platform. 
• BIDIR: Same as the UPLINK type and includes a downlink payload processing. 

To optimize resource usage, it is recommended that customers integrate only with the Advanced data callback service to collect the data, most notably for business cases where delivery time is not critical, where a 30-second delay is acceptable, AND where a downlink mechanism is not required.  

 

Creating a callback 

Callback creation information can be found on the Sigfox Support portal: 

• Custom callback: https://support.sigfox.com/docs/custom-callback-creation 
• Built-in callback: https://support.sigfox.com/docs/callbacks-and-connectors 

 

Custom callbacks

If you wish to instantly send incoming messages to your private server or to a custom service, you will have to complete information about the service: 

• Is it for an uplink message or a downlink message? 
• What is the URL pattern? 
• What are the payload parameters? 
• etc. 

By doing so, you will be able to process data sent from the device server-side and render the information gathered intelligibly for the end-user -- after decoding the hexadecimal frame. 

To get all the details about callback configuration, see this page on the Sigfox Backend portal (connection required).

 

Built-in callbacks

Here is the list of currently available platforms. 

More resources on callbacks

• Callback documentation
• Certificate authority
• Callback error logs
• Callback troubleshooting

Description of the Sigfox REST API  

The Sigfox REST API has a different objective than the Callback API. For instance, after setting up your callbacks, you will be able to receive messages from your device directly on your platform. Great! 

But callbacks are not meant for: 

• Managing a huge list of devices. 
• Registering new devices when customers activate them.  
• Knowing whether is Sigfox coverage at a designated location.  
• Recovering failed callback messages. 
• Automating callback management. 
• ... 

We have built a very powerful REST API which will allow you to automate every required action. Through this API, you can manage every Sigfox-related aspects of your business by yourself, through your platform. 

 

Accessing the REST API 

To access this API, you need to create an API User for yourself. To do so, when logged on Sigfox Cloud, click on your group, and navigate to the "API Access" tab on the left.  

You can browse the API v2 apidoc (in OpenAPI format), which describes the different endpoints available and how to access them. Find more information on the API documentation page. 

More resources on the API:

• API documentation main page
• Global Coverage API
• Timestamps format in API
• API credential creation
• API credentials renewal

Version 2 is a major upgrade introducing usage of simple HTTPS methods such as GET, POST, PUT and DELETE, in addition to extended device management capabilities and standardized OpenAPI specifications (available here: https://support.sigfox.com/apidocs). 

Migrating your implementation of the Sigfox REST API from v1 to v2 means knowing what v2 brings and changes. Here are the main items. 

Generalities 

Fundamentally, everything changes, since endpoints are not the same between v1 and v2.  

Also, the API now has: 

• a time limit of 3 days of messages. It is up to you to store all of your devices messages on your platform if you want to perform long-term calculations and data analysis. 
• a rate limit. Read more here: https://support.sigfox.com/docs/api-rate-limiting

Also: 

• REST verbs. The REST API now fully supports these REST verbs: GET, POST, PUT, DELETE. 
• OpenAPI spec. The API specification has been normalized to the OpenAPI format using industry-standard tools. 
• New resources manageable by APIs: users, API users, profiles, customers, orders (read-only). 
• New features to manage devices and subscription lifecycle. 

Updated Entities 

*Messages* 

The v2 API can only provide the last 3 days of data. 

*New names for endpoint* 

Some operations have been transferred to new endpoints: 

V1	V2
/api/devicetypes/{devicetype-id}/devices?snr={snr}	GET /api/device with device type fields
/api/devicetypes/{devicetype-id}/devices/bulk/create/async	Moved to device resource POST /devices/bulk
/api/devicetypes/{devicetype-id}/registration/{job-id}	GET /devices filtered with device type id which return the PAC per device
/api/devicetypes/{devicetype-id}/id-pac	Supported in GET/devices/{id}
/api/devices/{device-id}/token-state	Integrated in PUT /devices/{id}
/api/devices/token/forbid-renewal	Supported in PUT device not new operation
/api/callbacks/messages/error	Covered by Group/DeviceType/Device messages not sent in API v2

See the v1-v2 traceability matrix (.xlsx) for a full overview.

New Entities 

The Sigfox REST API v2 brings the following new entities: 

• ApiUsers: https://support.sigfox.com/apidocs#tag/ApiUsers
• Profiles: https://support.sigfox.com/apidocs#tag/Profiles
• Tiles: This is for map retrieval:  You can retrieve the Monarch or Public coverage maps in various format to display on a platform. https://support.sigfox.com/apidocs#tag/Tiles

 

New Services 

The Sigfox REST API v2 brings the following new services: 

• Devices entity: lifecycle and "callback not delivered".
• DeviceTypes entity: lifecycle and "callback not delivered".
• Users entity: almost everything is new.

 

Removed Operations 

The Sigfox REST API v2 removes the following new services: 

• Downlink entity. It was mostly administrative functions, not user functions. 
• Device and DeviceType entities:  

  - status => Transferred to PUT /devices/{id} 

  - count => Should come in roadmap 

  - messages deleted => no message purge by API 

  - token renewal => Supported in PUT device not new operation