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. 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 unit management APIs, 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. Use API calls to manage these complex properties.

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

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

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, such as a property, floor, wing, or 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. The parent of a unit can't be any of its sub 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 format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 to have. Accepted value: PLAIN String Yes
name.value.text The name of the unit. A unit name can contain letters or numbers and the following special characters, with no spaces or periods: _ - = # ; : ? @ &. The unit name can't exceed 250 characters. String Yes
parentId Unit under which to create the new unit. 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 Description

201 Created

The unit was created.

400 Bad Request

The request is malformed or is missing one or more required parameters.

  • INVALID_PARENT_ID – The parent unit Identifier specified is invalid.
  • INVALID_UNIT_NAME – Name can't be null or empty.
  • LEVEL_LIMIT_EXCEEDED – Unit can't 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 Senior Living Core

US

US, DE, IT, ES, JP

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

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 to have. Accepted value: PLAIN String Yes
name.value.text The name of the unit. String Yes
level Number of levels the unit is from the root unit. Root unit level is 0. Integer Yes
parentId ID of the parent unit for the retrieved 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 Description

200 OK

The request succeeded.

400 Bad Request

The request is malformed or is missing one or more required parameters.

  • 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 Not Found

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, the operation returns an empty list. The operation returns units that are accessible to the caller. All subunits up to depth specified, if any, are returned.

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 format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 fetch in a request. Default: up to 10 entries are returned, current max is 50.

Integer

No

nextToken

Token to fetch the next set of items. Set this property to the token provided in the paginationContext.nextToken property in the previous response. Use the same filter parameters as in first request. If filter parameters have changed, 400 Bad request exception is returned. For details, see Handling Pagination in Query Results.

String

No

queryDepth

Controls the number of immediate depth of subunits to retrieve. When not set, defaults to 1.

  • queryDepth=all – No restriction on subunit depth, return all child units.
  • queryDepth=1 (default) – Return the immediate children of parentUnitId.
  • queryDepth=value greater than 1 – Build the depth until max depth value level of the hierarchy or the depth specified in the parameter is reached. 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

An attribute or set of attributes to include in the response. Current values supported: all


When expand isn't set, the response for each unit includes unit ID in the id property and null for other response body properties. When expand is set to all, the response for each unit includes values for all the applicable properties.

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 example

{
  "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
results The units that matched the request. Array of unit objects Yes
results[*].id The id for the unit. String Yes
results[*].name.type The type of format the name.value field is expected to have. Possible values: PLAIN String Yes
results[*].name.value.text The name of the unit. String Yes
results[*].parentId ID of the parent unit for this unit. String Yes
results[*].level Number of levels the unit is from the root unit. Root unit level is 0. Integer Yes
paginationContext.nextToken Token used for getting the next page of results. For details, see Handling Pagination in Query Results. String No

When the request doesn't include expand=all, the level, name, and parentId properties are included in the response for each unit, but return null.

Additional request and response examples

The following example shows a request that uses the expand and queryDepth parameters to include all units for a parent unit and details for each unit.

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

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

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

The following example shows a request that uses the queryDepth 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.

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

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 Description

200 OK

The request succeeded.

400 Bad Request

The request is malformed or is missing one or more required parameters.

  • INVALID_NEXT_TOKEN – The token provided in nextToken is invalid or expired.
  • INVALID_MAX_RESULT – Number of requested results exceeds maximum supported.
  • 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 Not Found

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.

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 Senior Living Core

US

US, DE, IT, ES, JP

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

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 to have. Accepted value: PLAIN String Yes
name.value.text The name of the unit. The name of the unit. A unit name can contain letters or numbers and the following special characters, with no spaces or periods: _ - = # ; : ? @ &. The unit name can't exceed 250 characters. String 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 Description

200 OK

The unit was updated.

400 Bad Request

The request is malformed or is missing one or more required parameters.

  • INVALID_UNIT_NAME – Name can't be null or empty.
  • INVALID_UNIT_ID – The 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 is returned.

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 format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Description

200 OK

The unit was deleted.

400 Bad Request

The request is malformed or is missing one or more required parameters.

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

401 Unauthorized

The access token is missing or invalid.

403 Forbidden

The user doesn't have permission to access the service.

404 Not Found

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.

Was this page helpful?

Last updated: May 17, 2024