Fix ambiguous push_data flow in Reservation Automations guide

docs/capability-guides/reservation-automations.md

@@ -14,50 +14,65 @@ Built for short-term bookings—whether hotel stays, gym classes, coworking room
 
 Reservation Automations follow the lifecycle of a reservation:
 
-1. You enable Automations in [Console](https://console.getseam.com/).
+1. You create spaces and assign devices using [`/spaces/create`](../api/spaces/create.md).
 2. You send reservation and guest data with `push_data`.
 3. Seam applies the right access and climate settings at the right times.
 4. Webhooks notify you when settings are issued, updated, or revoked.
 5. If a reservation is canceled, you call `delete_data` to roll back device settings.
 
 ***
 
-### Before you begin![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg) <a href="#before-you-begin" id="before-you-begin"></a>
+### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>
 
 Set up these resources in your Seam workspace:
 
 * [Customer](customer-portals/) – identify who the automation belongs to with a `customer_key`.
-* [Spaces](../core-concepts/mapping-your-resources-to-seam-resources.md) – represent the real-world units your customer manages (i.e. _Room 101_ in a hotel, _Studio 3_ in a gym). Reservations should reference these spaces.
-* Devices or entrances – connect locks, thermostats, or other devices to each Space (e.g., assign the lock in Room 101 to the _Room 101_ space)
+* [Spaces](../core-concepts/mapping-your-resources-to-seam-resources.md) – 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`](../api/spaces/create.md) 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.
+* Unique user identity emails – each `user_identity` you push must have a unique `email_address`. If an email already exists from a previous call, the reservation is silently skipped.
 
-Reservation Automations use these resources to decide where and how to apply settings.
+{% hint style="warning" %}
+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`](../api/spaces/create.md), 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`.
+{% endhint %}
 
 {% hint style="success" %}
 You can also let customers configure their own accounts, spaces, and devices with [Customer Portals](customer-portals/).
 {% endhint %}
 
 ***
 
-### 1. Enable Reservation Automations in Console.
+### 1. Create spaces with devices
+
+Before pushing reservation data, create a space for each bookable unit using the [`/spaces/create`](../api/spaces/create.md) endpoint. Each space must have a `space_key` (your identifier) and at least one assigned device or entrance.
+
+```bash
+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"]
+  }'
+```
 
-Go to **Console** → **Developer** → **Automations** and turn on an Automations for your workspace.
+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.
 
-<figure><img src="../.gitbook/assets/Screenshot 2025-09-01 at 5.25.53 PM (1).png" alt=""><figcaption></figcaption></figure>
+The `space_key` is what you reference in `push_data` reservations. Without it, `push_data` cannot match reservations to the space.
 
 ***
 
 ### 2. 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`.
-
-Use the `push_data` endpoint to provide Seam your customer, guest, and reservation data. Seam uses this to issue access credentials and 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`.
 
 ```bash
 curl -X POST \
-  https://api.seam.co/customers/push_data \
-  -H "Authorization: Bearer $YOUR_API_KEY" \
+  https://connect.getseam.com/customers/push_data \
+  -H "Authorization: Bearer $SEAM_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "customer_key": "sample_customer_key",
@@ -83,6 +98,10 @@ curl -X POST \
 * 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.
 
+{% hint style="info" %}
+The `push_data` [API reference](../api/customers/push_data.md) 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`](../api/customers/delete_data.md).
+{% endhint %}
+
 ***
 
 ### 3.  Use webhooks to listen for updates
@@ -112,8 +131,8 @@ Calling `delete_data` removes the underlying reservation records, which tells au
 
 ```bash
 curl -X POST \
-  https://api.seam.co/customers/delete_data \
-  -H "Authorization: Bearer $YOUR_API_KEY" \
+  https://connect.getseam.com/customers/delete_data \
+  -H "Authorization: Bearer $SEAM_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "reservation_keys": ["res_456"],
@@ -127,4 +146,21 @@ curl -X POST \
 
 ***
 
+### 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`](../api/spaces/create.md) 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 | Duplicate `email_address` on a `user_identity` | Each user identity must have a unique email. 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 |
+
+{% hint style="info" %}
+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.
+{% endhint %}
+
 ***