From 9bacc3c4295d438f0f4e5e0ac9cb113395c9962d Mon Sep 17 00:00:00 2001 From: itelo Date: Fri, 26 Jun 2026 11:32:23 -0300 Subject: [PATCH 1/4] feat: Expand push_data guidance in Reservation Automations guide Add to section 3 (Push reservation data): - Update examples for changing reservation time and assigned space - Guidance to use a stable reservation_key not derived from underlying resources, plus the delete-before-update pattern when the key must change - Recommendation to push only confirmed reservations to reduce unneeded hardware operations and avoidable errors Co-Authored-By: Claude Opus 4.8 (1M context) --- .../reservation-automations.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/docs/guides/capability-guides/reservation-automations.md b/docs/guides/capability-guides/reservation-automations.md index e23c2681b..3bd119ca6 100644 --- a/docs/guides/capability-guides/reservation-automations.md +++ b/docs/guides/capability-guides/reservation-automations.md @@ -154,6 +154,72 @@ curl -X POST \ The `push_data` [API reference](https://docs.seam.co/latest/api/customers/push_data) 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`](https://docs.seam.co/latest/api/customers/delete_data). {% endhint %} +#### Update a reservation + +To update an existing reservation, call `push_data` again with the **same `reservation_key`** and the new values. Seam diffs the incoming data against what it already has and reconfigures only what changed—you do not need to delete and recreate the reservation for routine edits. + +**Change the reservation time** + +When a guest extends their stay or a booking moves, send the updated `starts_at` and `ends_at`. Seam shifts the access window and reissues credentials as needed. + +```bash +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", + "reservations": [ + { + "reservation_key": "res_456", + "user_identity_key": "user_789", + "starts_at": "2025-08-12T19:47:27.490Z", + "ends_at": "2025-08-16T19:47:27.490Z", + "space_keys": ["unit-101-key"] + } + ] + }' +``` + +**Change the assigned space** + +When a guest is moved to a different unit, send the new `space_keys`. Seam revokes access on the previous space and issues access on the new one. + +```bash +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", + "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-202-key"] + } + ] + }' +``` + +#### Choose a stable `reservation_key` + +The `reservation_key` is how Seam tells an update apart from a brand-new reservation. Use a value that stays constant for the life of the booking—typically your system's own reservation or booking ID. + +Do **not** derive the key from underlying resources such as a space, room number, device ID, or guest. If you do, the key changes whenever that resource changes, and Seam treats the next `push_data` as a different reservation: it creates a new one and leaves the original active, so two sets of credentials end up on the hardware. + +{% hint style="warning" %} +If the `reservation_key` itself must change—for example, because it was built from data that is no longer stable—the only safe path is to [`delete_data`](https://docs.seam.co/latest/api/customers/delete_data) with the **old** key first, then `push_data` with the new key. This rolls back the original credentials before the new ones are issued and prevents orphaned access from lingering on the device. +{% endhint %} + +#### Push only confirmed reservations + +Most booking systems move a reservation through several intermediate states—_inquiry_, _pending_, _tentative_, _on hold_—before it is actually confirmed. Send data to Seam only once the reservation is confirmed and access is genuinely needed. + +Every `push_data` call that changes a reservation can translate into a physical operation on a lock, keypad, or access control system. Seam handles this synchronization reliably, but each command sent to hardware is an opportunity for a device to be offline, rate-limited, or slow to respond. Pushing speculative or short-lived states multiplies those commands for bookings that may never need access, increasing both load and the chance of an avoidable error. Waiting until a reservation is confirmed keeps the data you send aligned with the access you actually intend to grant. + *** ### 4. Use webhooks to listen for updates From 9bb01d885a86554bf4ab1695069b0574e71d66c3 Mon Sep 17 00:00:00 2001 From: itelo Date: Fri, 26 Jun 2026 11:49:06 -0300 Subject: [PATCH 2/4] feat: Document multi-room (sub-reservation) push_data pattern Add a "Bookings that span multiple rooms" subsection: push one reservation per sub-reservation, keyed by _ with each sub-reservation's own space, so each room's access stays independently addressable for updates and delete_data. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../reservation-automations.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/guides/capability-guides/reservation-automations.md b/docs/guides/capability-guides/reservation-automations.md index 3bd119ca6..342a74077 100644 --- a/docs/guides/capability-guides/reservation-automations.md +++ b/docs/guides/capability-guides/reservation-automations.md @@ -214,6 +214,40 @@ Do **not** derive the key from underlying resources such as a space, room number If the `reservation_key` itself must change—for example, because it was built from data that is no longer stable—the only safe path is to [`delete_data`](https://docs.seam.co/latest/api/customers/delete_data) with the **old** key first, then `push_data` with the new key. This rolls back the original credentials before the new ones are issued and prevents orphaned access from lingering on the device. {% endhint %} +#### Bookings that span multiple rooms + +Some booking systems model a single booking as a parent reservation with multiple **sub-reservations**, where each sub-reservation occupies its own room. Don't collapse these into one `reservation_key` with several `space_keys`—the sub-reservations can be added, moved, or canceled independently, and a single key cannot track them apart. + +Instead, push **one reservation per sub-reservation**, and build each `reservation_key` from your two stable identifiers, `_`, with that sub-reservation's own space: + +```bash +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", + "reservations": [ + { + "reservation_key": "res_456_sub_1", + "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"] + }, + { + "reservation_key": "res_456_sub_2", + "user_identity_key": "user_789", + "starts_at": "2025-08-12T19:47:27.490Z", + "ends_at": "2025-08-14T19:47:27.490Z", + "space_keys": ["unit-102-key"] + } + ] + }' +``` + +This keeps each room's access independently addressable: you can update or `delete_data` a single sub-reservation without touching the others. Both parts of the key remain stable booking identifiers, so this is consistent with the rule above—you are combining IDs, not deriving the key from the room itself. + #### Push only confirmed reservations Most booking systems move a reservation through several intermediate states—_inquiry_, _pending_, _tentative_, _on hold_—before it is actually confirmed. Send data to Seam only once the reservation is confirmed and access is genuinely needed. From 3d6be6e3a13d0035aed3209b9bc9b9af15caf844 Mon Sep 17 00:00:00 2001 From: itelo Date: Fri, 26 Jun 2026 11:53:53 -0300 Subject: [PATCH 3/4] feat: Reframe automation settings as trigger-based automation rules Restructure section 2 around the Console's Automation Rules model: - Organize the access-method settings under a "When a reservation is created" rule and document the drag-to-reorder access-method preference order - Add a "When a staff member is created" rule that provisions access for staff to their associated properties Co-Authored-By: Claude Opus 4.8 (1M context) --- .../reservation-automations.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/guides/capability-guides/reservation-automations.md b/docs/guides/capability-guides/reservation-automations.md index 342a74077..f8b938094 100644 --- a/docs/guides/capability-guides/reservation-automations.md +++ b/docs/guides/capability-guides/reservation-automations.md @@ -63,18 +63,22 @@ The `space_key` is what you reference in `push_data` reservations. Without it, ` *** -### 2. Customize automation settings +### 2. Configure automation rules -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. +Automation rules control what access Seam creates and when. Configure them in **Console** > **Developer** > **Automations**. Each rule is tied to an event—when a reservation is created, or when a staff member is created—and defines the access Seam issues in response. -**Access methods** +#### When a reservation is created -Choose which credential types to issue when a reservation is created. You must enable at least one. +Seam creates access for the guest to the property (space) associated with the reservation, valid for the duration of the reservation. The settings below control which credentials are issued and how. + +**Access methods to create (in order of preference)** + +Choose which credential types to issue. You must enable at least one. Drag the enabled methods to set their order of preference: for each door, Seam works down the list and creates access using the methods that door supports. | Method | Description | | ---------------- | --------------------------------------------- | -| **PIN code** | A numeric code the guest enters on a keypad. | | **Plastic card** | A physical card encoded for the lock. | +| **PIN code** | A numeric code the guest enters on a keypad. | | **Mobile key** | A digital key delivered to the guest's phone. | **Access method creation strategy** @@ -115,6 +119,10 @@ When enabled, multiple guests can share the same email address or phone number.
+#### When a staff member is created + +Seam creates access for the staff member to the property (space) associated with that staff member. Use this rule to automatically provision access for on-site staff—such as housekeeping or maintenance—alongside guest access. The same access method settings above determine which credentials are issued. + ### 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. From dca3e72db2086e9f62f971721996e8961b463e33 Mon Sep 17 00:00:00 2001 From: itelo Date: Fri, 26 Jun 2026 11:54:50 -0300 Subject: [PATCH 4/4] feat: Remove staff member automation rule subsection Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/guides/capability-guides/reservation-automations.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/guides/capability-guides/reservation-automations.md b/docs/guides/capability-guides/reservation-automations.md index f8b938094..f5a4c9fff 100644 --- a/docs/guides/capability-guides/reservation-automations.md +++ b/docs/guides/capability-guides/reservation-automations.md @@ -119,10 +119,6 @@ When enabled, multiple guests can share the same email address or phone number.
-#### When a staff member is created - -Seam creates access for the staff member to the property (space) associated with that staff member. Use this rule to automatically provision access for on-site staff—such as housekeeping or maintenance—alongside guest access. The same access method settings above determine which credentials are issued. - ### 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.