Home and Community API

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties for residential partners. See Get Started with Alexa Smart Properties for Residential APIs.

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.

API endpoint

The endpoint of the Home and Community 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 Home and Community API API includes the following operations.

Operation	HTTP Method and URI
Create a home community	`POST /enterprise/residential/v1/homeCommunities`
Get a home community	`GET /enterprise/residential/v1/homeCommunities/{id}`
List home communities	`GET /enterprise/residential/v1/homeCommunities?organizationId={organizationId}`
Update a home community	`PUT /enterprise/residential/v1/homeCommunities/{id}`
Delete a home community	`DELETE /enterprise/residential/v1/homeCommunities/{id}`
Create a home	`POST /enterprise/residential/v1/homes`
Get a home	`GET /enterprise/residential/v1/homes/{id}`
List homes	`GET /enterprise/residential/v1/homes?homeCommunityId={homeCommunityId}`
Update a home	`PUT /enterprise/residential/v1/homes/{id}`
Delete a home	`DELETE /enterprise/residential/v1/homes/{id}`

Manage home communities

Create a home community

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

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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 Smart Properties 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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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 Smart Properties 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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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 Smart Properties 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 Smart Properties 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.

Note: Organization ID can't be updated.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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 Smart Properties 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.

Important: If there are any homes in the community, you must delete them before you can delete the home community.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US, CA	None	None

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.

Last updated: Nov 10, 2022