Skip to main content

Vivin Booking Engine integration

First-time workspace setup

White-label engine routes share the same operator prerequisites as partial listing pulls — complete Getting Started — Recommended Setup Sequence steps 11–13 (Integrations, Integration field capability, Listings + Property & listing details (booking engine) for write payloads) before PUT /listing or POST /property-listing. Set Tenant categories default for integrations on steps 11–12; validate POST /bookings imports on step 14 and Onboarding a New Property — Step 7. 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 Authentication and Endpoints overview, then Update listing (write) and Submit bookings for white-label flows. Shares partial reads with Listings & Availability and POST /bookings with Creating Bookings; write routes need the same externalId mapping in Property & Unit Mapping. 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: Booking Engine API section cross-reference · API Reference — API guide cross-reference.

The vivin-booking-engine-integration prefix serves direct / white-label booking sites that embed Vivin availability and submit confirmed reservations without a third-party marketplace in the middle. It shares the partial listing and booking patterns documented in Listings & Availability and Creating Bookings, and adds write routes for catalogue sync and coliving housemate display.

Swagger

Open https://<api-host>/vivin-booking-engine-integration (exact host from onboarding) to inspect CreateInlifeProperty, IntegrationUpdateListingDto, and response models interactively.

Operator-facing branding, visits, and instant-booking behaviour are covered in Integrations & Distribution and Property & listing details (booking engine).

Operator content that feeds the API​

White-label sites read the same bilingual copy, amenities, rules, and photos operators edit under Listings → Full integration pill. Those fields map into partial listing JSON and into richer payloads when you call write routes:

Property Details — Profile &amp; copy tab with bilingual title and description fields

Listing Details — Integration listings tab with per-platform toggles

Try requests in Swagger​

Authorize with your booking-engine Bearer key, then expand listings, bookings, and write groups (PUT /listing, POST /property-listing, GET …/housemates):

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

Booking submission uses the same POST …/bookings pattern as other integrations — see the dedicated capture on Creating Bookings:

Integration Swagger — POST …/bookings expanded with request body schema and Try it out

Authentication​

Pair with other Booking Engine API sections

Bearer keys are account-scoped — rotate compromised keys through Vivin support before retrying write routes. 401/403 recovery: Error Handling. Full endpoint map: Booking Engine API section cross-reference.

All routes use Bearer authentication with the API key Vivin issues for your booking-engine integration (same header as other partner prefixes — see Authentication).

POST /property-listing additionally resolves the target account from that key server-side.

Full pairing matrix: Booking Engine API section cross-reference.

Endpoints overview​

MethodPathPurpose
GET/listingsPartial listing catalogue (ListingDto[]) — calendar, pricing, blocks
GET/listings/:externalIdSingle partial listing
PUT/listingPush rent, fees, capacity, and unavailabilities for one mapped listing
POST/bookingsSubmit a confirmed reservation (queued job — same semantics as other platforms)
POST/property-listingCreate a property and one or more listings from an engine payload
GET/listings/:externalId/housematesCurrent residents for coliving / housemate UI

Partial listings (read)​

Pair with other Booking Engine API sections

Partial ListingDto reads share semantics with Listings & Availability — marketing copy originates in Booking engine details. Calendar-only subscribers: iCal feeds. Full endpoint map: Booking Engine API section cross-reference.

Same contract as Listings & Availability:

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

Poll on the same 15–30 minute cadence recommended for other partial feeds; honour unavailabilities before showing a unit as bookable.

Full pairing matrix: Booking Engine API section cross-reference.

Update listing (write)​

Pair with other Booking Engine API sections

externalId must exist before PUT /listing — provision with Property & Unit Mapping or POST /property-listing. Operator sync status: Sales — Channel Manager. Full endpoint map: Booking Engine API section cross-reference.

Push pricing and calendar blocks from the booking engine back into Vivin for a listing you already mapped.

PUT /vivin-booking-engine-integration/listing HTTP/1.1
Host: api.vivin.app
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body (IntegrationUpdateListingDto)​

