Home and Community API

Use the Home and Community API to manage home communities and homes. For details about how to manage home communities and homes, see Managing Homes, Communities, and Skills.

Manage home communities

Create a home community

Call POST /enterprise/residential/v1/homeCommunities to create a home community.

Request format

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

Request body

{
  "name": "{homeCommunityName}",
  "organizationId": "amzn1.alexa.unit.did.{id}"
}
Field Description Type Required
name The home community name. String Yes
organizationId The Alexa for Residential organization ID, in the format "amzn1.alexa.unit.did.{id}". String Yes

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/enterprise/residential/v1/homeCommunities/{id}"
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
id Home community ID as part of the Location header URI. String Yes

Response body

{
  "id": "amzn1.alexa.unit.did.{id}"
}
Field Description Type Required
id The home community ID for the new home community. String Yes

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
201 Created The home community was successfully created.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
500 Internal Server Error The request couldn't be handled because of an internal service error.

Get a home community

Call GET /enterprise/residential/v1/homeCommunities/{id} to retrieve the metadata of a specific home community provided that the user has access to view it.

Request format

GET /enterprise/residential/v1/homeCommunities/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
id The unit ID for the home community, in the Amazon Common Identifier (ACI) 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.{id}",
   "organizationId": "amzn1.alexa.unit.did.{id}",
   "name": "{homeCommunityName}"
}
Field Description Type Required
id The home community ID. String Yes
organizationId The Alexa for Residential organization ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
name The home community name. String Yes

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
200 OK The request succeeded.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home community wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.

List home communities

Call GET /enterprise/residential/v1/homeCommunities?organizationId={organizationId} to get a list of home communities.

Request format

GET /enterprise/residential/v1/homeCommunities?organizationId={organizationId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request query parameters

Field Description Type Required
organizationId The Alexa for Residential organization ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
maxResults Maximum number of results to display. The value of this parameter must between 1 and 10. Default is 10. Integer No
nextToken Continuation token returned in response object of previous list home communities response. For details, see Handling Pagination in Query Results. 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

{
   "homeCommunities": [
      {
         "id": "amzn1.alexa.unit.did.{id}",
         "name": "{homeCommunityName}",
         "organizationId": "amzn1.alexa.unit.did.{id}"
      }
   ]
}
Field Description Type Required
id The home community ID. String Yes
name The home community name. String Yes
organizationId The Alexa for Residential organization ID, in the format "amzn1.alexa.unit.did.{id}". String Yes

HTTP response codes

Status code Name Description
200 OK The request succeeded.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.

Update a home community

Call PUT /enterprise/residential/v1/homeCommunities/{id} to update the metadata of a specific home community provided that the user has access to update it.

Request format

PUT /enterprise/residential/v1/homeCommunities/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
id The unit ID for the home community, in the Amazon Common Identifier (ACI) format "amzn1.alexa.unit.did.{id}". String Yes

Request body

{ 
   "id": "amzn1.alexa.unit.did.{id}",
   "organizationId": "amzn1.alexa.unit.did.{id}",
   "name": "{homeCommunityNameUpdated}"
}
Field Description Type Required
id The home community ID. String Yes
organizationId The Alexa for Residential organization ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
name The updated home community name. String Yes

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

None.

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
204 No content The home community was successfully updated.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home community wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.

Delete a home community

Call DELETE /enterprise/residential/v1/homeCommunities/{id} to delete a home community.

Request format

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

Request path parameters

Field Description Type Required
id The unit ID for the home community, in the Amazon Common Identifier (ACI) 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

None.

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
204 No content The home community was successfully deleted.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home community wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.

Manage homes

Create a home

Call POST /enterprise/residential/v1/homes to create a new home in a home community.

Request format

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

Request body

{
  "name": "{homeName}",
  "homeCommunityId": "amzn1.alexa.unit.did.{id}"
}
Field Description Type Required
name The name of the home. String Yes
homeCommunityId The home community ID to add the home to, in the format "amzn1.alexa.unit.did.{id}". String Yes

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/enterprise/residential/v1/homes/{id}"
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
id Home ID as part of the Location header URI. String Yes

Response body

{
  "id": "amzn1.alexa.unit.did.{id}"
}
Field Description Type Required
id The ID for the new home. String Yes

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
201 Created The home was successfully created.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
500 Internal Server Error The request couldn't be handled because of an internal service error.

Get a home

Call GET /enterprise/residential/v1/homes/{id} to retrieve the metadata of a specific home provided that the user has access to view it.

Request format

GET /enterprise/residential/v1/homes/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Field Description Type Required
id The ID for the home. 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.{id}",
   "homeCommunityId": "amzn1.alexa.unit.did.{id}",
   "name": "{homeName}"
}
Field Description Type Required
id The home ID. String Yes
homeCommunityId The home community ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
name The home name. String Yes

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
200 OK The request succeeded.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.

List homes

Call GET /enterprise/residential/v1/homes?homeCommunityId={homeCommunityId} to get a list of homes.

Request format

GET /enterprise/residential/v1/homes?homeCommunityId={homeCommunityId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request query parameters

Field Description Type Required
homeCommunityId The home community ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
maxResults Maximum number of results to display. The value of this parameter must between 1 and 10. Default is 10. Integer No
nextToken Continuation token returned in response object of previous list homes response. For details, see Handling Pagination in Query Results. 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

{
   "homes": [
      {
         "homeCommunityId": "amzn1.alexa.unit.did.{id}",
         "id": "amzn1.alexa.unit.did.{id}",
         "name": "{homeName}"
      }
   ]
}
Field Description Type Required
homeCommunityId The home community ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
id The home ID. String Yes
name The home name. String Yes

HTTP response codes

Status code Name Description
200 OK The request succeeded.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.

Update a home

Call PUT /enterprise/residential/v1/homes/{id} to update the metadata of a specific home provided that the user has access to update it.

Request format

PUT /enterprise/residential/v1/homes/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Field Description Type Required
id The ID for the home. String Yes

Request path parameters

Field Description Type Required
id The unit ID for the home, in the Amazon Common Identifier (ACI) format "amzn1.alexa.unit.did.{id}". String Yes

Request body

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

Request body parameters

Field Description Type Required
id The home ID. String Yes
homeCommunityId The home community ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
name The new home name. String Yes

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

None.

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
204 No content The home was successfully updated.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.

Delete a home

Call DELETE /enterprise/residential/v1/homes/{id} to delete a specific home provided that the user has access to delete it.

Request format

DELETE /enterprise/residential/v1/homes/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Field Description Type Required
id The ID for the home. 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

None.

Error response

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

Error response parameters

Field Description Type Required
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status code Name Description
204 No content The home was successfully deleted.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing or invalid.
403 Forbidden The user doesn't have permission to access the service.
404 Not found The requested home wasn't found.
500 Internal Server Error The request couldn't be handled because of an internal service error.