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.

API endpoint

The endpoint of the Property Hierarchy Management API 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 API includes the following operations.

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.

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

Response header

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

Response body

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

Response body parameters

Error response

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

Error response parameters

HTTP response codes

Get a Unit

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

This operation is available in the following countries.

Request format

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

Request parameters

Request body

None.

Response header

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

Response body

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

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

Response body parameters

Error response

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

Error response parameters

HTTP response codes

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

This operation is available in the following countries.

Request format

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

Request query parameters

Request body

None.

Response header

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

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

Error response

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

Error response parameters

HTTP response codes

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

Response body example

{
  "results": [
    {
      "id": "amzn1.alexa.unit.{unitId}",
      "name": {
             "type": "PLAIN",
              "value": {
                  "text": "Name"
               }
           }
      "parentId": "amzn1.alexa.unit.{unitId}",
      "level":2
    },
    {
      "id": "amzn1.alexa.unit.{unitId}",
      "name": {
             "type": "PLAIN",
              "value": {
                  "text": "Name"
               }
           }
      "parentId": "amzn1.alexa.unit.{unitId}",
      "level":2
    },
    {
      "id": "amzn1.alexa.unit.{unitId}",
      "name": {
             "type": "PLAIN",
              "value": {
                  "text": "Name"
               }
           }
      "parentId": "amzn1.alexa.unit.{unitId}",
      "level":2
    }
  ],
  "paginationContext": {
    "nextToken": "ABC124"
  }
}

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

Response body example

{
  "results": [
    {
      "id": "amzn1.alexa.unit.{unitID}"
    }
  ],
  "paginationContext": {
    "nextToken": "ABC124"
  }
}

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

Response body example

{
  "results": [
    {
      "id": "amzn1.alexa.unit.{unitId}"
    },
    {
      "id": "amzn1.alexa.unit.{unitId}"
    },
    {
      "id": "amzn1.alexa.unit.{unitId}"    
    }
  ],
  "paginationContext": {
    "nextToken": "ABC1234"
  }
}
}

Update a unit

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

This operation is available in the following countries.

Request format

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

Request path parameters

Request body format

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

Request body parameters

Response header

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

Response body

None.

Response body parameters

None.

Error response

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

Error response parameters

HTTP response codes

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.

Request format

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

Request path parameters

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}"

Response body

None.

Response body parameters

None.

Error response

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

Error response parameters

HTTP response codes

Last updated: Nov 22, 2022