Skip to content

Users and Devices#

This is a good place for getting started with the API.

One of the most important things you'll do in your application will be to list your user's locks and their statuses. Since all of your API calls will be over the internet, all of your user's locks must have bridges like the August Connect or August Doorbell. Listing the user's bridges is the right place to start because this also gives a list of the attached locks.

Here is a handy sequence diagram to show you how to list the locks and two ways to get their statuses. The fast way (~0.4s) indicates the last known state as reported by the bridge or an API operation. The slower way (~5.0s) forces the bridge to check the current status of the lock and report it.

Sequence Diagram of Listing Locks

DoorSense ™#

Type 3 and Type 4 locks may have DoorSense ™ enabled. Not every owner will install the magnet and calibrate the lock for this feature, but if they do, then you will see additional state data in calls to /locks/:lockID/status and /remoteoperate/:lockID/status We expect most owners will install and calibrate for DoorSense if the lock supports it.

Please see the API Reference Links above for examples of what DoorSense data will look like, but in general you are looking for a field named doorState.

Webhooks, not Polling, for Realtime Notification#

By using webhooks, you can get near-realtime notifications of locks going online and offline, locking and unlocking. Please use webhooks instead of polling the August locks. If you keep the bridge busy with polling then no other commands can reach the lock from the app or bridge.

Don't DoS the lock!

Using PUT for Status#

Why PUT vs GET

Note that even though you're using the PUT verb with /remoteoperate/status, you are not changing the lock status. You are reading the lock status.

There is a side effect that the status reported in GET /locks/:LockID gets updated, and that is the reason for PUT vs GET.

Status unknown and not-advertising#

see also List of Lock States

  • If status == unknown then the Connect went offline.
  • if status == not-advertising then the August servers can communicate with the bridge, but the bridge recently said that the lock is not advertising.

💡