Device

The APIs here are designed for device management, including obtaining device lists, device information, device statuses, device configurations, and more.

Fetch Devices

Obtain a list of all current devices. The device ID is required for enrolling an NFC card.

Request URL: /api/v1/developer/devices
Permission Key: view:device
Method: GET

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Token required for authentication and access control.

Query Parameters

Parameter	Required	Type	Description	Example
refresh	F	String	Refresh the device cache. If true, fetches real-time device info but may be slower.	refresh=true

Response Body

Parameter	Required	Type	Description	Purpose	Related API
id	T	String	Identity ID of the device.	Used for enrolling an NFC card.	/api/v1/developer/credentials/nfc_cards sessions
name	T	String	Name of the device.
type	T	String	Device model type (e.g., UA-G2-PRO, UAH-DOOR).
alias	T	String	Alias of the device.
capabilities	T	Array[String]	List of device capabilities (e.g., pin_code, nfc, face, qr_code).
connected_uah_id	T	String	MAC address of the connected UA Hub (empty for hubs themselves).
is_adopted	T	Boolean	Whether the device has been adopted.
is_connected	T	Boolean	Whether the device is currently connected.
is_managed	T	Boolean	Whether the device is managed.
is_online	T	Boolean	Whether the device is online.
location_id	T	String	Door ID the device is bound to.

Note: The data field is a nested array (array of arrays). Each inner array groups devices by door/location.

Request Sample: Shell/cURL

bash

curl '{host}/api/v1/developer/devices?refresh=true' \
-H 'Authorization: Bearer wHFmHR*****kD6wHg' \
-H 'accept: application/json' \
--insecure

Response Body

json

{
  "code": "SUCCESS",
  "data": [
    [
      {
        "alias": "",
        "capabilities": [
          "pin_code",
          "nfc",
          "face",
          "qr_code",
          "is_reader",
          "support_reboot"
        ],
        "connected_uah_id": "58d61f25c2d5",
        "id": "58d61f309629",
        "is_adopted": true,
        "is_connected": true,
        "is_managed": true,
        "is_online": true,
        "location_id": "2ad41f5a-55ca-4751-b36e-432833638c62",
        "name": "UA G2 Pro 9629",
        "type": "UA-G2-PRO"
      },
      {
        "alias": "",
        "capabilities": [
          "unlock_failure_limit",
          "emergency_settings",
          "is_hub",
          "pin_code"
        ],
        "connected_uah_id": "",
        "id": "58d61f25c2d5",
        "is_adopted": true,
        "is_connected": true,
        "is_managed": true,
        "is_online": true,
        "location_id": "2ad41f5a-55ca-4751-b36e-432833638c62",
        "name": "UA-HUB-DOOR-C2D5",
        "type": "UAH-DOOR"
      }
    ]
  ],
  "msg": "success"
}

Fetch Access Device's Access Method Settings

This API allows you to fetch the current access method settings of an Access device.

Request URL: /api/v1/developer/devices/:device_id/settings
Permission Key: view:device
Method: GET
UniFi Access Requirement: Version 3.3.10 or later

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Token required for authentication and access control.

Request Path

Parameter	Required	Type	Description	How to Get It?
device_id	T	String	Unique ID of the device.	Get it from the API /api/v1/developer/devices

Request Sample: Shell/cURL

bash

curl --location 'https://192.168.1.1:12445/api/v1/developer/devices/942a6f4247b2/settings' \
--header 'Authorization: Bearer bphw1H4jw7q9uQ751PN3Nw'

Response Body

