Lock Events

`lock.locked`

A lock was locked.

{
  "access_code_id": "00000000-0000-0000-0000-000000000000",
  "access_code_is_managed": true,
  "action_attempt_id": "00000000-0000-0000-0000-000000000000",
  "code": "1234",
  "connected_account_custom_metadata": {},
  "connected_account_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2025-01-01T00:00:00.000Z",
  "customer_key": "",
  "device_custom_metadata": {},
  "device_id": "00000000-0000-0000-0000-000000000000",
  "event_description": "A [lock](/low-level-apis/smart-locks) was locked.",
  "event_id": "00000000-0000-0000-0000-000000000000",
  "event_type": "lock.locked",
  "is_via_bluetooth": true,
  "is_via_nfc": true,
  "method": "keycode",
  "occurred_at": "2025-01-01T00:00:00.000Z",
  "workspace_id": "00000000-0000-0000-0000-000000000000"
}

Properties

access_code_id

String (UUID)

ID of the access code that was used to lock the device.

access_code_is_managed

Boolean

Whether the access code is managed by Seam (true) or unmanaged (false). Only present when access_code_id is set.

action_attempt_id

String (UUID)

ID of the Seam action attempt that triggered this lock. Present only when the lock was initiated through Seam (via a LOCK_DOOR action attempt).

code

String

Code (PIN) that was used to lock the device, if known. Taken from the matched managed or unmanaged access code, or from the code reported by the provider when no access code matched.

connected_account_custom_metadata

Object

Custom metadata of the connected account, present when connected_account_id is provided.

connected_account_id

String (UUID)

ID of the connected account associated with the event.

created_at

String (ISO 8601)

Date and time at which the event was created.

customer_key

String

The customer key associated with the device, if any.

device_custom_metadata

Object

Custom metadata of the device, present when device_id is provided.

device_id

String (UUID)

ID of the affected device.

event_description

String

Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.

event_id

String (UUID)

ID of the event.

event_type

Enum (String)

Value: lock.locked

is_via_bluetooth

Boolean

Whether the lock action was performed over Bluetooth by a remote client (such as the provider’s mobile app), rather than a direct physical interaction or a Seam-initiated remote action.

is_via_nfc

Boolean

Whether the lock action was performed by an NFC credential tap (such as an Apple Home Key or an NFC key fob) presented to the lock, rather than a direct physical interaction or a Seam-initiated remote action.

method

Enum (String)

Method by which the lock was locked. keycode: an access code was used (see access_code_id). manual: a physical action such as a thumbturn or button press. remote: a remote action via an app, Bluetooth, or the Seam API (see action_attempt_id if Seam-initiated; see is_via_bluetooth or is_via_nfc for the transport). automatic: triggered automatically, for example by an auto-relock timer. unknown: could not be determined.Possible values: keycode, manual, automatic, unknown, remote

occurred_at

String (ISO 8601)

Date and time at which the event occurred.

workspace_id

String (UUID)

ID of the workspace associated with the event.

`lock.unlocked`

A lock was unlocked.

{
  "access_code_id": "00000000-0000-0000-0000-000000000000",
  "access_code_is_managed": true,
  "acs_entrance_id": "00000000-0000-0000-0000-000000000000",
  "acs_system_id": "00000000-0000-0000-0000-000000000000",
  "acs_user_id": "00000000-0000-0000-0000-000000000000",
  "action_attempt_id": "00000000-0000-0000-0000-000000000000",
  "code": "1234",
  "connected_account_custom_metadata": {},
  "connected_account_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2025-01-01T00:00:00.000Z",
  "customer_key": "",
  "device_custom_metadata": {},
  "device_id": "00000000-0000-0000-0000-000000000000",
  "event_description": "A [lock](/low-level-apis/smart-locks) was unlocked.",
  "event_id": "00000000-0000-0000-0000-000000000000",
  "event_type": "lock.unlocked",
  "is_via_bluetooth": true,
  "is_via_nfc": true,
  "method": "keycode",
  "occurred_at": "2025-01-01T00:00:00.000Z",
  "user_identity_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "00000000-0000-0000-0000-000000000000"
}

Properties

access_code_id

String (UUID)

ID of the access code that was used to unlock the affected device.

access_code_is_managed

Boolean

Whether the access code is managed by Seam (true) or unmanaged (false). Only present when access_code_id is set.

acs_entrance_id

String (UUID)

undocumented: Unreleased.

ID of the ACS entrance associated with the unlock event.

acs_system_id

String (UUID)

undocumented: Unreleased.

ID of the ACS system associated with the unlock event.

acs_user_id

String (UUID)

undocumented: Unreleased.

ID of the ACS user associated with the unlock event.

action_attempt_id

String (UUID)

ID of the Seam action attempt that triggered this unlock. Present only when the unlock was initiated through Seam (via an UNLOCK_DOOR action attempt).

code

String

Code (PIN) that was used to unlock the affected device, if known. Taken from the matched managed or unmanaged access code, or from the code reported by the provider when no access code matched.

connected_account_custom_metadata

Object

