Home Occupancy API

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.

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 this URL:

https://www.amazon.com/alexaresidential/occupancyId/{occupancyID}

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.

Request format

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

or

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

Request body

None.

Response header

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

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

Error response

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

Error response parameters

HTTP response codes

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.

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

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

LinkedApplication object schema

Response header

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

Response body example

{
  "occupancyId": "AedQo29xxx"
}

Response parameters

Error response

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

Error response parameters

HTTP response codes