Properties

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

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 orderBy, like Optional on create only, but not on any subsequent uses. The unique identifier for this property.
name String Yes orderBy, like No The display name for this property, must be unique
address String Yes orderBy, like Yes The address for this property.
description String Yes orderBy, like Yes A description for this property.
enforceMaxUnits Boolean Yes orderBy, like Yes<false> Indicates if a value configured for "max units" will be enforced when adding a unit to the property.
maxUnits int Yes orderBy, like No<0> The maximum number of units permitted for this property.
allowSeparateGuestSecret Boolean Yes orderBy, 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 orderBy, like Yes Name that will be assigned in all email and SMS communications.
managementPhone String Yes orderBy, like Yes Phone that will be assigned in all email and SMS communications.
managementEmail String Yes orderBy, 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.
sendEmail Boolean Yes Neither Yes<true> Indicates that email will be sent to tenants when there are changes on a unit.
sendSms Boolean Yes Neither Yes<true> Indicates that SMS will be sent to tenants when there are changes on a unit.
smsPassphraseChange String Yes Neither Yes

If enabled, this is the SMS text that gets sent to the unit owner when the passphrase or guest passphrase is changed. Users are responsible for creating text correctly if they are using the guest passphrase or the tenant portal.

what "guidelines" about creating text correctly? What are we warning them about?
The following variables are used to substitute the passphrases and the portal URL in all cases:

${PROPERTY_NAME} , ${UNIT_PASSPHRASE}, ${GUEST_PASSPHRASE}, ${UNIT_PORTAL_URL}, ${UNIT_MANAGER}, ${UNIT_CONTACT_NAME}

what exactly happens with the portal URL?

emailPassphraseSubject String Yes Neither Yes If set, this is the subject for the email that gets sent to the unit owner when either the passphrase or guest passphrase for a unit is changed.
emailPassphraseChange String Yes Neither Yes

If set, this is the email text that will be sent to the unit owner when the passphrase or guest passphrase is changed. Users are responsible for creating text correctly if they are using the guest passphrase or the tenant portal. The following variables are used to substitute the passphrases and the portal URL in all cases:

${PROPERTY_NAME} , ${UNIT_PASSPHRASE}, ${GUEST_PASSPHRASE}, ${UNIT_PORTAL_URL}, ${UNIT_MANAGER}, ${UNIT_CONTACT_NAME}
smsAssigedUnit String Yes Neither Yes

If set, this is the SMS text that gets sent to the unit owner when a unit is created. Users are responsible for creating text correctly if they are using the guest passphrase or the tenant portal. The following variables are used to substitute the passphrases and the portal URL in all cases:

${PROPERTY_NAME} , ${UNIT_PASSPHRASE}, ${GUEST_PASSPHRASE}, ${UNIT_PORTAL_URL}, ${UNIT_MANAGER}, ${UNIT_CONTACT_NAME}
emailAssignedUnitSubject String Yes Neither Yes If set, this is the subject for the email that gets sent to the unit owner when they are assigned a unit.
emailAssignedUnit String Yes Neither Yes

If set, this is the email text that will be sent to the unit owner when a unit is created. Users are responsible for creating text correctly if they are using the guest passphrase or the tenant portal. The following variables are used to substitute the passphrases and the portal URL in all cases:

${PROPERTY_NAME} , ${UNIT_PASSPHRASE}, ${GUEST_PASSPHRASE}, ${UNIT_PORTAL_URL}, ${UNIT_MANAGER}, ${UNIT_CONTACT_NAME}

links:

self, units, dpskPool, uiConfiguration, networkSegmentationGroups		 Link Yes* orderBy, like (dpskPool) Optional on create only, but not on any subsequent uses. Self-referencing link, dpskPool, uiConfiguration link, link to the list of units associated with this property, and links to any network segmentation groups to which the property may be assigned.
Shannon - I added the sentence about the net seg groups -do you want to add something to the wiki page too?
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
apiAllowed
this name is different in the wiki, but I went with the repsonse I got from running the API
 Boolean Yes No Yes<true> Indicates if access is permitted to the tenant API.
portalAllowed Boolean Yes No Yes<true> Indicates if access is permitted to the tenant portal. The "apiAllowed" property must be enabled for this to be true.
updated this accordingly from the prior comment; wiki should be updated too
tenantSetDpsk
new for 5.9R3 - don't believe I saw it in wiki though
 Boolean Yes No Yes; default is <false> Indicates if the tenant can manually set the wifi passphrase on the tenant portal to a specific desired value.