Parameter	Type	Description
nfc	Object	NFC access method setting.
nfc.enabled	String	Indicates whether the NFC access method is enabled ("true" or "false").
bt_tap	Object	Mobile Tap (via Bluetooth) access method setting.
bt_tap.enabled	String	Indicates whether Mobile Tap is enabled ("true" or "false").
bt_button	Object	Mobile Unlock (via Bluetooth) access method setting.
bt_button.enabled	String	Indicates whether Mobile Unlock is enabled ("true" or "false").
bt_shake	Object	Mobile Shake (via Bluetooth) access method setting.
bt_shake.enabled	String	Indicates whether Mobile Shake is enabled ("true" or "false").
mobile_wave	Object	Mobile Wave access method setting.
mobile_wave.enabled	String	Indicates whether Mobile Wave is enabled ("true" or "false").
pin_code	Object	PIN access method setting.
pin_code.enabled	String	Indicates whether PIN is enabled ("true" or "false").
pin_code.pin_code_shuffle	String	Determine whether PIN shuffle is enabled ("true" or "false").
face	Object	Face Unlock access method setting.
face.enabled	String	Determine whether Face Unlock is enabled ("true" or "false").
face.anti_spoofing_level	String	enum anti_spoofing_level {high, medium, no} Anti-spoofing security level for Face Unlock.
face.detect_distance	String	enum detect_distance {near, medium, far} Face Unlock detection distance setting.
wave	Object	Hand Wave access method setting.
wave.enabled	String	Indicates whether Hand Wave is enabled ("true" or "false").
qr_code	Object	QR code access method setting.
qr_code.enabled	String	Indicates whether QR code is enabled ("true" or "false").
touch_pass	Object	Touch Pass access method setting.
touch_pass.enabled	String	Indicates whether Touch Pass is enabled ("true" or "false").

Response Sample

json

{
  "code": "SUCCESS",
  "data": {
    "access_methods": {
      "bt_button": {
        "enabled": "yes"
      },
      "bt_tap": {
        "enabled": "yes"
      },
      "face": {
        "anti_spoofing_level": "no",
        "detect_distance": "far"
      },
      "nfc": {
        "enabled": "yes"
      },
      "pin_code": {
        "enabled": "yes",
        "pin_code_shuffle": "no"
      },
      "qr_code": {
        "enabled": "yes"
      },
      "touch_pass": {
        "enabled": "yes"
      }
    },
    "device_id": "942a6f4247b2"
  },
  "msg": "success"
}

Update Access Device's Access Method Settings

This API allows you to update the access method settings of an Access device.

Request URL: /api/v1/developer/devices/:device_id/settings
Permission Key: edit:device
Method: PUT \
UniFi Access Requirement: Version 3.3.10 or later

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Bearer Token required for authentication and access control.
Content-Type	T	String	Must be application/json.

Request Path

Parameter	Required	Type	Description	How to Get It?
device_id	T	String	Unique ID of the device.	Get it from the API /api/v1/developer/devices

Request Body

Parameter	Required	Type	Description	Example	How to Get It?
nfc	F	Object	NFC access method setting.
nfc.enabled	F	String	Indicates whether the NFC access method is enabled ("true" or "false").	"true"
bt_tap	F	Object	Mobile Tap (via Bluetooth) access method setting.
bt_tap.enabled	F	String	Indicates whether Mobile Tap is enabled ("true" or "false").	"true"
bt_button	F	Object	Mobile Unlock (via Bluetooth) access method setting.
bt_button.enabled	F	String	Indicates whether Mobile Unlock is enabled ("true" or "false").	"true"
bt_shake	F	Object	Mobile Shake (via Bluetooth) access method setting.
bt_shake.enabled	F	String	Indicates whether Mobile Shake is enabled ("true" or "false").	"false"
mobile_wave	F	Object	Mobile Wave access method setting.
mobile_wave.enabled	F	String	Indicates whether Mobile Wave is enabled ("true" or "false").	"true"
pin_code	F	Object	PIN access method setting.
pin_code.enabled	F	String	Indicates whether PIN is enabled ("true" or "false").	"true"
pin_code.pin_code_shuffle	F	String	Indicates whether PIN shuffle is enabled ("true" or "false").	"false"
face	F	Object	Face Unlock access method setting.
face.enabled	F	String	Indicates whether Face Unlock is enabled ("true" or "false").	"true"
face.anti_spoofing_level	F	String	enum anti spoofing_level {high, medium, no} Anti spoofing security level for Face Unlock.	"medium"
face.detect_distance	F	String	enum detect_distance {near, medium, far} Face Unlock detection distance setting.	"medium"
wave	F	Object	Hand Wave access method setting.
wave.enabled	F	String	Indicates whether Hand Wave is enabled ("true" or "false").	"false"
qr_code	F	Object	QR code access method setting.
qr_code.enabled	F	String	Indicates whether QR code is enabled ("true" or "false").	"true"
touch_pass	F	Object	Touch Pass access method setting.
touch_pass.enabled	F	String	Indicates whether Touch Pass is enabled ("true" or "false").	"true"

NOTE: pin_code.pin_code_shuffle setting only takes effect when pin_code.enabled is set to "true" .

