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