Shannon is this correct?
emailTextResetAuth String Yes No Yes

If set, this is the email text that gets sent to the unit owner when the tenant portal authentication token is reset. The user is responsible for creating text correctly and can use the following variables to substitute the passphrases and the tenant portal URL in all cases:

${PROPERTY_NAME} , ${UNIT_PASSPHRASE}, ${GUEST_PASSPHRASE}, ${UNIT_PORTAL_URL}, ${UNIT_MANAGER}, ${UNIT_CONTACT_NAME}
emailSubjectResetAuth String Yes No Yes If set, this is the email subject that gets sent to the unit owner when the tenant portal authentication token is reset.
smsTextResetAuth String Yes No Yes

If set, this is the SMS message that gets sent to the unit owner when the tenant portal authentication token is reset. The user is responsible for creating text correctly and can use the following variables to substitute the passphrases and the tenant portal URL in all cases:

${PROPERTY_NAME} , ${UNIT_PASSPHRASE}, ${GUEST_PASSPHRASE}, ${UNIT_PORTAL_URL}, ${UNIT_MANAGER}, ${UNIT_CONTACT_NAME}
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.
loginText String (5.9) Yes No Yes Text to display during login to the tenant portal.
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.
iconFileName String No No Yes The name of the icon file, if one has been uploaded. This will be updated when the icon file is changed via the icon file link.
links         logoFile, favicon, 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
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
PUT Updates the tenant portal UI configuration resource.

404 - Not found

401 - Unauthorized

200 - OK
/properties/{guid}/networkSegmentationGroups
new for 5.9R3
 GET Returns the network segmentation groups assigned to the specified property. This is returned as a list. The list will be empty if the property has not been assigned to any network segmentation groups. If the Cloudpath server has not been correctly configured for SmartZone integration, this URI generates a "403 - Forbidden" message.
Shannon - Can a property be assigned to more than one Network segmentation group?

404 - Not found

403 - Forbidden

401 - Unauthorized

200 - OK
/properties/{guid}/networkSegmentationGroups/{segmentGuid}
new for 5.9R3
 PUT Assigns or replaces a network segmentation group to the specified property. There is a null body expected, and if provided is ignored.
Shannon - What null body is expected? Not sure exactly what behavior is expected.
If there is already one network segmentation group assigned to the specified property, that group is removed, and replaced by the network segmentation group whose GUID is specified in this URI. Also, this URI is permitted only if there are no units associated with the specified property; otherwise a "409 - Conflict" message is returned. If the Cloudpath server has not been correctly configured for SmartZone integration, this URI generates a "403 - Forbidden" message.

409 - Conflict

404 - Not found

403 - Forbidden

401 - Unauthorized

200 - OK
DELETE Removes the specified network segmentation group that is currently assigned to the property. All VNIs and APs associated with this network segmentation group are also removed. This cannot be undone. If the Cloudpath server has not been correctly configured for SmartZone integration, this URI generates a "403 - Forbidden" message.

404 - Not found

403 - Forbidden

401 - Unauthorized

200 - OK

/properties/{guid}/uiConfiguration/logoFile

 POST

This method allows you to post an image file that will be used for the tenant portal logo.

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
/properties/{guid}/uiConfiguration/favicon POST

This method allows you to post an image file that will be used for the tenant portal favicon.

Note: You must include the following Request header:

Key: Content-Type Value: multipart/form-data

The form data can contain two entries with the following keys:

  • file - favicon file contents.
  • iconFilename - a text entry with the name of the favicon file.

You can also set a null file if you do not want a favicon to appear on the tenant portal. If the file name is empty, the favicon 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/publicApi/properties

where https://Jeff245.cloudpath.net/admin/publicApi is the root URI of the Cloudpath system being used (must include https, as shown).

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, three properties exist, and the property called "Tech Pubs Building 1" is part of a network segmentation group. 

