Device Group Management API

About device groups

A device group represents a group of devices that a user can control together by speaking to an Alexa Built-in device that's a member of the group. Targeting can be explicit or implicit. Explicit targeting happens when the user specifies a device group name, for example, "Alexa, turn on the living room lights." Implicit targeting happens when the user doesn't specify the group name. For example, if a user says, "Alexa, turn on the lights" to a device that's in a device group, Alexa turns on all lights in the group. Devices in a device group are typically located in the same physical space, but this isn't a requirement.

In Alexa for Hospitality, you can use the Device Group Management API to create groups of devices within a unit. You can configure device groups by using calls such as the following:

Create a device group

Call POST /v1/deviceGroups to create a device group.

Request format

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

Request path parameters

None.

Request body format

{
  "friendlyName": {
    "type": "PLAIN",
    "value": {
      "text": "{groupFriendlyName}"
    }
  },
  "memberDevices": [
    {
      "id": "amzn1.alexa.endpoint.{endpointId}"
    }
  ],
  "associatedUnits": [
    {
      "id": "amzn1.alexa.unit.did.{UnitId}"
    }
  ]
}

Request body example

{
  "friendlyName": {
    "type": "PLAIN",
    "value": {
      "text": "kitchen"
    }
  },
  "memberDevices": [
    {
      "id": "amzn1.alexa.endpoint.es2fiL0v9nOJlfYf5Raw7Ff90bv7tAJkie3p3Zzf4C7svpIEL4GcGh8lQdBbYWIjqfA2ydFEvzy_kG3QBOg2MRUBDR0StBHCwNombp4-2N7SY8H1JCQxKO0mKO1Ez5VX3QPItZ26rEvnqpjjday41DZ0lz4lNZAHpoc0GuvX6M4uRKO9wFuTklf7XZf1EOiRLyKQg0rPBE1V7epjFqVRKtAZluxMmZkCgQJ30Mwt4MxQFmha-Ypfm0s2vzpXqe6"
    }
  ],
  "associatedUnits": [
    {
      "id": "amzn1.alexa.unit.did.7R9ITXF3SHFHJDGQYSAXJ9C7E78CA2DD3C1NM2RN70BSELVVZ1EDZZC4KVQ6GLZ72W0QXDIQ49RT5CMPU91DW6ZTSKA6HPQI3LAPZYMY"
    }
  ]
}

Request body parameters

Field Description Type Required
friendlyName The device group's friendly name, as a NameValue object. All device groups within a unit must have unique names. NameValue Object Yes
memberDevices Devices to add to the device group.
• All endpoints in the list must exist, and the caller must have access to them.
• All devices in the list must be associated with the same unit as the group being created.
• The list can be empty.
List of Endpoint objects. No
associatedUnits Unit identifiers to associate with the device group.
• Exactly one unit must be specified.
• The specified unit must exist and the caller must have access to it.
• Once created, a device group's associated unit cannot be changed.
• A unit cannot be associated with a device group after the device group has been created.
List of Unit objects. Yes

NameValue object

Field Description Type
type The name value type. Currently the only supported value is "PLAIN". String
value The name value, as a Value object. Object

Value object

Field Description Type
text The string value. String

Endpoint object

Field Description Type
id The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{endpointId}". String

DeviceGroup object

Field Description Type
id The device group ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpointGroup.{deviceGroupId}". String
friendlyName The device group's friendly name. NameValue object
memberDevices Devices that are members of the device group. List of Endpoint objects.
associatedUnits Unit identifiers that are associated with the device group. Currently only one unit identifier can be specified List of Unit objects.

Unit object

Field Description Type
id The unit ID, in the format "amzn1.alexa.unit.did.{UnitId}". String

Success response header

HTTP/1.1 201 Created
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

{
    "id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g"
}

Response body parameters

Field Description Type Required
id The device group ID for the new device group, in the format "amzn1.alexa.endpointGroup.{deviceGroupId}". String Yes

Error response

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

