Devices

Introduction

Devices represent doors, gates, turnstiles, elevators, alarms, and any other devices that can be operated by a controller. Note that some events and commands may refer to devices simply as doors, such as the door.request.allowed event.

The device object

{
  "id": 1,
  "name": "Test Device",
  "connection": 1,
  "port": 1,
  "partition": [
    {
      "id": 0,
      "name": "Default"
    }
  ],
  "type": "primaryReader",
  "publicIcon": "swingingDoor",
  "inputTypes": ["wiegand", "unencryptedOsdp", "encryptedOsdp"],
  "osdpAddress": 0,
  "readerType": "red",
  "readerSerialNumber": "032500000001773C",
  "supportBleCredentials": true,
  "securedReadsOnly": false,
  "delay": 0,
  "dwell": 30,
  "dps": false,
  "propAlarm": false,
  "propDelay": 0,
  "rex": false,
  "forcedAlarm": false,
  "autoOpenAfterFirstAllow": false,
  "authenticationPolicy": "cardOrPin",
  "hardwareVersion": "red1cn.d",
  "serialNumber": "8003323",
  "firmwareVersion": "1.1.41",
  "bootloaderVersion": "1.0.44",
  "startupVersion": "0.3.1",
  "created": "2023-05-17 15:59:30",
  "metadata": {}
}

Property	Type	Description
id	String	The device ID.
name	String	The device name.
connection	Integer	The connection ID.
port	Integer	The port number.
partition	Object[]	An array of partitions that include this device.
type	String	The device type. Possible values include primaryReader, additionalReader, ioDevice, premiumIoDevice, elevatorReader, additionalElevatorReader, and floorRelay.
publicIcon	String	The device icon. Possible values include swingingDoor, swingingGate, rollUpDoor, alarm, light, fan, panicButton, sprinkler, and other.
primaryReader	Integer	The primary reader ID. This only applies if type is set to additionalReader.
inputTypes	String[]	An array of allowed input types. Possible values include wiegand, unencryptedOsdp, and encryptedOsdp.
osdpAddress	Integer	The OSDP address. This only applies if inputTypes includes unencryptedOsdp or encryptedOsdp. Possible values include 0, 1, 2, and 3.
wirelessAddress	String	The wireless address of the device. This only applies if the connection type is set to wirelessCoordinator.
readerType	String	The reader type. Possible values include standard, touch, and red.
readerSerialNumber	String	The reader serial number.
supportBleCredentials	Boolean	Whether the device supports Bluetooth credentials.
securedReadsOnly	Boolean	Whether the device only supports high-security credentials.
delay	Integer	The amount of time (in tenths of a second) the relay will delay before actuating.
dwell	Integer	The amount of time (in tenths of a second) the relay will remain actuated.
dps	Boolean	Whether the door position sensor (DPS) is enabled. This only applies if a DPS is installed.
propAlarm	Boolean	Whether the prop alarm is enabled, which triggers an alarm if a device is left open. This only applies if dps is set to true.
propDelay	Integer	The amount of time (in seconds) a device must be left open before a prop alarm is triggered. This only applies if propAlarm is set to true.
rex	Boolean	Whether the request to exit (REX) sensor is enabled. This only applies if a REX sensor is installed.
forcedAlarm	Boolean	Whether the forced alarm is enabled, which triggers an alarm if a device is forced opened. This only applies if dps is set to true.
autoOpenAfterFirstAllow	Boolean	Whether auto open will be enabled after the first successful access event.
authenticationPolicy	String	The authentication policy for this device. Possible values include null, cardOnly, pinOnly, cardOrPin, and cardAndPin (for two-factor authentication). Note that card refers to all types of credentials (not just cards). If a policy is set for both a rule and its corresponding device, the more restrictive policy will be enforced.
hardwareVersion	String	The controller hardware version.
serialNumber	String	The controller serial number.
firmwareVersion	String	The controller firmware version.
bootloaderVersion	String	The controller bootloader version.
startupVersion	String	The controller startup version.
created	String	The device creation timestamp.
metadata	Object	A user-defined metadata object.

Basic Endpoints

