Reservation Automations

Reservation Automations sync reservation and guest data with your access and climate systems. Instead of building custom workflows for check-in, mid-stay changes, and checkout, you send reservation data to Seam and device settings update automatically. Use Reservation Automations for short-term bookings such as hotel stays, gym classes, coworking rooms and event rentals. The reservation supplies the intended access and climate window.

How it works

Reservation Automations follow the lifecycle of a reservation:

You create spaces and assign devices using /spaces/create.
You send reservation and guest data with push_data.
Seam applies the right access and climate settings at the right times.
Webhooks notify you when settings are issued, updated, or revoked.
If a reservation is canceled, call delete_data to request removal of its related resources.

Before you begin

Set up these resources in your Seam workspace:

Customer – identify who the automation belongs to with a customer_key.
Spaces – represent the real-world units your customer manages (i.e. Room 101 in a hotel, Studio 3 in a gym). Each space must be created via /spaces/create with a space_key and assigned devices or entrances before you call push_data. Reservations reference these spaces by space_key.
Devices or entrances – connect locks, thermostats, or ACS entrances to each space (e.g., assign the lock in Room 101 to the Room 101 space). Use device_ids for smart locks and thermostats, or acs_entrance_ids for access control system entrances.
Guest identity keys – reuse the same user_identity_key for the same guest. When shared email and phone are disabled, using the same contact details for different guest keys can cause a conflict. Check Automation Runs for identity errors.

Although push_data accepts a spaces array, it only creates a lightweight resource reference — it does not assign devices or entrances to the space. If you skip /spaces/create, the space will have no devices and automations will have nothing to configure. The call still returns ok: true, making this a silent failure. Always create spaces with device or entrance assignments first using /spaces/create.

You can also let customers configure their own accounts, spaces, and devices with Customer Portals.

1. Create spaces with devices

Before pushing reservation data, create a space for each bookable unit using the /spaces/create endpoint. Each space must have a space_key (your identifier) and at least one assigned device or entrance.

curl -X POST \
  https://connect.getseam.com/spaces/create \
  -H "Authorization: Bearer $SEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Room 101",
    "space_key": "unit-101-key",
    "device_ids": ["YOUR_LOCK_DEVICE_ID"]
  }'

Use device_ids for smart locks and thermostats, or acs_entrance_ids for access control system entrances. You can include both if the space has multiple access points. The space_key is what you reference in push_data reservations. Without it, push_data cannot match reservations to the space.

2. Customize automation settings

After enabling automations, you can configure how access credentials are issued for each reservation. These settings are available in Console > Developer > Automations under the access automation section. Access methods Choose which credential types to issue when a reservation is created. You must enable at least one.

Method	Description
PIN code	A numeric code the guest enters on a keypad.
Plastic card	A physical card encoded for the lock.
Mobile key	A digital key delivered to the guest’s phone.

Access method creation strategy Controls how many access methods are created per device when multiple types are enabled:

Strategy	Behavior
First available (default)	Creates only the first supported method on each device.
First two available	Creates up to two supported methods on each device.
All available	Creates every supported method on each device.

Card count The number of plastic cards to create per reservation. Only applies when the plastic card access method is enabled. Instant key max use count The maximum number of times a mobile key can be used. Only applies when the mobile key access method is enabled. Use guest phone last 4 digits as code When enabled, Seam will attempt to use the last 4 digits of the guest’s phone number as the PIN code instead of generating a random one. The phone number is looked up from the user identity data you provide via push_data. PIN code priority:

An explicit preferred_code on the reservation always takes precedence.
If no preferred_code is set and this option is enabled, Seam uses the last 4 digits of the guest’s phone number.
If the phone number is unavailable or has fewer than 4 digits, Seam falls back to an auto-generated code.

The derived code is a best-effort preference, not a guarantee. If the code conflicts with a device’s PIN constraints (for example, the code is already in use on that lock) Seam assigns an auto-generated code for that device and adds a relevant warning to the access grant.

Allow shared email and phone across guests When enabled, multiple guests can share the same email address or phone number. This is useful when the same person has multiple reservations or holds different roles.

3. Push reservation data

Use the push_data endpoint to send customer, user, and reservation data to Seam. Automations use this information to configure devices at the right times. A reservation represents a time-bound assignment of a user to a space. This can be a hotel stay, a gym day pass, or a coworking member’s conference room booking. Each reservation must include a unique reservation_key, which can be your system’s identifier for that record. Seam uses this key to know whether it should create a new reservation, update an existing one, or remove it later with delete_data.

curl -X POST \
  https://connect.getseam.com/customers/push_data \
  -H "Authorization: Bearer $SEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_key": "sample_customer_key",
    "user_identities": [
      {
        "user_identity_key": "user_789",
        "name": "John Doe",
        "email_address": "john@example.com"
      }
    ],
    "reservations": [
      {
        "reservation_key": "res_456",
        "user_identity_key": "user_789",
        "starts_at": "2025-08-12T19:47:27.490Z",
        "ends_at": "2025-08-14T19:47:27.490Z",
        "space_keys": ["unit-101-key"]
      }
    ]
  }'

Call push_data with a new reservation_key to create a reservation.
Call it again with the same reservation_key to update times or other details—Seam automatically reconfigures the device settings.

The push_data API reference also documents access_grants and bookings as alternative top-level keys. This guide uses reservations, which is the recommended key for short-term booking workflows. If you use access_grants instead, use access_grant_keys (not reservation_keys) when calling delete_data.

Change reservation times