Error response parameters

Field Description Type Required
type The error type for the error. String Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String Yes

HTTP response codes

Status code Type Message Description
201 CREATED Created The request succeeded.
400 BAD_REQUEST Bad Request The request was malformed, for one of the following reasons.
• A device group with the specified friendly name already exists for the specified associated unit.
• A specified associated unit doesn't exist, or the caller doesn't have permission to access it.
• A specified member device doesn't exist, or the caller doesn't have permission to access it.
• A specified member device doesn't have the same associated unit as the device group.
• A specified Alexa-Enabled member device is already a member device of another device group.
401 UNAUTHORIZED Unauthorized Authorization failed.
403 FORBIDDEN Forbidden The request couldn't be completed.
429 TOO_MANY_REQUESTS Too Many Requests The request was throttled.
500 INTERNAL_SERVER_ERROR Internal Server Error A server-side error occurred.
503 SERVICE_UNAVAILABLE Service Unavailable The service is temporarily unavailable.

Add a device to a device group

Call POST /v1/deviceGroups/{id}/memberDevices to add a device to a device group.

Request format

POST /v1/deviceGroups/{id}/memberDevices HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
id The device group identifier. Must represent a valid device group. String Yes

Request body format

{
    "memberDevice": {
      "id": "{endpointId}"
    }
}

Request body example

{
    "memberDevice": {
      "id": "amzn1.alexa.endpoint.W28D0yZ5FzcjByRRnEQwmUHC1tZAncTyo8ekrOky8oVUtkayVpomPYpy7gjIVGDa5VoiRpNT8AKJGtmD92xmV2hlzIyBQSzYrELdsIBSXxSrahd375XACr2iuyo2POKCBbgYBaCSzIvXoklLdAEugOMk5WG8gi1sh4l7IBVoQ9RwzkPp731ZbTtnjHyC5WCceM4s5a9RFtrYDD3ejoER5RBX3o0W7FYtGlM3faDbgTPeL1Nr4cWoyIAguRK4J2P"
    }
}

Request body parameters

Field Description Type Required
memberDevice Device to add to the device group as a member.
• Must represent a valid Endpoint object.
• The endpoint must exist, and the caller must have access to it.
• The endpoint must be associated with the same unit as the device group it is being added to.
Endpoint object Yes

Success response header

HTTP/1.1 204 No Content
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

Error response

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

Error response parameters

Field Description Type Required
type The error type for the error. String Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String Yes

HTTP response codes

Status code Type Message Description
204 NO_CONTENT No Content The request succeeded.
400 BAD_REQUEST Bad Request The request was malformed, for one of the following reasons.
• The specified member device doesn't exist, or the caller doesn't have permission to use it.
• The specified member device doesn't have the same associated unit as the device group.
• The specified Alexa-Enabled member device is already a member device of another device group.
401 UNAUTHORIZED Unauthorized Authorization failed.
403 FORBIDDEN Forbidden The request couldn't be completed.
404 NOT_FOUND Not Found The specified device group doesn't exist, or the caller doesn't have permission to access it.
429 TOO_MANY_REQUESTS Too Many Requests The request was throttled.
500 INTERNAL_SERVER_ERROR Internal Server Error A server-side error occurred.
503 SERVICE_UNAVAILABLE Service Unavailable The service is temporarily unavailable.

Remove a device from a device group

Call DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId} to remove a device from a device group.

Request format

DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
id The device group identifier. Must represent a valid device group. String Yes
endpointId The endpoint identifier for the device to remove from the device group. Must represent a valid Endpoint object for a member device in the device group. String Yes

Success response header

HTTP/1.1 204 No Content
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

Error response

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

Error response parameters

Field Description Type Required
type The error type for the error. String Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String Yes

HTTP response codes

