Devices

A device that has been connected to Seam

The device object represents a device that has been connected to Seam.

device Properties

The device object has the following properties:

Property	Type	Description
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	Collection of capabilities that the device supports when connected to Seam. See capabilities_supported Values. Important: Superseded by capability flags.
properties	Object Required	Properties of the device. See device.properties Properties.
location	Object Optional	Read-only location information for the device. See location Properties.
connected_account_id	String (UUID) Required	ID of the connected account associated with the device.
workspace_id	String (UUID) Required	ID of the workspace that contains the device.
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. message provides a more detailed description of the error, offering insights into the issue and potentially how to rectify it. See Device Error Types.
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. message provides a more detailed description of the warning, offering insights into the issue and potentially how to rectify it. See Device Warning Types.
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	Indicates whether the device can perform a remote unlock operation. See Capability Flags.
can_remotely_lock	Boolean Optional	Indicates whether the device can perform a remote lock operation. See Capability Flags.
can_program_online_access_codes	Boolean Optional	Indicates whether the device can program online access codes. See Capability Flags.
can_program_offline_access_codes	Boolean Optional	Indicates whether the device can program offline access codes. See Capability Flags.
can_hvac_heat	Boolean Optional	Indicates whether the thermostat device (in conjunction with the associated HVAC system) supports heat mode. See Capability Flags.
can_hvac_cool	Boolean Optional	Indicates whether the thermostat device (in conjunction with the associated HVAC system) supports cool mode. See Capability Flags.
can_hvac_heat_cool	Boolean Optional	Indicates whether the thermostat device (in conjunction with the associated HVAC system) supports heat-cool (auto) mode. See Capability Flags.
can_turn_off_hvac	Boolean Optional	Indicates whether the thermostat device (in conjunction with the associated HVAC system) supports off mode. See Capability Flags.
can_simulate_removal	Boolean Optional	Indicates whether you can simulate removal of the sandbox device. See Testing Your App Against Device Disconnection and Removal.
can_simulate_connection	Boolean Optional	Indicates whether you can simulate connection (or reconnection) of the sandbox device. See Testing Your App Against Device Disconnection and Removal.
can_simulate_disconnection	Boolean Optional	Indicates whether you can simulate disconnection of the sandbox device. See Testing Your App Against Device Disconnection and Removal.

capabilities_supported Values

Superseded by capability flags.

Capability	Description
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

Property	Type	Description
online	Boolean Required	Indicates whether the device is online.
accessory_keypad	Object Optional	Accessory keypad state. See accessory_keypad Properties.
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	Device model properties. See model Properties.
has_direct_power	Boolean Optional	Indicates whether the device has direct power.
battery_level	Number Required	Indicates the battery level of the device as a decimal value between 0 and 1, inclusive. If the device is offline, Seam does not return this property. Deprecated. Use device.properties.battery.level instead.
battery	Object Optional	Device battery properties. If the device is offline, Seam does not return this property. See Devicebattery Properties.
manufacturer	String Optional	Manufacturer of the device. See Device Manufacturers.
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	Indicates whether it is currently possible to use online access codes for the device. Superseded by the device.properties.can_program_online_access_codes capability flag.
offline_access_codes_enabled	Boolean Optional	Indicates whether it is currently possible to use offline access codes for the device. Superseded by the device.properties.can_program_offline_access_codes capability flag.
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. Applicable to devices that support access codes. See Access Code Constraints.
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	Indicates whether the device supports backup access code pools. Applicable to devices that support access codes.
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. See keypad_battery Properties.
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	Current climate setting for the thermostat. Applicable to thermostats. See current_climate_setting Properties.
default_climate_setting	Object Required	Deprecated. Use fallback_climate_preset_key to specify a fallback climate preset instead.
available_climate_presets	Array of objects Required	Set of climate presets that are available for the thermostat device. See available_climate_presets Properties.
fallback_climate_preset_key	String Optional	Key that identifies the current fallback climate preset.
active_thermostat_schedule	Object Optional	Currently active thermostat schedule. See active_thermostat_schedule Properties.
min_cooling_set_point_celsius	Number Required	Minimum cooling set point that this thermostat supports, measured in Celsius. Applicable to thermostats.
min_cooling_set_point_fahrenheit	Number Required	Minimum cooling set point that this thermostat supports, measured in Fahrenheit. Applicable to thermostats.
max_cooling_set_point_celsius	Number Required	Maximum cooling set point that this thermostat supports, measured in Celsius. Applicable to thermostats.
max_cooling_set_point_fahrenheit	Number Required	Maximum cooling set point that this thermostat supports, measured in Fahrenheit. Applicable to thermostats.
min_heating_set_point_celsius	Number Required	Minimum heating set point that this thermostat supports, measured in Celsius. Applicable to thermostats.
min_heating_set_point_fahrenheit	Number Required	Minimum heating set point that this thermostat supports, measured in Fahrenheit. Applicable to thermostats.
max_heating_set_point_celsius	Number Required	Maximum heating set point that this thermostat supports, measured in Celsius. Applicable to thermostats.
max_heating_set_point_fahrenheit	Number Required	Maximum heating set point that this thermostat supports, measured in Fahrenheit. Applicable to thermostats.
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	Acceptable temperature bounds consisting of a temperature range or single upper or lower temperature. Seam emits a thermostat.temperature_threshold_exceeded event if the thermostat reports a temperature outside the specified threshold. See temperature_threshold Properties.
XXX_metadata	Object	Manufacturer-specific metadata for the device, where XXX is the manufacturer.

