Units (Property Management)

You can use property management API calls to obtain information about existing units, to update details about a unit, or to add a unit to a property.
section updated for 5.9r3

Updates that are allowed on a unit are based on the access control fields that have been defined for the applicable management portal configuration in the Cloudpath UI. Refer to the Cloudpath Enrollment System Property Management Administration Guide for more information.

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 (< >).

Note: In the "Editable" column below, "yes" indicates that a property is editable provided that the administrator enabled these properties using the access controls defined in the corresponding management portal.

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 "TOKEN_RESET", "SUSPENDED", or "ACTIVE".
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.
apiHashSecret String No No Yes The unique secret needed to access the tenant portal APIs. For more information, see Tenant Portal API Requirements.
maxDeviceCount int No no Yes The maximum number of devices permitted for this unit.
guestMaxDeviceCount int No 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.
vlan String Yes No Yes The vlan applied to the unit when the unit is created. If vlan override is set, the vlan is returned on a GET call. The vlan cannot be changed on a PUT, but it can be set on a create.
guestVlan String Yes No Yes The vlan applied to the unit when the unit is created. If vlan override is set, the vlan is returned on a GET call. The vlan cannot be changed on a PUT, but it can be set on a create.
           
expirationDate DateTime No Neither Yes Iso 80601 DateTime that indicates when this wifi passphrase expires.
guestExpirationDate DateTime Yes Neither Yes Iso 80601 DateTime that indicates when this guest wifi passphrase expires.
networkSegmentationDetails
new for 5.9r3
 Network Segmentation Details No No Yes

If the unit is part of a property that is in a network segmentation group, this resource specifies the network segmentation details (described later in this section) for this unit.
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

Resource: Network Segmentation Details

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
           
vni Number No No Yes The VNI assigned to this unit.
assignedAccessPoint Assigned Access Point No No Yes The access point details assigned to the unit.

Resource: Assigned Access Point

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
szName String No No Yes The name of the associated access point.
ethernetPorts List No No Yes The ethernet ports assigned to this unit.

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
/propertyMgmtPortals/{portalGuid}/properties/{propertyGuid}/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, and creates the DPSKs for the unit. The DPSKs are assigned the secrets provided in the request body; if no secrets are specified, they are automatically generated and assigned.

If the API call is not permitted by access controls configured in Cloudpath management portal configuration, a "403 - Forbidden" message is returned.

201- Created

401 - Unauthorized

403- Forbidden
/propertyMgmtPortals/{portalGuid}/properties/{propertyGuid}/units/{guid} GET Returns information about the specified unit.

200- OK

404 - Not Found

401 - Unauthorized

403- Forbidden
  PUT

Updates details about the unit. Updates that are allowed on a unit are based on the access control fields that have been defined for the applicable management portal configuration in the Cloudpath UI. Refer to the Cloudpath Enrollment System Property Management Administration Guide for more information.

If the change requested is not permitted by access controls, a "403 - Forbidden" message is returned.

200- OK

404 - Not Found

401 - Unauthorized

403- Forbidden
  DELETE Removes the unit, the DPSKs associated with the unit, and any devices associated with those DPSKs. If this API call not permitted by access controls, a "403 - Forbidden" is returned.

204 - No content

200 - OK

401 - Unauthorized

403- Forbidden

Example of Using GET for Units

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

URI:

This example uses the following URI: 

https://Jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d/units

where:

  • https://Jeff245.cloudpath.net/admin/rest/ is the root URI of the Cloudpath system being used (must include https, as shown)
  • MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503 is the GUID of the management portal.
  • Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d is the GUID of the property.

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.eyJzdWIiOiJMYWtlIFZpZXcgQXBhcnRtZW50cyBNYW5hZ2VtZW50IFBvcnRhbCIsInBvcnRhbEd1aWQiOiJNZHVQb3J0YWxBY2Nlc3MtNzkyOTNhMzMtMjYyYy00MTViLThmMGMtOThlYmMwMWViNTAzIiwiYWNjb3VudFBrIjoiMSIsInVzZXJFbWFpbCI6ImplZmYucmhvZGllQGNvbW1zY29wZS5jb20iLCJwb3J0YWxTZWNyZXQiOiJzZWNyZXQiLCJpYXQiOjE2Mjg5MDcwOTQsImV4cCI6MTYyODkwNzM5NH0.F_h48OPwUI_F1KDFNpz8zFM1qQzbxyG5KrLyc7HR7IE

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

