Skip to main content
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.