Devices

Devices are objects like locks, thermostats, sensors, or cameras. In the Seam API, Devices have capabilities that describe the functions they can perform, as well as online and managed status.
Supported Capabilities
Seam decomposes the ensemble of features offered by a device into one or more capabilities such as access_codes or thermostat. Seam exposes each capability as a set of APIs that are standardized across brands for ease of integration. For example, an unlock action on a door lock always requires the same API call irrespective of the device brand.
Furthermore, a single device capability can further be decomposed into 3 sets of affordances:
Actions — commands you can issue the device, such as unlocking
Properties — the current state of the device, such as its locked status
Events — notifications related to changes in the state of the device, such as an unlocking operation performed with an access code.
To retrieve the list of supported capabilities for a given device, use the capability_supported attribute on the Device object:
Javascript
Python
Ruby
PHP
const device = await seam.devices.get({
  device_id: "77208078-6dd7-44e5-a3e4-a2ed3a34efc9"
})
console.log(device.capabilities_supported)
// ['access_code', 'lock']
device = seam.devices.get("0e2e6262-7f91-4970-a58d-47ef30b41e2e")
print(device.capabilities_supported)
# ['access_code', 'lock']
seam = Seam::Client.new()
device_id = "aa3958c3-4236-4f71-bd77-3b60f85b3456"
some_lock = seam.locks.get(device_id)
puts some_lock.capabilities_supported
# [access_code, lock]
use Seam\SeamClient;
​
$seam = new SeamClient("YOUR_API_KEY");
​
$device = $seam->devices->get("0e2e6262-7f91-4970-a58d-47ef30b41e2e");
​
# Inspect this device to see which capabilities it supports
echo json_encode($device->capabilities_supported, JSON_PRETTY_PRINT);
​
# [
#     "access_code",
#     "lock"
# ]
​
Managed Devices vs Unmanaged Devices
To increase billing flexibility, Seam provides the ability to mark devices as managed or unmanaged:
Managed devices: these devices can be fully controlled through the Seam API and are billed to your Seam account as a regular device.
Unmanaged device these devices are not billed and consequently cannot be controlled through the Seam API.
Seam makes it possible to toggle a device back and forth between managed and unmanaged states.
Convert Managed Device to Unmanaged
Converting a device to an unmanaged state pauses billing for the device and converts all the managed device resources (e.g. Access Codes) to unmanaged resources. As a result, Seam will no longer monitor the lifecycle of these resources.
Javascript
Python
Ruby
PHP
​
const deviceId = "77208078-6dd7-44e5-a3e4-a2ed3a34efc9"
​
// take a managed device
const device = await seam.devices.get({
  device_id: deviceId
})
​
// set its managed status to false
const updatedDevice = await seam.devices.update({
  device_id: deviceId,
  is_managed: false
})
​
// retrieve the unmanaged device
const unmanagedDevice = await seam.devices.unmanaged.get({
  device_id: deviceId
})
​
​
​
console.log(unmanagedDevice)
​
/*
{
  is_managed: false,
  device_id: '77208078-6dd7-44e5-a3e4-a2ed3a34efc9',
  device_type: 'yale_lock',
  connected_account_id: '4e5acceb-2bda-4dc1-814e-39c998431683',
  capabilities_supported: [ 'access_code', 'lock' ],
  workspace_id: '1d2826eb-4a26-4f46-bddb-ef5898baa859',
  created_at: '2023-08-29T04:30:14.914Z',
  errors: [],
  warnings: [],
  properties: {
    name: 'FRONT DOOR',
    online: true,
    manufacturer: 'august',
    image_url: 'https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png',
    image_alt_text: 'Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front',
    model: { display_name: 'Lock', manufacturer_display_name: 'August' }
  }
}
​
*/
from seamapi import Seam
seam = Seam()
​
device_id = "aaa5664a-a959-499d-82a7-c25516565788"
​
seam.devices.update(
  device=device_id, 
  is_managed=False
)
​
unmanaged_device = seam.devices.unmanaged.get(device=device_id)
print(unmanaged_device)
​
# UnmanagedDevice(device_id='aaa5664a-a959-499d-82a7-c25516565788',
#                 device_type='august_lock',
#                 properties={'image_alt_text': 'August Wifi Smart Lock 3rd Gen, '
#                                               'Silver, Front',
#                             'image_url': 'https://connect.getseam.com/assets/images/devices/august_wifi-smart-lock-3rd-gen_silver_front.png',
#                             'manufacturer': 'august',
#                             'model': {'display_name': 'Lock',
#                                       'manufacturer_display_name': 'August'},
#                             'name': 'GARAGE',
#                             'online': True},
#                 connected_account_id='4fd987a7-21e1-4b01-aa6a-eedfe35c05e3',
#                 workspace_id='1d2826eb-4a26-4f46-bddb-ef5898baa859',
#                 created_at='2023-09-16T20:01:58.984Z',
#                 errors=[],
#                 warnings=[],
#                 capabilities_supported=['access_code', 'lock'],
#                 is_managed=False)
require "seamapi"
​
seam = Seam::Client.new()
device_id = "aa3958c3-4236-4f71-bd77-3b60f85b3456"
​
seam.devices.update(device_id: device_id, is_managed: false)
unmanaged_device = seam.unmanaged_devices.get(device_id)
puts unmanaged_device.inspect
​
# <Seam::UnmanagedDevice:0x00438
#   is_managed=false
#   device_id="aa3958c3-4236-4f71-bd77-3b60f85b3456"
#   device_type="yale_lock"
#   connected_account_id="d2ab9339-d0ad-4594-b9a2-6ce71e4d4521"
#   capabilities_supported=["access_code", "lock"]
#   workspace_id="1d2826eb-4a26-4f46-bddb-ef5898baa859"
#   created_at=2023-08-30 05:33:58.45 UTC
#   errors=[]
#   warnings=[]
#   properties={"name"=>"FRONT DOOR", "online"=>true, "manufacturer"=>"august", "image_url"=>"https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png", "image_alt_text"=>"Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front", "model"=>{"display_name"=>"Lock", "manufacturer_display_name"=>"August"}}>
use Seam\SeamClient;
​
$seam = new SeamClient("YOUR_API_KEY");
​
$device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e";
$device = $seam->devices->get($device_id);
​
$seam->devices->update(
    device_id: $device_id,
    is_managed: false);