Status code Type Message Description
204 NO_CONTENT No Content The request succeeded.
400 BAD_REQUEST Bad Request The request was malformed.
401 UNAUTHORIZED Unauthorized Authorization failed.
404 NOT_FOUND Not Found The request failed for one of the following reasons.
• The specified device group does not exist, or the caller does not have permission to access it.
• The specified member device does not exist within the device group, or the caller does not have permission to access it.
429 TOO_MANY_REQUESTS Too Many Requests The request was throttled.
500 INTERNAL_SERVER_ERROR Internal Server Error A server-side error occurred.
503 SERVICE_UNAVAILABLE Service Unavailable The service is temporarily unavailable.

Change a device group's friendly name

Call POST /v1/deviceGroups/{id}/friendlyName to change a device group's friendly name.

Request format

POST /v1/deviceGroups/{id}/friendlyName HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
id The device group identifier. Must represent a valid device group. String Yes

Request body format

{
  "type": "PLAIN",
  "value": {
    "text": "{groupFriendlyName}"
  }
}

Request body example

{
  "type": "PLAIN",
  "value": {
    "text": "kitchen"
  }
}

Request body parameters

Field Description Type  
friendlyName The new friendly name for the device group, as a NameValue object. NameValue object Yes

Success response header

HTTP/1.1 204 No Content
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

Error response

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

Error response parameters

Field Description Type Required
type The error type for the error. String Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String Yes

HTTP response codes

Status code Type Message Description
204 NO_CONTENT No Content The request succeeded.
400 BAD_REQUEST Bad Request The request was malformed, for one of the following reasons.
• A device group with the specified friendly name already exists for the specified associated unit.
401 UNAUTHORIZED Unauthorized Authorization failed.
403 FORBIDDEN Forbidden The request couldn't be completed.
404 NOT_FOUND Not Found The specified device group doesn't exist, or the caller doesn't have permission to access it.
429 TOO_MANY_REQUESTS Too Many Requests The request was throttled.
500 INTERNAL_SERVER_ERROR Internal Server Error A server-side error occurred.
503 SERVICE_UNAVAILABLE Service Unavailable The service is temporarily unavailable.

Delete a device group

Call DELETE /v1/deviceGroups/{id} to delete a device group. All member devices and associated units are removed from the device group upon deletion, but they continue to exist.

Request format

DELETE /v1/deviceGroups/{id}  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
id The device group identifier. Must represent a valid device group. String Yes

Success response header

HTTP/1.1 204 No Content
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

Error response

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

Error response parameters

Field Description Type Required
type The error type for the error. String Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String Yes

HTTP response codes

Status code Type Message Description
204 NO_CONTENT No Content The request succeeded.
400 BAD_REQUEST Bad Request The request was malformed.
401 UNAUTHORIZED Unauthorized Authorization failed.
404 NOT_FOUND Not Found The specified device group doesn't exist, or the caller doesn't have permission to access it.
429 TOO_MANY_REQUESTS Too Many Requests The request was throttled.
500 INTERNAL_SERVER_ERROR Internal Server Error A server-side error occurred.
503 SERVICE_UNAVAILABLE Service Unavailable The service is temporarily unavailable.

List device groups

Call GET /v1/deviceGroups to retrieve a list of device groups.

Request format

