Property Hierarchy Management API

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties in senior living partners. See Get Started with Alexa Smart Properties in senior living APIs.

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. Alternatively, if you wish to add another level in your hierarchy, you could 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 unit management APIs, you can create up to 15 levels of units in your hierarchy to represent your property. Note that for property hierarchies with more than 2 levels, you need to use APIs to manage them and you cannot manage such properties in the console.

API endpoint

The endpoint of the Property Hierarchy Management API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Property Hierarchy Management API includes the following operations.

Operation	HTTP Method and URI
Create a unit	`POST /v2/units`
Get a unit	`GET /v2/units/{unitId}`
List units	`GET /v2/units`
Update a unit	`PUT /v2/units/{unitId}`
Delete a unit	`DELETE /v2/units/{unitId}`

Create a unit

Call POST /v2/units to create a unit to represent a physical unit (e.g. property, floor, wing, room) in your property.

A Unit is an administrative construct for organizing people and resources (skill, devices) that interact with Alexa systems. Units are hierarchical in nature and can have zero or more sub units. A Unit's parent cannot be any of its sub units.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	DE, IT	None	CA, DE, FR, IT, UK, and US	US

Request format

POST /v2/units HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

None.

Request body format

{
  "name": {
              "type": "PLAIN",
              "value": {
                   "text": "name of unit"
               }
            },
  "parentId": "amzn1.alexa.unit.did.{unitId}"
}

Request body parameters

Field	Description	Type	Required
`name.type`	The type of format the name.value field is expected in. Accepted value: `PLAIN`	String	Yes
`name.value`	The name of the unit.	NameValue	Yes
`parentId`	Unit under which the newly created unit will exist.	String	Yes

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units"

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes
`propertyId`	Property ID as part of the `Location` header URI.	String	Yes

Response body

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

Response body parameters

Field	Description	Type	Required
`id`	The unit ID for the new unit.	String	Yes

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}"
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error.	String	No

HTTP response codes

Status Code	Name	Description
201	Created	The unit was successfully created.
400	Bad Request	The request is malformed or is missing one or more required parameters.
400	Invalid_Parent_Id	The parent unit Identifier specified is invalid.
400	Invalid_Unit_Name	Name cannot be NULL or empty.
400	Level_Limit_Exceeded	Unit cannot be more than 15 levels deep.
401	Unauthorized	The access token is missing or invalid.
403	Forbidden	The user doesn't have permission to access the service.
429	Too many requests	Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

Get a Unit

Call GET /v2/units/{unitId} to retrieve a unit.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	DE, IT	None	CA, DE, FR, IT, UK, and US	US

Request format

GET /v2/units/{unitId}
&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request parameters

Field	Description	Type	Required
`unitId`	Identifier for the unit you want to retrieve in the following format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Request body

None.

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

{
    "id": "amzn1.alexa.unit.did.{unitId}",
    "name": {

              "type": "PLAIN",
               "value": {
                   "text": "UnitName"
               }
            },
    "level": 0,
    "parentId": null
}

Response body parameters

Field	Description	Type	Required
`name.type`	The type of format the name.value field is expected in. Accepted value: `PLAIN`	String	Yes
`name.value`	The name of the unit.	NameValue	Yes
`level`	Number of levels the unit is from the root unit. Root unit level is 0.	Integer	Yes
`parentId`	Unit under which the newly created unit will exist.	String	Yes

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}"
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
400	Bad_Request	The request was malformed.
400	Invalid_Unit_Id	The `unitId` was invalid.
401	Unauthorized	The access token is missing or invalid.
403	Forbidden	The user doesn't have permission to access the service.
404	No_Such_Unit	The requested unit wasn't found.
429	Too_many_requests	Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

List Units

Call GET /v2/units/ to retrieve units. If there are no child units, an empty list will be returned. Only units that are accessible by the caller will be returned. All subunits will be returned up to depth specified (if any).

Note: PaginationToken should be checked for null to ensure there are no more results. In certain cases, empty list can be returned, if all units have been filtered due to authorization check.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	DE, IT	None	CA, DE, FR, IT, UK, and US	US

Request format

GET /v2/units/
&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request query parameters

