Home Occupancy 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 Occupancy API to manage home-occupancy state.

API endpoint

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

Operation	HTTP Method and URI
Get a home's occupancy state	`GET /enterprise/residential/v1/homes/{id}/occupancies/{occupancyId}` `GET /enterprise/residential/v1/homes/{id}/occupancies/~latest`
Set a home's occupancy state	`POST /enterprise/residential/v1/homes/{id}/occupancies`

About home occupancy states

A home's occupancy state defines who has access to the home unit (as an object in the Alexa Smart Properties for residential system) and the home's resources (such as smart home devices). There are three possible occupancy states: vacant, occupied, and linked.

When a home is in the vacant state, you, as an enterprise user, control the home unit and all home resources. When you create a new home, it's in the vacant state.

When a home is in the occupied state, you, as an enterprise user, have read access to the home unit via Alexa APIs. You don't have access to the home's resources. This protects the resident's privacy and security. You provide a smart home skill that Alexa Smart Properties for residential can enable for — and link to — the resident's Amazon account when the home's state changes to linked. See Skill enablement for homes in the linked state

When a home is in the linked state, you, as an enterprise user, have read access to the home unit via Alexa APIs. You no longer have access to the home's resources. Alexa Smart Properties for residential moves these resources to the resident's Amazon account. The resident can then control them as their own personal devices by using the smart home skill that you provided.

Home occupancy state transitions

A home's occupancy state changes when one of the following actions occurs: move in, move out, link resident's personal Amazon account, and unlink resident's personal Amazon account.

Move in — When a resident moves into a home, you change the home's occupancy state from vacant to occupied. When you do so, Alexa Smart Properties for residential returns an occupancyId you put in the URL that the resident uses to access the Alexa Smart Properties for residential account linking web app. See Resident account link URL generation.
Move out — When a resident moves out, you change the home's occupancy state from occupied to vacant. All permissions revert back to you, the enterprise user, to manage the home and its resources.
Link resident's personal Amazon account — The resident logs in to the Alexa Smart Properties for residential web app using their Amazon account credentials, and they accept the app's terms and conditions to link their personal Amazon account with the home. When this happens, Alexa Smart Properties for residential changes the home's state to linked.
Unlink resident's personal Amazon account — The resident can unlink their personal Amazon account from the home at any time by using the Alexa Smart Properties for residential web app. If a resident unlinks their personal Amazon account, the home's occupancy state changes from linked to occupied. You, the enterprise user, can also make this happen by explicitly changing the home's occupancy state from linked to occupied; this state change unlinks the resident's personal Amazon account from the home and notifies the resident of the change.
Move out in linked state — You can change the home's occupancy state from linked state to vacant. This action unlinks the resident's account from the home, revokes all permissions from the resident, and restores all permissions to you, the enterprise user, to manage the home and its resources.

Resident account link URL generation

Resident account linking is accomplished by providing a link in your app or portal to the Alexa Smart Properties for residential web app. Resident account linking transfers device ownership to the resident in addition to automatically linking your skill with their account. To generate a URL that a resident can follow from your app to the Alexa Smart Properties for residential account linking portal, create the following URL.

Country	URL
US	`https://www.amazon.com/alexaresidential/occupancyId/{occupancyID}`
Canada	`https://www.amazon.ca/alexaresidential/occupancyId/{occupancyID}`

Note: Resident account linking is only functional when the home is in the occupied state. Every time the home's occupancy state changes a new occupancyID is created. Please make sure to use the most recent occupancyID that was created after the home is in the occupied state.

Get a home's occupancy state

Call GET /enterprise/residential/v1/homes/{id}/occupancies/{occupancyId} to get details for a specific home occupancy or GET /enterprise/residential/v1/homes/{id}/occupancies/~latest to get details of the latest home occupancy created for a home. This request returns a HomeOccupancy object.

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/{homeId}/occupancies/{occupancyId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

GET https://api.amazonalexa.com/enterprise/residential/v1/homes/{id}/occupancies/~latest 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, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.unit.did.{unitId}"`.	String	Yes
`occupancyId`	The unique identifier for the occupancy. To get the latest occupancy, use the reserved identifier `~latest`.	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 example

The response body is a HomeOccupancy object.

{
   "occupancyId": "AedQo29xxx",
   "state": "VACANT",
   "requestedState": "OCCUPIED",
   "linkedApplications": [
       {
           "type": "SKILL",
           "stage": "live",
           "id": "amzn1.ask.skill.123456789",
           "accountLinkRequest": {
               "redirectUri": "https://example.com",
               "authCode": "3pauthcode",
               "type": "AUTH_CODE"
           }
       }
   ]
}

HomeOccupancy object schema

Field	Description	Type	Required
`occupancyId`	The unique identifier for the occupancy.	String	Yes
`state`	The occupancy state of the home: `"VACANT"`, `"OCCUPIED"`, or `"LINKED"`.	String	Yes
`requestedState`	The requested occupancy state of the home: `"VACANT"`, `"OCCUPIED"`, or `"LINKED"`. Exists only if a home-occupancy state change is in progress.	String	No
`linkedApplications`	List of LinkedApplication objects, one for each linked application.	List	No

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. 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, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested home or occupancy wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	The service is currently unavailable to handle the request.

Set a home's occupancy state

Call POST /enterprise/residential/v1/homes/{id}/occupancies to set a home's occupancy state by creating a HomeOccupancy object.

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/{id}/occupancies 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, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.unit.did.{unitId}"`.	String	Yes

Request body example

{
    "state": "OCCUPIED",
    "linkedApplications": [
        {
            "type": "SKILL",
            "stage": "live",
            "id": "amzn1.ask.skill.123456789",
            "accountLinkRequest": {
                "redirectUri": "https://example.com",
                "authCode": "3pauthcode",
                "type": "AUTH_CODE"
            }
        }
    ]
}

Request body parameters

Field	Description	Type	Required
`state`	The occupancy state of the home: `"VACANT"` or `"OCCUPIED"`.	String	Yes
`linkedApplications`	List of LinkedApplication objects, one for each linked application.	List	No

LinkedApplication object schema

Field	Description	Type	Required
`type`	App type. Currently the only supported value is `"SKILL"`.	Object	Yes
`stage`	Skill stage: `development`, `certification`, or `live`.	Enum	Yes
`id`	Unique ID for the app. Skill IDs must be in the Amazon Common Identifier (ACI) format `"amzn1.ask.skill.{skillId}"`.	String	Yes
`accountLinkRequest`	Account linking request information, as an AccountLinkRequest object.	Object	Yes, for skills that support account linking

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

{
  "occupancyId": "AedQo29xxx"
}

Response parameters

Field	Description	Type	Required
`occupancyId`	A unique identifier for the occupancy.	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. 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
202	Accepted	The request has been accepted for processing, and the response body contains the `occupancyId` for the new occupancy.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested home wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	The service is currently unavailable to handle the request.

Last updated: Nov 10, 2022