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 |
---|---|
| |
|
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 |
|
Canada |
|
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}
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 |
---|---|---|---|
|
The unit ID for the home, in the Amazon Common Identifier (ACI) format |
String |
Yes |
|
The unique identifier for the occupancy. To get the latest occupancy, use the reserved identifier |
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 |
---|---|---|---|
|
The unique identifier for the occupancy. |
String |
Yes |
|
The occupancy state of the home: |
String |
Yes |
|
The requested occupancy state of the home: |
String |
No |
|
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 |
---|---|---|---|
|
App type. Currently the only supported value is |
Object |
Yes |
|
Skill stage: |
Enum |
Yes |
|
Unique ID for the app. Skill IDs must be in the Amazon Common Identifier (ACI) format |
String |
Yes |
|
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