{
    "page": {
        "page": 1,
        "pageSize": 4,
        "totalCount": 4
    },
    "contents": [
        {
            "guid": "Unit-d289217b-80c3-4abd-86ab-df8d8a7a3108",
            "number": "Apartment 5",
            "description": "",
            "status": "ACTIVE",
            "secret": "nlkagshnkhrv",
            "guestSecret": "jekvmhhvztxt",
            "apiHashSecret": "CPNENCv2:BC|2AA29636-E945-4CAE-B05D-196CDB47B3D3|bixX//pk5Lv9QRrKM/L2wg==:QPURvUUAwPmM9RYlNG9BvQ==",
            "contact": {
                "contactName": "Jane Smithson",
                "phoneNumber": "000-555-0105",
                "email": "js@ltapts.com",
                "links": [
                    {
                        "rel": "smsCountryCode",
                        "href": "https://jeff245.cloudpath.net/admin/publicApi/system/smsCountryCodes/12310",
                        "hreflang": null,
                        "media": null,
                        "title": null,
                        "type": null,
                        "deprecation": null
                    }
                ]
            },
            "vlan": "5",
            "guestVlan": "5",
            "links": [
                {
                    "rel": "property",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d/units/Unit-d289217b-80c3-4abd-86ab-df8d8a7a3108",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7C5F7EE7E1-3A45-41BB-A5B9-65FC34A88050%7Clmd%2BMLR73Iz75jArKzhydA%3D%3D%3ARP9WmjP3ErSjhjxTWB1NyA%3D%3D&property=Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d&api=UUBqrkAaJKs2",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Unit-b7d7f0d0-e2fa-4802-b2de-da6970889aa1",
            "number": "Apartment 6",
            "description": "",
            "status": "ACTIVE",
            "secret": "lgovrjqoxbsk",
            "guestSecret": "wtpmrttyvflc",
            "apiHashSecret": "CPNENCv2:BC|5731D43E-7AC4-4720-9DDE-FFFF34621B83|rhihZGDqg1i72koSVUM19w==:X0iPLkN01bCqaeRTsi7orA==",
            "contact": {
                "contactName": "Mary Matheson",
                "phoneNumber": "000-555-0106",
                "email": "mm@matheson.com",
                "links": [
                    {
                        "rel": "smsCountryCode",
                        "href": "https://jeff245.cloudpath.net/admin/publicApi/system/smsCountryCodes/12310",
                        "hreflang": null,
                        "media": null,
                        "title": null,
                        "type": null,
                        "deprecation": null
                    }
                ]
            },
            "vlan": "6",
            "guestVlan": "6",
            "links": [
                {
                    "rel": "property",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d/units/Unit-b7d7f0d0-e2fa-4802-b2de-da6970889aa1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7CE5572AFF-1B4E-4B0C-82B7-D4A3A3502021%7CvE8Uc6%2Bi03OsKo5dUu5brw%3D%3D%3AXpv7FwxNVvlKqhYxz5vDuw%3D%3D&property=Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d&api=UUBqrkAaJKs2",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Unit-a94dd1f4-d2ed-4879-a577-da1d9d00a621",
            "number": "Apartment 7",
            "description": "",
            "status": "ACTIVE",
            "secret": "vykmbuhiwpnz",
            "guestSecret": "qoiapafxfizl",
            "apiHashSecret": "CPNENCv2:BC|1082ECE8-8A8D-4062-A5B3-DC32A5C9FCE7|fvOy1h3/t1Ewc0T3hsGITw==:OFxrkdL0N6fRtsEyxX2jEw==",
            "contact": {
                "contactName": "Jake Sterling",
                "phoneNumber": "000-555-0107",
                "email": "js@sterling.com",
                "links": [
                    {
                        "rel": "smsCountryCode",
                        "href": "https://jeff245.cloudpath.net/admin/publicApi/system/smsCountryCodes/12310",
                        "hreflang": null,
                        "media": null,
                        "title": null,
                        "type": null,
                        "deprecation": null
                    }
                ]
            },
            "vlan": "7",
            "guestVlan": "7",
            "links": [
                {
                    "rel": "property",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d/units/Unit-a94dd1f4-d2ed-4879-a577-da1d9d00a621",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7C877A3CC3-E903-490D-8E55-C40EEA5D8730%7CZh%2FI7b3bYp0SQ5CX7pz3yQ%3D%3D%3AYdFRoole8A4Z9ftUlWdMWA%3D%3D&property=Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d&api=UUBqrkAaJKs2",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Unit-8b4e9a86-9373-431f-b88b-d82d12c643d0",
            "number": "Apartment 8",
            "description": "",
            "status": "ACTIVE",
            "secret": "xvusroyzaqol",
            "guestSecret": "opzqzxjvjojq",
            "apiHashSecret": "CPNENCv2:BC|C8D17978-2D4C-459B-912B-34E0CC77B686|+P+9hqEnJjt1ml73U3r7Xg==:Os+3/vI4CKuoN8L3OnThdA==",
            "contact": {
                "contactName": "Zack Jordan",
                "phoneNumber": "000-555-0108",
                "email": "zj@jordan.com",
                "links": [
                    {
                        "rel": "smsCountryCode",
                        "href": "https://jeff245.cloudpath.net/admin/publicApi/system/smsCountryCodes/12310",
                        "hreflang": null,
                        "media": null,
                        "title": null,
                        "type": null,
                        "deprecation": null
                    }
                ]
            },
            "vlan": "8",
            "guestVlan": "8",
            "links": [
                {
                    "rel": "property",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/rest/propertyMgmtPortals/MduPortalAccess-79293a33-262c-415b-8f0c-98ebc01eb503/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d/units/Unit-8b4e9a86-9373-431f-b88b-d82d12c643d0",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "tenantPortal",
                    "href": "https://jeff245.cloudpath.net/tenant?&auth=CPNENCv2%3ABC%7C0039519A-9239-480F-A7BF-BF60CF7B61EA%7C001me7RfqlTO6qRikVQdQw%3D%3D%3AzpoZdwX7Bi7hMKZbtDQR1A%3D%3D&property=Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d&api=UUBqrkAaJKs2",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Parent topic: Property Management APIs