iCal Sync Help
Overview
The iCal Sync tab lets you connect reservation calendars from Airbnb, Booking.com, and other OTAs to automatically import guest reservations into UnlockOS. Each iCal feed is linked to a specific room in your facility. An initial sync runs automatically the moment a feed is registered, and recurring automatic syncs continue after that. Imported reservations appear in the Reservations list and Calendar.
What you can do on this tab:
- Register an iCal feed URL and link it to a room (an initial sync runs immediately on registration)
- View all registered feeds and their sync status
- Trigger an immediate manual sync
- Edit a feed's URL to safely swap the calendar without creating duplicate reservations
- Switch the matching mode between guest self-verification and host-managed check-in
- Find the guest check-in URLs in the Check-in tab (Booking Management)
- Use the email forwarding address to import reservations from confirmation emails
How to Access
Booking Management Dashboard → iCal Sync tab
Or navigate directly with the URL parameter: ?tab=ical
Features
Feature 1: Adding an iCal Feed
To register a new iCal feed:
- Copy the iCal export URL from your OTA (e.g. Airbnb, Booking.com).
- Paste it into the iCal URL field.
- Select the Room this feed corresponds to from the dropdown (you can type to search the room list).
- Click Add Feed.
After the feed is added, an initial sync runs automatically. Once sync completes, any imported reservations appear in your Reservations list. A green success banner appears with a Go to Check-in Tab button — click it to navigate directly to the Check-in tab, where you can copy the check-in URL to share with guests.
Both the iCal URL and a room selection are required. The Add Feed button is disabled until both are filled in.
Large calendars (such as a detailed Google Calendar with years of history) are handled safely. The initial sync only processes events within a window of roughly one week ago to three months ahead, so even calendars with thousands of past events complete in a predictable time.
Feature 2: Registered Feeds Table
All registered feeds appear in a table (or cards on mobile). Each row shows:
| Column | Description |
|---|---|
| Feed URL | The registered iCal URL (truncated; hover to see the full URL) |
| Room | The room this feed is linked to |
| Last Sync | Timestamp of the most recent sync |
| Events | Number of reservations imported in the last sync |
| Status | Sync result: Synced, Error, or Pending |
| Matching | The current matching mode for this feed (change in the Check-in tab) |
| Actions | Sync, Edit URL, and Delete buttons |
Sync Status Indicators
| Status | Meaning |
|---|---|
| Synced | The last sync completed successfully |
| Error | The last sync encountered an error; hover the badge to see the error message |
| Pending | This feed has not been synced yet |
Feature 3: Manual Sync
To sync a feed immediately, click the circular arrow (sync) button on the right side of a feed row. The icon spins while the sync is running. When complete, the Last Sync timestamp and Events count update.
Feature 4: Deleting a Feed
Click the Delete (X) button on a feed row. A confirmation modal appears — click Delete to confirm removal. After deletion:
- Automatic syncing stops for that feed.
- Reservations imported from this feed that are in "pending" or "confirmed" status are cancelled. Already checked-in, completed, or already-cancelled reservations are unaffected.
If you want to change the calendar URL (for example because your OTA generated a new one), use Edit URL instead of deleting. Editing the URL updates existing reservations in place with no cancellations and no duplicate bookings (see Feature 5 below).
Feature 5: Editing a Feed URL (Double-Booking-Safe Swap)
When your OTA calendar URL changes, you can safely update it without touching existing reservations.
Click the Edit URL (pencil icon) button on a feed row. Enter the new URL in the modal and click Save.
What happens:
- The feed ID does not change, so existing reservations are matched by their feed-ID + event-UID key and updated in place rather than re-imported as new reservations.
- No duplicate or double-booking conflicts are created.
- A re-sync runs automatically at the time of the URL save, reflecting the new calendar content immediately.
If you delete a feed and re-add the URL as a new feed, a new feed ID is issued and the old reservations are not linked to it — the same reservations will be imported again, creating duplicates. Always use Edit URL to change a calendar URL.
Feature 6: Importing OTA Event Titles and Notes
When a feed is synced, iCal event fields are imported into the reservation record.
| iCal field | Where it appears in UnlockOS |
|---|---|
| SUMMARY (event title) | Imported as the guest name (generic text such as "Busy" is excluded) |
| DESCRIPTION (event notes) | Shown in the Notes field of reservation detail |
| LOCATION (location) | Appended to Notes as "📍 location name" |
Imported notes appear in the reservation detail view (accessible from the Reservations list). Notes that contain line breaks are displayed with correct formatting across multiple lines.
Once the host manually edits a reservation (marked internally as host-edited), later automatic syncs preserve the host's changes — the guest name and notes are protected and only the check-in / check-out dates are updated from the iCal feed. For reservations the host has not edited, each sync overwrites the guest name and notes with the latest iCal content.
Feature 7: Copying Check-in URLs
Guest-facing check-in URLs are found in the Check-in tab of the Booking Management dashboard. Each iCal feed appears there as a URL card with a copy button.
The check-in URL format:
https://checkin.unlockos.io/{slug}?configId=...&mode=reservation-search
Share this URL with guests via your OTA Arrival Guide, email, or a QR code at your property.
Feature 8: Matching Mode
Each feed's matching mode can be changed in the Check-in tab. The iCal Sync tab shows the current mode on each feed row — clicking the mode badge navigates you to the Check-in tab.
| Mode | Label | Description |
|---|---|---|
| Guest verification | Screenshot | Guests check in by uploading a screenshot or forwarding their OTA confirmation email |
| Host managed | Code/Name | The host enters a confirmation code and guest name in the reservation detail; guests check in using that code or name |
When Host managed mode is active on mobile, an info banner reminds you to enter confirmation codes and guest names in reservation details.
Feature 9: Email Forwarding
As an alternative to iCal URLs, you can forward OTA confirmation emails to your facility's dedicated forwarding address. UnlockOS will parse the email and import the reservation automatically.
- Find your forwarding address in the Email Forwarding section at the bottom of the tab.
- Click Copy to copy the address to your clipboard.
- Set up email forwarding in your email client, or add the address as a CC/BCC recipient when receiving OTA confirmation emails.
The address format is:
ical+{facility-id}@inbound.unlockos.com
Frequently Asked Questions
Q: What OTA platforms are supported?
Any platform that provides a standard iCal (.ics) export URL is supported. This includes Airbnb, Booking.com, VRBO, and most other major OTAs.
Q: How often are feeds synced automatically?
An initial sync runs immediately when you register a feed. After that, feeds are synced on a recurring schedule managed by UnlockOS (approximately every 30 minutes). To sync immediately at any time, click the sync button on any feed card.
Q: What happens to existing reservations if I delete a feed?
Deleting a feed cancels all "pending" and "confirmed" reservations that were imported from that feed. Already checked-in and completed reservations are not affected. If your goal is to change the calendar URL, use Edit URL instead — it updates existing reservations in place without cancelling them.
Q: My OTA calendar URL changed. What should I do?
Do not delete and re-add the feed. Instead, click the Edit URL (pencil icon) button on the feed row and enter the new URL. The same feed ID is retained so existing reservations are updated in place, with no duplicates and no cancellations.
Q: Why is the Add Feed button disabled?
Both the iCal URL and a room selection are required. Make sure you have selected a room from the dropdown and pasted a valid URL.
Q: There are no rooms in the Room dropdown
Rooms must be created and set as active in the Facility Settings before they appear in this dropdown. Only rooms of service type "room" are shown.
Q: The sync status shows Error
Hover over the Error badge to see the specific error message. Common causes include:
- The iCal URL has expired or changed (copy a fresh URL from your OTA dashboard)
- The OTA temporarily blocked the request (try manual sync again after a few minutes)
- The URL is not a valid iCal feed
Q: A reservation from Airbnb is not appearing
- Click the sync button to trigger an immediate sync.
- Check that the feed status shows "Synced" after the sync completes.
- Confirm the reservation date falls within the visible date range in the Reservations tab.
- If the reservation was recently created on Airbnb, wait a few minutes and sync again.
Q: What is the difference between the two matching modes?
- Screenshot (Guest verification): Guests upload a screenshot of their OTA booking confirmation to prove their identity and receive the access key. No manual host action is required.
- Code/Name (Host managed): You enter a confirmation code and guest name in the reservation detail inside UnlockOS. Guests enter the code or name at the check-in screen to receive the access key. Use this mode when you prefer to control key issuance manually.
Q: Can I use both iCal Sync and Google Calendar read binding for the same room?
No. Connecting the same room's calendar via both iCal Sync and a Google Calendar read binding will import the same reservations twice, creating false double-booking conflicts. Choose exactly one import channel per room. See Google Calendar Integration for details.
Keys for synced reservations
- Each synced reservation receives the key for the room it is assigned to (the room's own smart lock) — not a key from the check-in configuration's unit. In a multi-room property, every guest gets their own room's key.
- The key is issued ahead of time and KEYVOX distributes it to the lock from about 72 hours before check-in, so it is live by the time the guest arrives.
- Synced reservations are free at the kiosk (payment is handled by the booking platform). Selecting a price plan on the assigned check-in configuration does not charge these guests.
- If a feed points at a room that has no smart lock assigned, check-in is refused (no fallback key is issued) so the misconfiguration is visible.