Ask or search…
K
Links
Comment on page

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)
Unique identifier for the device.
device_type
String
Type of the device.
capabilities_supported
Collection of capabilities that the device supports when connected to Seam.
errors
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.
warnings
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.
location
Location information for the device.
manufacturer
Manufacturer of the device.
properties
Properties of the device.
workspace_id
String (UUID)
Unique identifier for the Seam workspace associated with the device.
created_at
Datetime
Date and time at which the device object was created.

device.properties Properties

Property
Type
Description
locked
Boolean
Indicates whether the device is locked.
online
Boolean
Indicates whether the device is online.
door_open
Boolean
Indicates whether the door is open.
manufacturer
String
Manufacturer of the device.
battery_level
Float
Battery level of the device.
XXX_metadata
Object
Manufacturer-specific metadata for the device, where XXX is the manufacturer.
supported_code_lengths
Array
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.
online_access_codes_enabled
Boolean
Indicates whether it is currently possible to use online access codes for the device.
offline_access_codes_enabled
Boolean
Indicates whether it is currently possible to use offline access codes for the device.
max_active_codes_supported
Integer
Maximum number of codes that can exist on the device at one time.
code_constraints
Array
Constraints on access codes that can be set on the device for devices that support access codes.
name
String
Name of the device.
battery
Object
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.
keypad_battery
Object
Information about the keypad battery for the device, if available. Includes a level property.
serial_number
String
Serial number for the device, if available.
image_url
String
Image URL for the device or placeholder image URL if a device-specific image is unavailable.

location Properties

Property
Type
Description
location_name
String
Name of the device location.
timezone
String
Time zone of the device location, as a name from the IANA time zone database.

capabilities_supported Values

Capability
Description
access_code
If present, you can set access codes on the device.
battery
If present, you can look at the battery_level of the device
health
If present, you can introspect some parameters related to the health of the device.
lock
If present, you can lock and unlock the device.
noise_sensor
If present, the device can issue noise alerts when noise thresholds are exceeded.
thermostat
If present, the device can regulate the temperature of a system so that the temperature of the system is maintained near a desired set point temperature.

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.
Seam might return the following manufacturers:
  • august
  • keywe
  • kwikset
  • lockly
  • philia
  • samsung
  • schlage
  • yale
  • unknown

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.
Possible categories: stable
The following example shows a device provider object:
{
"device_provider_name": "august",
"display_name": "August",
"image_url": "https://connect.getseam.com/assets/images/logos/august_logo_square.png",
"provider_categories": ["stable"]
}

Access Code Constraints

Each constraint in the code_constraints array is an object with at least the constraint_type property. The constraint_type property can be one of the following:
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 3 digits in a row can be consecutive or the same in the PIN code.
cannot_specify_pin_code
A PIN code cannot be specified. It must be left empty, and one will be generated by the lock provider.
pin_code_matches_existing_set
If a PIN code is specified, it must match an existing set of PIN codes used in the account.
For example, the PIN code matches the code assigned to a user in the system.
start_date_in_future
For time-bound codes, the start date has to be in the future.
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.

device Methods

You can perform the following actions on device objects: