Understanding Lock and Unlock Events

When a lock is locked or unlocked, Seam emits a lock.locked or lock.unlocked event. Each event has a method field that tells you how the lock was operated, plus other fields that tell you who or what triggered it. This article explains what those fields mean and why you might see an unexpected value.

Method values

method	What it means
keycode	Someone entered a code on the lock's keypad. See access_code_id for which code.
manual	The lock was operated physically, for example with a key, thumb turn, or button.
automatic	The lock operated on its own, for example with an auto-lock timer.
remote	The lock was operated remotely: from the manufacturer's app, over Bluetooth, from a smart home platform, or through the Seam API.
card	A physical credential, such as an RFID card or an NFC wallet pass, was presented at the reader.
mobile_key	A phone-based mobile credential in the manufacturer's app was presented at the lock.
unknown	Seam couldn't determine how the lock was operated.

Not every lock reports every method. Which values you see depends on what the manufacturer sends to Seam.

Finding out who or what triggered the event

• action_attempt_id: present when the lock was locked or unlocked through the Seam API. A remote event without action_attempt_id was most likely triggered from the manufacturer's app or another integration.

• access_code_id: on keycode events, the access code that was used, when Seam can match it. access_code_is_managed is true for a code created through Seam and false for an unmanaged code that Seam found on the lock.

• code: the PIN that was used, if known.

• is_via_bluetooth and is_via_nfc: whether the action was performed over Bluetooth by an app, or by an NFC tap such as a phone wallet key or key fob.

To see all lock and unlock activity for one code, call List Events with the access_code_id filter.

Why an event shows an unexpected method

1. unknown instead of a specific method: the manufacturer reported the lock change without saying how it happened, and the change didn't match an action you started through the Seam API. This depends on the lock model and firmware.

2. keycode without access_code_id: the lock didn't report which code was used, or Seam has no access code on that device that matches it.

3. remote when you didn't use the Seam API: someone operated the lock from the manufacturer's app or another integration. Check for action_attempt_id to tell the two apart.

SmartThings locks

SmartThings reports its own method values, which Seam maps as follows:

SmartThings reports	Seam method
keypad	keycode
manual	manual
auto	automatic
command	remote (from the SmartThings app, a SmartThings routine, or the Seam API)
No method, or any other value	remote if it matches an action you started through the Seam API, otherwise unknown

SmartThings reports each lock activity separately, so you may see repeated lock.locked or lock.unlocked events even when the lock was already in that state.

Related resources

• List Events API reference

• SmartThings integration guide