Skip to main content

Listings & Availability

First-time workspace setup

Poll GET /listings only after Getting Started — Recommended Setup Sequence steps 11–13 — connect channels on Settings > Integrations, align payload fields in Integration field capability, set Tenant categories default for integrations, then finish the Listings property wizard with externalId on each unit’s Channels tab (Property & Unit Mapping). Complete steps 14–15 and Onboarding a New Property — Step 7 before you treat partial pulls as production truth. Guide pairing after go-live: Setup sequence after go-live (hub: API Reference — Setup sequence after go-live).

Finding your way in this guide

Start with Get All Listings and Field Reference for partial payload shapes, then Sync Strategy for polling cadence. Catalogue publishers also need Full listing feeds; calendar-only subscribers should read iCal feeds instead. Confirm externalId in Property & Unit Mapping before Creating Bookings. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Handling a Late Payment collections, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Listings & Availability section cross-reference · API Reference — API guide cross-reference.

Use these endpoints to retrieve all listings associated with your integration, including real-time pricing, availability windows, and calendar blocks. This data should be polled periodically to keep your platform synchronised with Vivin.

Partial feed

This page documents the partial listing pull (GET /{platform}-integration/listings and GET /{platform}-integration/listings/:externalId) — the shared calendar/pricing/booking shape. For partner-shaped full publish feeds (GET /{platform}-integration/:landlordKey/listings/full), see Full listing feeds and API Reference — Partial vs full integration feeds.

Housing Anywhere partial rows extend ListingDto with a costs array — see Full listing feeds — HA partial. iCal calendar export is a separate module — iCal feeds.

Partial-only prefixes (Channex, RoomLess, Erasmus Life Lisboa, iCal, Vivin Booking Engine) are listed in API Reference — Partial-only integrations.

Exercise the same calls in Swagger

Use your integration’s OpenAPI page on the API host to run authenticated GET listing requests interactively — see API Reference — Try requests in Swagger.

Get All Listings​

Pair with other Listings & Availability sections

Authorize with Authentication before your first GET /listings call. Catalogue publishers contrast with Full listing feeds; calendar-only partners use iCal feeds instead. Full endpoint map: Listings & Availability section cross-reference.

Retrieve all active listings published to your integration platform.

GET /{platform}-integration/listings HTTP/1.1
Host: api.vivin.app
Authorization: Bearer YOUR_API_KEY

Response​

[
  {
    "externalId": "abc-123",
    "availableFrom": "2026-05-01T00:00:00.000Z",
    "minStayPeriod": 1,
    "maxStayPeriod": 12,
    "isRentFixed": false,
    "rent": 850.0,
    "capacity": 2,
    "extraPricePerTenant": 100.0,
    "cleaningFeeValue": 75.0,
    "billsIncluded": true,
    "billsIncludedMaxValue": 50.0,
    "adminFeeValue": 250.0,
    "depositValue": 850.0,
    "landlordEmail": "[email protected]",
    "rentsPerMonth": [
      { "month": 1, "rent": 750.0 },
      { "month": 2, "rent": 750.0 },
      { "month": 3, "rent": 800.0 },
      { "month": 4, "rent": 850.0 },
      { "month": 5, "rent": 900.0 },
      { "month": 6, "rent": 950.0 },
      { "month": 7, "rent": 1000.0 },
      { "month": 8, "rent": 1000.0 },
      { "month": 9, "rent": 950.0 },
      { "month": 10, "rent": 850.0 },
      { "month": 11, "rent": 800.0 },
      { "month": 12, "rent": 750.0 }
    ],
    "unavailabilities": [
      {
        "from": "2026-05-01T00:00:00.000Z",
        "to": "2026-08-31T00:00:00.000Z",
        "reason": "booked"
      }
    ],
    "bookingWindows": [
      {
        "minStartDate": "2026-09-01T00:00:00.000Z",
        "maxStartDate": "2026-12-31T00:00:00.000Z",
        "minEndDate": "2026-10-01T00:00:00.000Z",
        "maxEndDate": "2027-08-31T00:00:00.000Z"
      }
    ],
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2026-04-19T14:22:00.000Z"
  }
]