Create a device

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Device",
  "connection": 1,
  "port": 1
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
panel_token	Header	String	Yes	A valid panel token.
name	Body	String	Yes	The device name. This must be unique within a cloud node. The maximum length is 70 characters.
connection	Body	Integer	Yes	The connection ID.
port	Body	Integer	Yes	The port number. This port must not be occupied by another device.
type	Body	String	No	The device type. Possible values include primaryReader (default), additionalReader, ioDevice, premiumIoDevice, elevatorReader, additionalElevatorReader, and floorRelay.
publicIcon	Body	String	No	The device icon. Possible values include swingingDoor (default), swingingGate, rollUpDoor, alarm, light, fan, panicButton, sprinkler, and other.
primaryReader	Body	Integer	No	The primary reader ID. This only applies if type is set to additionalReader.
inputTypes	Body	String[]	No	An array of allowed input types. Possible values include wiegand, unencryptedOsdp, and encryptedOsdp. All types are allowed by default.
osdpAddress	Body	Integer	No	The OSDP address. This only applies if inputTypes includes unencryptedOsdp or encryptedOsdp. Possible values include 0, 1, 2, and 3.
wirelessAddress	Body	String	No	The wireless address of the device. This only applies if the connection type is set to wirelessCoordinator.
readerType	Body	String	No	The reader type. Possible values include standard, touch, and red. The default is standard.
readerSerialNumber	Body	String	No	The reader serial number.
supportBleCredentials	Body	Boolean	No	Whether the device should support Bluetooth credentials.
securedReadsOnly	Body	Boolean	No	Whether the device should only support high-security credentials.
delay	Body	Integer	No	The amount of time (in tenths of a second) the relay should delay before actuating. The minimum value is 0 (default) and the maximum value is 9999.
dwell	Body	Integer	No	The amount of time (in tenths of a second) the relay should remain actuated. The minimum value is 1 and the maximum value is 9999. The default value is 30 (3 seconds).
dps	Body	Boolean	No	Whether the door position sensor (DPS) should be enabled. This only applies if a DPS is installed. The default value is false.
propAlarm	Body	Boolean	No	Whether the prop alarm should be enabled, which triggers an alarm if a device is left open. This only applies if dps is set to true. The default value is false.
propDelay	Body	Integer	No	The amount of time (in seconds) a device must be left open before a prop alarm is triggered. This only applies if propAlarm is set to true. The minimum value is 0 (default) and the maximum value is 9999.
rex	Body	Boolean	No	Whether the request to exit (REX) sensor should be enabled. This only applies if a REX sensor is installed. The default value is false.
forcedAlarm	Body	Boolean	No	Whether the forced alarm should be enabled, which triggers an alarm if a device is forced opened. This only applies if dps is set to true. The default value is false.
autoOpenAfterFirstAllow	Body	Boolean	No	Whether auto open should be enabled after the first successful access event. The default value is false.
authenticationPolicy	Body	String	No	The authentication policy for this device. Possible values include null (default), cardOnly, pinOnly, cardOrPin, and cardAndPin (for two-factor authentication). Note that card refers to all types of credentials (not just cards). If a policy is set for both a rule and its corresponding device, the more restrictive policy will be enforced.
metadata	Body	Object	No	A user-defined metadata object. The data storage limit is 10 KB.

Response

The response contains the ID of the newly created device object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1
}

Retrieve a device

Request

GET https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains a device object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "Test Device",
  "connection": 1,
  "port": 1,
  "partition": [
    {
      "id": 0,
      "name": "Default"
    }
  ],
  "type": "primaryReader",
  "publicIcon": "swingingDoor",
  "inputTypes": ["wiegand", "unencryptedOsdp", "encryptedOsdp"],
  "osdpAddress": 0,
  "readerType": "red",
  "readerSerialNumber": "032500000001773C",
  "supportBleCredentials": true,
  "securedReadsOnly": false,
  "delay": 0,
  "dwell": 30,
  "dps": false,
  "propAlarm": false,
  "propDelay": 0,
  "rex": false,
  "forcedAlarm": false,
  "autoOpenAfterFirstAllow": false,
  "authenticationPolicy": "cardOrPin",
  "hardwareVersion": "red1cn.d",
  "serialNumber": "8003323",
  "firmwareVersion": "1.1.41",
  "bootloaderVersion": "1.0.44",
  "startupVersion": "0.3.1",
  "created": "2023-05-17 15:59:30",
  "metadata": {}
}

Update a device

Request

