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.

Request format

GET /enterprise/residential/v1/homes/{id}/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.{id}". String Yes
occupancyId The unique identifier for the occupancy. 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

{
   "occupancyId": "AedQo29xxx",
   "state": "VACANT",
   "requestedState": "OCCUPIED"
}

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

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

Set a home's occupancy state

Call POST /enterprise/residential/v1/homes/{id}/occupancies to set a home's occupancy state.

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.{id}". String Yes

Request body

{
   "state": "OCCUPIED"
}

Request body parameters

Field Description Type Required
state The occupancy state of the home: "OCCUPIED" OR "VACANT". String 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
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 endpoint 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.