Full pairing matrix: Listings & Availability section cross-reference.

Get Single Listing​

Pair with other Listings & Availability sections

Use Integration Swagger to exercise the path-parameter variant — see the capture below and Try requests in Swagger. Confirm the returned externalId against Property & Unit Mapping before POST /bookings. Full endpoint map: Listings & Availability section cross-reference.

Retrieve a specific listing by its external ID.

GET /{platform}-integration/listings/{externalId} HTTP/1.1
Host: api.vivin.app
Authorization: Bearer YOUR_API_KEY

In Swagger, the single-listing operation is the one that takes your platform’s externalId as a path parameter — expand it, fill the path value, and execute after you have authorized with the same key you use in HTTP.

Integration Swagger — GET listing by external id path parameter and Try it out

Response​

Returns a single listing object (same schema as above).

Full pairing matrix: Listings & Availability section cross-reference.

Field Reference​

Pair with other Listings & Availability sections

billsIncludedMaxValue ties to operator Listings — Step 3 Extra payments and monthly Utilities overage. unavailabilities must align before Creating Bookings enqueue. Full endpoint map: Listings & Availability section cross-reference.

Listing Object​

FieldTypeDescription
externalIdstringThe unique identifier for this listing on your platform. This is the ID you provided during the mapping setup.
availableFromstring (ISO 8601)The earliest date this listing is available for move-in.
minStayPeriodintegerMinimum stay duration in months.
maxStayPeriodintegerMaximum stay duration in months.
isRentFixedbooleanIf true, the rent field contains the fixed monthly rent. If false, pricing varies by month - use rentsPerMonth.
rentnumberMonthly rent in EUR. When isRentFixed is false, this is the base/default rent.
capacityintegerMaximum number of tenants the listing can accommodate.
extraPricePerTenantnumberAdditional monthly charge (EUR) for each tenant beyond the first.
cleaningFeeValuenumberOne-time cleaning fee (EUR) charged at booking.
billsIncludedbooleanWhether utility bills are included in the rent.
billsIncludedMaxValuenumberMaximum monthly amount (EUR) of included bills. If actual bills exceed this, the tenant pays the difference. 0 or null means unlimited.
adminFeeValuenumberOne-time administrative fee (EUR) charged at booking confirmation.
depositValuenumberSecurity deposit amount (EUR).
landlordEmailstringEmail of the property manager managing this listing.
rentsPerMonthRentPerMonth[]Month-by-month pricing (see below). Only relevant when isRentFixed is false.
unavailabilitiesUnavailability[]Date ranges when the listing is not available (see below).
bookingWindowsBookingWindow[]Allowed check-in/check-out date ranges (see below).
createdAtstring (ISO 8601)When the listing was first created in Vivin.
updatedAtstring (ISO 8601)When the listing was last modified. Use this for incremental sync.

RentPerMonth Object​

Seasonal or variable pricing. Each entry specifies the rent for a specific calendar month.

FieldTypeDescription
monthinteger (1-12)Calendar month (1 = January, 12 = December).
rentnumberMonthly rent (EUR) for that month.

How to calculate a stay's total rent: For a booking spanning multiple months, sum the rent value for each calendar month covered. For partial months, pro-rate based on the number of days.

Unavailability Object​

Represents a date range when the listing cannot be booked.

FieldTypeDescription
fromstring (ISO 8601)Start of unavailable period (inclusive).
tostring (ISO 8601)End of unavailable period (inclusive).
reasonstringReason for the block (e.g. "booked", "maintenance", "owner_block").
Calendar blocks

Always respect unavailabilities when showing availability on your platform. These reflect confirmed bookings and manual blocks across all connected channels. Ignoring them may result in double-bookings, which will cause the booking submission to fail.

BookingWindow Object​

Defines the allowed date ranges for new bookings. If present, only bookings with check-in/check-out dates within these windows will be accepted.

FieldTypeDescription
minStartDatestring (ISO 8601)Earliest allowed check-in date.
maxStartDatestring (ISO 8601)Latest allowed check-in date.
minEndDatestring (ISO 8601)Earliest allowed check-out date.
maxEndDatestring (ISO 8601)Latest allowed check-out date.