location Properties

Property	Type	Description
location_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

Property	Type	Description
is_connected	Boolean Required	Indicates whether the accessory keypad is connected to the device.
battery	Object Optional	Keypad battery properties. See Keypad battery Properties.

Keypad battery Properties

Property	Type	Description
level	Number Required	Indicates the battery level of the keypad as a decimal value between 0 and 1, inclusive.

keypad_battery Properties

Property	Type	Description
level	Number Required	Indicates the battery level of the keypad as a decimal value between 0 and 1, inclusive.

model Properties

Property	Type	Description
can_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	Indicates whether the device supports offline access codes. Superseded by the device.properties.can_program_offline_access_codes capability flag.
online_access_codes_supported	Boolean Optional	Indicates whether the device supports online access codes. Superseded by the device.properties.can_program_online_access_codes capability flag.
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

If the device is offline, Seam does not return these properties.

Property	Type	Description
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

Property	Type	Description
climate_preset_key	String Required	Unique key to identify the current climate preset.
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	Current desired fan mode setting. Possible values: auto on circulate
hvac_mode_setting	Enum (string) Required	Current desired HVAC mode setting. Possible values: cool heat heat_cool off
cooling_set_point_celsius	Number Optional	Temperature to which the thermostat should currently cool (in °C). See also Set Points.
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

Property	Type	Description
climate_preset_key	String Required	Unique key to identify the climate preset.
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	Desired fan mode setting. Possible values: auto on circulate
hvac_mode_setting	Enum (string) Required	Desired HVAC mode setting. Possible values: cool heat heat_cool off
cooling_set_point_celsius	Number Optional	Temperature to which the thermostat should cool (in °C). See also Set Points.
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

Property	Type	Description
thermostat_schedule_id	String (UUID) Required	ID of the active thermostat schedule.
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	Key of the climate preset to use for the thermostat schedule.
max_override_period_minutes	Integer Required	Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled climate preset. See also Specifying Manual Override Permissions.
starts_at	String (Datetime) Required	Date and time at which the thermostat schedule starts, in ISO 8601 format.
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	Date and time at which the thermostat schedule ends, in ISO 8601 format.
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

Property	Type	Description
lower_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:

"errors": [
  {
    "is_device_error": true,
    "error_code": "device_disconnected",
    "message": "Device Disconnected, you may need to reconnect the device.",
    "created_at": "2023-06-27T22:50:19.440Z
  }
]

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.

Error Type	Description
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.

Error Type	Description
missing_device_credentials	Missing device credentials. Create a new Connect Webview to provide the 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:

"warnings": [
  {
    "warning_code": "device_has_flaky_connection",
    "message": "Device has a flaky connection to the internet.",
    "created_at": "2023-06-27T22:50:19.440Z
  }
]

Warning Type	Description
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:

Property	Type	Description
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	Indicates whether at least one supported device from the provider can perform a remote unlock operation. See Capability Flags.
can_remotely_lock	Boolean	Indicates whether at least one supported device from the provider can perform a remote lock operation. See Capability Flags.
can_program_online_access_codes	Boolean	Indicates whether at least one supported device from the provider can program online access codes. See Capability Flags.
can_program_offline_access_codes	Boolean	Indicates whether at least one supported device from the provider can program offline access codes. See Capability Flags.

The following example shows a device_provider object:

{
  "device_provider_name": "august",
  "display_name": "August",
  "image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/logos/august_logo_square.png&q=75&w=128",
  "provider_categories": [
    "stable",
    "consumer_smartlocks"
  ],
  "can_remotely_lock": true,
  "can_remotely_unlock": true,
  "can_program_online_access_codes": true
}

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:

Constraint Type	Description
no_zeros	0s 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

You can perform the following actions on device objects:

• List devices
• List device providers
• Get a device
• Update a device
• List unmanaged devices
• Get an unmanaged devices
• Update an unmanaged device