Setting Up Customer Connections with Connect Webviews

Last updated: December 13, 2025

Overview

Learn how to link Connect Webviews to your internal customer IDs and handle the complete post-connection flow, including detecting what was connected and syncing resources.

Part 1: Linking Connect Webviews to Your Customers

Using `customer_key` to Track Customers

When you create a Connect Webview, tag it with your internal customer or property ID using customer_key. Seam automatically copies this key to the resulting Connected Account, allowing you to retrieve all accounts for a specific customer.

Best practice: Use your existing customer/property ID directly - no transformation needed.

# Creating a Connect Webview for a specific customer
webview = seam.connect_webviews.create(
  customer_key="property-456",  # Your internal property ID
  accepted_providers=["salto", "assa_abloy_visionline"]
)

# Later: retrieve all accounts for this customer
accounts = seam.connected_accounts.list(
  customer_key="property-456"
)

Note on `custom_metadata`

While custom_metadata can store additional data, use customer_key for your primary customer/property identifier since it's specifically designed for this purpose and enables direct retrieval.

Part 2: Post-Connection Flow

Step 1: Receive the Webhook or Redirect

After a customer completes the Connect Webview:

Listen for the connected_account.connected webhook
Store the connected_account_id and customer_key in your database

Step 2: Detect What Type of System Was Connected

The same Connect Webview works for both smart locks and access control systems. Determine which was connected by querying resources:

# Check for ACS systems
acs_systems = seam.acs.systems.list(
  connected_account_id=account.connected_account_id
)

if acs_systems:
  # It's an ACS - get entrances
  for system in acs_systems:
    entrances = seam.acs.entrances.list(
      acs_system_id=system.acs_system_id
    )
    # Store entrances in your database
else:
  # It's smart locks - get devices
  devices = seam.devices.list(
    connected_account_id=account.connected_account_id
  )
  # Store devices in your database

Step 3: Understanding Timing with `wait_for_device_creation`

You have two options for when devices/systems become available:

Option A: `wait_for_device_creation=true` (Simpler)

User waits slightly longer in the Connect Webview
When redirect happens, devices/ACS are already synced
You can immediately query and get resources
Best for: Simpler implementations, setup wizards where user waits anyway

Option B: `wait_for_device_creation=false` (Faster Redirect)

User redirects immediately
Must wait for connected_account.completed_first_sync webhook
Then query for resources
Best for: When you want the fastest possible redirect, async workflows

Recommended Webhook Flow (Option B)

# Webhook 1: connected_account.connected
# → Store connected_account_id and customer_key

# Webhook 2: connected_account.completed_first_sync
# → Now query and store devices/ACS systems

Part 3: Complete Code Example

# 1. Create Connect Webview
webview = seam.connect_webviews.create(
  customer_key="property-456",
  wait_for_device_creation=True,  # or False, depending on your UX
  accepted_providers=["salto", "yale", "august"]
)

# 2. User completes the flow, you receive webhook or redirect

# 3. Detect and sync resources
def sync_resources(connected_account_id):
  # Try ACS first
  acs_systems = seam.acs.systems.list(
    connected_account_id=connected_account_id
  )
  
  if acs_systems:
    for system in acs_systems:
      entrances = seam.acs.entrances.list(
        acs_system_id=system.acs_system_id
      )
      store_entrances_in_db(entrances)
  else:
    # It's smart lock devices
    devices = seam.devices.list(
      connected_account_id=connected_account_id
    )
    store_devices_in_db(devices)

# 4. Later: retrieve all accounts for a customer
accounts = seam.connected_accounts.list(customer_key="property-456")

Troubleshooting

Q: Should I use `customer_key` or `custom_metadata` for my customer ID?

A: Use customer_key. It's designed specifically for linking to your customers and enables direct retrieval via connected_accounts.list(customer_key=...).

Q: When are devices/systems available to query?

A: If wait_for_device_creation=true, immediately after redirect. If false, wait for the connected_account.completed_first_sync webhook.

Q: Can one customer have multiple Connected Accounts?

A: Yes! A hotel property might connect multiple systems (e.g., Salto for guest rooms + Yale smart locks for amenity areas). Use customer_key to retrieve all of them.