Custom metadata of the connected account, present when connected_account_id is provided.

connected_account_id

String (UUID)

ID of the connected account associated with the event.

created_at

String (ISO 8601)

Date and time at which the event was created.

customer_key

String

The customer key associated with the device, if any.

device_custom_metadata

Object

Custom metadata of the device, present when device_id is provided.

device_id

String (UUID)

ID of the affected device.

event_description

String

Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.

event_id

String (UUID)

ID of the event.

event_type

Enum (String)

Value: lock.unlocked

is_via_bluetooth

Boolean

Whether the unlock action was performed over Bluetooth by a remote client (such as the provider’s mobile app), rather than a direct physical interaction or a Seam-initiated remote action.

is_via_nfc

Boolean

Whether the unlock action was performed by an NFC credential tap (such as an Apple Home Key or an NFC key fob) presented to the lock, rather than a direct physical interaction or a Seam-initiated remote action.

method

Enum (String)

Method by which the lock was unlocked. keycode: an access code was used (see access_code_id). manual: a physical action such as a thumbturn or handle press. remote: a remote action via an app, Bluetooth, or the Seam API (see action_attempt_id if Seam-initiated; see is_via_bluetooth or is_via_nfc for the transport). automatic: triggered automatically, for example by a time-based schedule. unknown: could not be determined.Possible values: keycode, manual, automatic, unknown, remote

occurred_at

String (ISO 8601)

Date and time at which the event occurred.

user_identity_id

String (UUID)

undocumented: Unreleased.

ID of the user identity associated with the unlock event.

workspace_id

String (UUID)

ID of the workspace associated with the event.

`lock.access_denied`

The lock denied access to a user after one or more consecutive invalid attempts to unlock the device.

{
  "access_code_id": "00000000-0000-0000-0000-000000000000",
  "acs_entrance_id": "00000000-0000-0000-0000-000000000000",
  "acs_system_id": "00000000-0000-0000-0000-000000000000",
  "acs_user_id": "00000000-0000-0000-0000-000000000000",
  "connected_account_custom_metadata": {},
  "connected_account_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2025-01-01T00:00:00.000Z",
  "customer_key": "",
  "device_custom_metadata": {},
  "device_id": "00000000-0000-0000-0000-000000000000",
  "event_description": "The [lock](/low-level-apis/smart-locks) denied access to a user after one or more consecutive invalid attempts to unlock the device.",
  "event_id": "00000000-0000-0000-0000-000000000000",
  "event_type": "lock.access_denied",
  "occurred_at": "2025-01-01T00:00:00.000Z",
  "reason": {
    "message": "",
    "reason_code": "unknown_code"
  },
  "user_identity_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "00000000-0000-0000-0000-000000000000"
}

Properties

access_code_id

String (UUID)

ID of the access code that was used in the unlock attempts.

acs_entrance_id

String (UUID)

undocumented: Unreleased.

ID of the ACS entrance associated with the access-denied event.

acs_system_id

String (UUID)

undocumented: Unreleased.

ID of the ACS system associated with the access-denied event.

acs_user_id

String (UUID)

undocumented: Unreleased.

ID of the ACS user associated with the access-denied event.

connected_account_custom_metadata

Object

Custom metadata of the connected account, present when connected_account_id is provided.

connected_account_id

String (UUID)

ID of the connected account associated with the event.

created_at

String (ISO 8601)

Date and time at which the event was created.

customer_key

String

The customer key associated with the device, if any.

device_custom_metadata

Object

Custom metadata of the device, present when device_id is provided.

device_id

String (UUID)

ID of the affected device.

event_description

String

Human-readable description of the event. Persisted when the event is created (so the creating code, including a provider, can supply a tailored description) and otherwise derived from the event.

event_id

String (UUID)

ID of the event.

event_type

Enum (String)

Value: lock.access_denied

occurred_at

String (ISO 8601)

Date and time at which the event occurred.

reason

Object

Why access was denied, when the provider reports a determinable cause. Omitted when unknown.

Show properties

message

String

Human-readable explanation of why access was denied.

reason_code

Enum (String)

Normalized reason a lock denied access. Provider-agnostic; not all providers report every value.Possible values: unknown_code, expired_code, blocklisted_code, too_many_attempts, blocked_by_privacy_mode, credential_error

user_identity_id

String (UUID)

undocumented: Unreleased.

ID of the user identity associated with the access-denied event.

workspace_id

String (UUID)

ID of the workspace associated with the event.

Getting Started

Granting Access

Devices and Systems

Setup

Monitoring

Low-Level APIs

Lock Events

`lock.locked`

`lock.unlocked`

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.

`lock.access_denied`

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.

​lock.locked

​lock.unlocked

​undocumented: Unreleased.

​undocumented: Unreleased.

​undocumented: Unreleased.

​undocumented: Unreleased.

​lock.access_denied

​undocumented: Unreleased.

​undocumented: Unreleased.

​undocumented: Unreleased.

​undocumented: Unreleased.

`lock.locked`

`lock.unlocked`

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.

`lock.access_denied`

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.

undocumented: Unreleased.