Skip to main content

API Reference

First-time workspace setup

Complete Getting Started — Recommended Setup Sequence (steps 1–12 on Account Settings tabs per Recommended setup order, then steps 13–15 in Listings, Bookings, and Tenants) and Onboarding a New Property — Step 7 go-live verification before you provision partner integrations or poll live listing feeds. Guided walkthrough of settings steps 4–12: Onboarding a New Property. Configure steps 11–12 (Integrations, Integration field capability, Tenant categories default for integrations) before requesting Bearer keys from [email protected]. When sign-in was restored mid-setup, see Getting Started — Lockout catch-up after password recovery. Workflow pairing after go-live: Setup sequence after go-live (hub parity: Introduction — Setup sequence after go-live, Account Settings — Setup sequence after go-live, Common Workflows — Setup sequence after go-live, Modules — Setup sequence after go-live, Concepts — Setup sequence after go-live, Glossary — Setup sequence after go-live, FAQ — Setup sequence after go-live, Support — Setup sequence after go-live).

This section contains the technical documentation for integrating with the Vivin platform via its REST API. It is intended for external partners, channel managers, and third-party platforms that want to:

  • Pull listings with real-time pricing and availability
  • Submit bookings into the Vivin system
  • Map their own property/unit identifiers to Vivin's internal listings

Property managers automating outside the browser should read Management session authentication (Core API JWT + refresh cookie, curl examples, and session sequence) or use Landlord MCP — not the integration Bearer keys below.

For how channels, calendars, and the booking engine fit together in the product (operator-facing), start with Integrations & Distribution. For Webhook terminology and how callbacks differ from polling, see the Glossary entry (it links to Webhooks & notifications).

Finding your way in this section

New partners: Authentication → Listings & Availability → Property & Unit Mapping → Creating Bookings. Catalogue publishers also need Full listing feeds; calendar subscribers need iCal feeds instead of JSON pulls. Hub subsection map: API hub subsection index (integration guides + Related subsections). After first writes, read Booking Lifecycle & Validations and configure Webhooks & Notifications when you want push updates. Tenant-visible behaviour after import: Tenant Portal (including Portal access by tenant category); booking-scoped automation: Tenant MCP. Each sub-guide opens with First-time workspace setup and a Finding your way in this guide tip that points to key sections and companion guides. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Handling a Late Payment collections) have matching Related subsections on every API sub-guide. Full pairing matrix: API guide cross-reference.

Before You Start​

Pair with other API Reference hub sections

Credential requests pair with Try requests in Swagger once you receive your Bearer key. Catalogue publishers need Partial vs full integration feeds before polling GET …/listings/full. Operator automation contrast: Management session authentication (not partner Bearer keys). Full pairing matrix: API guide cross-reference.

To integrate with Vivin you will need:

  1. An API key (Bearer token) issued by the Vivin team
  2. The base URL of the Vivin API environment you are connecting to
  3. Agreement on which external IDs will be used to map your listings to Vivin's

Contact [email protected] to request API credentials and onboarding support.

Try requests in Swagger​

Pair with other API Reference hub sections

Swagger Try it out pairs with Authentication (Authorize dialog) and Listings & Availability (field meanings in JSON). Publish-ingest partners continue to Full listing feeds; calendar subscribers use iCal feeds instead. Full pairing matrix: API guide cross-reference.

Each provisioned integration ships an OpenAPI (Swagger) UI on the same API host you call with your integration API key. These documents stay enabled so partners can inspect paths, models, and Try it out flows. (The internal Core API catalogue at /api may be turned off on some hosts; that is separate from integration Swagger.)