NOTE: face.anti_spoofing_level and face.detect_distance settings only take effect when face.enabled is set to "true" .

NOTE: anti_spoofing_level and detect_distance must use valid combinations to adjust Face Unlock sensitivity. The following combinations are supported: no/far , no/medium , medium/near , high/near . Only these combinations will take effect.

Request Sample: Shell/cURL

bash

curl --location --request PUT \
'https://192.168.1.1:12445/api/v1/developer/devices/942a6f4247b2/settings' \
--header 'Authorization: Bearer N8oZJZ6U16i4mN6ZnRhw/A' \
--header 'Content-Type: application/json' \
--data '{
    "access_methods": {
        "bt_button": { "enabled": "yes" },
        "bt_tap": { "enabled": "yes" },
        "face": { "anti_spoofing_level": "medium", "detect_distance": "medium" },
        "nfc": { "enabled": "yes" },
        "pin_code": { "enabled": "yes", "pin_code_shuffle": "no" },
        "qr_code": { "enabled": "yes" },
        "touch_pass": { "enabled": "yes" }
    }
}'

Response Sample

json

{
  "code": "SUCCESS",
  "data": "success",
  "msg": "success"
}

Trigger Doorbells

This API allows you to trigger the doorbell on an Intercom or Reader Pro.

Request URL: /api/v1/developer/devices/:device_id/doorbell
Permission Key: edit:device
Method: POST
UniFi Access Requirement: Version 4.0.10 or later

Request Header

Parameter	Required	Type	Description
Authorization	T	String	Bearer Token required for authentication and access control.
Content-Type	T	String	Must be application/json.

Request Path

Parameter	Required	Type	Description	How to Get It?
device_id	T	String	Unique ID of the reader.	Get it from the API /api/v1/developer/devices

Request Body

Parameter	Required	Type	Description	Example
room_name	T	String	Specifies the Intercom's directory name to trigger the doorbell. Use empty string to ring the default doorbell.	"intercom directory name"
cancel	F	Boolean	If set to true, cancels the previous doorbell if it's still ringing.	false

Note (verified against live API): room_name is required — omitting it or sending an empty body returns CODE_PARAMS_INVALID. An empty string "" is accepted and rings the default doorbell.

Request Sample: Shell/cURL

yaml

curl --location 'https://192.168.1.1:12445/api/v1/developer/devices/788a20c002c7/doorbell' \
--header 'Authorization: Bearer qw8wle29QpEiUuRzdraOdoLQirvukxPT' \
--header 'Content-Type: application/json' \
--data '{ "room_name": "intercom directory name", "cancel": true }'

Response Sample

json

{
  "code": "SUCCESS",
  "data": "success",
  "msg": "success"
}

/access_policies

/nfc_cards

/delete

/pin_codes

/license_plates

/avatar

/identity/assignments

/touch_passes/{touch_pass_id}

/license_plates/{license_plate_id}

/invitations

/assignments

/users

/delete

/all

/access_policies

/identity/assignments

/nfc_cards

/delete

/pin_codes

/qr_codes

/license_plates

/{id}

/{id}

/sessions

/{id}

/tokens

/{token}

/import

/search

/assignable

/{id}

/unlock

/lock_rule

/settings

/doorbell

/export

/resource/{id}

Device ​

Fetch Devices ​

Request Header ​

Query Parameters ​

Response Body ​

Request Sample: Shell/cURL ​

Response Body ​

Fetch Access Device's Access Method Settings ​

Request Header ​

Request Path ​

Request Sample: Shell/cURL ​

Response Body ​

Response Sample ​

Update Access Device's Access Method Settings ​

Request Header ​

Request Path ​

Request Body ​

Request Sample: Shell/cURL ​

Response Sample ​

Trigger Doorbells ​

Request Header ​

Request Path ​

Request Body ​

Request Sample: Shell/cURL ​

Response Sample ​

Device

Fetch Devices

Request Header

Query Parameters

Response Body

Request Sample: Shell/cURL

Response Body

Fetch Access Device's Access Method Settings

Request Header

Request Path

Request Sample: Shell/cURL

Response Body

Response Sample

Update Access Device's Access Method Settings

Request Header

Request Path

Request Body

Request Sample: Shell/cURL

Response Sample

Trigger Doorbells

Request Header

Request Path

Request Body

Request Sample: Shell/cURL

Response Sample