iCal feeds

VIVIN publishes a read-only iCalendar (.ics) feed for every unit, so Airbnb, Booking.com, channel managers and calendar apps block the nights that are taken in VIVIN.

Before you start

Item	Value
Base URL	https://api.vivin.app/ical-integration
Authentication	None. The unit ID in the URL is the only protection: anyone with the link can read the unit's blocked dates and event titles
Content	Dates and event titles only: no rent, fees, tenant details or booking windows. For those, use the JSON listing feed
Freshness	Built again on every request. How often a subscriber sees changes depends on its own refresh schedule
Where landlords find it	Sales → Channel Manager in the management app (https://platform.vivin.app/sales/channels)

Get a unit's feed URL

Landlords copy the URL from VIVIN; partners rarely build it themselves.

• One unit: in Sales → Channel Manager, click the Copy iCal icon in the actions column of the unit's row.
• Many units: click Export on the same tab and choose CSV or Excel. The file has a VIVIN iCal column with one URL per unit in the current filter.
• During Airbnb or Booking.com setup: step 2 of the setup window shows the same link (Two-way sync).

Retrieve a calendar

Method	Path	Notes
GET	/ical-integration/listings/{listingId}/iCal	Main route
GET	/ical-integration/listings/{listingId}/iCal.ics	Same response. The links VIVIN copies use this form

Path parameters

Name	Type	Required	Description
listingId	string, UUID	Yes	The unit's VIVIN ID. Not the ID a channel uses for the unit (Property and unit mapping). The interactive reference names it externalId

Request headers

No header is required. Three optional headers tell VIVIN who is reading the feed (Retrofeed):

Header	Used for
Origin	An Airbnb or Booking.com host
Referer	Same as Origin
User-Agent	When neither of the above identifies the platform

Example request

curl https://api.vivin.app/ical-integration/listings/550e8400-e29b-41d4-a716-446655440000/iCal.ics

The interactive reference is at https://api.vivin.app/ical-integration, and the OpenAPI file at https://api.vivin.app/ical-integration-json.

Response

200 OK with these headers and a standard iCalendar document, one VEVENT per block:

Header	Value
Content-Type	text/calendar
Content-Disposition	attachment; filename="calendar.ics"

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//vivin.app//ical//EN
BEGIN:VEVENT
UID:9b2f6c1e-4a7d-4c1b-8f3e-2d5a6b7c8d90
SEQUENCE:0
DTSTAMP:20260926T090000Z
DTSTART:20260501T000000Z
DTEND:20260901T000000Z
SUMMARY:Booked
END:VEVENT
BEGIN:VEVENT
UID:550e8400-e29b-41d4-a716-446655440000
SEQUENCE:0
DTSTAMP:20260926T090000Z
DTSTART:20270301T000000Z
DTEND:20280926T000000Z
SUMMARY:Security lock
END:VEVENT
END:VCALENDAR

Block in VIVIN	SUMMARY
A booking	Booked
A manual block	The Reason typed on the block (empty if none)
A block imported from a channel's calendar	The title that channel sent (Airbnb reservations arrive as Reserved, for example)
The export horizon (below)	Security lock

• UID is the block's VIVIN ID. The Security lock event uses the unit's ID.
• DTSTART and DTEND are midnight UTC timestamps (20260501T000000Z), not all-day VALUE=DATE values. Read them as dates.
• The feed lists every block of the unit, past ones included. A block deleted in VIVIN, or a booking that is cancelled, disappears from the next fetch.

Errors

A failed request answers JSON, not a calendar, with the standard error body.

Status	message	Cause	What to do
400	Validation failed (uuid is expected)	listingId is not a UUID	Use the VIVIN unit ID. Copy the link again with Copy iCal
404	Listing not available	No unit has that ID, or the unit was deleted	Ask the landlord for the current link
500	Internal server error	An unexpected problem on VIVIN's side	Retry later

{
  "statusCode": 404,
  "message": "Listing not available",
  "error": "NotFoundException"
}

End dates are exclusive

DTEND is the first free day, not the last blocked night. Calendar apps read it as the morning the unit is free again, so the last night stays blocked.

• Manual and imported blocks: VIVIN stores the last blocked night, which is the inclusive to of the JSON feeds. For a manual block, that is the To date in Audit → Manual blocks; the block's Edit block dialog shows the next day, when the unit is free again. DTEND is that last night plus one day.
• Bookings: DTSTART is the check-in date and DTEND the check-out date. With preparation days (Settings → Global Settings → Booking Defaults: Short-term Prep for Airbnb and Booking.com bookings, Mid-term Prep for the others), DTEND moves that many days later, so the unit stays blocked while it is prepared.

Meaning (a manual block from 1 May to 31 August)	Date
First blocked night (DTSTART)	1 May 2026
Last blocked night (To in Audit → Manual blocks, JSON to)	31 August 2026
DTEND, the first free morning	1 September 2026

Do not treat DTEND as a blocked night

Block the nights from DTSTART up to the day before DTEND. Copying DTEND into an inclusive "last night" field blocks one extra night.

When VIVIN imports an Airbnb or Booking.com calendar, it reads the platform's end date the same exclusive way, so the imported block ends on the platform's last booked night, plus any Short-term Prep days.

Retrofeed: Airbnb and Booking.com

Airbnb must not get its own reservations back from VIVIN as blocks, and neither must Booking.com. When VIVIN recognises the subscriber, it leaves out the blocks whose source is that platform: the blocks imported from its calendar and the bookings that came from it.

VIVIN identifies the subscriber in this order:

1. Origin or Referer: a host on an Airbnb domain (for example www.airbnb.com), or booking.com or any of its subdomains.
2. User-Agent, when neither identifies the platform: it contains airbnb or booking.com, in any letter case.

Subscriber	Feed contents
Airbnb	Every block except those whose source is Airbnb
Booking.com	Every block except those whose source is Booking.com
Anyone else (calendar apps, other channel managers, scripts)	Every block

How far ahead the feed goes

A landlord can stop the feed from offering dates beyond a cutoff. With a cutoff, the feed adds one Security lock event from the cutoff date to two years from today, so the cutoff day and everything after it show as blocked. A cutoff in the past blocks every future date. With no cutoff, there is no Security lock event.

Cutoff	Where it is set	Priority
Unit	The unit's Short Term Max date (Portfolio → Listings → the unit → Setup → Unit Information). Apply to all listings (Airbnb and Booking.com cards) and Apply to selected listings (Airbnb card) copy the account date onto units	1
Property	Not shown in the app. It applies to the property's units that have no date of their own	2
Account	Settings → Integrations → Channel Manager → Short-term iCal Max Date. The Airbnb and Booking.com cards under Booking Platforms show the same value as Short Term Max Date	3

If a subscriber reports that everything is blocked from a certain month on, check these dates first. If none of them explains a Security lock, contact VIVIN.

Two-way sync with Airbnb and Booking.com

You can connect both directions for one unit: VIVIN imports the platform's calendar, and the platform subscribes to VIVIN's feed. The Airbnb and Booking.com columns appear in Sales → Channel Manager only while that platform is switched on under Settings → Integrations → Booking Platforms.

1. In Sales → Channel Manager, click the unit's Airbnb or Booking.com cell.
2. Paste the platform's private calendar link (the platform's "Step 1") and click Integrate.
3. Click Copy next to VIVIN's link. On the platform, add it as the calendar to import ("Step 2") and name it "Vivin Calendar".
4. Click Sync to import the platform's blocks now.