GET /v1/deviceGroups?associatedUnits.id={UnitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

None.

Request and response examples

The following examples show how to use this call.

Include only default information

This example shows how to include only default information for each device group.

Following is the request:

GET /v1/deviceGroups?associatedUnits.id=amzn1.alexa.unit.did.KOHSO00IAQYD6S0W5GWBKF1U2JQFDK1GHAJFNPAK4MTCHO0VJNMTJQOQVOVHMOUW4CW5XM0TC4LDRKBA1NLOS6EKPAXDD5AVEY3E5QVN HTTP/1.1

Following is the response:

HTTP/1.1 200 OK
{
  "paginationContext": {
    "nextToken": null
  },
  "results": [
    {
      "deviceGroup": {
        "id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g"
      }
    }
  ]
}

Include details for each device group

This example shows how to include details for each device group by using the expand=all parameter.

Following is the request:

GET /v1/deviceGroups?associatedUnits.id=amzn1.alexa.unit.did.GMCCVDN5EIN4PBFQMNRHT7U6H4RDMXNEYAIHYX4C1IVX3RARAEAZJU1KMAC74VFK00TPD0PWWITP991M4E6UE14KW2Q4BGM0X0PEMEHD&expand=all HTTP/1.1

Following is the response:

HTTP/1.1 200 OK
{
  "paginationContext": {
    "nextToken": null
  },
  "results": [
    {
      "deviceGroup": {
        "id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g",
        "friendlyName": {
          "type": "PLAIN",       
          "value": {
            "text": "kitchen"
          }
        },
        "memberDevices": [
          {
            "id": "amzn1.alexa.endpoint.BmX5E58b3nEKsmwSwKs6NofAP9eNe3jFs9C5aa3Ui49CAnpmkwKiZ58OhdPrsMVzxjZkgn5TWrFioHkACNhAmNKximBGWTpfBzh1IpJIR14b0gfT83evGBCvMBf0HpAz9HEzBqnToo1NnSjBGUqpiFUr8FfrCa26bNYdqhsIZ8aNlOdmb8UK4dT2tQnYn52MFP9x4lkfGsXN93YIaI3ur42GxuvO5CFOBgJ8ALPf7UDCMadoZ3WM3db2cZ2EW92"
          }
        ],
        "associatedUnits": [
          {
            "id": "amzn1.alexa.unit.did.7RBKKY0AGCGS9WWGNGG6QLFJQ2U6XADPWRQCS15O7DWNO62U0AAHYF5B79I018JMGLFWQTRUHTGSI7BA7A9CEOD929TBP253R82V03R3"
          }
        ]
      }
    }
  ]
}

Request query parameters

Field Description Type Required
associatedUnits.id Filter device groups to those that are associated with the specified unit. String Yes
maxResults Maximum number of results per call. The value of this parameter must be between 1 and 10. The default value is 10. Integer No
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. Same filter parameters should be passed as in first request. If filter parameters have changed, 400 Bad Request will be returned. For details, see Handling Pagination in Query Results. String No
expand The set of properties to return in the response. Currently the only supported value is "all". If this parameter isn't specified, only the "id" property is returned. String No

Success response header

HTTP/1.1 200 OK
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 parameters

Field Description Type Expanded Results Only
paginationContext Object containing pagination information. If present, the response contains incomplete results. If omitted, all results were already returned. For details, see Handling Pagination in Query Results. Object No
paginationContext.nextToken Use the value of nextToken in the next request as the continuation token to list the next set of objects. String No
results List of device groups returned in response to the query. List of DeviceGroup objects No
results.deviceGroup Device group object. DeviceGroup object No
results.deviceGroup.id The device group ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpointGroup.{deviceGroupId}". String No
results.deviceGroup.friendlyName The device group's friendly name. NameValue object Yes
results.deviceGroup.memberDevices Devices that are members of the device group. List of Endpoint objects. Yes
results.deviceGroup.associatedUnits Unit identifiers that are associated with the device group. Currently only one unit identifier can be specified List of Unit objects. Yes

Error response

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

Error response parameters

Field Description Type Required
type The error type for the error. String Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String Yes

HTTP response codes

Status code Type Message Description
200 OK OK The request succeeded.
400 BAD_REQUEST Bad Request The request was malformed, for one of the following reasons.
• An invalid or expired nextToken value was specified.
• A valid nextToken value was specified, but filter parameters did not match those in the previous request.
• An invalid maxResults value was specified.
401 UNAUTHORIZED Unauthorized Authorization failed.
403 FORBIDDEN Forbidden The request couldn't be completed.
429 TOO_MANY_REQUESTS Too Many Requests The request was throttled.
500 INTERNAL_SERVER_ERROR Internal Server Error A server-side error occurred.
503 SERVICE_UNAVAILABLE Service Unavailable The service is temporarily unavailable.