Tenant Portal Units
The following table lists the properties that can be used in the body of a units-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: Unit
| Property Name | Type | Editable | Sort/Filter | Optional in Request/Response Body? | Description |
|---|---|---|---|---|---|
| guid | String | No | Yes | No | The unique identifier for this unit. |
| number | String | Yes | Yes | No | The display name for this unit; must be unique. |
| description | String | Yes | Yes | yes | A description of the unit. |
| status | String <Enum> | Yes | Yes | Yes | Can be changed to reset the account access token only: "TOKEN_RESET" |
| secret | String | Yes | No | No | The current secret that is used for tenant devices. A request for a null or empty string is ignored. |
| guestSecret | String | Yes | No | Yes | The current secret that is used for guest devices in the unit. If the unit supports guest devices, this must be provided. However, if this property is provided but guest devices are not supported for this unit, this value is ignored. A request for a null or empty string is also ignored. |
| maxDeviceCount | int | Yes | no | Yes | The maximum number of devices permitted for this unit. |
| guestMaxDeviceCount | int | Yes | no | Yes | The maximum number of guest devices permitted for this unit. |
|
contact (embedded) |
Contact <Object> | Yes | Neither | Yes | Contact information for this unit. For a definition of the Contact resource, see Resource: Contact. All "contact" properties can be set from this URI. |
| links | Link | No | No | Yes |
Contains the following link as hrefs for use in other API calls: |
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/login | POST | This URI is required to obtain an authorization token that needs to be included in the Request header of all tenant portal APIs. For instructions, refer to Tenant Portal API Requirements. |
401 - Unauthorized 200 - OK |
| /properties/{prop_guid}/units/{guid} | GET | Returns details about the specified unit. |
401 - Unauthorized 200 - OK |
| PUT | Updates details about the unit. If the passphrase or unit name are null, a "409 - Conflict" error is returned. |
409 - Conflict 401 - Unauthorized 200 - OK |
Example of Using GET for Units
This example demonstrates how to obtain information about a specified unit within a property.
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
- 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.
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.eyJzdWIiOiJBcGFydG1lbnQgMSIsImFjY2Vzc1Rva2VuIjoiWkFZZGxMM0ciLCJwcm9wZXJ0eUd1aWQiOiJQcm9wZXJ0eS1hZmFjY2RmOC01ZTM5LTQxY2UtOTA5OC05NzQ3Y2MzOGFhYTAiLCJ1bml0R3VpZCI6IlVuaXQtZjU5ZjJjOTMtNjc4Ni00ZDhlLWFkYWQtMmU0NGQzM2RmMzk5IiwiYXBpS2V5IjoieVJDakpPYldSNkVSIiwiaWF0IjoxNjE0MTQ5MTg5LCJleHAiOjE2MTQxNDk0ODl9.nirUAxLkinvXRZzlTSjbvPq4vSdB1OiISPoVDsnVwho |
None required.
Use the GET action to send the request.Once the request is sent, you will receive a "Status: 200 OK" if the GET is successful. The response body provides information about the specified unit.
{
"guid": "Unit-f59f2c93-6786-4d8e-adad-2e44d33df399",
"number": "Apartment 1",
"description": "",
"status": "ACTIVE",
"secret": "khqmiogxzjn",
"guestSecret": "oxjqogvhnow",
"contact": {
"contactName": "Andy Jones",
"phoneNumber": "000-555-0101",
"email": "aj@jones.com",
"links": [
{
"rel": "smsCountryCode",
"href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/system/smsCountryCodes/12310",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null
}
]
},
"links": [
{
"rel": "property",
"href": "https://jeff245.cloudpath.net/admin/rest/tenant/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0",
"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",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null
},
{
"rel": "devices",
"href": "https://jeff245.cloudpath.net/admin/rest/tenant/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/Unit-f59f2c93-6786-4d8e-adad-2e44d33df399/devices{?type}",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null
},
{
"rel": "tenantPortal",
"href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7CD0A49F55-2B80-4D47-9A90-BC94F5ACF433%7CdhZ1zfqLYWsUKP9hNBIgeA%3D%3D%3ADRG5DkqlW%2BnpEjT0Hjfosw%3D%3D&property=Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0&api=yRCjJObWR6ER",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null
}
]
}