After setup, VIVIN reads the platform's calendar again every 30 minutes. To pull changes sooner, reopen the cell and click Sync; the window then shows the platform's link, and VIVIN's own link stays under Copy iCal.

From	What VIVIN imports
Airbnb	Only events titled Reserved or Closed. Other Airbnb blocks are skipped
Booking.com	Every event. If the link is a Hostify calendar, blocks longer than three months are skipped

Imported blocks show on the unit's calendar (as Airbnb Guest or Booking.com Guest), in Sales → Multicalendar, and as short-term arrivals and departures in Operations → Check-in/out. They block the dates but create no booking, contract or payment plan. If the property has automatic tickets set up, VIVIN creates them for imported blocks too.

Some accounts also have an Airbnb or Booking.com account connected under Settings → Integrations. For those, the cell first asks how the unit should sync: Full integration, Calendar link (iCal) or No integration. A unit uses either the full integration or a calendar link for a platform, never both. Switching to Full integration deletes the calendar link and the blocks it imported, and cannot be undone.

Limits

• No authentication and no rate limit: fetch as often as your calendar needs.
• The feed is always current, so there is nothing to retry except a 500 or a dropped connection.

Troubleshooting

Symptom	Likely cause and fix
A block seems to end one day late	Expected: DTEND is the first free morning, and VIVIN's end date is the last blocked night. Preparation days also extend bookings
Airbnb does not show its own reservations in VIVIN's feed	The retrofeed working as designed. Other subscribers still get them
A subscriber shows the same stay twice	It imports both VIVIN's feed and the platform's own calendar. Keep one source per platform
Block reasons are visible to the public	The Reason of a manual block becomes the event title, and anyone with the link can read it. Keep reasons neutral
400 or 404 for a unit that exists	The URL has a channel's listing ID or a mistyped ID instead of the VIVIN unit ID. Copy it again with Copy iCal
Everything is blocked from one date on	A Security lock cutoff (How far ahead the feed goes)

Related

• Listings and availability: JSON feeds with rent, rules and blocks
• Property and unit mapping: VIVIN unit IDs and channel IDs
• Error handling: the shared error format
• Sales: the Channel Manager and Multicalendar tabs
• Integrations settings: booking platforms and Short-term iCal Max Date