​
$unmanaged_device = $seam->devices->unmanaged->get(
    device_id: $device_id
);
​
# Inspect this device to confirm it's unmanaged
echo json_encode($unmanaged_device, JSON_PRETTY_PRINT);
​
// {
//     "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
//     "device_type": "nuki_lock",
//     "connected_account_id": "5fe50f46-274f-4a03-ba95-3a517464fdc7",
//     "workspace_id": "1d2826eb-4a26-4f46-bddb-ef5898baa859",
//     "created_at": "2023-08-30T06:45:59.213Z",
//     "properties": {
//         "name": "Office Lock",
//         "manufacturer": "nuki",
//         "image_url": "https:\/\/connect.getseam.com\/assets\/images\/devices\/nuki_smart_lock_3_pro_black.png",
//         "image_alt_text": "Nuki Smart Lock 3.0 Pro Black, Front",
//         "model": {
//             "display_name": "Lock",
//             "manufacturer_display_name": "Nuki"
//         }
//     },
//     "errors": [],
//     "warnings": []
// }
Convert Unmanaged Device to Managed
To convert an unmanaged device back to managed, retrieve it using the unmanaged device API and use the update function to change its managed state back to true. Note that unmanaged device resources (e.g. Access Codes) will need to be converted back to managed as well.
Javascript
Python
Ruby
PHP
const deviceId = "77208078-6dd7-44e5-a3e4-a2ed3a34efc9"
​
// retrieve the unmanaged device if needed
const unmanagedDevice = await seam.devices.unmanaged.get({
  device_id: deviceId
})
​
// update it
await seam.devices.unmanaged.update({
  device_id: deviceId, 
  is_managed: true
})
​
// retrieve it
const device = await seam.devices.get({
    device_id: deviceId
})
​
console.log(device)
/*
{
  device_id: '77208078-6dd7-44e5-a3e4-a2ed3a34efc9',
  device_type: 'yale_lock',
  capabilities_supported: [ 'access_code', 'lock' ],
  properties: {
    locked: true,
    online: true,
    door_open: false,
    manufacturer: 'august',
    battery_level: 0.9999532347993827,
    serial_number: '00000004-992d-45a0-bea1-9128fdcd8d12',
    august_metadata: {
      lock_id: 'lock-1',
      house_id: 'house-1',
      lock_name: 'FRONT DOOR',
      has_keypad: true,
      house_name: 'My House',
      keypad_battery_level: 'Not Available'
    },
    supported_code_lengths: [ 4, 5, 6, 7, 8 ],
    has_native_entry_events: true,
    name: 'FRONT DOOR',
    model: { display_name: 'Lock', manufacturer_display_name: 'August' },
    battery: { level: 0.9999532347993827, status: 'full' },
    image_url: 'https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png',
    image_alt_text: 'Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front',
    code_constraints: [],
    supports_backup_access_code_pool: true
  },
  location: { timezone: 'America/Los_Angeles', location_name: 'My House' },
  connected_account_id: '4e5acceb-2bda-4dc1-814e-39c998431683',
  workspace_id: '1d2826eb-4a26-4f46-bddb-ef5898baa859',
  created_at: '2023-08-29T04:30:14.914Z',
  errors: [],
  warnings: [],
  is_managed: true
}
*/
​
from seamapi import Seam
seam = Seam()
​
device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e"
​
# Use the unmanaged update call to update the status
seam.devices.unmanaged.update(
  device=device_id, 
  is_managed=True
)
​
# Confirm that the device is now managed by retrieving it
device = seam.devices.get(device=device_id)
print(device)
​
# Device(device_id='0e2e6262-7f91-4970-a58d-47ef30b41e2e',
#        device_type='nuki_lock',
#        location=None,
#        properties={'battery': {'level': 0.86, 'status': 'full'},
#                    'battery_level': 0.86,
#                    'code_constraints': [{'constraint_type': 'cannot_start_with_12'},
#                                         {'constraint_type': 'no_zeros'},
#                                         {'constraint_type': 'name_length',
#                                          'max_length': 20}],
#                    'has_native_entry_events': True,
#                    'image_alt_text': 'Nuki Smart Lock 3.0 Pro Black, Front',
#                    'image_url': 'https://connect.getseam.com/assets/images/devices/nuki_smart_lock_3_pro_black.png',
#                    'keypad_battery': {'level': 1},
#                    'locked': False,
#                    'manufacturer': 'nuki',
#                    'model': {'display_name': 'Lock',
#                              'manufacturer_display_name': 'Nuki'},
#                    'name': 'Office Lock',
#                    'nuki_metadata': {'device_id': '545636389',
#                                      'device_name': 'Office Lock',
#                                      'keypad_battery_critical': False},
#                    'online': True,
#                    'supported_code_lengths': [6],
#                    'supports_backup_access_code_pool': True},
#        capabilities_supported=['access_code', 'lock'],
#        errors=[],
#        warnings=[],
#        connected_account_id='5fe50f46-274f-4a03-ba95-3a517464fdc7',
#        workspace_id='1d2826eb-4a26-4f46-bddb-ef5898baa859',
#        created_at='2023-08-30T06:45:59.213Z')
require "seamapi"
​
seam = Seam::Client.new()
device_id = "aa3958c3-4236-4f71-bd77-3b60f85b3456"
seam.unmanaged_devices.update(device_id: device_id, is_managed: true)
​
device = seam.devices.get(device_id)
​
puts device.inspect
# <Seam::Device:0x00438
#   device_id="aa3958c3-4236-4f71-bd77-3b60f85b3456"
#   device_type="yale_lock"
#   capabilities_supported=["access_code", "lock"]
#   properties={"locked"=>true, "online"=>true, "door_open"=>false, "manufacturer"=>"august", "battery_level"=>0.9999532347993827, "serial_number"=>"00000004-992d-45a0-bea1-9128fdcd8d12", "august_metadata"=>{"lock_id"=>"lock-1", "house_id"=>"house-1", "lock_name"=>"FRONT DOOR", "has_keypad"=>true, "house_name"=>"My House", "keypad_battery_level"=>"Not Available"}, "supported_code_lengths"=>[4, 5, 6, 7, 8], "has_native_entry_events"=>true, "name"=>"FRONT DOOR", "model"=>{"display_name"=>"Lock", "manufacturer_display_name"=>"August"}, "battery"=>{"level"=>0.9999532347993827, "status"=>"full"}, "image_url"=>"https://connect.getseam.com/assets/images/devices/yale_assure-lock-touchscreen-wifi-smart-lock_satin-nickel_front.png", "image_alt_text"=>"Yale Assure Touchscreen Wifi Smart Lock, Satin Nickel, Front", "code_constraints"=>[], "supports_backup_access_code_pool"=>true}
#   connected_account_id="d2ab9339-d0ad-4594-b9a2-6ce71e4d4521"
#   workspace_id="1d2826eb-4a26-4f46-bddb-ef5898baa859"
#   created_at=2023-08-30 05:33:58.45 UTC
#   errors=[]
#   warnings=[]
#   is_managed=true>
use Seam\SeamClient;
​
$seam = new SeamClient("YOUR_API_KEY");
​
$device_id = "0e2e6262-7f91-4970-a58d-47ef30b41e2e";
​
$seam->devices->unmanaged->update(
  device_id: $device_id,
  is_managed: true
);
​
$device = $seam->devices->get($device_id);
​
# Inspect this device to make sure it was correct converted
echo json_encode($device, JSON_PRETTY_PRINT);
​
// {
//     "device_id": "0e2e6262-7f91-4970-a58d-47ef30b41e2e",
//     "workspace_id": "1d2826eb-4a26-4f46-bddb-ef5898baa859",
//     "connected_account_id": "5fe50f46-274f-4a03-ba95-3a517464fdc7",
//     "device_type": "nuki_lock",
//     "properties": {
//         "online": true,
//         "locked": false,
//         "name": "Office Lock",
//         "battery_level": 0.86,
//         "battery": {
//             "level": 0.86,
//             "status": "full"
//         },
//         "manufacturer": "nuki",
//         "supported_code_lengths": [
//             6
//         ],
//         "code_constraints": [
//             {
//                 "constraint_type": "cannot_start_with_12"
//             },
//             {
//                 "constraint_type": "no_zeros"
//             },
//             {
//                 "constraint_type": "name_length",
//                 "max_length": 20
//             }
//         ],
//         "model": {
//             "display_name": "Lock",
//             "manufacturer_display_name": "Nuki"
//         },
//         "image_url": "https:\/\/connect.getseam.com\/assets\/images\/devices\/nuki_smart_lock_3_pro_black.png",
//         "image_alt_text": "Nuki Smart Lock 3.0 Pro Black, Front",
//         "nuki_metadata": {
//             "device_id": "545636389",
//             "device_name": "Office Lock",
//             "keypad_battery_critical": false
//         }
//     },
//     "location": null,
//     "created_at": "2023-08-30T06:45:59.213Z",
//     "capabilities_supported": [
//         "access_code",
//         "lock"
//     ],
//     "errors": [],
//     "warnings": []
// }
Automatically Set New Devices to Unmanaged
New devices added to a workspace via a Connect Webview can automatically be set to unmanaged by default. To do so, set the automatically_manage_new_devices to false when creating a Connect Webview. Any device added once the Connect Webview is authorized will be set to unmanaged.
Javascript
Python
Ruby
PHP
const connectWebview = await seam.connectWebviews.create({
    // accepted_providers: ["schlage", "august"...etc], <== use these for precise control of accepted providers
    provider_category: "stable",
    automatically_manage_new_devices: false
})
​
console.log(connectWebview)
​
/*
{
  url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=323b4ffa-ce24-4cff-a965-ff532563ec7a&auth_token=JrunXm29x7GCWFrVJsZHLFsD5YAioyaAu',
  status: 'pending',
  workspace_id: '1d2826eb-4a26-4f46-bddb-ef5898baa859',
  custom_metadata: {},
  accepted_devices: [],
  login_successful: false,
  accepted_providers: [
    'august',      'avigilon_alta',
    'schlage',     'smartthings',
    'yale',        'nuki',
    'salto',       'controlbyweb',
    'minut',       'my_2n',
    'kwikset',     'ttlock',
    'noiseaware',  'igloohome',
    'ecobee',      'hubitat',
    'four_suites'
  ],
  any_device_allowed: false,
  connect_webview_id: '323b4ffa-ce24-4cff-a965-ff532563ec7a',
  custom_redirect_url: null,
  any_provider_allowed: false,
  device_selection_mode: 'none',
  wait_for_device_creation: false,
  custom_redirect_failure_url: null,
  automatically_manage_new_devices: false,
  created_at: '2023-08-29T04:59:13.890Z'
}
*/
from seamapi import Seam
​
seam = Seam()
​
connect_webview = seam.connect_webviews.create(
    provider_category="stable",
    automatically_manage_new_devices=False
)
​
print(connect_webview)
​
# ConnectWebview(workspace_id='1d2826eb-4a26-4f46-bddb-ef5898baa859',
#                connect_webview_id='fc251dba-f7e6-4789-b638-e4135ba069d5',
#                status='pending',
#                url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=fc251dba-f7e6-4789-b638-e4135ba069d5&auth_token=FLGyaQMhhDRtcT4XjFvDnjj3ydreMY2KP',
#                login_successful=False,
#                device_selection_mode='none',
#                any_provider_allowed=False,
#                any_device_allowed=False,
#                created_at='2023-09-16T20:14:13.417Z',
#                custom_metadata={},
#                connected_account_id=None,
#                authorized_at=None,
#                custom_redirect_url=None,
#                custom_redirect_failure_url=None,
#                accepted_providers=['august',
#                                    'avigilon_alta',
#                                    'brivo',
#                                    'schlage',
#                                    'smartthings',
#                                    'yale',
#                                    'nuki',
#                                    'salto',
#                                    'controlbyweb',
#                                    'minut',
#                                    'my_2n',
#                                    'kwikset',
#                                    'ttlock',
#                                    'noiseaware',
#                                    'igloohome',
#                                    'ecobee',
#                                    'hubitat',
#                                    'four_suites',
#                                    'dormakaba_oracode'],
#                accepted_devices=[],
#                selected_provider=None,
#                wait_for_device_creation=False,
#                automatically_manage_new_devices=False)
​
require "seamapi"
​
seam = Seam::Client.new()
connect_webview = seam.connect_webviews.create(
    provider_category: "stable",
    automatically_manage_new_devices: false,
)
​
puts connect_webview.inspect
# <Seam::ConnectWebview:0x00438
#   url="https://connect.getseam.com/connect_webviews/view?connect_webview_id=96e673d8-2df2-49b2-b538-6cc88cbaf78e&auth_token=7AHzFs1iJ3EHvAk1AyKwxRaeVUm2qBsG9"
#   status="pending"
#   workspace_id="1d2826eb-4a26-4f46-bddb-ef5898baa859"
#   custom_metadata={}
#   accepted_devices=[]
#   login_successful=false
#   accepted_providers=["august", "avigilon_alta", "brivo", "schlage", "smartthings", "yale", "nuki", "salto", "controlbyweb", "minut", "my_2n", "kwikset", "ttlock", "noiseaware", "igloohome", "ecobee", "hubitat", "four_suites"]
#   any_device_allowed=false
#   connect_webview_id="96e673d8-2df2-49b2-b538-6cc88cbaf78e"
#   custom_redirect_url=nil
#   any_provider_allowed=false
#   device_selection_mode="none"
#   wait_for_device_creation=false
#   custom_redirect_failure_url=nil
#   automatically_manage_new_devices=false <====== see flag
#   created_at=2023-09-07 05:52:41.329 UTC>
​
$connect_webview = $seam->connect_webviews->create(
  provider_category: "stable",
  automatically_manage_new_devices: false
);
Core Concepts - Previous
Workspaces
Next - Core Concepts
Connect Webviews
Last modified 10d ago