Skip to main content

​
Overview

Seam enables you to lock or unlock your door lock remotely. This guide walks you through how to perform these actions using the Seam API. When you send a command to a smart lock, it might take a while for Seam to confirm the action’s success. To handle this, Seam provides an “action attempt” object, which indicates whether the action was successful. To ensure that the action has been successfully executed, we advise checking the status of the action attempt object by polling the “Get Action Attempt” request. Once Seam has successfully confirmed the action, the action attempt’s status will indicate success. Some providers and device models cannot confirm whether the physical lock or unlock happened in a reasonable time or at all. In those cases, a successful action attempt can still include action_attempt.result.was_confirmed_by_device = false.

​
Before You Begin: Confirm Capabilities

Before you attempt to lock or unlock a device, be sure to confirm that your device has the capability to perform these operations. You can inspect the capabilities of a device by checking the following capability flags for the device:
  • device.can_remotely_lock
  • device.can_remotely_unlock
Use Get Device for a specific device to return these capability flags. Then, use an if statement or similar check to confirm that the relevant flag is both present and true before attempting to lock or unlock the device. If either of these capability flags is false or not present, you can view the properties of the device, errors or warnings for the device, and events related to the device to learn more about the cause of these issues. For example, you could examine device.properties.online. In addition, you could look for a device.disconnected event. Request:
Response:

​
Locking a Door

You can lock a door using the lock_door endpoint. To confirm the success of the action, see Verifying the success of a lock or unlock action. Request:
Response:

​
Unlocking a Door

You can unlock a door using the unlock_door endpoint. To confirm the success of the action, see Verifying the success of a lock or unlock action. Request:
Response:

​
Verifying the Success of a Lock or Unlock Action

​
1. Execute a Lock request (or other action)

When initiating a lock or unlock action, the Seam API returns an action attempt, which monitors the success or failure of the action. Request:
Response:

​
2. Poll the Action Attempt to Verify the Success of the Action

Use the action_attempt_id from the prior response to make a Get Action Attempt request. When the action attempt’s status changes to success, it indicates the action has been successful.
Some providers and device models do not confirm whether a lock or unlock completed on the physical device. In those cases, the action attempt can still succeed while action_attempt.result.was_confirmed_by_device is false. Use this property to set the right expectation in your UI, especially for unlock flows.
Request:
Response:

​
Checking the Locked Status of a Lock

To retrieve the locked status of a specific door lock, use the Get Device endpoint by providing the device_id of the desired lock. This operation returns detailed information, including the current locked status. Note that if the lock is offline, Seam does not return the device.locked property. Request:
Response:

​
Lock and Unlock Events

Whenever a lock is locked or unlocked, Seam emits a lock.locked or lock.unlocked event. You can retrieve these events by making a List Events request or receive them in real time by setting up a webhook. For more information on how to set up webhooks, see the Webhooks guide. For the complete list of properties on each event, see the Lock Events reference. A lock.unlocked event looks like the following:

​
Determining How a Lock Was Operated

Use the method property to determine how the lock was locked or unlocked. Both lock.locked and lock.unlocked events include this property. For remote events, the following properties tell you which remote channel was used:
  • action_attempt_id: Present only when the action was initiated through Seam, using a LOCK_DOOR or UNLOCK_DOOR action attempt. Use it to tie the event back to the specific API call your application made. When this property is absent, the remote action originated outside of Seam—for example, from the provider’s own mobile app.
  • is_via_bluetooth: true when the action was performed over Bluetooth by a remote client, such as the provider’s mobile app, rather than through Seam or a physical interaction.
  • is_via_nfc: true when the action was performed by tapping an NFC credential, such as an Apple Home Key or an NFC key fob, at the lock.

​
Identifying the Access Code Used

When method is keycode, the event identifies the access code that was used:
  • access_code_id: ID of the access code that was entered.
  • access_code_is_managed: true if the code is managed by Seam—that is, one that you created through the Seam API—or false if it is an unmanaged code that was programmed directly on the device. This property is present only when access_code_id is set.

​
Common Scenarios

The following examples show the properties that distinguish common ways a lock is operated. Each event also includes the standard event_id, device_id, occurred_at, and other envelope properties, omitted here for brevity.