During onboarding, Vivin confirms your base URL and the path prefix for your document (for example https://api.example.com/ical-integration for the iCal integration module). The guides below use the pattern GET /{platform}-integration/listings — substitute the prefix you were given.

Integration Swagger route prefixes​

Each provisioned partner integration exposes its own OpenAPI UI at https://<api-host>/<route-prefix> on the same host you call with your Bearer key. Vivin ships separate documents for these route prefixes (exact access depends on which integration was provisioned for your account):

Route prefixTypical partner / channel
uniplaces-integrationUniplaces
inlife-integrationInlife
roomless-integrationRoomLess
housinganywhere-integrationHousing Anywhere
spotahome-integrationSpotahome
ical-integrationiCal / calendar feeds
vivin-booking-engine-integrationWhite-label booking engine
channex-integrationChannex
erasmus-life-integrationErasmus Life Lisboa

Your onboarding email names the prefix and base URL for your integration only — you do not need every row above. Paths inside each document follow the same shapes described in this section (GET …/listings, POST …/bookings, and platform-specific webhooks where applicable).

  1. Open the Swagger URL in a browser.
  2. Click Authorize, choose the Bearer scheme, and paste your API key (with or without the Bearer prefix, per the form hint).
  3. Expand listings (or the group your integration exposes) and execute the calls you need.

The capture below shows a typical listings group with schema and execute controls — your exact titles and path segments follow your integration slug.

Integration Swagger UI — listings group with schema and Try it out

For listing payloads and field meanings after you receive JSON, continue with Listings & Availability and Creating Bookings.

Partial vs full integration feeds​

Pair with other API Reference hub sections

Transport depth here pairs with Property & Unit Mapping (landlordKey, externalId) and operator Integration field capability (field coverage matrix). Booking import after partial pulls: Creating Bookings → Booking Lifecycle & Validations. Full pairing matrix: API guide cross-reference.

Vivin exposes two depths of outbound listing JSON for major marketplace partners. Both use the same Bearer API key on your provisioned route prefix; they differ in payload shape and use case.

FeedTypical path patternPurpose
PartialGET /{platform}-integration/listings and GET /{platform}-integration/listings/:externalIdCalendar, pricing, availability windows, and booking-oriented fields — the shared ListingDto shape described in Listings & Availability. Poll this for sync and booking import.
FullGET /{platform}-integration/:landlordKey/listings/full (+ single-listing variants where documented)Rich property/listing payload shaped for the partner’s publish feed (descriptions, amenities, photos, partner-specific blocks). Poll when you ingest the complete listing catalogue for listing creation/update on the channel.

landlordKey is the path segment before listings/full. Vivin resolves it to an account by matching either the stored account landlordKey or that account’s integration email for the platform (case-insensitive). Inbound webhooks still require the account landlordKey only. Exact schemas are named in each integration’s Swagger (for example UniplacesFullFeedListingDto, Spotahome full feed models). See Full listing feeds — landlordKey.

Platforms with a full feed in Core API today include Uniplaces, Spotahome, Housing Anywhere, and Inlife. Other route prefixes in the table above may expose partial GET …/listings only. Path patterns, landlordKey, Housing Anywhere costs on the partial feed, and Spotahome’s legacy /listings/feed route are documented in Full listing feeds.

Partial-only integrations (no full publish feed)​

These route prefixes are provisioned for partial listing pulls and booking import using the shared ListingDto shape. They do not expose GET …/:landlordKey/listings/full in Core API today:

Route prefixPartner / channelNotes
channex-integrationChannexPartial GET …/listings + GET …/listings/:externalId; inbound webhooks where provisioned — see your Swagger group
roomless-integrationRoomLessPartial listing pull only
erasmus-life-integrationErasmus Life LisboaPartial listing pull only
ical-integrationiCal / OTA calendarsPer-listing text/calendar export — iCal feeds, not JSON GET /listings
vivin-booking-engine-integrationWhite-label booking enginePartial read surface plus write routes — Booking Engine API

Poll partial feeds on the schedule your integration agreement defines; use Listings & Availability for field meanings and Housing Anywhere costs when your prefix is housinganywhere-integration.

iCal availability export uses a separate module — GET /ical-integration/listings/{listingId}/iCal (no JSON GET /listings). See iCal feeds for retrofeed behaviour, response headers, and operator horizon settings.

The Vivin Booking Engine adds write routes (PUT /listing, POST /property-listing) and GET …/housemates on top of the partial listing + booking surface — see Booking Engine API.

Operator-facing guidance on which payload fields are required per marketplace — and how they map to Listings / Full integration pill — lives in Integration field capabilities and Property & listing details (booking engine). Partial vs full is a transport split; the capability matrix explains field coverage.

Available Guides​

GuideDescription
AuthenticationPartner integration Bearer token on every request
Management sessionOperator Core API sign-in (POST /auth/login, refresh cookie, JWT)
AI usageAccount-scoped LLM token ledger (GET /ai-usage, GET /ai-usage/summary)
MCP OAuthOAuth 2.1 Authorization Server for Claude.ai / ChatGPT MCP connectors
Listings & AvailabilityPartial ListingDto pull — pricing, availability, and calendar blocks
Full listing feedsPartner-shaped publish feeds (Uniplaces, Spotahome, HA, Inlife)
iCal feedsPer-listing text/calendar export and retrofeed
Creating BookingsSubmit a new booking into Vivin
Booking Engine APIWhite-label engine — listing updates, property create, housemates
Property & Unit MappingHow external IDs are mapped to Vivin listings
Booking Lifecycle & ValidationsWhat happens after a booking is submitted and what validations are enforced
Webhooks & NotificationsReceive real-time updates on booking status changes
Error HandlingStandard error responses and how to handle them

API guide cross-reference​

Pair with other API Reference hub sections

Use this table when one integration guide naturally leads into another — each row links to the API guides you should read before or after the primary topic. Pair with individual sub-guide section cross-reference tables for longer matrices and Related subsection anchors (for example Authentication — Companion API guides, Webhooks & Notifications — Upstream & downstream workflows). Setup sequencing: Related — Setup sequence after go-live. Full hub map: the Finding your way tip at the top of this page.

Use this table when one integration guide naturally leads into another — each row links to the API guides you should read before or after the primary topic.

| Guide | Pair with these API guides | | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API hub subsection index | Introduction hub subsection index (platform overview), Getting Started hub subsection index (onboarding sections), Concepts hub subsection index (underlying models), Modules hub subsection index (screen workspaces), Common Workflows hub subsection index (operational procedures), Account Settings hub subsection index (setup tabs), FAQ subsection cross-reference (operator troubleshooting), Glossary deep-dive index (integrator terms), Available Guides (sub-guide table), Partial vs full integration feeds (transport split) | | Authentication | Listings & Availability (first authorized read), Error Handling (401 / 403), Management session (operator JWT — not partner Bearer) — section cross-reference, Setup sequence after go-live | | Management session | Authentication (partner Bearer contrast), AI usage (LLM cost ledger), Error Handling (refresh and session expiry), Tenant Portal (operator vs tenant-facing URLs), Tenant MCP (booking-scoped automation contrast), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent) — section cross-reference, Setup sequence after go-live | | AI usage | Management session (JWT + account_settings.module), Automation & AI — Management AI Assistant (landlord_chat), Automation & AI — AI Invoice Reader (utility_bill_extraction), AI Chat module, Utilities — Bills tab, Error Handling, Glossary — AI usage ledger, Glossary — Deposit lifecycle status — section cross-reference, Setup sequence after go-live, Key glossary terms | | MCP OAuth | Landlord MCP — Connector OAuth (operator narrative), AI / MCP — Connector OAuth (settings UI), Management session (browser login contrast), Error Handling (access_denied on refresh) — section cross-reference, Setup sequence after go-live | | Listings & Availability | Full listing feeds (publish catalogue vs partial pull), Property & Unit Mapping (externalId keys), iCal feeds (calendar export instead of JSON) — section cross-reference, Setup sequence after go-live | | Full listing feeds | Listings & Availability (partial sync and booking import), Property & Unit Mapping (landlordKey and externalId), Webhooks & Notifications (listing.updated) — section cross-reference, Setup sequence after go-live | | iCal feeds | Listings & Availability (JSON partial pull contrast), Property & Unit Mapping (per-listing UUID in feed URLs) — section cross-reference, Setup sequence after go-live | | Creating Bookings | Property & Unit Mapping (externalId on POST /bookings), Booking Lifecycle & Validations (enqueue pipeline), Error Handling (validation 400s), Settings > Tenant categories (default for integration-created tenants), Glossary — Tenant category, Tenant Portal (portal credentials and payment schedules after import), Tenant MCP (booking-scoped automation), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent) — section cross-reference, Setup sequence after go-live | | Booking Engine API | Listings & Availability (partial read), Creating Bookings (POST /bookings), Property & Unit Mapping (write routes and externalId), Settings > Tenant categories (engine-created tenant segments), Glossary — Tenant category, Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent) — section cross-reference, Setup sequence after go-live | | Property & Unit Mapping | Listings & Availability (confirm externalId in GET /listings), Creating Bookings (booking create lookup), Full listing feeds (landlordKey scoping) — section cross-reference, Setup sequence after go-live | | Booking Lifecycle & Validations | Creating Bookings (201 enqueue vs final booking), Webhooks & Notifications (booking.* events), Error Handling (async validation failures), Settings > Tenant categories (integration-created tenant segments), Glossary — Tenant category, Booking lifecycle (computed UI statuses), Tenant Portal (tenant-visible lifecycle and payments), Tenant MCP (booking-scoped automation), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent) — section cross-reference, Setup sequence after go-live | | Webhooks & Notifications | Booking Lifecycle & Validations (event timing vs enqueue), Listings & Availability (listing.updated / unavailability.* payloads), Authentication (inbound webhook signing), Settings > Tenant categories (default for integrations on booking.* imports), Glossary — Tenant category, Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent) — section cross-reference, Setup sequence after go-live | | Error Handling | Authentication (401 / 403), Booking Lifecycle & Validations (business-rule 400s), Creating Bookings (retry policy on enqueue), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent) — section cross-reference, Setup sequence after go-live | | Setup sequence after go-live | Getting Started — Recommended Setup Sequence (steps 1–15), Onboarding a New Property — Step 7, Support — Setup sequence escalation, FAQ — Settings & tenant communications, Onboarding a New Property (guided steps 4–12) | | Documentation map & escalation | Introduction — Section cross-reference, FAQ — Section cross-reference, Support — Section cross-reference, Common Workflows section cross-reference, Using in-app support | | Navigation & bookmarks | Management session authentication, Management Frontend Deep Links, Create New menu, Try requests in Swagger | | Settings & payload editors | Integration field capabilities, Settings > Integrations, Settings > Tenant categories, Property & listing details (booking engine) | | Deeper concept reads | Integrations & Distribution, Landlord MCP · Tenant MCP, Booking lifecycle, Payment Allocation; reciprocal Deeper API reads anchors on concept sub-guides | | Deeper workflow reads | Common Workflows — Workflow cross-reference, Common Workflows — Deeper API reads; reciprocal Deeper workflow reads anchors on API Reference sub-guides | | Recommended operator workflows | Common Workflows — Workflow cross-reference, Onboarding a New Property, Processing a New Booking, Portfolio KPI review | | Lockout catch-up after password recovery | Sign-in restored after password reset; onboarding, alert, or month-end backlog accumulated during lockout | Common Workflows — Lockout catch-up after password recovery, Getting Started — Lockout catch-up after password recovery, Resetting a Management User Password | | Lockout catch-up after password recovery | Operational backlog mesh after sign-in recovery | Common Workflows — Lockout catch-up after password recovery, Getting Started — Lockout catch-up after password recovery, Resetting a Management User Password — Step 3 | | Walkthrough media | MP4 walkthroughs beside PNG screenshots | Common Workflows — Walkthrough media, Modules, Account Settings | | Notification row-click navigation | /notifications row-click before operator validates imported bookings | Common Workflows — Notification row-click navigation, Webhooks & Notifications (in-app rows after booking.* events), Notification triage, Glossary — Notification row navigation | | Payment alert to receivables triage | payment overdue in-app rows after partner import or webhook | Common Workflows — Payment alert to receivables triage, Processing a New Booking, Handling a Late Payment — Step 1, Notifications — Payment overdue alerts | | Finance debt receivables triage | Portfolio Top debtors after partner import alert triage | Common Workflows — Finance debt receivables triage, Finance module, FAQ — Finance debt receivables triage hub, Pending manual receipt approval, Handling a Late Payment collections (Steps 1–6 after triage surfaces) | | Handling a Late Payment collections | Partner imports / webhooks → operator Steps 1–6 collections follow-through | Common Workflows — Handling a Late Payment collections hub, Creating Bookings, Payment alert to receivables triage, Finance debt receivables triage, FAQ — Handling a Late Payment collections hub | | Finance Income status drill-down | Partner imports that skew Income Scheduled segments — reconcile before month-end sign-off | Common Workflows — Finance Income status drill-down, Creating Bookings, FAQ — Finance Income status drill-down hub (finance-overview-income-status-in-debt-modal.png, finance-overview-income-drill-down-flow.mp4) | | Cash flow forecast drill-down | Import-driven collections lag on Cash flow forecast month bars | Common Workflows — Cash flow forecast drill-down, Finance Income status drill-down, FAQ — Cash flow forecast drill-down hub (finance-overview-cash-flow-all-payments-modal.png, finance-overview-cash-flow-drill-down-flow.mp4) | | Same-day turnover coordination | Back-to-back partner imports on one unit same calendar day | Common Workflows — Same-day turnover coordination, Creating Bookings, Booking Lifecycle & Validations, FAQ — Same-day turnovers | | Check-out final utilities handoff | Departure-week final overages after first Ongoing partner imports | Common Workflows — Check-out final utilities handoff, Entering Monthly Utility Bills, Managing a Check-out — Step 6, FAQ — Check-out final utilities handoff | | Check-out collections before refund | Partner imports still need operator departure-week rent/fee collections before deposit release | Common Workflows — Check-out collections before refund, Handling a Late Payment, Managing a Check-out — Step 6, FAQ — Check-out collections before refund (workflows-check-out-coordination-flow.mp4, finance-contract-values-in-debt-filter.png) | | Check-out ledger cleanup before refund | Partner imports do not prevent duplicate manual receipt recording before deposit release | Common Workflows — Check-out ledger cleanup before refund, Reject/revert mistaken receipts, Managing a Check-out — Step 6, FAQ — Check-out ledger cleanup before refund (bookings-detail-transactions-revert-modal-info-banner.png, finance-transactions-bulk-reject-selected-bar.png) | | Check-out vs cancellation | Partner POST /bookings imports reach Ended or Canceled only through operator workflow choice | Common Workflows — Check-out vs cancellation, Booking Lifecycle & Validations, Managing a Check-out, Cancelling a Booking, FAQ — Check-out vs cancellation (workflows-cancel-booking-refund-modal-flow.mp4, bookings-list-canceled-tab.png) | | Cancellation collections before void | Partner POST /bookings imports do not settle pre-cancel rent/fee arrears before policy void | Common Workflows — Cancellation collections before void, Cancelling a Booking, Handling a Late Payment, FAQ — Cancellation collections before void (finance-contract-values-in-debt-filter.png, bookings-cancel-booking-modal-refund-types.png, workflows-cancel-booking-refund-modal-flow.mp4) | | Wrong tenant on a booking | Partner POST /bookings imports may match wrong tenant profile — operator Change tenant | Common Workflows — Wrong tenant on a booking, Creating Bookings, Booking Lifecycle & Validations, FAQ — Wrong tenant on a booking (bookings-detail-change-tenant-control.png, bookings-detail-change-tenant-flow.mp4) | | Cancel Booking vs Delete Booking | Partner imports need operator Cancel booking vs Delete Booking — API does not soft-archive | Common Workflows — Cancel Booking vs Delete Booking, Creating Bookings, Bookings module, FAQ — Cancel Booking vs Delete Booking (bookings-cancel-booking-modal-refund-types.png, workflows-cancel-booking-refund-modal-flow.mp4) | | Portfolio retirement decisions | Partner imports do not Archive property, Cancel booking, or Delete Booking — operator retirement scope | Common Workflows — Portfolio retirement decisions, Listings & Availability, Listings — Archived properties, FAQ — Portfolio retirement decisions (listings-archived-populated-table.png, listings-archived-unarchive-sidebar.png, finance-transactions-type-summary-cards.png) | | Archive property (building-level) | Partner listing feeds do not Archive property — operator building retirement on Listings | Common Workflows — Archive property (building-level), Listings & Availability, Listings — Archived properties, FAQ — Archive a property (listings-archived-populated-table.png, listings-archived-unarchive-sidebar.png) | | Utility overage collections | Partner imports still need operator utility bill posting before overage collections | Common Workflows — Utility overage collections, Entering Monthly Utility Bills, Handling a Late Payment, FAQ — Utility overage collections | | Property setup to first arrival handoff | Go-live listing feeds → first arrival week after partner imports | Common Workflows — Property setup to first arrival handoff, Onboarding a New Property — Step 7, Managing a Check-in — Step 1, FAQ — Property setup to first arrival handoff | | New inventory to first booking handoff | Go-live listing feeds → first Upcoming import after partner POST /bookings | Common Workflows — New inventory to first booking handoff, Onboarding a New Property — Step 7, Processing a New Booking — Step 1, FAQ — New inventory to first booking handoff | | Confirmation to check-in handoff | POST /bookings imports → Upcoming portal gates before operator arrival-week planning | Common Workflows — Confirmation to check-in handoff, Creating Bookings, Booking Lifecycle & Validations, FAQ — Confirmation to check-in handoff (bookings-detail-contract-method-of-payments.png, workflows-operations-check-in-out-planning-view.png) | | Check-in to check-out handoff | Partner imports → Ongoing operator departure-week planning after key handoff | Common Workflows — Check-in to check-out handoff, Booking Lifecycle & Validations, Managing a Check-in, Managing a Check-out, FAQ — Check-in to check-out handoff (operations-check-in-out-check-outs-next-7-days.png, bookings-timeline-view.png) | | Occupancy KPI to block hygiene handoff | Partner feeds do not explain Analytics Occupancy dips — operator Tools → Audit after KPI review | Common Workflows — Occupancy KPI to block hygiene handoff, Portfolio KPI review — Step 3, Manual block hygiene — Step 1, FAQ — Occupancy KPI to block hygiene handoff hub (analytics-kpi-occupancy-tab.png, audit-manual-blocks-workspace.png) | | Confirmation alert triage | Upcoming Booking created / Payment received after POST /bookings enqueue | Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b / Step 6, Pending manual receipt approval | | Portfolio segmentation by tenant category | Settings > Tenant categories, Bookings — Other filters, Glossary — Tenant category, FAQ — Finance tenant category filter parity | | Reject/revert mistaken receipts | Common Workflows — Reject/revert mistaken receipts, Payment Allocation — Correcting mistaken receipts, FAQ — Reject or revert an incoming payment | | Month-end invoicing (fixed date) | Fixed Invoice date before bulk Issue allocation — no partner API for document dating | Common Workflows — Month-end invoicing (fixed date), Settings > Invoicing — Default invoice date, Finance — Month-end invoicing with a fixed date, FAQ — Month-end invoicing (fixed date) hub (settings-invoicing-invoice-date-toggle.png, finance-transactions-bulk-toolbar-fixed-invoice-date-banner.png) | | Bulk Hostkit invoicing | No partner API for Hostkit bulk Issue allocation — operator Finance → Transactions pacing after imports | Common Workflows — Bulk Hostkit invoicing, Integrations — Hostkit API pacing, Finance — Invoice automation, FAQ — Bulk Hostkit invoicing hub (finance-transactions-bulk-selection-bar.png, settings-invoicing-hostkit-series.png) | | Rent reduction after invoicing | No partner API for invoiced floor — operators use booking workspace + Issue credit notes after export | Common Workflows — Rent reduction after invoicing, Booking Lifecycle & Validations, Finance — Invoiced floor and rent edits, FAQ — Lower rent below invoiced (bookings-detail-change-monthly-rent-modal.png, bookings-rent-reduction-invoiced-floor-flow.mp4) | | Modules shaped by partner integrations | Listings, Bookings, Sales, Finance, Modules — Module cross-reference | | Key glossary terms | Glossary cluster cross-reference, Webhook, Partial vs full integration feeds, Glossary — Credit note (payment reject/revert), Glossary — Deposit lifecycle status |

