Property Hierarchy Management REST API Reference

Use the Property Hierarchy Management REST API to represent your property as a hierarchy of floors, units, and rooms.

The unit forms the building block of property hierarchy. You can create a unit under your organization to represent your property, and then create several units under it to represent rooms. You can also add more levels in your hierarchy. For example, you can create units under the property unit to represent floors in your property, and then create units under each floor unit to represent rooms on that floor. With the Create unit operation, you can create up to 15 levels of units in your hierarchy to represent your property. You can't manage properties with more than two levels in the console. Instead, use the Property Hierarchy Management API to manage complex properties.

To configure unit settings, such as the default music station provider, see Unit Settings REST API Reference.

API endpoint

Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.

Country Endpoint

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.amazonalexa.com

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.

Operations

The Property Hierarchy Management API includes the following operations.

Operation HTTP Method and URI

Create unit

POST /v2/units

Delete unit

DELETE /v2/units/{unitId}

Get unit

GET/v2/units?maxResults={maxResults}&nextToken={nextToken}

List units

GET /v2/units

Update unit

PUT /v2/units/{unitId}

Create unit

Create a unit to represent a physical property, floor, wing, or room.

A unit is an administrative construct for organizing people and resources that interact with Alexa systems. Units are hierarchical in nature and can have zero or more child units. The parent of a unit can't be any of its child units.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, DE, IT, ES, JP

CA, DE, FR, IT, UK, US, ES, JP

US

Request

To create a unit, you make a POST request to the /v2/units resource.

Request path and header example

Copied to clipboard.

POST /v2/units
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "name": {
        "type": "PLAIN",
        "value": {
            "text": "Room-100"
        }
    },
  "parentId": "amzn1.alexa.unit.did.1"
}

Request body properties

Property Description Type Required

name

Name of the unit.

NameValue object

Yes

parentId

Identifies the unit under which to create the new unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

Response

A successful response returns HTTP 200 OK, along with newly created unit ID. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
  "id": "amzn1.alexa.unit.did.100"
}

Response body properties

Property Description Type

unitId

Identifies the new unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

HTTP status codes

Status Description

200 OK

Response body contains new unit ID.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete unit

Delete the specified unit. You can't delete a unit that has child units or associated endpoints.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, DE, IT, ES, JP

CA, DE, FR, IT, UK, US, ES, JP

US

Request

To remove a unit, you make a DELETE request to the /v2/units resource.

Request path and header example

Copied to clipboard.

DELETE /v2/units/{unitId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

unitId

Path

Identifies the unit to delete.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Unit deleted successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

  • UNIT_HAS_CHILD &ndash This unit can't be deleted as it has one or more child units.
  • UNIT_HAS_ENDPOINT &ndash The unit can't be deleted because there are one or more endpoints associated. The following example shows the response body with the error code and message. 
    {
   "message": "The property is outside the allowed range.",
   "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested unit not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get unit

Get the details of the specified unit.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, DE, IT, ES, JP

CA, DE, FR, IT, UK, US, ES, JP

US

Request

To get the unit, you make a GET request to the /v2/units resource.

Request path and header example

Copied to clipboard.

GET /v2/units/{unitId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

unitId

Path

Identifies the unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the unit details. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body examples

{
    "id": "amzn1.alexa.unit.did.1",
    "name": {
        "type": "PLAIN",
        "value": {
            "text": "Room-100"
        }
    },
    "level": 0,
    "parentId": null
}

Response body properties

Property Description Type

unitId

Identifies the specified unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

name

Name of the unit.

NameValue object

level

Number of levels from the root unit.
The root unit level is 0.

Integer

parentId

Identifies the unit under the specified unit lives.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

HTTP status codes

Status Description

200 OK

Response body contains details about the specified unit.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List units

Get a list of units under the specified parent unit. If there are no child units, the operation returns an empty list. The operation only returns units that are accessible to the caller.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, DE, IT, ES, JP

CA, DE, FR, IT, UK, US, ES, JP

US

Request

To list units, you make a GET request to the /v2/units resource.

Request path and header example

Copied to clipboard.

GET/v2/units?parentId={parentId}&queryDepth={queryDepth}&expand={expand}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

parentId

Path

Identifies the unit under which to list the child units.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

queryDepth

Query

Controls the number of levels of child units to retrieve.
Default: 1.
Valid values:

  • all – No restriction on depth, return all child units.
  • 1 – Return the immediate children of parentId.
  • Values greater than 1 – List the child units up to the maximum level of the hierarchy or the depth specified in queryDepth.
    For example, queryDepth=4 returns units to a depth of four if the unit hierarchy has four levels. If the hierarchy has three levels, this option returns units to a depth of three.

String

No

expand

Query

Get expanded information about each unit.
To get unit attributes, specify all. To get the unit ID only, exclude this parameter.
Valid value: all.

String

No

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–50. Default: 10.

Integer

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of units under the specified parent unit. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The following example shows the response that includes the parentId=amzn1.alexa.unit.2&expand=all query parameters to get the details of the units one level under the parent unit.

The following example shows the response that includes the parentId=amzn1.alexa.unit.1 query parameter to get the units one level under the parent unit. Because the request doesn't include expand=all, the level, name, and parentId properties are null.

The following example shows a request that uses the queryDepth=all parameter to include all units for a parent unit, but no details. Because the request doesn't include expand=all, the level, name, and parentId properties all return null.

Response body properties

When the request doesn't include expand=all, the response includes the level, name, and parentId properties set to null for each unit.

Property Description Type

results

List of units under the specified parent ID.

Array of objects

results[].id

Identifies the unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

results[].name

Name of the unit.

NameValue object

results[].parentId

Identifies the parent unit.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

results[].level

Number of levels from the root unit.
The root unit level is 0.

Integer

paginationContext

(Optional) Indicates whether there are more results to return.
For details, see Handling Pagination in Query Results

Object

paginationContext.nextToken

Included when the response is truncated. Use this value in a subsequent request.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of units under the specified parent unit.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update unit

Update the name of the unit.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, DE, IT, ES, JP

CA, DE, FR, IT, UK, US, ES, JP

US

Request

To update a unit, you make a PUT request to the /v2/units resource.

Request path and header example

Copied to clipboard.

PUT /v2/units/{unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

unitId

Path

Identifies the unit to update.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.unit.did.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "name": {
        "type": "PLAIN",
        "value": {
            "text": "Room 101A"
        }
    }
}

Request body properties

Property Description Type Required

name

Name of the unit.

NameValue object

Yes

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Unit updated successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Property Hierarchy Management API defines the following objects.

Error object

The Error object defines the error type and message included in the response when an error occurs.

The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
Property Description Type

type

Type of error that occurred.
For specific error types, see the HTTP status code table for each operation.

String

message

Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.

String

NameValue object

The NameValue object is a container for names of objects.

The following table defines the properties of the object.

Property Description Type

type

Format of the value field. At this time, the only supported type is plain text.
Valid values: PLAIN.

String

value

Name.

Object

value.text

Name given in plain text.
Maximum length: 250 characters.
Valid values: String of letters, numbers, and the following special characters, with no spaces or periods: _ - = # ; : ? @ &

String

Was this page helpful?

Last updated: Nov 01, 2024