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/{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

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

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

{
    "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

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.