Setting Up Customer Connections with Connect Webviews

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.

TextCopy
1# Creating a Connect Webview for a specific customer
2webview = seam.connect_webviews.create(
3  customer_key="property-456",  # Your internal property ID
4  accepted_providers=["salto", "assa_abloy_visionline"]
5)
6
7# Later: retrieve all accounts for this customer
8accounts = seam.connected_accounts.list(
9  customer_key="property-456"
10)

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:

TextCopy
1# Check for ACS systems
2acs_systems = seam.acs.systems.list(
3  connected_account_id=account.connected_account_id
4)
5
6if acs_systems:
7  # It's an ACS - get entrances
8  for system in acs_systems:
9    entrances = seam.acs.entrances.list(
10      acs_system_id=system.acs_system_id
11    )
12    # Store entrances in your database
13else:
14  # It's smart locks - get devices
15  devices = seam.devices.list(
16    connected_account_id=account.connected_account_id
17  )
18  # 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)

TextCopy
1# Webhook 1: connected_account.connected
2# → Store connected_account_id and customer_key
3
4# Webhook 2: connected_account.completed_first_sync
5# → Now query and store devices/ACS systems

---

Part 3: Complete Code Example

TextCopy
1# 1. Create Connect Webview
2webview = seam.connect_webviews.create(
3  customer_key="property-456",
4  wait_for_device_creation=True,  # or False, depending on your UX
5  accepted_providers=["salto", "yale", "august"]
6)
7
8# 2. User completes the flow, you receive webhook or redirect
9
10# 3. Detect and sync resources
11def sync_resources(connected_account_id):
12  # Try ACS first
13  acs_systems = seam.acs.systems.list(
14    connected_account_id=connected_account_id
15  )
16  
17  if acs_systems:
18    for system in acs_systems:
19      entrances = seam.acs.entrances.list(
20        acs_system_id=system.acs_system_id
21      )
22      store_entrances_in_db(entrances)
23  else:
24    # It's smart lock devices
25    devices = seam.devices.list(
26      connected_account_id=connected_account_id
27    )
28    store_devices_in_db(devices)
29
30# 4. Later: retrieve all accounts for a customer
31accounts = 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.

---

Related Resources

• Connect Webviews

• Connected Accounts

• Mapping Your Hotel PMS Resources to Seam