Field	Description	Type	Required
`parentId`	Identifier of the unit for which child units should be returned. In format of `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`maxResults`	Number of entries to be fetched in a request. Default: 10 entries will be returned, current max is 50.	Integer	No
`nextToken`	Token to fetch next set of items. Same filter parameters should be passed as in first request. If filter parameters have changed, 400 Bad request exception will be returned.	String	No
`queryDepth`	Controls the number of immediate depth of subunits to be returned. Default: Default sub unit depth returned is 1. queryDepth = `all;` No restriction on subunit depth, all child units are returned. queryDepth = `1;` Immediate children of parentUnitId is retrieved. queryDepth `> 1;` The depth is built until max depth value level of the hierarchy or the depth specified in the parameter is reached. Example: queryDepth=4 will return 4 depth level if the unit hierarchy has all that levels. If the hierarchy has only 3 levels, then only 3 depth level will be returned.	String	No
`expand`	An attribute (or set of attributes) to include in the response. Current values supported: `all` If `expand=all` is not passed in the request, only the `id` property of the unit is returned in the response.	String	No

Request body

None.

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

{
  "results": [
    {
      "id": "amzn1.alexa.unit.{unitId}",
      "name": {
             "type": "PLAIN",
              "value": {
                  "text": "unitName"
               }
           }
      "parentId": "amzn1.alexa.unit.{unitID}",
      "level":0
    }
  ],
  "paginationContext": {
    "nextToken": "ABCD1234"
  }
}

Response body parameters

Field	Description	Type	Required
`id`	The id for the unit.	String	Yes
`name.type`	The type of format the name.value field is expected in. Accepted value: `PLAIN`	String	Yes
`name.value`	The name of the unit.	NameValue	Yes
`parentId`	Unit under which the newly created unit will exist.	String	Yes
`level`	Number of levels the unit is from the root unit. Root unit level is 0.	Integer	Yes
`nextToken`	Token used for getting the next page of results. For details, see Handling Pagination in Query Results.	String	No

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}"
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
400	Bad_Request	The request was malformed.
400	Invalid_Next_Token	The Pagination Token is invalid or expired.
400	Invalid_Max_Result	Number of requested results exceeds maximum supported.
400	Invalid_Parent_Id	The parent unit identifier is null or empty.
401	Unauthorized	The access token is missing or invalid.
403	Forbidden	The user doesn't have permission to access the service.
404	No_Such_Unit	The requested unit wasn't found.
429	Too_many_requests	Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

Include full depth and all details.

This example shows how to include all units below a parent unit and details for each unit, use the following expand=all and queryDepth=all parameters.

GET /v2/units?parentId={unitId}&queryDepth=all&expand=all HTTP/1.1

queryDepth one, no expansion parameters

This example shows how to include all units below a parent unit and details for each unit, use the following expand=all and queryDepth=all parameters.

GET /v2/units?parentId={unitId}&queryDepth=1 HTTP/1.1

queryDepth all, no expansion parameters

This example shows how to include all units below a parent unit and details for each unit, use the following expand=all and queryDepth=all parameters.

GET /v2/units?parentId={unitId}&queryDepth=all HTTP/1.1

Update a unit

Call PUT /v2/units/{unitId} to update the name of the unit.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	DE, IT	None	CA, DE, FR, IT, UK, and US	US

Request format

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

Request path parameters

Field	Description	Type	Required
`unitId`	Identifier for the unit you want to update in the following format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Request body format

{
   "name": {
             "type": "PLAIN",
              "value": {
                  "text": "NAME"
               }
           }
}

Request body parameters

Field	Description	Type	Required
`name.type`	The type of format the name.value field is expected in. Accepted value: `PLAIN`	String	Yes
`name.value`	The name of the unit.	NameValue	Yes

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units/{unitId}"

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes
`propertyId`	Property ID as part of the `Location` header URI.	String	Yes

Response body

None.

Response body parameters

None.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}"
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error.	String	No

HTTP response codes

Status Code	Name	Description
204	OK	The unit was successfully updated.
400	Bad Request	The request is malformed or is missing one or more required parameters.
400	Invalid_Unit_Name	Name cannot be NULL or empty.
400	Invalid_Unit_ID	`unitId` is invalid.
401	Unauthorized	The access token is missing or invalid.
403	Forbidden	The user doesn't have permission to access the service.
429	Too many requests	Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

Delete a unit

Call DELETE /v2/units/{unitId} to delete a unit. If the unit has child Units, 400 Bad request will be returned.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	DE, IT	None	CA, DE, FR, IT, UK, and US	US

Request format

DELETE /v2/units/{unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`unitId`	Identifier for the unit you want to update in the following format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Request body format

None.

Request body parameters

None.

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units/{unitId}"

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Response body parameters

None.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}"
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error.	String	No

HTTP response codes

Status Code	Name	Description
204	OK	The unit was successfully deleted.
400	Bad Request	The request is malformed or is missing one or more required parameters.
400	Invalid_Unit_ID	`unitId` is invalid.
400	Unit_Has_Chile	This unit cannot be deleted as it has one or more child unit.
400	Invalid_Unit_ID	The unit cannot be deleted because there are one or more endpoints associated
401	Unauthorized	The access token is missing or invalid.
403	Forbidden	The user doesn't have permission to access the service.
404	No_Such_Unit	The unit does not exist.
429	Too many requests	Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

Last updated: Mar 30, 2022