{
    "page": {
        "page": 1,
        "pageSize": 3,
        "totalCount": 3
    },
    "contents": [
        {
            "guid": "Property-f6c3d9be-9763-4549-9a3d-1157bfd5a7eb",
            "name": "Building 1",
            "address": "000 Lake View Road\r\nLake Town, MN",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": true,
            "ssids": [
                "ssid1"
            ],
            "managementName": "J. Smith",
            "managementPhone": "555-000-0100",
            "managementEmail": "jeff@commscope.com",
            "tenantPortalHelpText": "Please contact management for any concerns.",
            "tenantPortalAnnouncements": "Welcome to your tenant portal",
            "sendEmail": true,
            "sendSms": true,
            "smsPassphraseChange": "",
            "emailPassphraseSubject": "",
            "emailPassphraseChange": "",
            "smsAssignedUnit": "",
            "emailAssignedUnitSubject": "",
            "emailAssignedUnit": "",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-f6c3d9be-9763-4549-9a3d-1157bfd5a7eb",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-f6c3d9be-9763-4549-9a3d-1157bfd5a7eb/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/dpskPools/AccountDpskPool-4d1f71cb-c4b7-403e-aceb-7e8f1d38469c",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "units",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-f6c3d9be-9763-4549-9a3d-1157bfd5a7eb/units?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Property-82d632d7-e1cc-44fc-a09b-63a34582c496",
            "name": "Building 2",
            "address": "200 Lake View Road\r\nLake Town, MN",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": true,
            "ssids": [
                "ssid2"
            ],
            "managementName": "J. Smith",
            "managementPhone": "555-000-0100",
            "managementEmail": "jeff@commscope.com",
            "tenantPortalHelpText": "",
            "tenantPortalAnnouncements": "",
            "sendEmail": true,
            "sendSms": true,
            "smsPassphraseChange": "",
            "emailPassphraseSubject": "",
            "emailPassphraseChange": "",
            "smsAssignedUnit": "",
            "emailAssignedUnitSubject": "",
            "emailAssignedUnit": "",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-82d632d7-e1cc-44fc-a09b-63a34582c496",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-82d632d7-e1cc-44fc-a09b-63a34582c496/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/dpskPools/AccountDpskPool-ce59eb06-4a07-42e0-9128-44c97e607ab2",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "units",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-82d632d7-e1cc-44fc-a09b-63a34582c496/units?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "Property-40ac7e72-97ed-4567-a180-7d20967c5a72",
            "name": "Tech Pubs Building 1 ",
            "address": "001 Tech Pubs Road\r\nLake Town, CA",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": true,
            "ssids": [
                "Jeff eDPSK"
            ],
            "managementName": "Sushma A",
            "managementPhone": "0005550200",
            "managementEmail": "sushma@commscope.com",
            "tenantPortalHelpText": "",
            "tenantPortalAnnouncements": "",
            "sendEmail": true,
            "sendSms": true,
            "smsPassphraseChange": "",
            "emailPassphraseSubject": "",
            "emailPassphraseChange": "",
            "smsAssignedUnit": "",
            "emailAssignedUnitSubject": "",
            "emailAssignedUnit": "",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-40ac7e72-97ed-4567-a180-7d20967c5a72",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-40ac7e72-97ed-4567-a180-7d20967c5a72/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/dpskPools/AccountDpskPool-390c47b8-5c61-4d06-bb9b-6693c65db8b6",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "units",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-40ac7e72-97ed-4567-a180-7d20967c5a72/units?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "networkSegmentationGroups",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-40ac7e72-97ed-4567-a180-7d20967c5a72/networkSegmentationGroups?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Example of Using GET to Obtain the Network Segmentation Group Assigned to a Property

new example for 5.9R3
This example demonstrates how to obtain information about the network segmentation group that has been assigned to the specified property in your Cloudpath system by using the REST API GET call.
Note: A property does not necessarily need to be part of a network segmentation group.

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/publicApi/properties/Property-40ac7e72-97ed-4567-a180-7d20967c5a72/networkSegmentationGroups

where:

  • https://Jeff245.cloudpath.net/admin/publicApi is the root URI of the Cloudpath system being used (must include https, as shown).
  • Property-40ac7e72-97ed-4567-a180-7d20967c5a72 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.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. You can see that the response provided the information about the network segmentation group, called "chris-1", that is assigned to the property. 

{
    "page": {
        "page": 1,
        "pageSize": 1,
        "totalCount": 1
    },
    "contents": [
        {
            "guid": "fe1b1ea8-87c0-467f-9b9f-7827f576cd82",
            "name": "chris-1",
            "vniRange": {
                "firstVni": 2000000,
                "lastVni": 2001000
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/networkSegmentationGroups/fe1b1ea8-87c0-467f-9b9f-7827f576cd82",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "property",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/networkSegmentationGroups/fe1b1ea8-87c0-467f-9b9f-7827f576cd82/properties?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "vxlanNetworkIdentifiers",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/networkSegmentationGroups/fe1b1ea8-87c0-467f-9b9f-7827f576cd82/vxlanNetworkIdentifiers?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "accessPoints",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/networkSegmentationGroups/fe1b1ea8-87c0-467f-9b9f-7827f576cd82/accessPoints?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Parent topic: Property Management