Devices
A device that has been connected to Seam
The device
object represents a device that has been connected to Seam.
device
Properties
device
PropertiesThe device
object has the following properties:
device_id
String (UUID) Required
Unique identifier for the device.
device_type
String Required
Type of the device.
display_name
String Required
Display name for the device.
capabilities_supported
Array of strings Required
properties
Object
Required
location
Object Optional
connected_account_id
String (UUID) Required
workspace_id
String (UUID) Required
errors
Array of objects Required
Array of errors associated with the device.
Each error object within the array contains two fields: error_code
and message
.
error_code
is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue.
warnings
Array of objects Required
Array of warnings associated with the device.
Each warning object within the array contains two fields: warning_code
and message
.
warning_code
is a string that uniquely identifies the type of warning, enabling quick recognition and categorization of the issue.
created_at
String (datetime) Required
Date and time at which the device object was created.
is_managed
Boolean Required
Indicates whether Seam manages the device.
custom_metadata
JSON object Optional
Set of custom_metadata
for the device.
Specify up to 50 keys, with key names up to 40 characters long. Accepts string or Boolean values. Strings are limited to 500 characters.
can_remotely_unlock
Boolean Optional
can_remotely_lock
Boolean Optional
can_program_online_access_codes
Boolean Optional
can_program_offline_access_codes
Boolean Optional
can_hvac_heat
Boolean Optional
can_hvac_cool
Boolean Optional
can_hvac_heat_cool
Boolean Optional
can_turn_off_hvac
Boolean Optional
can_simulate_removal
Boolean Optional
can_simulate_connection
Boolean Optional
can_simulate_disconnection
Boolean Optional
capabilities_supported
Values
capabilities_supported
ValuesSuperseded by capability flags.
access_code
If present, the device can manage and utilize digital PIN codes for secure access.
lock
If present, the device controls a door locking mechanism, enabling the remote opening and closing of doors and other entry points.
noise_detection
If present, the device supports monitoring and responding to ambient noise levels.
thermostat
If present, the device can regulate and adjust indoor temperatures.
battery
If present, the device can manage battery life and health.
phone
If present, the device is a mobile phone.
device.properties
Properties
device.properties
Propertiesonline
Boolean Required
Indicates whether the device is online.
accessory_keypad
Object Optional
appearance
Object Required
Appearance-related properties, including the read-only name
of the device, as seen from the provider API and application.
model
Object Required
has_direct_power
Boolean Optional
Indicates whether the device has direct power.
battery_level
Number Required
battery
Object Optional
Device battery properties.
manufacturer
String Optional
image_url
String (URL) Optional
Image URL for the device or placeholder image URL if a device-specific image is unavailable.
image_alt_text
String Optional
Alternative text for the device image.
serial_number
String Optional
Serial number of the device.
online_access_codes_enabled
Boolean Optional
offline_access_codes_enabled
Boolean Optional
noise_level_decibels
Number Optional
Current noise level in decibels, if the device supports noise detection.
currently_triggering_noise_threshold_ids
Array of strings Optional
Array of noise threshold IDs that are currently triggering.
code_constraints
Array of objects Optional
Constraints on access codes that can be set on the device.
supported_code_lengths
Array of numbers Optional
Supported code lengths for the device.
For example, [4,5]
means that 1234
and 12345
are valid codes, but 123
and 123456
are invalid codes.
Applicable to devices that support access codes.
max_active_codes_supported
Number Optional
Maximum number of codes that can exist on the device at one time. Applicable to devices that support access codes.
supports_backup_access_code_pool
Boolean Optional
has_native_entry_events
Boolean Optional
Indicates whether Seam receives lock and unlock events from the device provider.
locked
Boolean Optional
Indicates whether the device is locked.
Applicable to locks. If the device is offline, Seam does not return this property.
keypad_battery
Object Optional
Keypad battery properties.
Applicable to locks.
door_open
Boolean Optional
Indicates whether the door is open.
Applicable to locks. If the device is offline, Seam does not return this property.
temperature_fahrenheit
Number Required
Temperature, measured in Fahrenheit. Applicable to thermostats.
temperature_celsius
Number Required
Temperature, measured in Celsius. Applicable to thermostats.
relative_humidity
Number Required
Relative humidity, the amount of moisture in the air compared to the maximum amount of moisture the air can hold at a given temperature. It is a percentage expressed as a number between 0
and 1
, inclusive.
Applicable to thermostats.
available_hvac_mode_settings
Array of enums (strings)
List of the available HVAC mode settings for the thermostat. Possible values:
cool
heat
heat_cool
off
Applicable to thermostats.
available_fan_mode_settings
Array of enums (strings)
List of the available fan mode settings for the thermostat. Possible values:
auto
on
circulate
Applicable to thermostats.
is_heating
Boolean Required
Indicates whether the heating system is currently heating. Applicable to thermostats.
is_cooling
Boolean Required
Indicates whether the cooling system is currently cooling. Applicable to thermostats.
is_fan_running
Boolean Required
Indicates whether the fan is currently running. Applicable to thermostats.
fan_mode_setting
Enum (string) Required
Fan mode setting of the thermostat.
Deprecated. Use current_climate_setting.fan_mode_setting
instead.
Applicable to thermostats.
is_temporary_manual_override_active
Boolean Required
Indicates whether the current thermostat settings differ from the configured current_climate_setting
.
Applicable to thermostats.
current_climate_setting
Object Required
default_climate_setting
Object Required
available_climate_presets
Array of objects Required
fallback_climate_preset_key
String Optional
active_thermostat_schedule
Object Optional
min_cooling_set_point_celsius
Number Required
min_cooling_set_point_fahrenheit
Number Required
max_cooling_set_point_celsius
Number Required
max_cooling_set_point_fahrenheit
Number Required
min_heating_set_point_celsius
Number Required
min_heating_set_point_fahrenheit
Number Required
max_heating_set_point_celsius
Number Required
max_heating_set_point_fahrenheit
Number Required
min_heating_cooling_delta_celsius
Number Required
Minimum temperature difference—that is, delta—in degrees Celsius between the cooling and heating set points when in heat-cool (auto) mode. Applicable to thermostats.
min_heating_cooling_delta_fahrenheit
Number Required
Minimum temperature difference—that is, delta—in degrees Fahrenheit between the cooling and heating set points when in heat-cool (auto) mode. Applicable to thermostats.
temperature_threshold
Object Optional
XXX_metadata
Object
Manufacturer-specific metadata for the device, where XXX
is the manufacturer.
location
Properties
location
Propertieslocation_name
String
Read-only name of the device location.
timezone
String
Read-only time zone of the device location, as a name from the IANA time zone database.
accessory_keypad
Properties
accessory_keypad
Propertiesis_connected
Boolean Required
Indicates whether the accessory keypad is connected to the device.
battery
Object Optional
Keypad battery
Properties
battery
Propertieslevel
Number Required
Indicates the battery level of the keypad as a decimal value between 0
and 1
, inclusive.
keypad_battery
Properties
keypad_battery
Propertieslevel
Number Required
Indicates the battery level of the keypad as a decimal value between 0
and 1
, inclusive.
model
Properties
model
Propertiescan_connect_accessory_keypad
Boolean Optional
Indicates whether the device can connect a accessory keypad.
display_name
String Required
Display name of the device model.
manufacturer_display_name
String Required
Display name that corresponds to the manufacturer-specific terminology for the device.
has_built_in_keypad
Boolean Optional
Indicates whether the device has a built in accessory keypad.
offline_access_codes_supported
Boolean Optional
online_access_codes_supported
Boolean Optional
accessory_keypad_supported
Boolean Optional
Indicates whether the device supports an accessory keypad.
Deprecated. Use device.properties.model.can_connect_accessory_keypad
instead.
Device battery
Properties
battery
PropertiesIf the device is offline, Seam does not return these properties.
level
Number Required
Indicates the battery level of the device as a decimal value between 0
and 1
, inclusive.
status
Enum (string) Required
Represents the current status of the battery charge level.
Values are:
critical
: Indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging.low
: Signifies that the battery is under the preferred threshold and should be charged soon.good
: Denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging.full
: Represents a battery that is fully charged, providing the maximum duration of usage.
current_climate_setting
Properties
current_climate_setting
Propertiesclimate_preset_key
String Required
can_edit
Boolean Required
Indicates whether the current climate preset can be edited.
can_delete
Boolean Required
Indicates whether the current climate preset can be deleted.
name
String Optional
User-friendly name to identify the current climate preset.
display_name
String Required
Display name for the current climate preset.
fan_mode_setting
Enum (string) Required
Possible values:
auto
on
circulate
hvac_mode_setting
Enum (string) Required
Possible values:
cool
heat
heat_cool
off
cooling_set_point_celsius
Number Optional
heating_set_point_celsius
Number Optional
Temperature to which the thermostat should currently heat (in °C).
cooling_set_point_fahrenheit
Number Optional
Temperature to which the thermostat should currently cool (in °F).
heating_set_point_fahrenheit
Number Optional
Temperature to which the thermostat should currently heat (in °F).
manual_override_allowed
Boolean Required
Indicates whether another user can use the thermostat or API to override this climate setting.
Deprecated. Use thermostat_schedule.is_override_allowed
instead.
available_climate_presets
Properties
available_climate_presets
Propertiesclimate_preset_key
String Required
can_edit
Boolean Required
Indicates whether the climate preset can be edited.
can_delete
Boolean Required
Indicates whether the climate preset can be deleted.
name
String Optional
User-friendly name to identify the climate preset.
display_name
String Required
Display name for the climate preset.
fan_mode_setting
Enum (string) Required
Possible values:
auto
on
circulate
hvac_mode_setting
Enum (string) Required
Possible values:
cool
heat
heat_cool
off
cooling_set_point_celsius
Number Optional
heating_set_point_celsius
Number Optional
Temperature to which the thermostat should heat (in °C).
cooling_set_point_fahrenheit
Number Optional
Temperature to which the thermostat should cool (in °F).
heating_set_point_fahrenheit
Number Optional
Temperature to which the thermostat should heat (in °F).
manual_override_allowed
Boolean Required
Indicates whether another user can use the thermostat or API to override this climate setting.
Deprecated. Use thermostat_schedule.is_override_allowed
instead.
active_thermostat_schedule
Properties
active_thermostat_schedule
Propertiesthermostat_schedule_id
String (UUID) Required
device_id
String (UUID) Required
ID of the thermostat device.
name
String Optional
User-friendly name to identify the thermostat schedule.
climate_preset_key
String Required
max_override_period_minutes
Integer Required
starts_at
String (Datetime) Required
is_override_allowed
Boolean Optional
Indicates whether a person at the thermostat or using the API can change the thermostat's settings.
ends_at
String (Datetime) Required
created_at
String (Datetime) Required
Date and time at which the thermostat schedule was created.
errors
Array of objects Optional
Array of errors associated with the thermostat schedule. Each error object within the array contains two fields: error_code
and message
. error_code
is a string that uniquely identifies the type of error, enabling quick recognition and categorization of the issue. message
provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it.
temperature_threshold
Properties
temperature_threshold
Propertieslower_limit_celsius
Number Optional
Lower acceptable temperature bound in degrees Celsius.
lower_limit_fahrenheit
Number Optional
Lower acceptable temperature bound in degrees Fahrenheit.
upper_limit_celsius
Number Optional
Upper acceptable temperature bound in degrees Celsius.
upper_limit_fahrenheit
Number Optional
Upper acceptable temperature bound in degrees Fahrenheit.
Device Error Types
Errors are returned in a list. For example:
Generic Errors
Seam recommends adding error handling logic to you app for each generic error in this table. Seam may add more generic errors in the future, so your app should include a fallback case if it encounters an unknown generic error code.
device_disconnected
Device is disconnected.
device_removed
Device has been removed from the connected account. Seam can no longer sync with this device.
hub_disconnected
The hub that the device is connected to is offline. Seam is unable to sync updates to this device.
Specific Errors
When Seam is able to provide more specific information beyond one of the generic errors, one or more errors from the list of specific errors may appear. This gives your app the option to display additional context or suggest provider specific resolutions.
If the connected account associated with a device has an error, it is attached to the device alongside any other device errors. Treat these errors as specific errors. See Connected Account Error Types.
missing_device_credentials
ttlock_lock_not_paired_to_gateway
The lock is not paired with a gateway. Seam cannot unlock or program access codes on the lock. Add a gateway to enable support.
Device Warning Types
Warnings are returned in a list. For example:
device_has_flaky_connection
Device has a flaky connection to the internet.
third_party_integration_detected
We detected that another third-party service (for example, Operto) is being used to manage this device. This situation may cause access codes that Seam sets to fail because the third-party service is making modifications to Seam codes.
salto_office_mode
Lock is in office mode. Access codes will not unlock doors. You can disable office mode in the Salto dashboard.
salto_privacy_mode
Lock is in privacy mode. Access Codes will not unlock doors. You can disable privacy mode by pressing the back of the lock.
ttlock_lock_gateway_unlocking_not_enabled
Turn on the remote unlock feature in the lock settings to enable unlocks. This feature must be turned on from the mobile app while near the door lock.
Device Manufacturers
On some account types, Seam provides additional information about the manufacturer of the door lock. Where the device is being connected through a smart hub, the manufacturer of the door lock might be different from that of the smart hub.
Device Providers
Seam maintains a list of device providers that you can access using the List Device Providers endpoint.
The device_provider
object includes the following information:
device_provider_name
String
Name of the device provider.
For example: august
display_name
String
Formatted version of the device_provider_name
.
For example: August
image_url
String
Image URL for the provider logo.
provider_categories
Array
Array of associated categories for the provider.
Supported categories:
stable
consumer_smartlocks
thermostats
noise_sensors
can_remotely_unlock
Boolean
can_remotely_lock
Boolean
can_program_online_access_codes
Boolean
can_program_offline_access_codes
Boolean
The following example shows a device_provider
object:
Access Code Constraints
Each constraint in the code_constraints
array contains objects with the constraint_type
property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer or device-specific.
The constraint_type
property can be one of the following enum values:
no_zeros
0
s cannot be used as digits in the PIN code.
cannot_start_with_12
The PIN code cannot start with the sequence of digits 12
.
no_triple_consecutive_ints
No more than three digits in a row can be consecutive or the same in the PIN code.
cannot_specify_pin_code
You cannot specify a PIN code. You must leave the code empty, and the lock provider generates a PIN code.
pin_code_matches_existing_set
If you specify a PIN code, it must match an existing set of PIN codes used in the account.
For example, the PIN code could match the code assigned to a user in the system.
start_date_in_future
For time-bound codes, the start date must be in the future.
no_ascending_or_descending_sequence
The PIN code cannot consist of a sequence of consecutive digits.
at_least_three_unique_digits
The PIN must contain at least three unique digits.
cannot_contain_089
The PIN code cannot contain the digits 0
, 8
, or 9
.
For example, this restriction could apply to a cylinder lock that only includes the digits 1
to 7
.
cannot_contain_0789
The PIN code cannot contain the digits 0
, 7
, 8
, or 9
.
For example, this restriction could apply to a cylinder lock that only includes the digits 1
to 6
.
name_length
The name of the code has some restrictions on length.
When the constraint_type
is name_length
, the constraint object has one or two additional properties called min_length
and max_length
to specify the length constraints.
name_must_be_unique
The name of the code must be unique within the device.
device
Methods
device
MethodsYou can perform the following actions on device
objects:
Last updated