PUT https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "name": "Test Device",
  "type": "primaryReader",
  "publicIcon": "swingingDoor",
  "connection": 1,
  "port": 1,
  "delay": 0,
  "dwell": 3,
  "dps": false,
  "rex": false,
  "autoOpenAfterFirstAllow": false,
  "authenticationPolicy": "cardOrPin"
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.
name	Body	String	Yes	The device name. This must be unique within a cloud node. The maximum length is 70 characters.
connection	Body	Integer	Yes	The connection ID.
port	Body	Integer	Yes	The port number. This port must not be occupied by another device.
type	Body	String	Yes	The device type. Possible values include primaryReader (default), additionalReader, ioDevice, premiumIoDevice, elevatorReader, additionalElevatorReader, and floorRelay.
publicIcon	Body	String	Yes	The device icon. Possible values include swingingDoor (default), swingingGate, rollUpDoor, alarm, light, fan, panicButton, sprinkler, and other.
primaryReader	Body	Integer	No	The primary reader ID. This only applies if type is set to additionalReader.
inputTypes	Body	String[]	No	An array of allowed input types. Possible values include wiegand, unencryptedOsdp, and encryptedOsdp. All types are allowed by default.
osdpAddress	Body	Integer	No	The OSDP address. This only applies if inputTypes includes unencryptedOsdp or encryptedOsdp. Possible values include 0, 1, 2, and 3.
wirelessAddress	Body	String	No	The wireless address of the device. This only applies if the connection type is set to wirelessCoordinator.
readerType	Body	String	No	The reader type. Possible values include standard, touch, and red. The default is standard.
readerSerialNumber	Body	String	No	The reader serial number.
supportBleCredentials	Body	Boolean	No	Whether the device should support Bluetooth credentials.
securedReadsOnly	Body	Boolean	No	Whether the device should only support high-security credentials.
delay	Body	Integer	Yes	The amount of time (in tenths of a second) the relay should delay before actuating. The minimum value is 0 (default) and the maximum value is 9999.
dwell	Body	Integer	Yes	The amount of time (in tenths of a second) the relay should remain actuated. The minimum value is 1 and the maximum value is 9999. The default value is 30 (3 seconds).
dps	Body	Boolean	Yes	Whether the door position sensor (DPS) should be enabled. This only applies if a DPS is installed. The default value is false.
propAlarm	Body	Boolean	No	Whether the prop alarm should be enabled, which triggers an alarm if a device is left open. This only applies if dps is set to true. The default value is false.
propDelay	Body	Integer	No	The amount of time (in seconds) a device must be left open before a prop alarm is triggered. This only applies if propAlarm is set to true. The minimum value is 0 (default) and the maximum value is 9999.
rex	Body	Boolean	Yes	Whether the request to exit (REX) sensor should be enabled. This only applies if a REX sensor is installed. The default value is false.
forcedAlarm	Body	Boolean	No	Whether the forced alarm should be enabled, which triggers an alarm if a device is forced opened. This only applies if dps is set to true. The default value is false.
autoOpenAfterFirstAllow	Body	Boolean	Yes	Whether auto open should be enabled after the first successful access event. The default value is false.
authenticationPolicy	Body	String	Yes	The authentication policy for this device. Possible values include null (default), cardOnly, pinOnly, cardOrPin, and cardAndPin (for two-factor authentication). Note that card refers to all types of credentials (not just cards). If a policy is set for both a rule and its corresponding device, the more restrictive policy will be enforced.
metadata	Body	Object	No	A user-defined metadata object.

Response

HTTP/1.1 204 No Content

Delete a device

Request

DELETE https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

List all devices

Request

GET https://panel-{{panel_id}}.pdk.io/api/devices HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
page	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
per_page	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains an array of device objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "name": "Test Device 1",
    "connection": 1,
    "port": 1,
    "partition": [
      {
        "id": 0,
        "name": "Default"
      }
    ],
    "type": "primaryReader",
    "publicIcon": "swingingDoor",
    "inputTypes": ["wiegand", "unencryptedOsdp", "encryptedOsdp"],
    "osdpAddress": 0,
    "readerType": "red",
    "readerSerialNumber": "032500000001773C",
    "supportBleCredentials": true,
    "securedReadsOnly": false,
    "delay": 0,
    "dwell": 30,
    "dps": false,
    "propAlarm": false,
    "propDelay": 0,
    "rex": false,
    "forcedAlarm": false,
    "autoOpenAfterFirstAllow": false,
    "authenticationPolicy": "cardOrPin",
    "hardwareVersion": "red2.?",
    "serialNumber": "8003323",
    "firmwareVersion": "1.1.41",
    "bootloaderVersion": "1.0.44",
    "startupVersion": "0.3.1",
    "created": "2023-05-17 15:59:30",
    "metadata": {}
  },
  {
    "id": 2,
    "name": "Test Device 2",
    "connection": 1,
    "port": 2,
    "partition": [
      {
        "id": 0,
        "name": "Default"
      }
    ],
    "type": "primaryReader",
    "publicIcon": "swingingDoor",
    "inputTypes": ["wiegand", "unencryptedOsdp", "encryptedOsdp"],
    "osdpAddress": 1,
    "readerType": "red",
    "readerSerialNumber": "032500000001773D",
    "supportBleCredentials": true,
    "securedReadsOnly": false,
    "delay": 0,
    "dwell": 30,
    "dps": false,
    "propAlarm": false,
    "propDelay": 0,
    "rex": false,
    "forcedAlarm": false,
    "autoOpenAfterFirstAllow": false,
    "authenticationPolicy": "cardOrPin",
    "hardwareVersion": "red2.?",
    "serialNumber": "8003324",
    "firmwareVersion": "1.1.41",
    "bootloaderVersion": "1.0.44",
    "startupVersion": "0.3.1",
    "created": "2023-05-17 15:59:30",
    "metadata": {}
  }
]

