Skip to main content

Property & Unit Mapping

First-time workspace setup

Configure externalId values during Getting Started — Recommended Setup Sequence step 13 — Listings property wizard and each unit’s Channels tab — before any partner GET /listings or POST /bookings. Complete steps 11–12 (Integrations, Integration field capability, Tenant categories default for integrations) so channel credentials and payload fields match your mapping plan. Finish steps 14–15 and Onboarding a New Property — Step 7 to confirm mapped IDs appear in operator UI before escalating sync defects. 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 How Mapping Works and Mapping Setup in the operator UI, then Verifying Your Mappings before partner traffic. Confirm externalId values in Listings & Availability before POST /bookings in Creating Bookings. Full-feed paths also require landlordKey resolution — see Full listing feeds. 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: Property & Unit Mapping section cross-reference · API Reference — API guide cross-reference.

Every listing on your platform must be mapped to the corresponding listing (unit) in Vivin. This mapping is what allows Vivin to know which unit a booking belongs to when you submit it via the API.

How Mapping Works​

Pair with other Property & Unit Mapping sections

GET /listings returns your externalId on each row — verify against Listings & Availability before POST /bookings. Full endpoint map: Property & Unit Mapping section cross-reference.

Each mapping is stored as a Listing Integration record in Vivin, which links:

Your SideVivin Side
Your platform's listing ID (externalId)A Vivin listing (unit)
Your platform nameThe integration platform identifier

When you call GET /listings, the externalId in each listing response is your ID - the one your platform uses to identify that unit.

When you submit a booking via POST /bookings, you send the externalId and Vivin looks up the corresponding Vivin listing to create the booking on the correct unit.

Confirm externalId in Swagger

In Integration Swagger, GET /listings/{propertyId} (by Vivin property id) returns listings with the externalId your platform must send on booking create. See Listings availability for the workflow screenshot.

Integration Swagger — GET listings for a Vivin property id with path parameter and Try it out

Mapping Setup​

Pair with other Property & Unit Mapping sections

Operators save externalId on each unit Channels row — see Settings > Integrations and Sales → Channel Manager. Full endpoint map: Property & Unit Mapping section cross-reference.

Mapping is configured in the Vivin management dashboard by the property manager:

  1. Settings > Integrations - Enable your integration platform
  2. Listings > Channels Tab - For each listing, the property manager enters the external ID that corresponds to the listing on your platform
  3. Once mapped, the listing appears in your GET /listings response

Operators link each unit to your platform from the unit sidebar Channels section (after account credentials are enabled in Settings). The externalId you send on POST /bookings must match the value saved on that row:

Listings — unit sidebar Channels section with platform logos and external ID / link controls (example unit AA-11-5D-R1)

For account-wide platform toggles and credentials, see Settings > Integrations. For day-to-day sync status across many units, use Sales > Channel Manager.

Who creates the mapping?

The property manager creates the mapping in Vivin's UI, not the integrating platform. During onboarding, coordinate with the property manager to ensure every listing they want to distribute through your platform has the correct external ID configured.

Mapping Data Model​

Pair with other Property & Unit Mapping sections

Full-feed landlordKey scoping reuses the same account linkage — see Full listing feeds — landlordKey. Field matrix: Integration field capabilities. Full endpoint map: Property & Unit Mapping section cross-reference.

┌──────────────────────┐         ┌──────────────────────┐
│   Your Platform      │         │       Vivin          │
│                      │         │                      │
│  Listing ID: "R-42"  │ ──────► │  Listing: Studio 3A  │
│                      │  maps   │  Property: Casa Sol   │
│                      │   to    │  Account: Acme PM     │
└──────────────────────┘         └──────────────────────┘

Each mapping record contains:

FieldDescription
externalIdYour platform's listing identifier
integrationPlatformYour platform name (e.g. housinganywhere, uniplaces)
listingIdThe Vivin listing UUID
accountIdThe Vivin account (property manager) UUID
link(Optional) URL to the listing on your platform

