Implementing your Device Model & Discovery

A clean, predictable device model helps Seam present accurate information to end users and orchestrate smart-lock behavior across hospitality, multifamily, STR, and coworking environments. The fields listed below form the baseline for a Seam-compatible integration.

Device Object Schema

Your API should expose a device resource with a stable, predictable structure. This lets Seam identify devices, correlate events, and display meaningful details to the user. A typical device object includes:

device_id: unique, stable identifier
device_type: smart_lock, hub, or bridge
device_model: hardware model identifier
online: whether your cloud can reach the device
battery_level: percentage 0–100
signal_quality: optional, recommended
location: latitude/longitude if available
timezone: IANA timezone string
bridge_id: parent hub/bridge if applicable
lock_state: locked, unlocked, or unknown
door_state: open, closed, or ajar (if supported)

Device example

{
  "device_id": "lock_491829",
  "device_type": "smart_lock",
  "device_model": "LockPro X200",
  "online": true,
  "battery_level": 72,
  "signal_quality": -68,
  "location": { "latitude": 37.7859, "longitude": -122.4011 },
  "timezone": "America/Los_Angeles",
  "bridge_id": "bridge_99211",
  "lock_state": "locked",
  "door_state": "closed",
  "device_time": "2025-05-22T10:35:12Z",
  "updated_at": "2025-05-22T10:35:12Z"
}

Listing door locks

After a lock owner logs in through OAuth, Seam lists all locks associated with their account so the user can select which devices to connect. Your API should return a JSON list of all accessible locks.

List All Locks Example

GET https://devicecloud.example.com/locks

{
  "locks": [
    {
      "lock_id": "3043fde0-3c6d-4913-981f-2607f05fe74e",
      "name": "Office Front Door",
      "model": "example_model",
      "address": "123 Amy Lane, CA, 94110, United States"
    },
    {
      "lock_id": "1c33d4cf-e178-4c06-8a9a-aadd6dc5a804",
      "name": "Back Door",
      "model": "example_model",
      "address": "999 Louis Lane, CA, 94110, United States"
    }
  ]
}

Getting a single lock

Seam may request information about a specific lock to display full details or perform deeper synchronization.

Get a Lock Example

GET https://devicecloud.example.com/locks/<LOCK_ID>

{
  "lock_id": "3043fde0-3c6d-4913-981f-2607f05fe74e",
  "name": "Office Front Door",
  "model": "example_model",
  "address": "123 Amy Lane, CA, 94110, United States"
}

Connectivity reporting

To keep device state fresh, your platform should send webhook events whenever connectivity changes.

Send an event when the device goes offline
Send another when it comes back online
Report hub or bridge status separately

Online event example

{
  "event_type": "device.online",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:48:18Z"
}

Offline event example

{
  "event_type": "device.offline",
  "device_id": "lock_491829",
  "timestamp": "2025-05-22T10:45:01Z"
}

Power & battery reporting

Your API should report battery percentage and emit events when power levels change.

Battery level example

{
  "battery_level": 72
}

Low-battery event

{
  "event_type": "battery.low",
  "device_id": "lock_491829",
  "battery_level": 15,
  "timestamp": "2025-05-22T11:02:44Z"
}

Battery replaced / charged

{
  "event_type": "battery.replaced",
  "device_id": "lock_491829",
  "battery_level": 100,
  "timestamp": "2025-05-22T12:10:15Z"
}

Time & timezone reporting

Accurate time lets Seam validate access-code schedules and align audit logs. Accurate timezone data is especially important during daylight-savings transitions.

Required fields

device_time: the current time reported by the device
timezone: an IANA timezone string

Device-time example

{
  "created_at": "2025-05-22T10:30:12Z",
  "device_time": "2025-05-22T10:31:47Z",
  "timezone": "America/Los_Angeles",
  "device_model": "LockPro X200"
}

Seam compares device_time with server time to detect clock drift and identify devices that may evaluate schedules incorrectly.

Guidance for manufacturers

If scheduling is evaluated on-device, the reported device time and timezone must be kept accurate and updated reliably.

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Implementing your Device Model & Discovery

Device Object Schema

Device example

Listing door locks

List All Locks Example

Getting a single lock

Get a Lock Example

Connectivity reporting

Online event example

Offline event example

Power & battery reporting

Battery level example

Low-battery event

Battery replaced / charged

Time & timezone reporting

Required fields

Device-time example

Guidance for manufacturers

​Device Object Schema

​Device example

​Listing door locks

​List All Locks Example

​Getting a single lock

​Get a Lock Example

​Connectivity reporting

​Online event example

​Offline event example

​Power & battery reporting

​Battery level example

​Low-battery event

​Battery replaced / charged

​Time & timezone reporting

​Required fields

​Device-time example

​Guidance for manufacturers

Device Object Schema

Device example

Listing door locks

List All Locks Example

Getting a single lock

Get a Lock Example

Connectivity reporting

Online event example

Offline event example

Power & battery reporting

Battery level example

Low-battery event

Battery replaced / charged

Time & timezone reporting

Required fields

Device-time example

Guidance for manufacturers