Devices

Download the specification

In addition to the standard create, retrieve, update, delete, and list actions, devices expose two important sub-collections.

The device-groups sub-resource allows you to view and manage the groups a device belongs to, complementing the platform’s top-level /device-groups resource.

The network-adapters sub-resource provides access to the physical connectivity interfaces of a device—such as cellular (IMEI-based), LoRa (DevEUI-based), or generic internet adapters—which determine how the device connects to the platform.

Retrieve devices, filtered by search term and / or client ID.

get

Retrieve all devices that match the query parameters given. If a search parameter is provided, devices whose name or description (partially) match are returned.

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

cursorstring · cursorOptional

String that encodes all necessary information to retrieve a page.

limitintegerOptional

Limit the number of results (per page).

Default: 50

sortstringOptional

Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.

Example: createdAt,-name

qstring · min: 1Optional

Include only devices whose name or description contain the search term. Matching is done case-insensitively.

clientIdstring · uuidOptional

Include only owned devices that match the provided clientId. If clientId is omitted, all owned devices are included.

barcodestringOptional

Include only devices owned by the client partially matching barcode.

deviceSpecificationIdstring · uuid[]Optional

Filter devices by their device specification.

Example: null

createdBeforestring · date-timeOptional

Include only devices created before the provided date and time. The date-time must be in ISO 8601 format.

createdSincestring · date-timeOptional

Include only devices created at or after the provided date and time. The date-time must be in ISO 8601 format.

modifiedBeforestring · date-timeOptional

Include only devices modified before the provided date and time. The date-time must be in ISO 8601 format.

modifiedSincestring · date-timeOptional

Include only devices modified at or after the provided date and time. The date-time must be in ISO 8601 format.

Responses

200

Page of filtered devices. Only devices that are accessible to the caller are returned.

application/json

A paginated list of devices

and

400

Request is missing required information or invalid

application/problem+json

get

/devices

HTTPcURLJavaScriptPython

GET /devices HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Create a new device.

post

Create a new device.

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

idstring · uuidRead-onlyOptional

The id of the device

Example: 36e75427-4c6e-438c-89b5-0cbdb0d4068c

createdAtstring · date-timeRead-onlyOptional

The timestamp when the device is created in the system.

Example: 2024-12-31T23:00:00.000Z

createdBystringRead-onlyOptional

The user who created the device.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

modifiedAtstring · date-timeRead-onlyOptional

The timestamp when the device is last modified in the system.

Example: 2024-12-31T23:00:00.000Z

modifiedBystringRead-onlyOptional

The user who last modified the device.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

namestring · min: 1 · max: 255Required

Name of this device

Example: My first devicePattern: ^(?!\s*$).+

statusstringOptional

Status of the device. Known values include: ACTIVE and INACTIVE

barcodestringOptional

Barcode of the device

Example: 123456789

descriptionstring · max: 255Optional

Description of this device

Example: Device to explore KPN Things

clientIdstring · uuidRequired

ID of owning client

Example: 7098dc22-fed5-4d9e-8e68-6c6f853eac0c

projectIdstring · uuidRequired

ID of the project the device belongs to

Example: b6a883a8-41f9-428e-a8a1-4597de54fec6

deviceSpecificationIdstring · uuidRequired

ID of the device specification of the device

Example: 9c359e94-ace1-448c-8ac9-443a7d3d963f

Responses

201

The newly created device.

application/json

400

Request is missing required information or invalid

application/problem+json

post

/devices

HTTPcURLJavaScriptPython

POST /devices HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

No content

Retrieve a device by ID.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

Query parameters

Responses

200

The device.

application/json

Device with optional embedded entities

400

Request is missing required information or invalid

application/problem+json

get

/devices/{deviceId}

HTTPcURLJavaScriptPython