Add devices to a partition

Request

PUT https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/devices HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "devices": [1, 2, 3]
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
partition_id	Path	Integer	Yes	The partition ID.
panel_token	Header	String	Yes	A valid panel token.
devices	Body	Integer[]	Yes	An array of device IDs.

Response

HTTP/1.1 204 No Content

Remove a device from a partition

Request

DELETE https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/devices/{{device_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
partition_id	Path	Integer	Yes	The partition ID.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

List all devices on a partition

Request

GET https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/devices HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
partition_id	Path	Integer	Yes	The partition ID.
page	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
per_page	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains an array of device objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "name": "Test Device 1",
    "connection": 1,
    "port": 1,
    "type": "primaryReader",
    "publicIcon": "swingingDoor",
    "inputTypes": ["wiegand", "unencryptedOsdp", "encryptedOsdp"],
    "osdpAddress": 0,
    "readerType": "red",
    "readerSerialNumber": "032500000001773C",
    "supportBleCredentials": true,
    "securedReadsOnly": false,
    "delay": 0,
    "dwell": 30,
    "dps": false,
    "propAlarm": false,
    "propDelay": 0,
    "rex": false,
    "forcedAlarm": false,
    "autoOpenAfterFirstAllow": false,
    "authenticationPolicy": "cardOrPin",
    "hardwareVersion": "red2.?",
    "serialNumber": "8003323",
    "firmwareVersion": "1.1.41",
    "bootloaderVersion": "1.0.44",
    "startupVersion": "0.3.1",
    "created": "2023-05-17 15:59:30",
    "metadata": {}
  },
  {
    "id": 2,
    "name": "Test Device 2",
    "connection": 1,
    "port": 2,
    "type": "primaryReader",
    "publicIcon": "swingingDoor",
    "inputTypes": ["wiegand", "unencryptedOsdp", "encryptedOsdp"],
    "osdpAddress": 1,
    "readerType": "red",
    "readerSerialNumber": "032500000001773D",
    "supportBleCredentials": true,
    "securedReadsOnly": false,
    "delay": 0,
    "dwell": 30,
    "dps": false,
    "propAlarm": false,
    "propDelay": 0,
    "rex": false,
    "forcedAlarm": false,
    "autoOpenAfterFirstAllow": false,
    "authenticationPolicy": "cardOrPin",
    "hardwareVersion": "red2.?",
    "serialNumber": "8003324",
    "firmwareVersion": "1.1.41",
    "bootloaderVersion": "1.0.44",
    "startupVersion": "0.3.1",
    "created": "2023-05-17 15:59:30",
    "metadata": {}
  }
]

Commands

Open and close a device as a person

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/virtual_read HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "personId": 1
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.
personId	Body	Integer	Yes	A person ID.

Response

HTTP/1.1 204 No Content

Open and close a device

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/open_close HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "delay": 30
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.
delay	Body	Integer	Yes	The amount of time (in tenths of a second) the device will remain open before closing. The minimum value is 0 and the maximum value is 9999.

Response

HTTP/1.1 204 No Content

Open a device

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/open HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

Open a device after a delay

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/delay_open HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "delay": 30
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.
delay	Body	Integer	Yes	The amount of delay (in tenths of a second) before the device opens. The minimum value is 0 and the maximum value is 9999.

Response

HTTP/1.1 204 No Content

Close a device

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/close HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

Close a device after a delay

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/delay_close HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "delay": 30
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.
delay	Body	Integer	Yes	The amount of delay (in tenths of a second) before the device closes. The minimum value is 0 and the maximum value is 9999.

Response

HTTP/1.1 204 No Content

Toggle a device's state

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/force_toggle HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

Toggle a device's do not disturb mode

Request

POST https://panel-{{panel_id}}.pdk.io/api/devices/{{device_id}}/dnd HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
device_id	Path	Integer	Yes	The device ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content