Custom Metadata Everywhere!

This week, we’re excited to introduce the ability to store and filter resources using your own metadata within Seam! For example, you can now store your internal user or property id directly inside the device’s custom_metadata attribute. Furthermore, you can use this metadata to filter devices on the /list endpoint.

Why Use Custom Metadata

Most applications have to maintain a mapping between Seam devices and their internal resources (locations, user accounts…etc). This mapping requirement usually involves having to develop a schema as well as search and retrieval functions.

Being able to store custom metadata on Seam resources, as well as being able to filter by a subset of that metadata, makes developing applications significantly easier. You no longer have to maintain complex schema and search functions on your server. Simply store any mapping information on a Seam resource, and use our /list endpoint to retrieve associated resources using this metadata.

Resource Availability & Behavior

Seam custom_metadata was already available on Connect Webview objects. Today we’re rolling it out on Device and Connected Account objects. Our plan is to roll this out to additional resources later on, such as Access Codes and Climate Schedules.

To improve overall developer experience, we also automatically copy over any custom_metadata that you define on a Connect Webview to the resulting Connected Account that gets authorized. This makes initial account and device retrieval faster, saving you from having to re-query the Connect Webview.

Storing Custom Metadata

To store custom metadata, simply use the update function of a given resource and pass it the custom metadata as a dictionary/map of key value pairs.

1seam.devices.update(
2    device=device_id, 
3    name="My Lock", 
4    custom_metadata={"internal_account_id": "user-1"}
5)

See more code samples for Devices and Connected Account.

Note that custom metadata has a couple of constraints worth pointing out. You can specify up to 50 pieces of custom metadata as JSON-formatted key:value pairs on supported objects. The key names can be up to 40 characters long, and the corresponding values can be strings or Booleans. Strings can contain up to 500 characters. Over time, our intention is to expand the supported types as well as maximum sizes.

Filtering via Custom Metadata

To retrieve objects, specify custom_metadata_has as part of the list endpoint. This will return all matching resources.

1devices = seam.devices.list(
2    custom_metadata_has={
3        "internal_property_id": "property-1"
4    }
5)

See more code samples for Device and Connected Account.

Rollout

This feature is available right away (and thanks to those who have been testing this feature for a while). As aforementioned, we will continue rolling this out to additional Seam resources; please do let us know if you’d like us to prioritize this for a specific resource. Last but not least, if you run into issues, please contact us at support@getseam.com.