Property Hierarchy Management API

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.

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.

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.

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

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

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.

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.