Tenant Portal Unit Device

You can use tenant portal API calls to obtain information about unit devices, to make changes to devices, or to delete devices.
New for 5.8

The following table lists the properties that can be used in the body of a device-related request and/or are provided in the response body. (In the "Optional" column, if a default value is applicable, it is listed in angle brackets (< >).

Resource: UnitDevice

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
guid String No No No The unique identifier for this device
type String <Enum> No Yes No

The type of device, either "TENANT" or "GUEST"; as a query parameter: devices?type=TENANT
displayName String Yes No yes The display name for this device.
description String Yes No yes The description of the device.
macAddress String No No No The MAC address for this device.

Units URIs and Actions

The following table indicates the URIs that you can append to the root URI, along with the actions you can take, and possible return codes you can receive.

Units URIs and Actions

URI Action Description Return Codes
/properties/{prop_guid}/units/{guid}/devices GET

Returns the list of devices that belong to the unit (and guest if you have a "guest dpsk"). This is only for the tenant portal. To manage these via the Cloudpath ES authentication, use the DPSK API directly. The unit provides links to the dpsks.

404 - Not found

401 - Unauthorized

200 - OK
/properties/{prop_guid}/units/{guid}/devices/{deviceGuid} GET Returns details about the specified device that belongs to the unit (and guest if you have a "guest dpsk"). This is only for the tenant portal. To manage these via Cloudpath ES authentication, use the DPSK API directly. The unit provides links to the dpsks.

404 - Not found

401 - Unauthorized

200 - OK
/properties/{prop_guid}/units/{guid}/devices/{deviceGuid} PUT Only supports changing the display name and description on the device.

404 - Not found

401 - Unauthorized

200 - OK
/properties/{prop_guid}/units/{guid}/devices/{deviceGuid} DELETE Deletes the specified device that belongs to the unit or guest. This is only for the tenant portal.  

Example of Using GET for Unit Devices

This example demonstrates how to obtain information about all devices within one property.

URI:

This example uses the following URI: 

https://Jeff245.cloudpath.net/admin/rest/tenant/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/Unit-f59f2c93-6786-4d8e-adad-2e44d33df399/devices

where:

  • https://Jeff245.cloudpath.net/admin/rest/tenant is the root URI of the Cloudpath system being used (must include https, as shown)
  • yRCjJObWR6ER is an example of an API key generated from the Configuration > API Keys section of the Cloudpath UI
  • Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0 is the GUID of the property.
  • Unit-f59f2c93-6786-4d8e-adad-2e44d33df399 is the GUID of the unit from which you want to obtain a list of devices.

Request Headers:

The following table shows the required request headers for this URI example, with an example value of an active token that must be pasted into the Authorization header value:

Request Headers

Key Value
Content-type application/json
Authorization eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBcGFydG1lbnQgMSIsImFjY2Vzc1Rva2VuIjoiWkFZZGxMM0ciLCJwcm9wZXJ0eUd1aWQiOiJQcm9wZXJ0eS1hZmFjY2RmOC01ZTM5LTQxY2UtOTA5OC05NzQ3Y2MzOGFhYTAiLCJ1bml0R3VpZCI6IlVuaXQtZjU5ZjJjOTMtNjc4Ni00ZDhlLWFkYWQtMmU0NGQzM2RmMzk5IiwiYXBpS2V5IjoieVJDakpPYldSNkVSIiwiaWF0IjoxNjE0MTUxMDc4LCJleHAiOjE2MTQxNTEzNzh9.wJpeI8zW7FGynjfFGel1gpjKev_ug217WQBiFziXcls

Request Body:

None required.

Action:

Use the GET action to send the request.

Response Body:

Once the request is sent, you will receive a "Status: 200 OK" if the GET is successful. The response body provides information about all existing devices in the unit that was specified; in this case only one device belonged to the unit, as shown below. 

{
    "page": {
        "page": 1,
        "pageSize": 1,
        "totalCount": 1
    },
    "contents": [
        {
            "guid": "AccountDpskDevice-1c41324f-28e8-41e9-a74c-09d2db59deac",
            "type": "TENANT",
            "displayName": "Andy's laptop",
            "macAddress": "112233445566",
            "description": "",
            "links": [
                {
                    "rel": "units",
                    "href": "https://jeff245.cloudpath.net/admin/rest/tenant/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/Unit-f59f2c93-6786-4d8e-adad-2e44d33df399",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/rest/tenant/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/Unit-f59f2c93-6786-4d8e-adad-2e44d33df399/devices/AccountDpskDevice-1c41324f-28e8-41e9-a74c-09d2db59deac",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Parent topic: Tenant Portal APIs