Studio / Single-Unit Properties​

Some properties in Vivin are studios or single-unit properties where the property itself is the bookable unit. In these cases, the externalId may correspond to either:

  • The full listing reference (e.g. propertyId_roomId)
  • Just the property reference (e.g. propertyId)

Vivin handles this automatically: if a full ID match is not found, it falls back to matching by property ID only. This is relevant for platforms like Inlife and the Vivin Booking Engine where the URL structure may only include the property ID for studio units.

Verifying Your Mappings​

Pair with other Property & Unit Mapping sections

Authorize with Authentication before your first verification GET /listings. Missing rows map to 404 on booking create — see Error Handling. Full endpoint map: Property & Unit Mapping section cross-reference.

After the property manager has configured the mappings, verify them by calling:

GET /{platform}-integration/listings HTTP/1.1
Authorization: Bearer YOUR_API_KEY

Every listing that appears in the response has a valid mapping. If a listing you expect is missing:

  1. The external ID may not be configured in Vivin
  2. The listing may not be active (deleted or not yet published)
  3. The listing may not have a valid rent value configured

Multiple Platforms​

Pair with other Property & Unit Mapping sections

One Vivin unit can map to HousingAnywhere, Spotahome, and your platform at once — operator context in Integrations & Distribution. Calendar-only partners use iCal feeds instead of JSON externalId pulls. Full endpoint map: Property & Unit Mapping section cross-reference.

A single Vivin listing can be mapped to multiple external platforms simultaneously. This is how Vivin acts as a central distribution hub - one unit can be listed on HousingAnywhere, Spotahome, Uniplaces, and your platform at the same time, with availability synchronised across all of them.

Important

Each mapping is unique per platform. A single listing cannot have two different external IDs for the same platform.

Property & Unit Mapping section cross-reference​

Use this table when one mapping topic naturally leads into another API guide, operator UI, or downstream workflow — each row links to the docs you should read before or after wiring externalId values.

API topic / sectionPair with these docs
How Mapping WorksListings & Availability, Creating Bookings (externalId on enqueue), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1 (partner imports with unpaid schedules), Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent)
Mapping SetupSettings > Integrations, Listings — Channels tab, Sales → Channel Manager
Mapping Data ModelFull listing feeds — landlordKey, Integration field capabilities
Verifying Your MappingsAuthentication, Error Handling (404 on unknown externalId)
Multiple PlatformsIntegrations & Distribution, iCal feeds (UUID-based calendar export)

| Lockout catch-up after password recovery | Mapping verification backlog after sign-in recovery | Common Workflows — Lockout catch-up, Onboarding a New Property — Step 5, Listings — Channels tab | | Pending manual receipt approval | Mis-mapped imports with pending receipts | Common Workflows — Pending manual receipt approval, Creating Bookings, Finance — Pending manual payments | | Reject/revert mistaken receipts | Wrong-unit import receipts | Common Workflows — Reject/revert mistaken receipts, Cancelling a Booking, Payment Allocation — Correcting mistaken receipts | | Portfolio segmentation by tenant category | Segment triage after mapping fixes | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Bookings — Other filters | | Notification row-click navigation | Mapping fixes 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 | Wrong externalId 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 | Mapped 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 after mapping corrections | 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 | Mapped rent 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 | Mapping go-live 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 Property & Unit Mapping guide sections

Related below links externalId and landlordKey mapping 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: Property & Unit Mapping section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Property & Unit Mapping guide sections

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

Documentation map & escalation​

Pair with other Property & Unit Mapping guide sections

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

Companion API guides​