FieldTypeDescription
externalIdstringYour listing reference (must already exist in Vivin)
landlordEmailstringManaging operator email on the listing
availableFromISO dateEarliest move-in
minStayPeriod / maxStayPeriodnumberStay bounds in months
isRentFixedbooleanFixed vs seasonal rent
rentnumberBase monthly rent (EUR)
capacitynumberMax tenants
extraPricePerTenantnumberSurcharge per extra tenant (EUR / month)
cleaningFeeValuenumberOne-time cleaning fee (EUR)
billsIncludedMaxValuenumberCap on included bills (EUR)
adminFeeValuenumberAdmin fee (EUR)
depositValuenumberDeposit (EUR)
rentsPerMonth{ month, rent }[]Seasonal pricing when isRentFixed is false
unavailabilities{ from, to, reason? }[]Blocked ranges

Response: true when the listing update is accepted.

Mapping required

externalId must match an existing integration mapping. Creating net-new inventory uses POST /property-listing instead.

Full pairing matrix: Booking Engine API section cross-reference.

Create property and listings​

Pair with other Booking Engine API sections

Rich create payloads mirror Full listing feeds shape — operator wizard first: Onboarding a New Property. Sandbox accounts may return empty bodies on success HTTP — confirm with Vivin. Full endpoint map: Booking Engine API section cross-reference.

Provision a new property plus units from a rich engine payload (addresses, media, visit windows, listing copy — schema in Swagger as CreateInlifeProperty).

POST /vivin-booking-engine-integration/property-listing HTTP/1.1
Host: api.vivin.app
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Response (CreatePropertyListingResponseDto):

FieldTypeDescription
propertyProperty objectCreated property record
listingsListing[]Created unit listings

The server ties the new records to the account resolved from your API key. Onboarding may disable creation for specific sandbox accounts (empty property / listings response) — confirm with Vivin if you receive null bodies on success HTTP status.

Full pairing matrix: Booking Engine API section cross-reference.

Submit bookings​

Pair with other Booking Engine API sections

Queue semantics match Creating Bookings — post-submit lifecycle: Booking Lifecycle & Validations and Processing a New Booking. Unpaid schedules: Notifications — Payment overdue alerts → Handling a Late Payment — Step 1. Full endpoint map: Booking Engine API section cross-reference.

Identical queue semantics to other integrations:

POST /vivin-booking-engine-integration/bookings HTTP/1.1
Host: api.vivin.app
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

See Creating Bookings for the request body, idempotency expectations, and post-submit lifecycle (Booking lifecycle & validations).

Full pairing matrix: Booking Engine API section cross-reference.

Housemates (coliving)​

Pair with other Booking Engine API sections

HousemateDto windows come from active bookings on the mapped listing — operator context: Bookings module and tenant-facing copy in Tenant Portal. Full endpoint map: Booking Engine API section cross-reference.

Expose who currently lives in a unit for “meet your future housemates” widgets.

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

Response: array of HousemateDto:

FieldTypeDescription
namestringTenant display name
nationalitystring | nullWhen stored on the profile
moveIn / moveOutISO dateActive booking window
photostring | nullReserved — may be null today
age / occupation / gendervarious | nullReserved — may be null today

Only current residents on active bookings for that listing are returned.

Booking Engine API 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 the booking-engine integration.

API topic / sectionPair with these docs
AuthenticationAuthentication, Error Handling (401 / 403)
Partial listings (read)Listings & Availability, iCal feeds (calendar export contrast), Booking engine details module (operator payload source)
Update listing (write)Property & Unit Mapping, Sales — Channel Manager (operator sync status)
Create property and listingsOnboarding a New Property, Full listing feeds (rich payload contrast)
Submit bookingsCreating Bookings, Booking Lifecycle & Validations, Processing a New Booking, Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent)
Housemates (coliving)Tenant Portal, Bookings module (active stay windows)

| Lockout catch-up after password recovery | Engine import backlog after sign-in recovery | Common Workflows — Lockout catch-up, Processing a New Booking, Webhooks & Notifications | | Pending manual receipt approval | Direct-booking pending receipts | Common Workflows — Pending manual receipt approval, Creating Bookings, Finance — Pending manual payments | | Reject/revert mistaken receipts | Duplicate engine reservations | Common Workflows — Reject/revert mistaken receipts, Cancelling a Booking, Payment Allocation — Correcting mistaken receipts | | Portfolio segmentation by tenant category | Segment triage on engine bookings | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Bookings — Other filters | | Notification row-click navigation | Engine bookings create operator in-app rows | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | Direct engine payments vs payment overdue | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Engine confirmation-week alerts | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Receivables on engine-created stays | 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 | Income segments on engine bookings | 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 | Collections on engine payment rails | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Booking engine integration guide sections