Pair with other API Reference hub sections

Related below is the documentation map when partner HTTP behaviour spans settings, concepts, workflows, or escalation paths. Pair Setup sequence after go-live with Getting Started — Recommended Setup Sequence; pair Documentation map & escalation with Introduction — Section cross-reference. Each Related subsection has a row in API guide cross-reference above. Full pairing matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other API Reference hub sections

Post-go-live pairing starts with Getting Started — Recommended Setup Sequence (steps 11–15 for partner traffic) and Onboarding a New Property — Step 7. Credential requests: [email protected]. Full pairing matrix: API guide cross-reference.

Documentation map & escalation​

Pair with other API Reference hub sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Hub parity: Support — Section cross-reference, Concepts — Setup sequence after go-live. Full pairing matrix: API guide cross-reference.

Navigation & bookmarks​

Pair with other API Reference hub sections

Bookmark routes pair with Management Frontend Deep Links for operator validation of partner imports. Operator JWT contrast: Management session authentication. Full pairing matrix: API guide cross-reference.

Settings & payload editors​

Pair with other API Reference hub sections

Payload editors pair with Partial vs full integration feeds and Integration field capabilities. Tenant segments: Settings > Tenant categories. Full pairing matrix: API guide cross-reference.

Deeper concept reads​

Pair with other API Reference hub sections

