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 (Which listings appear). Habit-specific shortcuts live under Related below.

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.

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. That pull only includes units with a Channels mapping and that are still Included in feed for your platform. A unit marked Excluded from feed on Integration listings is omitted even when a mapping exists. The full catalogue can include unlinked units keyed by the Vivin listing id — Which listings appear.

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.

Kiwi, Capital Rooms, Porta85 & Lisbeyond

Kiwi, Capital Rooms, Porta85, and Lisbeyond single-landlord feeds return every listing on the provisioned account. Units without a channel link still appear — externalId is the Vivin listing UUID and listingInternalName carries the unit’s internal name. You can POST /bookings with that UUID. Details: API Reference — Kiwi, Capital Rooms, Porta85 & Lisbeyond.

Uniplaces webhook listing key

Uniplaces inbound bookings do not send {landlordKey} on the webhook URL. Store the full-feed reference_id and echo it as offer_api_reference. That value is your channel externalId when the unit is linked, or the Vivin listing id when it is not. See Webhooks & Notifications — Uniplaces and Full listing feeds — reference_id.

Housing Anywhere webhook listing key

Housing Anywhere inbound bookings do send {landlordKey} on the webhook URL — the stored landlord key or the Housing Anywhere integration email, same as the full feed. Store the full-feed listingReference and echo it as listing_external_reference. That value is your channel externalId when the unit is linked, or the Vivin listing id when it is not. See Webhooks & Notifications — Housing Anywhere and Full listing feeds — listingReference.

Inlife listing key

Inlife stores the channel key as propertyId_roomId. The full feed splits it into listing id (property) and room.id (room) — both underscore-free. Partial GET /listings and POST /bookings still use the joined string. See Full listing feeds — Inlife id and room.id.

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.

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. Until then it can still appear on GET …/listings/full keyed by the Vivin listing id.

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.

┌──────────────────────┐ ┌──────────────────────┐
│ 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 (for Inlife, propertyId_roomId from /house/{propertyId}/{roomId})
  • Just the property reference (for Inlife, propertyId from a studio URL /house/{propertyId})

When Inlife or the Vivin Booking Engine stored only the property id, a booking that arrives with propertyId_roomId still matches that row. Prefer storing the full pair when the listing URL includes both segments. See Full listing feeds — Inlife id and room.id.

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.

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 and a usable positive rent. 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 usable positive rent — a €0 fixed amount, or a variable grid with any zero month, omits the unit from both pulls (GET /listings/{externalId} then returns 404 Listing not available) — Listings & Availability — Usable rent required
  4. The unit may be Excluded from feed for your platform — Integration listings

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.

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 the endpoints and fields above. Related integrator pages are linked inline where useful.

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.

Setup sequence after go-live​

Pair with other Property & Unit Mapping guide sections

Complete Account Settings — Recommended setup order before partner traffic.

Documentation map & escalation​

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.

Upstream & downstream workflows​

Operator UI & settings​

Deeper concept reads​

Deeper workflow reads​

See Upstream & downstream workflows above for the same guides.

Operator habit hubs​

Day-to-day operator habits (lockout catch-up, pending receipts, payment triage, handoffs, and related playbooks) live on the Common Workflows habit hub.

Deep-link anchors for habit hubs

Lockout catch-up after password recovery​

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​

Key glossary terms​

Module documentation hubs​

Pair with other Property & Unit Mapping guide sections

for screen-by-screen operator follow-up.

  • 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 — AI Assistant using Landlord MCP tools (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)