Properties

You can use REST API calls to obtain information about existing properties, to create or edit properties, and to delete properties.
updated URIs for 5.9 and added newly supported properties; updated examples

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

 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
allowsTenantApi Boolean (5.9) Yes No Yes<true> Indicates if access is permitted to the tenant API.
allowsTenantPortal Boolean (5.9) Yes No Yes<true> Indicates if access is permitted to the tenant portal. The "allowsTenantApi" must be enabled for this to be true.
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}/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, two properties exist.

Shannon - The output below includes MDU segmentation. Is that going to be the case? If so, what should I say about it since we're not actually supporting it till 5.9R2?

{
    "page": {
        "page": 1,
        "pageSize": 2,
        "totalCount": 2
    },
    "contents": [
        {
            "guid": "Property-c7268d2a-a527-46df-9696-6975424a106b",
            "name": "Building 1",
            "address": "000 Lake View Road Lake Town, MN",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": true,
            "ssids": [
                "ssid1"
            ],
            "managementName": "J. Smith",
            "managementPhone": "0005550100",
            "managementEmail": "js@ltapts.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-c7268d2a-a527-46df-9696-6975424a106b",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-c7268d2a-a527-46df-9696-6975424a106b/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/dpskPools/AccountDpskPool-2eeda82a-418f-4116-a2e7-4c5e56f36d32",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "units",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-c7268d2a-a527-46df-9696-6975424a106b/units?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                
            ]
        },
        {
            "guid": "Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d",
            "name": "Building 2",
            "address": "200 Lake View Road Lake Town, MN",
            "description": "",
            "enforceMaxUnits": false,
            "maxUnits": 0,
            "allowSeparateGuestSecret": true,
            "ssids": [
                "ssid2"
            ],
            "managementName": "J. Smith",
            "managementPhone": "0005550100",
            "managementEmail": "js@ltapts.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-4567d598-5a6d-4847-b9d5-32f7ba34df8d",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "uiConfiguration",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d/uiConfiguration",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "dpskPool",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/dpskPools/AccountDpskPool-2a531247-b25c-4712-9554-311ab6aaee27",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "units",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-4567d598-5a6d-4847-b9d5-32f7ba34df8d/units?page=1&pageSize=10{&filter,orderBy}",
                    "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/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:

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 property 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/publicApi/dpskPools/AccountDpskPool-32eeb1b8-feaa-4cb0-a79f-796ec769ddf8"}
                    
    ]
}

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-5c2001d4-4d47-4c63-9588-c4f0a970d431",
    "name": "Building 3",
    "address": "",
    "description": "",
    "enforceMaxUnits": false,
    "maxUnits": 0,
    "allowSeparateGuestSecret": true,
    "ssids": [
        "ssid3"
    ],
    "managementName": "J. Smith",
    "managementPhone": "0005550100",
    "managementEmail": "js@smith.com",
    "tenantPortalHelpText": "",
    "tenantPortalAnnouncements": "",
    "sendEmail": true,
    "sendSms": true,
    "smsPassphraseChange": null,
    "emailPassphraseSubject": null,
    "emailPassphraseChange": null,
    "smsAssignedUnit": null,
    "emailAssignedUnitSubject": null,
    "emailAssignedUnit": null,
    "links": [
        {
            "rel": "self",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-5c2001d4-4d47-4c63-9588-c4f0a970d431",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "uiConfiguration",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-5c2001d4-4d47-4c63-9588-c4f0a970d431/uiConfiguration",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "dpskPool",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/dpskPools/AccountDpskPool-32eeb1b8-feaa-4cb0-a79f-796ec769ddf8",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        {
            "rel": "units",
            "href": "https://jeff245.cloudpath.net/admin/publicApi/properties/Property-5c2001d4-4d47-4c63-9588-c4f0a970d431/units?page=1&pageSize=10{&filter,orderBy}",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
            ]
}

Parent topic: Property Management