Concept reads pair with Concepts hub subsection index, Integrations & Distribution, and external MCP guides. Tenant-facing after import: Tenant Portal. Each bullet below also links the matching concept sub-guide Deeper API reads subsection (companion HTTP guides from the concept side). Full pairing matrix: API guide cross-reference.

Deeper workflow reads​

Pair with other API Reference hub sections

Workflow reads pair with Common Workflows hub subsection index and Workflow cross-reference. Each API sub-guide also has its own Deeper workflow reads subsection with reciprocal [Deeper API reads](../workflows/processing-a-new-booking.md#deeper-api-reads) anchors on workflow sub-guides — for example Creating Bookings — Deeper workflow reads, Webhooks & Notifications — Deeper workflow reads, Management session — Deeper workflow reads. Full pairing matrix: API guide cross-reference.

Pair with other API Reference hub sections

Workflow bullets pair with Common Workflows — Workflow cross-reference after partner POST /bookings enqueue. Month-end: Portfolio KPI review. Full pairing matrix: API guide cross-reference.

Notification row-click navigation​

Pair with other API Reference hub sections

Webhook-driven in-app rows on /notifications row-click into operator modules — contrast Dashboard bell General (in-panel only). Hub parity: Common Workflows — Notification row-click navigation. Full pairing matrix: API guide cross-reference.

Payment alert to receivables triage​

Pair with other API Reference hub sections

Ongoing/Ended payment overdue in-app rows after partner imports or webhooks — confirm booking balance before Finance → Overview → Debt Aging. Hub parity: Common Workflows — Payment alert to receivables triage. Full pairing matrix: API guide cross-reference.

Finance debt receivables triage​

Pair with other API Reference hub sections

Partner imports and webhooks that enqueue payment overdue rows often need portfolio Top debtors on Finance → Overview → Debt Aging after single-booking triage — clear amber Pending before KPI sign-off. Hub parity: Common Workflows — Finance debt receivables triage. Full pairing matrix: API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner POST /bookings imports and booking.* webhooks that enqueue payment overdue in-app rows still need operator Handling a Late Payment — Steps 1–6 after receivables triage — clear amber Pending and duplicate Revert rows before tenant outreach when KPIs lag. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: API guide cross-reference.

SymptomTriage surfaceCollections step
payment overdue after partner importRow-click on /notificationsHandling a Late Payment — Step 1
Ranked debtors after webhook batchFinance → Overview → Debt AgingStep 1 after booking open
Balance unchanged after transferPending manual receipt approvalStep 4b
Partner payload shows paid, management UI notPayment Plan / Transactions on opened bookingStep 1 confirm before Step 3

Finance Overview — Debt Aging panel with overdue buckets and top debtors for prioritizing late payments after partner imports

Walkthrough: open an arrears booking, confirm Payment Plan overdue pills, use Communication for tenant outreach, record a manual receipt via Transaction (Add Payment modal), then approve pending rows when your role allows.

Finance Income status drill-down​

Pair with other API Reference hub sections

Partner POST /bookings imports may inflate Scheduled segments — reconcile Income chart segment-click with Debt Aging Top debtors before integration sign-off. Hub parity: Common Workflows — Finance Income status drill-down. Full pairing matrix: API Reference — Section cross-reference.

Cash flow forecast drill-down​

Pair with other API Reference hub sections

Partner-import collections may lag Cash flow forecast month bars until bookings settle — distinct from Income status segments and Dashboard rent due chart. Hub parity: Common Workflows — Cash flow forecast drill-down. Full pairing matrix: API Reference — Section cross-reference.

Same-day turnover coordination​

Pair with other API Reference hub sections

Partner POST /bookings imports and iCal back-to-back rows can place departure and arrival on one unit the same calendar day — operators reconcile with Processing a New Booking — Step 1 before treating overlap as a duplicate. Hub parity: Common Workflows — Same-day turnover coordination. Full pairing matrix: API guide cross-reference.

Check-out final utilities handoff​

Pair with other API Reference hub sections

Partner POST /bookings imports and webhooks that reach Ended lifecycle still need operator-side utility bill entry before deposit release — integration payloads do not post landlord supplier bills. Hub parity: Common Workflows — Check-out final utilities handoff. Full pairing matrix: API guide cross-reference.

Check-out collections before refund​

Pair with other API Reference hub sections

Partner POST /bookings imports and webhooks do not record tenant rent/fee payments or clear In Debt rows — operators run Handling a Late Payment — Steps 1–4 before Managing a Check-out — Step 5 on departure-week arrears. Hub parity: Common Workflows — Check-out collections before refund. Full pairing matrix: API guide cross-reference.

Check-out ledger cleanup before refund​

Pair with other API Reference hub sections

Partner POST /bookings imports and webhooks do not prevent duplicate manual receipt recording — operators run Reject/revert mistaken receipts on departure-week Transactions before Managing a Check-out — Step 5. Hub parity: Common Workflows — Check-out ledger cleanup before refund. Full pairing matrix: API guide cross-reference.

Check-out vs cancellation​

Pair with other API Reference hub sections

Partner POST /bookings imports and webhooks do not choose lifecycle exit — operators run Managing a Check-out — Step 7 for completed stays (Ended) or Cancelling a Booking — Step 4 for policy voids (Canceled). Hub parity: Common Workflows — Check-out vs cancellation. Full pairing matrix: API guide cross-reference.

Cancellation collections before void​

Pair with other API Reference hub sections

Partner POST /bookings imports and webhooks do not record tenant rent/fee settlement — operators run Handling a Late Payment — Steps 1–4 before Cancelling a Booking — Step 4. Hub parity: Common Workflows — Cancellation collections before void. Full pairing matrix: API guide cross-reference.

Wrong tenant on a booking​

Pair with other API Reference hub sections

Partner POST /bookings imports and webhooks do not reassign tenant profiles — when a valid Upcoming reservation links to the wrong existing tenant (duplicate email/NIF match, picker mistake), operators run Change tenant on Contract Info via Processing a New Booking — Step 6 — distinct from duplicate-row Delete Booking. Hub parity: Common Workflows — Wrong tenant on a booking. Full pairing matrix: API guide cross-reference.

Cancel Booking vs Delete Booking​

Pair with other API Reference hub sections

Partner POST /bookings imports and webhooks do not choose Cancel booking vs Delete Booking — operators run Cancelling a Booking — Step 4 for policy voids or Delete Booking on Processing a New Booking — Step 1 for duplicate imports — distinct from Change tenant on valid stays. Hub parity: Common Workflows — Cancel Booking vs Delete Booking. Full pairing matrix: API guide cross-reference.

Portfolio retirement decisions​

Pair with other API Reference hub sections

Partner POST /bookings imports and listing feed pulls do not Archive property, Cancel booking, or Delete Booking — operators run Manual block hygiene — Step 5 before building Archive on Listings → Portfolio, Cancelling a Booking — Step 4 for policy voids, or Delete Booking on Processing a New Booking — Step 1 for duplicate imports. Hub parity: Common Workflows — Portfolio retirement decisions. Full pairing matrix: API guide cross-reference.

Archive property (building-level)​

Pair with other API Reference hub sections

Partner listing feed pulls and POST /bookings imports do not Archive property — operators retire buildings from Listings → Portfolio after Manual block hygiene — Step 5, distinct from reservation-level Cancel Booking vs Delete Booking. Hub parity: Common Workflows — Archive property (building-level). Full pairing matrix: API guide cross-reference.

Utility overage collections​

Pair with other API Reference hub sections

Partner POST /bookings imports do not post landlord supplier bills or tenant overage lines — operators run Entering Monthly Utility Bills — Steps 2–4 before Handling a Late Payment — Steps 1–4 collections on mid-stay overage arrears. Hub parity: Common Workflows — Utility overage collections. Full pairing matrix: API guide cross-reference.

Property setup to first arrival handoff​

Pair with other API Reference hub sections

Partner listing feeds and POST /bookings imports still need operator-side Onboarding a New Property — Steps 1–7 before Managing a Check-in — Step 1 — integration payloads do not configure Access Lockers or Tenant category defaults. Hub parity: Common Workflows — Property setup to first arrival handoff. Full pairing matrix: API guide cross-reference.

New inventory to first booking handoff​

Pair with other API Reference hub sections

Partner listing feeds and POST /bookings imports still need operator-side Onboarding a New Property — Steps 1–7 before Processing a New Booking — Step 1 — integration payloads do not replace Listings verify or duplicate-import checks on new inventory. Hub parity: Common Workflows — New inventory to first booking handoff. Full pairing matrix: API guide cross-reference.

Confirmation to check-in handoff​

Pair with other API Reference hub sections

POST /bookings imports create Upcoming reservations — partner payloads do not clear portal Contract Info gates or confirmation receipt approval. Finish Processing a New Booking — Steps 5b–6 before Managing a Check-in — Step 1. Hub parity: Common Workflows — Confirmation to check-in handoff. Full pairing matrix: API guide cross-reference.

Check-in to check-out handoff​

Pair with other API Reference hub sections

Partner POST /bookings imports transition to Ongoing after operator key handover — departure-week planning and Ready To Refund gates are operator-side after Managing a Check-in — Step 4. Finish Managing a Check-out — Step 1 for ~7 days before departure. Hub parity: Common Workflows — Check-in to check-out handoff. Full pairing matrix: API guide cross-reference.

Occupancy KPI to block hygiene handoff​

Pair with other API Reference hub sections

Partner listing feeds and POST /bookings imports do not clear stale manual blocks — when Analytics Occupancy / RevPAR dips without a rate change, pair Portfolio KPI review — Step 3 with Manual block hygiene — Step 1 before repricing or tenant-category rule edits. Hub parity: Common Workflows — Occupancy KPI to block hygiene handoff. Full pairing matrix: API guide cross-reference.

Confirmation alert triage​

Pair with other API Reference hub sections

Upcoming Booking created / Payment received rows after partner POST /bookings — finish Processing a New Booking — Step 5b / Step 6 before bulk mark-read. Hub parity: Common Workflows — Confirmation alert triage. Full pairing matrix: API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other API Reference hub sections

Partner automation after lockout pairs with Management session authentication (JWT refresh). Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: API guide cross-reference.

Walkthrough media​

Pair with other API Reference hub sections

MP4 clips complement PNG screenshots on workflow and module guides — start at Common Workflows — Walkthrough media. Hub parity: Common Workflows — Walkthrough media. Full pairing matrix: API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other API Reference hub sections

Integration-created tenants pair with Settings > Tenant categories (default for integration-created tenants) and Creating Bookings. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: API guide cross-reference.

Pending manual receipt approval​

Pair with other API Reference hub sections

Imported booking payments pair with Payment Allocation — Pending manual approval. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other API Reference hub sections

Receipt cleanup on imported bookings pairs with Payment Allocation — Correcting mistaken receipts. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: API guide cross-reference.

Month-end invoicing (fixed date)​

Pair with other API Reference hub sections

Partner POST /bookings imports and invoicing webhooks do not set fixed document dates — operators save Invoice date under Settings → Invoicing before bulk Issue allocation on Finance → Transactions after import settlement. Pair Bulk Hostkit invoicing on the same amber toolbar banner. Hub parity: Common Workflows — Month-end invoicing (fixed date). Full pairing matrix: API guide cross-reference.

Bulk Hostkit invoicing​

Pair with other API Reference hub sections

Partner HTTP has no Hostkit bulk invoicing API — operators run Issue allocation / Invoice selected on Finance → Transactions after imports settle. Pair Month-end invoicing (fixed date) when uniform document dates matter. Hub parity: Common Workflows — Bulk Hostkit invoicing. Full pairing matrix: API guide cross-reference.

Rent reduction after invoicing​

Pair with other API Reference hub sections

Partner HTTP has no rent-floor override — operators enforce invoiced floor on Bookings after Finance export, then Issue credit notes on Transactions when external accounting registers relief. Pair Bulk Hostkit invoicing for Hostkit pacing. Hub parity: Common Workflows — Rent reduction after invoicing. Full pairing matrix: API guide cross-reference.

Modules shaped by partner integrations​

Pair with other API Reference hub sections

Module rows pair with Listings & Availability field meanings and Modules — Module cross-reference. Full pairing matrix: API guide cross-reference.

  • Listings — Property wizard, Channels tab, Bills Included ceilings, and externalId mapping
  • Sales — Portfolio availability, monthly rent editing, and channel manager connections
  • Bookings — Imported reservation detail, payment plans, and contract generation after partner create
  • Finance — Portfolio ledgers, payment approval, and deposit settlement on imported schedules
  • Audit — Manual Blocks that affect unavailabilities in partial listing pulls; Discounts export for partner-imported contract values
  • Utilities — Bill entry and tenant overage when partner billsIncludedMaxValue ceilings are exceeded
  • Operations — Maintenance tickets and check-in/out coordination on imported stays
  • Dashboard — Post-login KPI snapshot distinct from partner listing pulls
  • Analytics — Month-range portfolio charts for reconciling imported booking volume
  • Tenants — Tenant directory and profile enrichment after partner imports
  • Inbox — Portfolio WhatsApp triage when chatbot rules escalate imported tenants
  • Notifications — Full /notifications history with search and row-click navigation; Payment overdue alerts when imported schedules are overdue
  • AI Chat — Vivin-internal AI Assistant using Landlord MCP tools for portfolio Q&A

Key glossary terms​

Pair with other API Reference hub sections

Glossary rows pair with Glossary cluster cross-reference integrator terms (Webhook, partial vs full feeds). Full pairing matrix: API guide cross-reference.

API hub subsection index​

Pair with other API Reference hub sections

This index pairs integration sub-guides and Related hub subsections — use it when partner HTTP spans credentials, payload depth, webhooks, or operator follow-up. Full pairing matrix: API guide cross-reference.

SubsectionWhen to open itPair with
Before You StartCredential requests and onboarding contacts[email protected], Authentication
Try requests in SwaggerOpenAPI Try it out on your route prefixAuthentication (Authorize dialog), Listings & Availability
Partial vs full integration feedsTransport depth before pollingFull listing feeds, Integration field capabilities
Partial-only integrationsPartners without listings/fulliCal feeds, Booking Engine API
AuthenticationPartner Bearer keys on integration prefixesManagement session (operator JWT contrast), Error Handling
Management sessionOperator Core API sign-in and refreshLandlord MCP (external AI alternative)
Listings & AvailabilityPartial ListingDto pull and syncProperty & Unit Mapping (externalId), Creating Bookings
Full listing feedsPublish catalogue JSONProperty & Unit Mapping (landlordKey), Webhooks & Notifications (listing.updated)
iCal feedsCalendar export instead of JSONListings & Availability (partial pull contrast)
Creating BookingsPOST /bookings enqueueBooking Lifecycle & Validations, Settings > Tenant categories
Booking Engine APIWhite-label write routesCreating Bookings, Property & Unit Mapping
Property & Unit MappingexternalId and landlordKey in UIListings (Channels tab), Sales
Booking Lifecycle & ValidationsPost-enqueue pipeline and guardsWebhooks & Notifications (booking.* events)
Webhooks & NotificationsPush callbacks and inbound signingBooking Lifecycle & Validations, Glossary — Webhook
Error HandlingRetries, 401/403, validation 400sAuthentication, Creating Bookings
Setup sequence after go-livePartner traffic after operator setupGetting Started — Recommended Setup Sequence
Documentation map & escalationDocumentation map across hubsIntroduction — Section cross-reference, FAQ — Section cross-reference
Navigation & bookmarksOperator validation routesManagement Frontend Deep Links, Management session
Settings & payload editorsField matrix and integration tabsIntegration field capabilities, Booking engine details
Deeper concept readsModels behind API payloads; reciprocal Deeper API reads on concept sub-guidesIntegrations & Distribution, Booking lifecycle, Concepts — Deeper API reads
Deeper workflow readsOperator follow-up after partner HTTP; reciprocal Deeper API reads on workflow sub-guidesCommon Workflows — Deeper API reads, Creating Bookings — Deeper workflow reads
Recommended operator workflowsOperator follow-up after importsProcessing a New Booking, Notification triage
Walkthrough mediaMP4 walkthroughs beside PNG screenshotsCommon Workflows — Walkthrough media, Modules, Account Settings
Notification row-click navigation/notifications row-click after webhook-driven in-app rowsCommon Workflows — Notification row-click navigation, Webhooks & Notifications, Notification triage
Payment alert to receivables triagepayment overdue alert → receivables before collections outreachCommon Workflows — Payment alert to receivables triage, Processing a New Booking, Handling a Late Payment — Step 1
Finance debt receivables triageTotal Debt / Debt Aging after import alert triageCommon Workflows — Finance debt receivables triage, Finance module, FAQ — Finance debt receivables triage hub, Handling a Late Payment collections (Steps 1–6 after triage surfaces)
Handling a Late Payment collectionsPartner import receivables → operator Steps 1–6Common Workflows — Handling a Late Payment collections hub, Creating Bookings, Webhooks & Notifications, Handling a Late Payment — Step 1
Finance Income status drill-downIncome segments after partner importCommon Workflows — Finance Income status drill-down, Creating Bookings, Finance module
Cash flow forecast drill-downCollections history after partner importCommon Workflows — Cash flow forecast drill-down, Creating Bookings, Finance module
Same-day turnover coordinationBack-to-back imports on one unit same calendar dayCommon Workflows — Same-day turnover coordination, Creating Bookings, FAQ — Same-day turnovers
Check-out final utilities handoffDeparture-week final overages after partner importsCommon Workflows — Check-out final utilities handoff, Entering Monthly Utility Bills, FAQ — Check-out final utilities handoff
Check-out collections before refundDeparture-week rent/fee arrears after partner importsCommon Workflows — Check-out collections before refund, Handling a Late Payment, Managing a Check-out, FAQ — Check-out collections before refund
Check-out ledger cleanup before refundDuplicate departure transfers after partner imports before refundCommon Workflows — Check-out ledger cleanup before refund, Reject/revert mistaken receipts, Bookings module, FAQ — Check-out ledger cleanup before refund
Check-out vs cancellationEnded vs Canceled lifecycle exit after partner importsCommon Workflows — Check-out vs cancellation, Booking Lifecycle & Validations, Bookings module, FAQ — Check-out vs cancellation
Cancellation collections before voidPre-cancel rent/fee arrears after partner imports before policy voidCommon Workflows — Cancellation collections before void, Cancelling a Booking, Bookings module, FAQ — Cancellation collections before void
Wrong tenant on a bookingWrong tenant profile on partner import — operator Change tenantCommon Workflows — Wrong tenant on a booking, Creating Bookings, Bookings module, FAQ — Wrong tenant on a booking
Cancel Booking vs Delete BookingOperator Cancel booking vs Delete Booking after partner imports — no API soft-archiveCommon Workflows — Cancel Booking vs Delete Booking, Creating Bookings, Bookings module, FAQ — Cancel Booking vs Delete Booking
Portfolio retirement decisionsOperator Archive property vs Cancel vs Delete after partner imports — no API retirementCommon Workflows — Portfolio retirement decisions, Listings & Availability, Listings module, FAQ — Portfolio retirement decisions
Archive property (building-level)Operator building Archive / Unarchive after partner imports — no API retirementCommon Workflows — Archive property (building-level), Listings & Availability, Listings module, FAQ — Archive a property
Utility overage collectionsMid-stay overage arrears after partner importsCommon Workflows — Utility overage collections, Entering Monthly Utility Bills, FAQ — Utility overage collections
Property setup to first arrival handoffGo-live feeds → first arrival week after partner importsCommon Workflows — Property setup to first arrival handoff, Onboarding a New Property — Step 7, Managing a Check-in
New inventory to first booking handoffGo-live feeds → first Upcoming import after partner POST /bookingsCommon Workflows — New inventory to first booking handoff, Onboarding a New Property — Step 7, Processing a New Booking
Confirmation to check-in handoffUpcoming portal gates after partner POST /bookingsCommon Workflows — Confirmation to check-in handoff, Creating Bookings, Processing a New Booking, Managing a Check-in
Check-in to check-out handoffOngoing departure-week planning after partner importsCommon Workflows — Check-in to check-out handoff, Managing a Check-in, Managing a Check-out, FAQ — Check-in to check-out handoff
Occupancy KPI to block hygiene handoffAnalytics Occupancy dip without rate change after partner importsCommon Workflows — Occupancy KPI to block hygiene handoff, Portfolio KPI review, Manual block hygiene
Confirmation alert triageUpcoming confirmation alerts after partner POST /bookingsCommon Workflows — Confirmation alert triage, Processing a New Booking — Step 5b, Pending manual receipt approval
Portfolio segmentation by tenant categoryReview only corporate, short-stay, or unassigned tenants on imported bookingsCommon Workflows — Portfolio segmentation by tenant category, Settings > Tenant categories, Glossary — Tenant category, FAQ — Finance tenant category filter parity
Pending manual receipt approvalRecorded bank transfers still pending until approval on imported bookingsCommon Workflows — Pending manual receipt approval, Finance — Pending manual payments, FAQ — Manual receipt still pending
Reject/revert mistaken receiptsDuplicate or invoiced receipt cleanup on imported bookingsCommon Workflows — Reject/revert mistaken receipts, Payment Allocation — Correcting mistaken receipts
Month-end invoicing (fixed date)Operator fixed Invoice date before month-end bulk export after partner importsCommon Workflows — Month-end invoicing (fixed date), Settings > Invoicing — Default invoice date, Portfolio KPI review — Step 7, FAQ — Month-end invoicing (fixed date) hub
Bulk Hostkit invoicingHostkit bulk Issue allocation pacing after partner imports settle on TransactionsCommon Workflows — Bulk Hostkit invoicing, Using in-app support — Bulk Hostkit invoicing, FAQ — Bulk Hostkit invoicing hub, FAQ — Bulk Hostkit invoicing slow
Modules shaped by partner integrationsScreen docs for imported dataModules — Module cross-reference
Key glossary termsIntegrator vocabularyGlossary deep-dive index, Glossary — Webhook