Tenant Portal Units

You can use tenant portal API calls to obtain information about existing units or to update details about a unit to which you have been authenticated by using an apiHashSecret associated with that unit to obtain your authorization token.

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:

  • Self-referencing link
  • Property link
  • Tenant portal link
  • Links to associated devices

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.

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

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.

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.eyJzdWIiOiJBcGFydG1lbnQgMSIsImFjY2Vzc1Rva2VuIjoiWkFZZGxMM0ciLCJwcm9wZXJ0eUd1aWQiOiJQcm9wZXJ0eS1hZmFjY2RmOC01ZTM5LTQxY2UtOTA5OC05NzQ3Y2MzOGFhYTAiLCJ1bml0R3VpZCI6IlVuaXQtZjU5ZjJjOTMtNjc4Ni00ZDhlLWFkYWQtMmU0NGQzM2RmMzk5IiwiYXBpS2V5IjoieVJDakpPYldSNkVSIiwiaWF0IjoxNjE0MTQ5MTg5LCJleHAiOjE2MTQxNDk0ODl9.nirUAxLkinvXRZzlTSjbvPq4vSdB1OiISPoVDsnVwho

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 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
        }
    ]
}

Parent topic: Tenant Portal APIs