Downlinks
Downlinks are messages sent from KPN Things to a device. The API provides two main approaches to sending downlinks:
Actuator-style downlinks (recommended for most cases)
Use the
/downlinksresource.You provide a high-level command, and KPN Things translates it into the correct low-level protocol format using the configured encoder for your device.
This approach is safer and easier to use, since KPN Things handles protocol-specific details.
Connection-specific downlinks (advanced usage)
Use protocol-specific APIs such as
/http/downlinks,/mqtt/downlinks,/sms/downlinks,/lora/downlinks, or/digitalmatter/downlinks.You send downlink payloads in the native format of the underlying connection type.
This allows greater flexibility but comes with risks: you may send commands that disrupt device operation (for example, disabling communication). Use these APIs only when actuator-style downlinks do not meet your requirements.
Choosing the Right API
Use actuator-style downlinks whenever possible. They are protocol-agnostic, simpler, and safer.
Use connection-specific APIs if you need full control over the payload format or protocol-specific features.
Actuator-Style Downlinks
Download the /downlinks specification
String that encodes all necessary information to retrieve a page.
Limit the number of results (per page).
50Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.
createdAt,-nameInclude only downlinks whose tagValue, networkId or message match the search term. The tagValue must match exactly. The networkId and message may match partially. Matching for every query parameter is done case-sensitively.
Include only downlinks created before the provided date and time. The date-time must be in ISO 8601 format.
Include only downlinks created at or after the provided date and time. The date-time must be in ISO 8601 format.
Include only downlinks modified before the provided date and time. The date-time must be in ISO 8601 format.
Include only downlinks modified at or after the provided date and time. The date-time must be in ISO 8601 format.
Page of filtered downlinks. Only downlinks that are accessible to the caller are returned.
A paginated list of downlinks
GET /downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
Page of filtered downlinks. Only downlinks that are accessible to the caller are returned.
No content
A request to create a downlink to be sent to an IoT device.
Optional external identifier that can be provided by API caller to reference the downlink with. Must be unique for the client that owns the device.
someExternalReference123Instruction in SenML format to send to the device. The provided instruction must contain a bn that identifies the device. The SenML instruction will be transformed into a protocol specific downlink using the configured encoder.
[{"bn":"urn:dev:ow:10e2073a01080063:"},{"n":"temperature","u":"Cel","v":23.1},{"n":"heating","u":"/","v":1},{"n":"fan","u":"/","v":0}]The maximum number of retries that should be performed for the downlink.
0Example: 3Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.
^P(?:(\d+D)(T(?:(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)?)|T(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)$The duration after which feedback is expected for the downlink. Must be at least 10 minutes.
PT25HIndicates if this is a dry run.
falseDownlink has been successfully created.
POST /downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Downlink has been successfully created.
No content
Downlink identifier
Downlink has been successfully fetched.
GET /downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
Downlink has been successfully fetched.
No content
Accepts and schedules full or partial cancellation of downlink for further downstream handling.
Downlink identifier
Whether to force the cancellation of the downlink or not.
falseDownlink cancellation has been accepted and scheduled for further downstream processing.
No content
Downlink status does not permit cancellation.
DELETE /downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
No content
HTTP Downlinks
Download the /http/downlinks specification
String that encodes all necessary information to retrieve a page.
Limit the number of results (per page).
50Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.
createdAt,-nameInclude only downlinks for the device with the provided deviceId. The deviceId must match exactly.
Include only HTTP downlinks created before the provided date and time. The date-time must be in ISO 8601 format.
Include only HTTP downlinks created at or after the provided date and time. The date-time must be in ISO 8601 format.
Include only HTTP downlinks modified before the provided date and time. The date-time must be in ISO 8601 format.
Include only HTTP downlinks modified at or after the provided date and time. The date-time must be in ISO 8601 format.
Include only HTTP downlinks whose status matches the provided status. The status must match exactly.
Page of filtered HTTP downlinks. Only downlinks that are accessible to the caller are returned.
A paginated list of HTTP downlinks.
GET /http/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
Page of filtered HTTP downlinks. Only downlinks that are accessible to the caller are returned.
No content
A downlink that is sent to an HTTP device.
Unique identifier for the downlink.
12345678-1234-1234-1234-123456789012The message of the HTTP downlink.
The status of the downlink. Known values include: PENDING, EXECUTING and DONE
The device identifier which this downlink is targeting.
1dca2857-da8c-4e47-991f-f7d13a563e45The timestamp when the downlink was created in the system.
2025-01-02T12:04:32.982ZThe timestamp when the downlink was last modified in the system.
2025-01-02T12:04:32.982ZDuration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.
^P(?:(\d+D)(T(?:(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)?)|T(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)$The duration after which feedback is expected for the downlink. Must be at least 10 minutes.
PT25HIndicates if this is a dry run.
falseThe failure reason of the HTTP downlink. Known values include: CANCELLED, TIMEOUT and EVICTED
HTTP downlink has been successfully created.
POST /http/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
HTTP downlink has been successfully created.
No content
The ID of the HTTP downlink to retrieve.
The requested HTTP downlink.
GET /http/downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
The requested HTTP downlink.
No content
Accepts and schedules full or partial cancellation of a HTTP downlink for further downstream handling.
HTTP downlink identifier.
Whether to force the cancellation of the HTTP downlink or not.
falseHTTP downlink cancellation has been accepted and scheduled for further downstream processing.
No content
HTTP downlink does not permit cancellation.
DELETE /http/downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
No content
LoRa downlinks
Download the /lora/downlinks specification
String that encodes all necessary information to retrieve a page.
Limit the number of results (per page).
50Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.
createdAt,-nameInclude only downlinks for the device with the provided deviceId. The deviceId must match exactly.
Include only LoRa downlinks created before the provided date and time. The date-time must be in ISO 8601 format.
Include only LoRa downlinks at or after the provided date and time. The date-time must be in ISO 8601 format.
Include only LoRa downlinks modified before the provided date and time. The date-time must be in ISO 8601 format.
Include only LoRa downlinks modified at of after the provided date and time. The date-time must be in ISO 8601 format.
Include only LoRa downlinks whose status matches the provided status. The status must match exactly.
Page of filtered LoRa downlinks. Only downlinks that are accessible to the caller are returned.
A paginated list of LoRa downlinks.
GET /lora/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
Page of filtered LoRa downlinks. Only downlinks that are accessible to the caller are returned.
No content
A downlink that is sent to a LoRa IoT device.
Unique identifier for the downlink.
12345678-1234-1234-1234-123456789012The status of the LoRa downlink. Known values include: PENDING, EXECUTING and DONE
The maximum number of retries that should be performed for the downlink.
0Example: 3The number of retries that have been performed for the downlink.
0The device identifier which this downlink is targeting.
014388b0-5244-4ced-9fbf-1088c1c0d328The timestamp when the downlink was created in the system.
2025-04-01T00:00:00.000ZThe timestamp when the downlink was last modified in the system.
2025-05-01T00:00:00.000ZDuration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.
^P(?:(\d+D)(T(?:(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)?)|T(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)$The duration after which feedback is expected for the downlink. Must be at least 10 minutes.
PT25HIndicates if this is a dry run.
falseThe failure reason of the LoRa downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, NOT_ACKNOWLEDGED_BY_DEVICE, FAILED_TO_TRANSMIT_TO_DEVICE, FAILED_TO_ENQUEUE_FOR_TRANSMISSION and EVICTED
LoRa downlink has been successfully created.
POST /lora/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
LoRa downlink has been successfully created.
No content
LoRa downlink identifier.
The LoRa downlink.
GET /lora/downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
The LoRa downlink.
No content
Accepts and schedules full or partial cancellation of a LoRa downlink for further downstream handling.
LoRa downlink identifier.
Whether to force the cancellation of the LoRa downlink or not.
falseLoRa downlink cancellation has been accepted and scheduled for further downstream processing.
No content
LoRa downlink status does not permit cancellation.
DELETE /lora/downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
No content
SMS Downlinks
Download the /sms/downlinks specification
String that encodes all necessary information to retrieve a page.
Limit the number of results (per page).
50Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.
createdAt,-nameInclude only downlinks for the device with the provided deviceId. The deviceId must match exactly.
Include only SMS downlinks created before the provided date and time. The date-time must be in ISO 8601 format.
Include only SMS downlinks at or after the provided date and time. The date-time must be in ISO 8601 format.
Include only SMS downlinks modified before the provided date and time. The date-time must be in ISO 8601 format.
Include only SMS downlinks modified at of after the provided date and time. The date-time must be in ISO 8601 format.
The status of the downlink. Known values include: PENDING, EXECUTING and DONE
Page of filtered SMS downlinks. Only downlinks that are accessible to the caller are returned.
A paginated list of SMS downlinks.
GET /sms/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
Page of filtered SMS downlinks. Only downlinks that are accessible to the caller are returned.
No content
A downlink that is sent to a mobile device.
Unique identifier for the downlink.
12345678-1234-1234-1234-123456789012The ICCID of the SIM card in the mobile device.
8901234567890123456The status of the downlink. Known values include: PENDING, EXECUTING and DONE
The device identifier which this downlink is targeting.
4fa05eed-4db6-4fe5-8cb1-744893286db1The timestamp when the downlink was created in the system.
2025-01-02T12:04:32.982ZThe timestamp when the downlink was last modified in the system.
2025-01-02T12:04:32.982ZThe maximum number of retries that should be performed for the downlink.
0Example: 3The number of retries that have been performed for the downlink.
0Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.
^P(?:(\d+D)(T(?:(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)?)|T(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)$The duration after which feedback is expected for the downlink. Must be at least 10 minutes.
PT25HIndicates if this is a dry run.
falseThe failure reason of the SMS downlink. Known values include: CANCELLED, FAILURE_TO_TRANSMIT_TO_DEVICE, FAILURE_TO_ENQUEUE_FOR_TRANSMISSION, FEEDBACK_TIMEOUT and EVICTED
SMS downlink has been successfully created.
POST /sms/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
SMS downlink has been successfully created.
No content
Accepts and schedules full or partial cancellation of a SMS downlink for further downstream handling.
SMS downlink identifier.
Whether to force the cancellation of the SMS downlink or not.
falseSMS downlink cancellation has been accepted and scheduled for further downstream processing.
No content
SMS downlink status does not permit cancellation.
DELETE /sms/downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
No content
MQTT Downlinks
Download the /mqtt/downlinks specification
String that encodes all necessary information to retrieve a page.
Limit the number of results (per page).
50Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.
createdAt,-nameInclude only downlinks for the device with the provided deviceId. The deviceId must match exactly.
Include only MQTT downlinks created before the provided date and time. The date-time must be in ISO 8601 format.
Include only MQTT downlinks created at or after the provided date and time. The date-time must be in ISO 8601 format.
Include only MQTT downlinks modified before the provided date and time. The date-time must be in ISO 8601 format.
Include only MQTT downlinks modified at or after the provided date and time. The date-time must be in ISO 8601 format.
The status of the downlink. Known values include: PENDING, EXECUTING and DONE
Page of filtered MQTT downlinks. Only downlinks that are accessible to the caller are returned.
A paginated list of MQTT downlinks.
GET /mqtt/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
Page of filtered MQTT downlinks. Only downlinks that are accessible to the caller are returned.
No content
A downlink that is sent to an MQTT device.
Unique identifier for the downlink.
12345678-1234-1234-1234-123456789012The status of the downlink. Known values include: PENDING, EXECUTING and DONE
The device identifier which this downlink is targeting.
7f97ccf0-2ae1-4e1f-bd3e-d901f31d801bThe timestamp when the downlink was created in the system.
2025-01-01T11:22:33.456ZThe timestamp when the downlink was last modified in the system.
2025-01-01T11:22:33.456ZDuration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.
^P(?:(\d+D)(T(?:(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)?)|T(\d+H)?(\d+M)?(\d+(\.\d{1,9})?S)?)$The duration after which feedback is expected for the downlink. Must be at least 10 minutes.
PT25HWhether or not this is a 'test' downlink that should not be delivered. If true the system will prevent actual delivery of the downlink to the MQTT account and pretend instead that successful delivery has occurred. This mode may be used to test your configuration within KPN Things without requiring a fully functional MQTT device.
falseThe failure reason of the MQTT downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, FAILED_TO_TRANSMIT_TO_DEVICE
MQTT downlink has been successfully created.
POST /mqtt/downlinks HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
MQTT downlink has been successfully created.
No content
MQTT downlink identifier.
The created MQTT downlink.
GET /mqtt/downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
The created MQTT downlink.
No content
MQTT downlink identifier.
Whether to force the cancellation of the MQTT downlink or not.
falseMQTT downlink cancellation has been accepted and scheduled for further downstream processing.
No content
MQTT downlink status does not permit cancellation.
DELETE /mqtt/downlinks/{downlinkId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer JWT
Accept: */*
No content
Last updated
Was this helpful?