Related below links public booking-engine HTTP 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: Booking engine integration section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Booking engine integration guide sections

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

Documentation map & escalation​

Pair with other Booking engine integration guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Full pairing matrix: Booking engine integration section cross-reference.

Upstream & downstream workflows​

Pair with other Booking engine integration guide sections

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

Operator UI & payload editing​

Deeper concept reads​

Pair with other Booking engine integration guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Booking engine integration section cross-reference · API guide cross-reference.

Deeper workflow reads​

Pair with other Booking engine integration 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: Booking engine integration section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Booking Engine API guide sections

White-label engine traffic may continue during operator lockout — reconcile direct-booking alerts after sign-in recovery. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: booking-engine-api-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Booking Engine API guide sections

Engine POST /bookings creates the same Layer 2 pending receipts as channel imports — pair with Finance — Pending manual payments. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: booking-engine-api-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Booking Engine API guide sections

Duplicate engine reservations and mistaken direct-booking receipts pair with Cancelling a Booking. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: booking-engine-api-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Booking Engine API guide sections

Engine-created tenants inherit default for integrations — pair with Settings > Tenant categories. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: booking-engine-api-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Booking Engine API guide sections

Public booking-engine reservations still surface operator /notifications rows — row-click into management bookings after engine checkout completes. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Booking Engine API section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Booking Engine API guide sections

Engine card or bank redirects may lag payment overdue alerts — row-click into booking Transactions before Debt Aging collections. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Booking Engine API section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Booking Engine API guide sections

Upcoming Booking created alerts on engine reservations pair with operator Processing a New Booking — Step 6. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Booking Engine API section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Booking Engine API guide sections

Engine-created stays feed receivables — triage portfolio Top debtors after single-booking alert row-click clears Pending receipts. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Booking Engine API section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner integration reads on Booking Engine Integration 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: booking-engine-integration-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Booking Engine API guide sections

Engine payment schedules shape Income → Scheduled segments — segment-click modals on Finance → Overview before engine go-live sign-off. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Booking Engine API section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Booking Engine API guide sections

Approved engine collections appear on Cash flow forecast month bars — distinct from Income status segments on the same booking. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Booking Engine API section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Booking engine integration guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Booking engine integration section cross-reference.

Companion API guides​

Pair with other Booking engine integration guide sections

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

  • Creating Bookings — POST /bookings body and queue behaviour
  • Property & unit mapping — externalId setup
  • Listings & Availability — Partial GET /listings reads that complement booking-engine writes
  • Full listing feeds — Partner-shaped publish payloads that share the same rich content as the booking engine
  • Webhooks & Notifications — Push events when white-label reservations succeed in the background
  • Error Handling — Public engine endpoints and validation failures
  • Authentication — Bearer key before PUT /listing and reservation endpoints
  • AI usage — Operator JWT ledger when reconciling white-label import volume with internal LLM spend (integration Bearer keys return 401)
  • Deep Links — Operator routes after white-label reservations land

Module documentation hubs​

Pair with other Booking engine integration guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen operator follow-up. Full pairing matrix: Booking engine integration section cross-reference.

  • Bookings module — Operator UI for reservations created via POST /bookings (hub)
  • Sales — Channel Manager — Operator channel status after PUT /listing updates sync outward (hub)
  • Finance module — Portfolio ledgers once engine-sourced stays accumulate Contract Values (hub)
  • Utilities module — Operator bill entry and tenant overage when actual costs exceed billsIncludedMaxValue written via PUT /listing (hub)
  • Audit module — Cross-portfolio discount export when white-label reservations include mid-stay repricing on payment plans (hub)
  • Notifications module — Account-wide booking alerts when engine imports land in /notifications (hub); Payment overdue alerts when white-label schedules are overdue
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)