Pair with other Property & Unit Mapping guide sections

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

  • Listings & Availability — externalId on each ListingDto row in partial pulls
  • Creating Bookings — externalId in the booking submission body
  • Full listing feeds — Partner-shaped catalogue exports that reuse the same mappings
  • iCal feeds — Calendar retrofeed URLs that reuse the same unit rows as partial pulls
  • Booking Lifecycle & Validations — Post-submit pipeline after partner POST /bookings references a mapped externalId
  • Webhooks & Notifications — Push callbacks when mapped units receive bookings or calendar updates
  • Error Handling — 404 on unknown externalId during mapping verification before first partner traffic
  • Booking Engine API — White-label engine IDs and PUT /listing updates
  • Authentication — Bearer token required before verification GET /listings
  • Management session — Operator JWT contrast when internal scripts poll account-scoped routes after mapping verification
  • AI usage — Internal LLM token ledger on the same management JWT (not integration Bearer keys)

Upstream & downstream workflows​

Pair with other Property & Unit Mapping guide sections

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

Operator UI & settings​

Pair with other Property & Unit Mapping guide sections

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

Deeper concept reads​

Pair with other Property & Unit Mapping guide sections

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

Deeper workflow reads​

Pair with other Property & Unit Mapping 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: Property & Unit Mapping section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Property & Unit Mapping guide sections

Mapping work in Channels may stall during lockout — finish externalId / landlordKey setup after sign-in recovery before partner pulls. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: property--unit-mapping-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Property & Unit Mapping guide sections

Correct externalId mapping prevents wrong-unit imports whose receipts later need pending approval — pair with Creating Bookings. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: property--unit-mapping-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Property & Unit Mapping guide sections

Wrong-unit imports from bad externalId keys pair with Cancelling a Booking and receipt Reject / Revert. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: property--unit-mapping-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Property & Unit Mapping guide sections

Mapping is unit-scoped; segment portfolio triage with Bookings — Other filters after imports land. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: property--unit-mapping-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Property & Unit Mapping guide sections

Fix externalId mismatches before /notifications row-click on import alerts — wrong mapping sends triage to the wrong booking. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Property & Unit Mapping section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Property & Unit Mapping guide sections

Mis-mapped POST /bookings can orphan payment overdue alerts — verify Property & Unit Mapping before receivables row-click. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Property & Unit Mapping section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Property & Unit Mapping guide sections

Newly mapped units trigger Upcoming Booking created alerts — complete mapping before first partner POST /bookings volume. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Property & Unit Mapping section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Property & Unit Mapping guide sections

Correct externalId before Top debtors triage — receivables rank on the wrong booking when mapping drifts. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Property & Unit Mapping section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner integration reads on Property Unit Mapping 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: property-unit-mapping-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Property & Unit Mapping guide sections

Unit rent mapping affects Income → Scheduled after imports — segment-click reconcile after mapping corrections. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Property & Unit Mapping section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Property & Unit Mapping guide sections

Mapping go-live timing vs Cash flow forecast collections — approve receipts on correctly mapped bookings first. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Property & Unit Mapping section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Property & Unit Mapping guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Property & Unit Mapping section cross-reference.

Module documentation hubs​

Pair with other Property & Unit Mapping guide sections

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

  • Audit module — Manual blocks on mapped units that still appear in unavailabilities pulls (hub)
  • Bookings module — Operator reconciliation when mapping alerts or import duplicates appear (hub)
  • Dashboard module — KPI snapshot when mapping gaps block occupancy or vacancy views (hub)
  • Analytics module — Occupancy KPIs on mapped units after channel sync (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 with payment approval and deposit settlement (hub)
  • Tenants module — Tenant directory and profile sidebars for imported stays (hub)
  • Sales module — Portfolio availability, monthly rent editing, and channel manager connections (hub)
  • Utilities module — Bills Included ceiling model and tenant overage charges on payment plans (hub)
  • Operations module — Maintenance tickets, cash flows, and check-in/out coordination (hub)
  • Inbox module — Portfolio-wide WhatsApp workspace (hub)
  • Notifications module — Full /notifications history with search and filters (hub); Payment overdue alerts when mapped partner imports leave unpaid schedules
  • AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)