Properties

You can use REST API v2 calls to obtain information about existing properties, to create or edit properties, and to delete properties.

New for 5.8

The following table lists the properties that can be used in the body of a properties-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: Properties

Property Name	Type	Editable	Sort/Filter	Optional in Request/Response Body?	Description
guid	String	No	sortBy, like	Optional on create only, but not on any subsequent uses.	The unique identifier for this property.
name	String	Yes	sortBy, like	No	The display name for this property, must be unique
address	String	Yes	sortBy, like	Yes	The address for this property.
description	String	Yes	sortBy, like	Yes	A description for this property.
enforceMaxUnits	Boolean	Yes	sortBy, like	Yes<false>	Indicates if a value configured for "max units" will be enforced when adding a unit to the property.
maxUnits	int	Yes	sortBy, like	No<0>	The maximum number of units permitted for this property.
allowSeparateGuestSecret	Boolean	Yes	sortBy, like	Yes<true>	Indicates whether units asigned to this property will have a separate secret for a separate guest network. This value may not be changed once the first unit is assigned to this property.
ssids	Array<String>	No	No	Yes	This is the list of ssids that are available to this property by means of the DPSK pool that this property is assigned to.
managementName	String	Yes	sortBy, like	Yes	Name that will be assigned in all email and SMS communications.
managementPhone	String	Yes	sortBy, like	Yes	Phone that will be assigned in all email and SMS communications.
managementEmail	String	Yes	sortBy, like	Yes	Email that will be assigned in all email and SMS communications
tenantPortalHelpText	String	Yes	Neither	Yes	Help text that will be provided to users of the tenant portal.
tenantPortalAnnouncements	String	Yes	Neither	Yes	Announcements that will be provided to users of the tenant portal.
links self, units, dpskPool, uiConfiguration	Link	Yes*	sortBy, like (dpskPool)	Optional on create only, but not on any subsequent uses.	Self-referencing link, dpskPool, uiConfiguration link, and link to the list of units associated with this property. The "dpskPool" link is a required link that must be provided on a POST. The link can be changed, but only if there are no units associated with the property. Otherwise, a "422 Unprocessable Entity" error is generated.

Resource: UiConfiguration

Property Name	Type	Editable	Sort/Filter	Optional in Request/Response Body?	Description
tenantTitle	String	Yes	No	Yes	The title to use in the Tenant UI.
tenantSubtitle	String	Yes	No	Yes	The subtitle to use in the Tenant UI.
mainColor	String	Yes	No	Yes	The main color is used for the main header and any buttons or links. White text will be used on top of this color.
accentColor	String	Yes	No	Yes	The accent color is used for sub-headers and borders.
separatorColor	String	Yes	No	Yes	The separator color is used for lines in between rows of data.
textColor	String	Yes	No	Yes	The text color is the default text color used to display information throughout the portal.
logoFileName	String	NO	No	Yes	The name of the logo file, if one has been uploaded. This will be updated when the logo file is changed via the logo file link.
links					logoFile, self, and property

Properties 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.

Property URIs and Actions

URI	Action	Description	Return Codes
/properties	GET	Returns the list of properties that are in the system.	401 - Unauthorized 200 - OK
/properties	POST	Creates a property within the system. The "dpskPool" link must be provided on a POST. The link can be changed only if there are no units yet associated with the property; otherwise, a "422 Unprocessable Entity" error is returned.	422- Unprocessable Entity 401 - Unauthorized 201 - Created
/properties/{guid}	GET	Returns the details about the property specified.	404 - Not found 401 - Unauthorized 200 - OK
	PUT	Updates details about property specified. If the PUT request body includes a change to the "dpskPool" link, the change is evaluated; if there are no units assigned to the property, the change is applied. Otherwise, the change to the "dpskPool" link will generate a "422 Unprocessable Entity" error.	422 - Unprocessable Entity 404 - Not found 401 - Unauthorized 200 - OK
	DELETE	Removes the specified property, all its associated units, the DPSKs associated with the units, and all child devices associated with the DPSKs.	401 - Unauthorized 204 - No content 200 - OK