GET /devices/{deviceId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a device.

put

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

Body

application/json

idstring · uuidRead-onlyOptional

The id of the device

Example: 36e75427-4c6e-438c-89b5-0cbdb0d4068c

createdAtstring · date-timeRead-onlyOptional

The timestamp when the device is created in the system.

Example: 2024-12-31T23:00:00.000Z

createdBystringRead-onlyOptional

The user who created the device.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

modifiedAtstring · date-timeRead-onlyOptional

The timestamp when the device is last modified in the system.

Example: 2024-12-31T23:00:00.000Z

modifiedBystringRead-onlyOptional

The user who last modified the device.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

namestring · min: 1 · max: 255Required

Name of this device

Example: My first devicePattern: ^(?!\s*$).+

statusstringOptional

Status of the device. Known values include: ACTIVE and INACTIVE

barcodestringOptional

Barcode of the device

Example: 123456789

descriptionstring · max: 255Optional

Description of this device

Example: Device to explore KPN Things

clientIdstring · uuidRequired

ID of owning client

Example: 7098dc22-fed5-4d9e-8e68-6c6f853eac0c

projectIdstring · uuidRequired

ID of the project the device belongs to

Example: b6a883a8-41f9-428e-a8a1-4597de54fec6

deviceSpecificationIdstring · uuidRequired

ID of the device specification of the device

Example: 9c359e94-ace1-448c-8ac9-443a7d3d963f

Responses

200

The updated device.

application/json

idstring · uuidRead-onlyOptional

The id of the device

Example: 36e75427-4c6e-438c-89b5-0cbdb0d4068c

createdAtstring · date-timeRead-onlyOptional

The timestamp when the device is created in the system.

Example: 2024-12-31T23:00:00.000Z

createdBystringRead-onlyOptional

The user who created the device.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

modifiedAtstring · date-timeRead-onlyOptional

The timestamp when the device is last modified in the system.

Example: 2024-12-31T23:00:00.000Z

modifiedBystringRead-onlyOptional

The user who last modified the device.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

namestring · min: 1 · max: 255Required

Name of this device

Example: My first devicePattern: ^(?!\s*$).+

statusstringOptional

Status of the device. Known values include: ACTIVE and INACTIVE

barcodestringOptional

Barcode of the device

Example: 123456789

descriptionstring · max: 255Optional

Description of this device

Example: Device to explore KPN Things

clientIdstring · uuidRequired

ID of owning client

Example: 7098dc22-fed5-4d9e-8e68-6c6f853eac0c

projectIdstring · uuidRequired

ID of the project the device belongs to

Example: b6a883a8-41f9-428e-a8a1-4597de54fec6

deviceSpecificationIdstring · uuidRequired

ID of the device specification of the device

Example: 9c359e94-ace1-448c-8ac9-443a7d3d963f

put

/devices/{deviceId}

HTTPcURLJavaScriptPython

PUT /devices/{deviceId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

200

The updated device.

No content

Delete a device.

delete

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

Responses

204

Device has been deleted successfully.

409

Conflict - Multiple possible reasons

application/json

delete

/devices/{deviceId}

HTTPcURLJavaScriptPython

DELETE /devices/{deviceId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Retrieve the device groups a device is linked to.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

Query parameters

createdBeforestring · date-timeOptional

Include only links created before the provided date and time. The date-time must be in ISO 8601 format.

createdSincestring · date-timeOptional

Include only links created at or after the provided date and time. The date-time must be in ISO 8601 format.

cursorstring · cursorOptional

String that encodes all necessary information to retrieve a page.

limitintegerOptional

Limit the number of results (per page).

Default: 50

sortstringOptional

Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.

Example: createdAt,-name

Responses

200

Page of devices groups linked to the specified device.

application/json

A paginated list of device to device group links

and

get

/devices/{deviceId}/device-groups

HTTPcURLJavaScriptPython

GET /devices/{deviceId}/device-groups HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Page of devices groups linked to the specified device.

No content

Retrieve the link between a device and a device group.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

deviceGroupIdstring · uuidRequired

The ID of the device group for which to retrieve the link to the device.

Query parameters

Responses

200

The link between the specified device and device group.

application/json

DeviceDeviceGroupLink with optional embedded entities

get

/devices/{deviceId}/device-groups/{deviceGroupId}

HTTPcURLJavaScriptPython

GET /devices/{deviceId}/device-groups/{deviceGroupId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

The link between the specified device and device group.

No content

Retrieve the network adapters attached to a device.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

Query parameters

typestringOptional

Include only network adapters of this type. Known values are: cellular, generic, lora.

Responses

200

List of network adapters attached to the specified device.

application/json

A list of network adapters

get

/devices/{deviceId}/network-adapters

HTTPcURLJavaScriptPython

GET /devices/{deviceId}/network-adapters HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of network adapters attached to the specified device.

No content

Add a network adapter to a device

post

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

Body

application/json

A network adapter

or

or

Responses

201

The newly created network adapter.

application/json

post

/devices/{deviceId}/network-adapters

HTTPcURLJavaScriptPython

POST /devices/{deviceId}/network-adapters HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

201

The newly created network adapter.

No content

Update a network adapter.

put

The CellularNetworkAdapter.imei, GenericNetworkAdapter.dvnUuid and LoraNetworkAdapter.devEui properties may not be updated. Attempting an update with a value identical to the existing network adapter is a no-op and results in a 200 OK response returning the existing network adapter. Update attempts with different values will result in a 400 Bad Request response.

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

adapterIdstring · uuidRequired

The ID of the network adapter to update.

Body

application/json

A network adapter

or

or

Responses

200

The updated network adapter.

application/json

A network adapter

or

or

put

/devices/{deviceId}/network-adapters/{adapterId}

HTTPcURLJavaScriptPython

PUT /devices/{deviceId}/network-adapters/{adapterId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

200

The updated network adapter.

No content

Delete a network adapter.

delete

Required scopes

This endpoint requires the following scopes:

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdone ofRequired

A device identifier in one of several supported formats.

string · uuidOptional

Things Device UUID

or

stringOptional

IMEI-based device ID

Pattern: (?i)^imei:[0-9]{15,16}$

or

stringOptional

LoRaWAN DevEUI device ID

Pattern: (?i)^deveui:[a-f0-9]{16}$

or

stringOptional

DVNUUID-based device ID

Pattern: (?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$

or

stringOptional

IMEI-based device URN

Pattern: (?i)^urn:dev:imei:[0-9]{15,16}:?$

or

stringOptional

LoRaWAN DevEUI device URN

Pattern: (?i)^urn:dev:deveui:[a-f0-9]{16}:?$

or

stringOptional

DVNUUID-based device URN

Pattern: (?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$

adapterIdstring · uuidRequired

The ID of the network adapter to delete.

Responses

204

Network adapter has been deleted successfully.

delete

/devices/{deviceId}/network-adapters/{adapterId}

HTTPcURLJavaScriptPython

DELETE /devices/{deviceId}/network-adapters/{adapterId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

Network adapter has been deleted successfully.

No content