Fix ambiguous push_data flow in Reservation Automations guide

[chmaltsp]

Summary

• Adds explicit "Create spaces" step — clarifies that spaces must be created via /spaces/create with a space_key and device_ids before calling push_data (previously the guide implied push_data creates spaces inline, which silently fails)
• Adds troubleshooting section — covers common push_data gotchas: missing spaces, no devices on spaces, duplicate user identity emails causing silent user_identity_email_or_phone_conflict, and automations not enabled
• Adds note about reservations vs access_grants — clarifies the mismatch between the guide (which uses reservations) and the API reference (which documents access_grants), noting both work
• Updates prerequisites — adds warnings about unique user identity emails and the requirement to pre-create spaces
• Updates "How it works" overview — replaces "Enable automations in Console" with the actual first step (creating spaces)

Test plan

• Verify the guide renders correctly on GitBook
• Confirm all internal links resolve (/spaces/create, /customers/push_data)
• Walk through the updated flow end-to-end in a sandbox workspace

Resolves DOC-117

🤖 Generated with Claude Code

[linear]

DOC-117 Reservation Automations docs: push_data flow is ambiguous and silently fails

Problem

The Reservation Automations guide shows push_data with inline spaces as if it creates spaces and assigns devices in a single call:

{
  "customer_key": "...",
  "spaces": [{ "space_key": "unit-101", "device_ids": ["..."] }],
  "reservations": [{ "space_keys": ["unit-101"], ... }]
}

In practice, calling push_data this way returns ok: true but:

• No spaces are created
• No access codes are generated
• No errors are returned

This silent failure is extremely hard to debug — both for developers and AI coding assistants trying to follow the docs.

Root cause (confirmed)

Spaces must be created separately via POST /spaces/create with a space_key and device_ids BEFORE calling push_data. The push_data endpoint does NOT create spaces — it only references them by space_key.

The correct working flow is:

1. POST /spaces/create with name, space_key, and device_ids
2. POST /customers/push_data with reservations referencing space_keys
3. Automations are enabled by default (docs say you need to enable in Console — this appears outdated)

We confirmed this works — the automation creates an access grant and access code on the device.

Additional finding: silent user_identity_email_or_phone_conflict

When push_data includes a user_identity with an email that already exists (from a previous call), the automation silently skips the reservation with a user_identity_email_or_phone_conflict error. This is only visible in the Console automation runs view — push_data still returns ok: true. This caused significant debugging time during our integration testing and would be extremely confusing for developers.

Specific issues

1. Spaces: NOT created by push_data

The guide implies push_data creates spaces with device assignments inline. It does not. Spaces must be pre-created via /spaces/create. The guide should make this explicit with a separate step.

2. Guide vs API reference mismatch

• The guide page uses reservations with space_keys in the push_data payload
• The API reference (/api/customers/push_data) shows access_grants with space_keys — completely different structure
• The reservations format works (confirmed), but the mismatch with the API reference is confusing

3. Outdated: "Enable automations in Console"

The guide says to enable automations in Console → Developer → Automations. In our testing, automations worked on a fresh sandbox workspace without manually enabling them. This step may be outdated.

4. No error feedback on conflicts

push_data returns ok: true even when:

• Spaces don't exist (reservation silently does nothing)
• User identity email conflicts (reservation silently skipped)
• Automations aren't enabled
  There should be warnings or errors in the response when the pushed data can't be acted on.

5. space_key is required but not emphasized

When creating spaces via /spaces/create, the space_key parameter is what push_data uses to reference the space. But the /spaces/create docs don't emphasize that space_key is required for Reservation Automations to work. Without it, push_data can't find the space.

Proposed docs improvements

1. Add a complete, working code example to the Reservation Automations guide showing the ACTUAL required flow:

   Step 1: POST /spaces/create  (with space_key + device_ids)
   Step 2: POST /customers/push_data  (with reservations referencing space_keys)
   Step 3: Verify access code was created
   

2. Add a "Prerequisites" checklist at the top of the guide:

   • Spaces created via /spaces/create with space_key and devices assigned
   • Connected devices that support access codes
   • Unique email addresses per user identity (duplicates cause silent failures)

3. Align the guide page with the API reference — clarify whether reservations or access_grants is the correct key in the push_data payload

4. Add troubleshooting section: "I called push_data and got ok: true but no access code was created" — covering the common gotchas:

   • Spaces not created (must use /spaces/create first)
   • Missing space_key on the space
   • Duplicate user identity email (causes silent user_identity_email_or_phone_conflict)
   • Check Console → Automation Runs for error details

5. Remove or update the "Enable Automations" step — if automations are now enabled by default

6. Long-term: Make push_data return warnings when referenced space_keys don't match any existing spaces, or when user identity conflicts occur

Context

Discovered while building the Seam PMS Integration Skill — an AI-guided integration assistant. If an AI agent following the docs can't get this working, developers won't be able to either.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 82f0dc29c1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reconcile the claim that push_data cannot create spaces

This warning now contradicts the generated API docs in the same repo: both docs/api/customers/push_data.md and docs/api/seam/v1/customers/push_data.md still describe push_data as accepting a top-level spaces array. As written, the guide tells readers to abandon an inline-space flow that our reference still documents, so either this statement is wrong for current integrations or the API reference also needs to be updated in the same change.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Clarify cleanup for the new access_grants flow

If we advertise access_grants as interchangeable with reservations here, the rest of the guide needs the matching cleanup path as well. The delete example later still uses reservation_keys, while docs/api/customers/delete_data.md documents a separate access_grant_keys field. Readers who follow this new note are left with the wrong key shape for deleting or rolling back the access grant they just created.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Allow entrance-backed spaces in the setup step

This sentence makes device_ids sound mandatory, but our Spaces docs define a space as a grouping of devices and entrances, and docs/api/spaces/create.md accepts acs_entrance_ids as well as device_ids. For ACS-only reservation flows, telling users they need an assigned device is inaccurate and will block valid entrance-backed setups from following this guide.

Useful? React with 👍 / 👎.

[itelo]

Feedback on the Spaces and Unique user identity emails sections.

[itelo]

Suggestion: update this to:

Each space must be created via /spaces/create with a space_key and assigned device_ids or acs_entrance_ids. The space_key is used to link your internal ID to Seam. If push_data is called before /spaces/create, the spaces will be in a draft state until you create them using the space endpoint — no reservations will be created until then. You can change the devices in a space at any time; it will trigger another automation and the reservation will be updated.

[itelo]

Suggestion: update this to:

If an email already exists from a previous call, the reservation is skipped and you will need to check the automation result. If you really want to use the same email for multiple user_identity records, you must enable it in the automation via the console.