Keep the same customer_key, reservation_key and user_identity_key when a booking changes. Send the intended check-in and checkout times as ISO 8601 timestamps with Z or an explicit UTC offset. Convert the property’s local time first; do not use your server’s local time zone. The following JavaScript example updates an existing reservation. Install the SDK and set SEAM_API_KEY on your server. Set the environment variables to the same customer, guest and space keys used when you created it. Set CHECKIN_AT and CHECKOUT_AT to the new times.

JavaScript

import { Seam } from 'seam'

const seam = new Seam()
const customerKey = process.env.CUSTOMER_KEY
const reservation = {
  reservation_key: process.env.RESERVATION_KEY,
  user_identity_key: process.env.USER_IDENTITY_KEY,
  space_keys: [process.env.SPACE_KEY],
  starts_at: process.env.CHECKIN_AT,
  ends_at: process.env.CHECKOUT_AT,
}
if (!customerKey || !reservation.reservation_key ||
    !reservation.user_identity_key || !reservation.space_keys[0]) {
  throw new Error('Set the existing customer, reservation, guest and space keys.')
}
const hasOffset = (value) => typeof value === 'string' && /(?:Z|[+-]\d{2}:\d{2})$/.test(value)
if (!hasOffset(reservation.starts_at) || !hasOffset(reservation.ends_at) ||
    !Number.isFinite(Date.parse(reservation.starts_at)) ||
    !Number.isFinite(Date.parse(reservation.ends_at)) ||
    Date.parse(reservation.ends_at) <= Date.parse(reservation.starts_at)) {
  throw new Error('Use an explicit time zone and an end time after the start time.')
}
await seam.customers.pushData({
  customer_key: customerKey,
  reservations: [reservation],
})

This submits the changed reservation. It does not confirm that a lock or thermostat has applied the change. Check Automation Runs and the access method events before reporting completion.

Move a reservation to another space

Create the destination space and assign its devices first. Keep the reservation key, then send the complete set of spaces that should now apply. To move from one room to another, replace the old room key; including both keys keeps both spaces in the reservation. Continue with the seam, customerKey and reservation values above:

JavaScript

const nextSpaceKey = process.env.NEW_SPACE_KEY
if (!nextSpaceKey) throw new Error('Set the destination space key.')
await seam.spaces.get({ space_key: nextSpaceKey })
await seam.customers.pushData({
  customer_key: customerKey,
  reservations: [{ ...reservation, space_keys: [nextSpaceKey] }],
})

A room move can require removing access from the old space and issuing access for the new one. Track both outcomes before telling a guest the move is ready. A successful push_data response confirms receipt of the data, not physical access or a completed thermostat change. Process booking notifications in order. Keep the latest booking version in your application so a delayed notification does not restore an old time or room. Reuse the same keys when retrying; do not create another reservation key for an update. Use delete_data to cancel the reservation rather than trying to represent cancellation with an empty space list. In a sandbox, test the time change, room move and cancellation separately. Check the stored reservation and automation result as well as the HTTP response; virtual-device results do not prove physical operation.

4. Use webhooks to listen for updates

Configure webhooks in Console > Developer > Webhooks to get notified when automations apply or revoke settings. Key events:

access_method.issued – access created
access_method.reissued – access updated
access_method.deleted – access removed

Webhook payloads include the keys that triggered the event, letting you sync state with your application.

5. Delete data

The delete_data endpoint is optional but important. Use it when access or device settings should no longer apply—such as when:

A hotel reservation is canceled
A conference room reservation ends early
A gym class is dropped
An event reservation is called off

Calling delete_data requests removal of the reservation and its related resources. Track the resulting automation and access method state before reporting that access or device settings have been removed. An accepted request does not establish immediate physical revocation.

curl -X POST \
  https://connect.getseam.com/customers/delete_data \
  -H "Authorization: Bearer $SEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation_keys": ["res_456"],
    "user_identity_keys": ["user_789"]
  }'

Pass reservation_keys to cancel a specific reservation and remove its device settings.
Pass user_identity_keys to remove all device settings tied to a specific person.
Pass customer_keys to offboard an entire customer and clear all their spaces, users, and settings.

Troubleshooting

I called `push_data` and got `ok: true` but no access code was created

push_data returns a success response even when automations cannot act on the data. Check these common causes:

Symptom	Cause	Fix
No access code created	Space does not exist or is missing a `space_key`	Create the space via `/spaces/create` with a `space_key` and `device_ids` or `acs_entrance_ids` before calling `push_data`
No access code created	No devices or entrances assigned to the space	Add `device_ids` or `acs_entrance_ids` when creating the space, or update the space to include them
Reservation silently skipped	Conflicting contact details while shared email/phone are disabled	Reuse the intended guest key or review the shared-email setting. Check Console → Automation Runs for `user_identity_email_or_phone_conflict` errors
Automation did not run	Automations not enabled	Go to Console → Developer → Automations and verify automations are enabled for your workspace

Check Console → Automation Runs for detailed error information. Errors like user_identity_email_or_phone_conflict are only visible there — they do not appear in the push_data response.

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Reservation Automations

How it works

Before you begin

1. Create spaces with devices

2. Customize automation settings

3. Push reservation data

Change reservation times

Move a reservation to another space

4. Use webhooks to listen for updates

5. Delete data

Troubleshooting

I called `push_data` and got `ok: true` but no access code was created

​How it works

​Before you begin

​1. Create spaces with devices

​2. Customize automation settings

​3. Push reservation data

​Change reservation times

​Move a reservation to another space

​4. Use webhooks to listen for updates

​5. Delete data

​Troubleshooting

​I called push_data and got ok: true but no access code was created

How it works

Before you begin

1. Create spaces with devices

2. Customize automation settings

3. Push reservation data

Change reservation times

Move a reservation to another space

4. Use webhooks to listen for updates

5. Delete data

Troubleshooting

I called `push_data` and got `ok: true` but no access code was created