Home Occupancy API
Use the Home Occupancy API to manage home-occupancy state. For details, see Managing Homes, Communities, and Skills.
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.
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.
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",
"state": "VACANT",
"requestedState": "OCCUPIED",
"linkedApplications": [
{
"type": "SKILL",
"stage": "live",
"id": "amzn1.ask.skill.123456789",
"accountLinkRequest": {
"redirectUri": "https://example.com",
"authCode": "3pauthcode",
"type": "AUTH_CODE"
}
}
]
}
Response parameters
| Field |
Description |
Type |
Required |
occupancyId |
The unique identifier for the occupancy. |
String |
Yes |
state |
The occupancy state of the home: "VACANT" or "OCCUPIED". |
String |
Yes |
requestedState |
The requested occupancy state of the home: "VACANT" or "OCCUPIED". Exists only if a home-occupancy state change is in progress. |
String |
No |
linkedApplications |
List of linked applications. For details, see Linked application schema. |
Object |
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.
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
{
"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: "OCCUPIED" OR "VACANT". |
String |
Yes |
Linked application 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. |
Object |
Yes, for skills that support account linking |
accountLinkRequest.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, for skills that support account linking |
accountLinkRequest.authCode |
A third-party cloud's OAuth 2.0 "Authorization Code." This value is required to perform account linking. For details, see Authorization code grant flow. |
String |
Yes, for skills that support account linking |
accountLinkRequest.type |
The type of account linking request, which is based on OAuth 2.0 authorization request protocols. |
String. Must be AUTH_CODE. |
Yes, for skills that support account linking |
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. |