/properties/{guid}/uiConfiguration	GET	Returns the details of the tenant portal UI configuration.	404 - Not found 401 - Unauthorized 200 - OK
/properties/{guid}/uiConfiguration	PUT	Updates the tenant portal UI configuration resource.	404 - Not found 401 - Unauthorized 200 - OK
/properties/{guid}/uiConfiguration/logoFile /properties/{guid}/uiConfiguration/logoFile/{fileName}	POST	This method allows you to post an image file that will be used for the tenant portal. Note: You must include the following Request header: Key: Content-Type Value: multipart/form-data You can also set a null file if you do not want a logo to appear on the tenant portal. If the file name is null, the logo file is null regardless of the data in the form. If the form data is bad, a "422 - Unprocessable Entity" error code is sent.	422 - Unprocessable Entity 404 - Not found 401 - Unauthorized 200 - OK

Example of Using GET for Properties

This example demonstrates how to obtain information about all properties that have already been created.

URI:

This example uses the following URI:

 https://Jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties

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

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 properties in your Cloudpath system. In this example, two properties exist.

{
    "page": {
        "page": 1,
        "pageSize": 2,
        "totalCount": 2
    },
    "contents": [
        {
            "guid": "Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0",
            "name": "Building 1",
            "address": "",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": true,
            "ssids": [
                "SSID20",
                "SSID19"
            ],
            "managementName": "J. Smith",
            "managementPhone": "0005550100",
            "managementEmail": "js@smith.com",
            "tenantPortalHelpText": "",
            "tenantPortalAnnouncements": "",
            "links": [
                {
                    "rel": "self",
                    "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": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "units",
                    "href": "/apiv2/yRCjJObWR6ER/properties/Property-afaccdf8-5e39-41ce-9098-9747cc38aaa0/units",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Property-01158da4-e28d-4faa-9e57-fcba1ac4c9e6",
            "name": "Building 2",
            "address": "",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": false,
            "ssids": [
                "ssid for dpsk pool 1"
            ],
            "managementName": "J. Smith",
            "managementPhone": "0005550100",
            "managementEmail": "js@smith.com",
            "tenantPortalHelpText": "",
            "tenantPortalAnnouncements": "",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties/Property-01158da4-e28d-4faa-9e57-fcba1ac4c9e6",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties/Property-01158da4-e28d-4faa-9e57-fcba1ac4c9e6/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-4c3e2491-084b-4877-9177-128aef9af006",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "units",
                    "href": "/apiv2/yRCjJObWR6ER/properties/Property-01158da4-e28d-4faa-9e57-fcba1ac4c9e6/units",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Example of Using POST to Create a Property

This example demonstrates how to create a new property in your Cloudpath system by using the REST API POST call.

URI:

This example uses the following URI:

 https://Jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties

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

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:

The following is an example of a request body for creating a property. You can refer to the preceding Resource tables for a list and descriptions of properties you can use to define your property. For instance, in this example, a pool called "Building 3" is being created with the values provided in the body.

{
            "name": "Building 3",
            "address": "",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": true,
            "managementName": "J. Smith",
            "managementPhone": "0005550100",
            "managementEmail": "js@smith.com",
            "tenantPortalHelpText": "",
            "tenantPortalAnnouncements": "",
            "links": [
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e"}
                    
    ]
}

Action:

Use the POST action to send the request.

Response Body:

Once the request is sent, you will receive a "Status: 201 Created" if the POST is successful. You can see that a "guid" (a unique identifier for the newly created pool) is included in the response body.

{
    "guid": "Property-64c45bd0-bb03-4b81-a035-e42e10cb34c0",
    "name": "Building 3",
    "address": "",
    "description": "",
    "enforceMaxUnits": false,
    "maxUnits": 0,
    "allowSeparateGuestSecret": true,
    "ssids": [
        "SSID19",
        "SSID20"
    ],
    "managementName": "J. Smith",
    "managementPhone": "0005550100",
    "managementEmail": "js@smith.com",
    "tenantPortalHelpText": "",
    "tenantPortalAnnouncements": "",
    "links": [
        {
            "rel": "self",
            "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties/Property-64c45bd0-bb03-4b81-a035-e42e10cb34c0",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "uiConfiguration",
            "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/properties/Property-64c45bd0-bb03-4b81-a035-e42e10cb34c0/uiConfiguration",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "dpskPool",
            "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/dpskPools/AccountDpskPool-6ee78505-926d-433a-aead-1897e4e7ea9e",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "units",
            "href": "/apiv2/yRCjJObWR6ER/properties/Property-64c45bd0-bb03-4b81-a035-e42e10cb34c0/units",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        }
    ]
}