Units

You can use REST API v2 calls to obtain information about existing units, to create or edit units, and to delete units.
New for 5.8

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 Does not need to be provided on a POST but needs to be provided in all other cases, and will always be returned. 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 The status of this unit -- SUSPENDED or ACTIVE. When suspended, both the DPSK and guest DPSK are revoked. An additional state of "TOKEN_RESET" is accepted on a PUT, and triggers the access token on the unit to be changed. An associated email and SMS message is sent to the contact for the unit.
apiHashSecret String No No Yes The unique secret needed to access the tenant portal APIs. For more information, see Tenant Portal API Requirements.

contact (embedded)

 Contact <Object> Yes Neither Yes Contact information for this unit.

links

 Link No No Yes

Contains the following link as hrefs for use in other API calls:

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

Note: If desired, you can go to the DPSKs to set overrides for the secret, guest secret, and vlans.

Resource: Contact

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
contactName String Yes Yes No The contact name for this unit.
phoneNumber String Yes Yes Yes The phone number to use for contacts with this unit.
email

String

<Email>

 Yes Yes Yes The email to use for contacts with this unit.
links Link Yes No Yes Allows the user to define the smsCountryCode to use. If not provided, this defaults to the country code for the account.

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 GET Returns the list of units that are assigned to this property.

401 - Unauthorized

200 - OK
POST Creates a unit within the specified property. This action also creates DPSKs that are assigned to the unit. The DPSKs are assigned default secret(s). If desired, you can go to the DPSKs (by using the links returned in the Response body) to set overrides for the secret, guest secret, and vlans.

401 - Unauthorized

201 - Created
/properties/{prop_guid}/units/{guid} GET Returns details about the specified unit.

404 - Not found

401 - Unauthorized

200 - OK
PUT Updates details about the specified unit

409 - Conflict

404 - Not found

401 - Unauthorized

200 - OK
DELETE Removes the unit, the DPSKs associated with the unit, and all child devices associated with the DPSKs.

401 - Unauthorized

204 - No content

200 - OK

Example of Using GET for Units

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

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units

where:

  • https://Jeff245.cloudpath.net/admin/apiv2 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 that contains the units in question.

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.eyJzdWIiOiJqZWZmLnJob2RpZUBjb21tc2NvcGUuY29tIiwicm9sZVBrIjoiMjEwMDAiLCJhY2NvdW50QWRtaW5QayI6IjIiLCJhcGlLZXkiOiJaV2NjTGpQZUdZMGUiLCJpYXQiOjE1NzU1NzUxNTcsImV4cCI6MTU3NTU3NTQ1N30.2q4KTyDUevkAAz7mJyp529Be1-ip3EC8P06Xarmz5ao

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 units in the property that was specified. 

{
    "page": {
        "page": 1,
        "pageSize": 4,
        "totalCount": 4
    },
    "contents": [
        {
            "guid": "Unit-f59f2c93-6786-4d8e-adad-2e44d33df399",
            "number": "Apartment 1",
            "description": "",
            "status": "ACTIVE",
            "apiHashSecret": "CPNENCv2:BC|E30EECAF-AEFE-41F5-BBF9-5D3D450155AB|lJCWKjdHjnjH6iwwHS/V0A==:oXgm2xCUIPuD8yFKYZnNDQ==",
            "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/apiv2/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/apiv2/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": "dpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-eaf6936c-d652-4104-8166-1268047d9e35",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "guestDpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-7368a879-82ec-4721-acd6-0339ff448f4a",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7C5FF3EF78-0925-4FE3-B208-E47BAA4C15E7%7CMbLKoh7goJRVFiJOiL%2FjsQ%3D%3D%3ACEBx3DL0nwbnSztQn57VqA%3D%3D&property=Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0&api=yRCjJObWR6ER",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Unit-106e2a83-cd28-4e06-8d01-1fd6433f2d25",
            "number": "Apartment 2",
            "description": "",
            "status": "ACTIVE",
            "apiHashSecret": "CPNENCv2:BC|63354EC5-480A-461B-ADAB-E7A3C3DE1D9D|xcoNsgDBfSY0z4c7mnSBzQ==:+zyhD5AEVa6xcZ9gwexW0w==",
            "contact": {
                "contactName": "Joe Johnson",
                "phoneNumber": "000-555-0102",
                "email": "jj@johnson.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/apiv2/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/apiv2/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/Unit-106e2a83-cd28-4e06-8d01-1fd6433f2d25",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-8fa23e84-1e45-4f34-add6-91f2e0afaa60",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "guestDpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-08c2530b-c2fd-400d-bdec-201573cbdb69",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7CD69CDBB0-4B13-41D7-9657-B726B4D98984%7CCruO1gDfnf5A4H8MGwJRpQ%3D%3D%3A2ygKET%2B1R69PZnOi%2BykJ1g%3D%3D&property=Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0&api=yRCjJObWR6ER",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Unit-fdfc0c58-1f14-4c64-ba6b-682e4478a89f",
            "number": "Apartment 3",
            "description": "",
            "status": "ACTIVE",
            "apiHashSecret": "CPNENCv2:BC|EDC63734-C57E-425E-A85E-EFFC3BB67536|F6tewpcmlh2NiZxUcmGo5g==:yVJeg3goCJ9FdzVy6EPNWw==",
            "contact": {
                "contactName": "Jennifer Wilson",
                "phoneNumber": "000-555-0103",
                "email": "jw@wilson.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/apiv2/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/apiv2/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/Unit-fdfc0c58-1f14-4c64-ba6b-682e4478a89f",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-829d473f-4bda-42d6-8bab-df8eee377e45",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "guestDpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-3abd4d92-e313-4b7c-b4c8-9c57ed8afdee",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7C15068133-9372-478C-AA05-DC8B7984F2C4%7CGSFLgi5SmkxlD2dCpz8XWA%3D%3D%3AhpYYejUCwIYstNeiwbJiCQ%3D%3D&property=Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0&api=yRCjJObWR6ER",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Unit-aac65b4a-0392-444b-9c8c-e389fdaa2000",
            "number": "Apartment 4",
            "description": "",
            "status": "ACTIVE",
            "apiHashSecret": "CPNENCv2:BC|FD2DCC84-4293-4B0B-974E-7AEF2B080F15|07Dtry1priM56jdDnCoDuw==:mvL3nahs2S9B/U4vL4izQQ==",
            "contact": {
                "contactName": "Kim Washington",
                "phoneNumber": "000-555-0104",
                "email": "kw@washington.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/apiv2/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/apiv2/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units/Unit-aac65b4a-0392-444b-9c8c-e389fdaa2000",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-12669a53-af00-49c8-991e-3776f3ca3081",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "guestDpsk",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e/dpsks/AccountDpsk-6dd540f4-ef42-487a-888a-55e096d56fe0",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7C18DEABD7-0212-4AD0-9DA3-465B050BE542%7CS1vxaZVyEWUNkpir%2ByIXHw%3D%3D%3A7AgVOBGU8%2BIy03FY8ZRAGg%3D%3D&property=Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0&api=yRCjJObWR6ER",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Parent topic: Property Management