Home Occupancy API

Use the Home Occupancy API to manage home-occupancy state.

About home occupancy states

A home's occupancy state defines who has access to the home unit (as an object in the Alexa 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 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 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 for Residential returns an occupancyId you put in the URL that the resident uses to access the Alexa 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 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 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 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 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 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

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.

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", "OCCUPIED", or "LINKED". 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

Field Description Type Required

redirectUri

The redirect_uri parameter that was included in the authorization request to your OAuth 2.0 server to obtain the user's authorization code. This enables Amazon to retrieve access tokens from your token server. This URL must be opaque to Amazon.

String

Yes

authCode

An OAuth 2.0 authorization code. This value is required to perform account linking. For details, see Authorization code grant flow.

String

Yes

type

The type of account linking request, which is based on OAuth 2.0 authorization request protocols.

String. Must be AUTH_CODE.

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