Skip to content

Houses#

Houses are the logical groupings where your locks are installed. Each house can have multiple locks and users. The API allows you to manage houses, including retrieving information about them and their associated locks.

Create a new house#

If you are looking to install locks on a new building, you will need to create a house for that building within our August/Yale ecosystem. You can do this using the following API call:

POST /houses

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

{
    "HouseName": "my-new-house"
}

All fields in the request body are required.

  • HouseName - The name of the new house you are creating.

This will create a new house with the name my-new-house. The API will respond with HTTP status 200 and a response body.

{
  "HouseName": "my-new-house",
  "HouseID": "00000000-0000-0000-0000-000000HOUSE1",
  "users": {
    "00000000-0000-0000-0000-000000001001": "superuser"
  }
}
  • HouseName - The name of the house you created.
  • HouseID - The unique August/Yale identifier for the house.
  • users - A map of user IDs to their roles in the house. This will initially contain your user ID as the superuser of the house.

Get a list of houses#

To retrieve a list of all houses associated with your partner user, you can use the following API call:

GET /users/houses/mine

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

The API will respond with HTTP status 200 and a response body containing all house IDs and names associated with your partner user.

{
  "houses": [
    {
      "HouseID": "00000000-0000-0000-0000-000000HOUSE1",
      "HouseName": "my-new-house",
      "type": "superuser",
      "imageInfo" : {
        ...
      }
    },
    {
      "HouseID": "00000000-0000-0000-0000-000000HOUSE2",
      "HouseName": "another-house",
      "type": "user",
      "imageInfo" : {
        ...
      }
    }
  ]
}
  • houses - An array of house objects referring to each house associated with your user, each containing:
  • HouseID - The unique August/Yale identifier for the house.
  • HouseName - The name of the house.
  • type - The role of the user in the house (e.g., superuser, user).
  • imageInfo - Additional information about the house image that is displayed in the Yale Access App.

Delete a house#

To delete a house, you can use the following API call:

Required

You must be a superuser of the house to use this endpoint. The house must also not have any locks or doorbells associated with it, otherwise the API will return an error.

DELETE /houses/:houseID

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

The following parameter is required in the request:

  • houseID - The unique August/Yale identifier for the house you want to delete.

This will delete the house with the specified houseID. The API will respond with HTTP status 200 and a response body indicating the house was successfully deleted.

{
  "message": "success"
}

Invite a user to a house#

When a new partner user is created, you may need to invite that user to a house so they can commission locks on that house. The user could commission the lock within the Yale Access App and add the new lock to the house that you initially created.

To invite a user to a house, you can use the following API call:

PUT /houses/adduser/:houseID/:otherUserID/:type

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

The following parameters are required in the request:

  • houseID - The unique August/Yale identifier for the house you want to invite the user to.
  • otherUserID - The unique August/Yale identifier for the user you want to invite to the house.
  • type - The role you want to assign to the user in the house (e.g., superuser, user).

This will invite the user with the specified otherUserID to the house with the specified houseID and assign them the specified role. The API will respond with HTTP status 200 and a response body indicating the user was successfully invited.

{
  "message": "success"
}

Update the name of a house#

To update the name of a house, you can use the following API call:

Required

You must be a superuser of the house to use this endpoint, otherwise the API will return an error.

PUT /houses/:houseID

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

{
    "HouseName": "new-house-name"
}

The following fields in the request parameters and request body are required:

  • houseID - The unique August/Yale identifier for the house you want to update.
  • HouseName - The new name you want to assign to the house.

This will update the name of the house with the specified houseID to the new name you provided. The API will respond with HTTP status 200 and a response body indicating the house name was successfully updated.

{
  "message": "success"
}