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.

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}

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}

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

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.

Was this page helpful?

Last updated: Nov 10, 2022