Full pairing matrix: Listings & Availability section cross-reference.

Sync Strategy​

Pair with other Listings & Availability sections

Prefer listing.updated / unavailability.* push events from Webhooks & Notifications when configured instead of aggressive polling. When blocks look stale, operators run Manual block hygiene. Full endpoint map: Listings & Availability section cross-reference.

  • Full sync: Every 15-30 minutes
  • Incremental sync: Compare updatedAt timestamps to detect changes since your last poll

Platform Markup​

Prices returned by the API already include any platform-specific markup configured by the property manager in Vivin. The values you receive are the final prices to display to end users on your platform.

Calendar Block Extension​

Vivin may automatically extend calendar blocks around bookings based on the property manager's configuration (e.g. adding a buffer day before/after each booking for cleaning). These extended blocks are included in the unavailabilities array.

Full pairing matrix: Listings & Availability section cross-reference.

Listings & Availability section cross-reference​

Use this table when one endpoint group naturally leads into operator UI, another API guide, or a downstream workflow — each row links to the docs you should read before or after wiring partial listing pulls.

API topic / sectionPair with these docs
Get All ListingsAuthentication, Full listing feeds (publish catalogue contrast), Property & Unit Mapping
Get Single ListingTry requests in Swagger, Property & Unit Mapping, Creating Bookings (pre-enqueue verify), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1 (post-import collections), Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent)
Field ReferenceListings — Step 3 Extra payments, Utilities module, Booking Lifecycle & Validations
Sync StrategyWebhooks & Notifications, iCal feeds (calendar export contrast), Manual block hygiene

| Lockout catch-up after password recovery | Channel sync backlog after sign-in recovery | Common Workflows — Lockout catch-up, Settings > Integrations, Notification triage | | Pending manual receipt approval | OTA imports with pending confirmation receipts | Common Workflows — Pending manual receipt approval, Creating Bookings, Finance — Pending manual payments | | Reject/revert mistaken receipts | Duplicate imports affecting availability | Common Workflows — Reject/revert mistaken receipts, Manual block hygiene, Payment Allocation — Correcting mistaken receipts | | Portfolio segmentation by tenant category | Segment operator triage on imported stays | Common Workflows — Portfolio segmentation, Bookings — Other filters, Settings > Tenant categories | | Notification row-click navigation | Availability pulls vs alert triage | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | Listed inventory vs overdue alerts | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | New units vs confirmation alerts | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Receivables on listed units | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Integration surface vs operator collections Steps 1–6 | | Finance Income status drill-down | Rent fields vs Income segments | API Reference — Finance Income status drill-down, Common Workflows — Finance Income status drill-down, FAQ — Finance Income status drill-down hub | | Cash flow forecast drill-down | Listed rent vs collections bars | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Listings & Availability guide sections

Related below links partial GET /listings pulls to setup, companion API guides, operator workflows, and escalation paths. Pair Setup sequence after go-live with Getting Started — Recommended Setup Sequence; pair Companion API guides with API Reference hub. Topic-to-guide pairing in sections above: Listings & Availability section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Listings & Availability guide sections

Complete Account Settings — Recommended setup order before partner traffic. Hub parity: API Reference — Setup sequence after go-live. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Documentation map & escalation​

Pair with other Listings & Availability guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Full pairing matrix: Listings & Availability section cross-reference.

Companion API guides​

Pair with other Listings & Availability guide sections

Companion guides share Bearer authorization or error shapes with this page — start from API Reference hub. Full pairing matrix: Listings & Availability section cross-reference.

Upstream & downstream workflows​

Pair with other Listings & Availability guide sections

Workflow bullets pair with Common Workflows — Workflow cross-reference after partner traffic lands in the management app. Full pairing matrix: Listings & Availability section cross-reference.

Operator UI & settings​

Pair with other Listings & Availability guide sections

Operator UI rows validate the same inventory and permissions behind integration HTTP — pair with Account Settings — Tab cross-reference. Full pairing matrix: Listings & Availability section cross-reference.

Deeper concept reads​

Pair with other Listings & Availability guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Deeper workflow reads​

Pair with other Listings & Availability guide sections

Workflow reads pair with Common Workflows hub subsection index and Workflow cross-reference. Each workflow sub-guide also has its own Deeper API reads subsection with reciprocal companion API anchors — hub parity: API Reference — Deeper workflow reads. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Listings & Availability guide sections

Partial GET /listings polling may continue during operator lockout — reconcile UI channel alerts after sign-in recovery. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: listings--availability-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Listings & Availability guide sections

Availability pulls do not surface receipt state — pair with Finance — Pending manual payments when OTA imports await approval. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: listings--availability-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Listings & Availability guide sections

Stale unavailabilities from duplicate imports may need operator receipt cleanup — pair with Manual block hygiene. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: listings--availability-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Listings & Availability guide sections

Partial listing pulls are account-wide — segment operator triage with Bookings — Other filters Tenant category. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: listings--availability-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Listings & Availability guide sections

Partial GET /listings pulls do not replace /notifications row-click — operators triage import alerts after availability sync. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Listings & Availability guide sections

Listed units with unpaid imported schedules surface payment overdue — row-click from alerts into booking Transactions. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Listings & Availability guide sections

First availability on newly mapped units pairs with Upcoming Booking created alert triage after externalId verification. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Listings & Availability guide sections

Availability reads inform occupancy — receivables triage stays on Finance → Overview → Debt Aging after alert row-click. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner integration reads on Listings Availability do not replace operator collections — payment overdue in-app rows still need Handling a Late Payment — Steps 1–6 after receivables triage. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: listings-availability-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Listings & Availability guide sections

Rent and cap fields on listings shape Income → Scheduled after imports — segment-click reconcile before month-end KPI sign-off. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Listings & Availability guide sections

Approved collections on imported stays appear on Cash flow forecast bars — distinct from availability updatedAt polling. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Listings & Availability section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Listings & Availability guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Listings & Availability section cross-reference.

Module documentation hubs​

Pair with other Listings & Availability guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen operator follow-up. Full pairing matrix: Listings & Availability section cross-reference.

  • Audit module — Cross-portfolio manual blocks that appear in unavailabilities alongside bookings (hub)
  • Bookings module — Imported stays that consume unavailabilities windows from partial pulls (hub)
  • Dashboard — Vacant Units — KPI signal when blocks in partial pulls suppress vacancy counts (hub)
  • Analytics — Overview tab — KPI reconciliation after partial-pull occupancy changes (hub)
  • Utilities module — Operator bill entry and tenant overage when actual supplier costs exceed billsIncludedMaxValue from partial pulls (hub)
  • Operations module — Maintenance tickets, cash flows, check-in/out coordination, Draft ticket queues, and linked cash flows (hub)
  • Dashboard module — Post-login Today, Total debt, Vacant Units, and forecast KPI snapshot with bell notification triage (hub)
  • Analytics module — Month-range portfolio KPI charts (Overview, Revenue, Occupancy, ADR, RevPAR, Maintenance) with rankings and heatmaps (hub)
  • Listings module — Property wizard, Channels tab, Archived inventory, and unit management (hub)
  • Properties workspace — Legacy /properties URL redirects into Listings (hub)
  • Booking engine details — Rich marketplace payload editor via the Full integration pill (hub)
  • Finance module — Portfolio ledgers (Overview, Income, Contract Values, Transactions, Payouts, Deposits) with payment approval and deposit settlement (hub)
  • Tenants module — Tenant directory, profile sidebars, With Debt segmentation, and table expand for linked bookings (hub)
  • Sales module — Portfolio availability, monthly rent editing, and channel manager connections (hub)
  • Inbox module — Portfolio-wide WhatsApp workspace with Dashboard bell Inbox sub-tab deep links (hub)
  • Notifications module — Full /notifications history with search, filters, and row-click navigation (hub); Payment overdue alerts when partner imports leave unpaid schedules
  • AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools for portfolio Q&A (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)