Property and unit mapping

Your platform reads and books a VIVIN unit through a link between that unit and your own listing ID, which the API calls externalId.

Before you start

Item	Value
Terms	A property is the building or flat. A unit (also called a listing) is what is rented: the whole property, a room or a bed
Who links	The landlord, in the VIVIN app. You cannot create or change links through the API
What you send	Your listing URLs, one per unit, so the landlord can paste them into VIVIN
Check with	GET /<prefix>/listings and GET /<prefix>/listings/{externalId}, with your partner token (Authentication)

How a link works

• One link per unit per platform. A unit can be linked to several platforms at once, each with its own ID. Saving a new URL for the same platform replaces the old ID.
• It is your ID, not VIVIN's. VIVIN reads it from the listing URL the landlord pastes (see How VIVIN reads your ID).
• No duplicates within an account. In one VIVIN account, the same ID cannot be linked to two units for the same platform. VIVIN refuses the second link.
• Availability is shared. A booking or block on the unit, from any channel, shows up in every platform's feed as an unavailabilities entry.

Where the ID appears

Route	ID
GET /<prefix>/listings	externalId on each listing
GET /<prefix>/listings/{externalId}	In the path
POST /<prefix>/bookings	externalId in the body
GET /<prefix>/{landlordKey}/listings/…/full	A per-platform field (Full feeds and webhooks)
Uniplaces and Housing Anywhere webhooks	offer_api_reference and listing_external_reference
GET /ical-integration/listings/{listingId}/…	Not your ID: the VIVIN unit ID (iCal feeds)

How the landlord links a unit

During onboarding, send the landlord your listing URL for each of their units. Then the landlord:

1. Fills in your platform's card under Settings → Integrations → Booking Platforms (recommended). Every platform has a card by default; one that was switched off comes back with Add under Platform Integrations. The card's Integration Email reaches you as landlordEmail, and the full feeds accept it as the landlordKey. Its Markup and Calendar Block settings also change what your feed shows.
2. Opens Portfolio → Listings, clicks the unit and opens the Setup tab. Saving a link needs the Listings → Edit permission.
3. In the Channels section, clicks the pencil next to your platform (Add listing URL), pastes the full URL of the unit's page on your platform and clicks Save. A bare ID is rejected, because VIVIN needs the URL to recognise the platform.
4. On the Full integration tab, under Integration listings, checks that your platform shows Included in feed (the default). With Excluded from feed, the unit stays out of your feeds even though it is linked.

The landlord can also add the link from Sales → Channel Manager: click the unit's cell in your platform's column, paste the full URL under Listing link and click Integrate. To remove a link, they click the trash icon (Remove integration) on the platform's row in Channels, then Delete.

Some units are linked automatically:

• Units brought in with Inlife Import or Inlife Full Import (in the app's Create New menu) are linked to Inlife.
• Units created with POST /vivin-booking-engine-integration/property-listing are linked to the Vivin Booking Engine.

How VIVIN reads your ID

The URL's domain tells VIVIN which platform it belongs to; a domain that does not match the row being edited is rejected. Tabs, line breaks and trailing slashes are ignored.

Platform (prefix)	What VIVIN stores as externalId
Uniplaces (uniplaces-integration)	The staticId query value when there is one, otherwise the last path segment
Spacest (roomless-integration)	The last path segment
Spotahome (spotahome-integration)	The last path segment
Housing Anywhere (housinganywhere-integration)	The path segment after /room/
Erasmus Life Lisboa (erasmus-life-integration)	The last path segment
Inlife (inlife-integration)	The one or two segments after /house/, joined with _: {propertyId}_{roomId}, or {propertyId} for a studio
Vivin Booking Engine (vivin-booking-engine-integration)	Same rule as Inlife

For Inlife and the Vivin Booking Engine, a unit linked with only {propertyId} still matches a request sent as {propertyId}_{roomId}.

Single-landlord feeds

A single-landlord feed (one prefix per landlord, given to you by VIVIN) is tied to one account and works without links:

• GET /<prefix>/listings returns every unit of that account, linked or not, except archived units, units in archived properties, and units without a usable rent.
• externalId is your ID when the landlord linked the unit to your platform, otherwise the VIVIN unit ID (a UUID). listingInternalName carries the unit's name in VIVIN, so you can tell units apart.
• GET /<prefix>/listings/{externalId} accepts only the VIVIN unit ID.
• POST /<prefix>/bookings accepts your linked ID or the VIVIN unit ID. A value that matches no unit of the account returns 404 at once.

Full feeds and webhooks

The full feeds (GET /<prefix>/{landlordKey}/listings/full, for Uniplaces, Spotahome, Housing Anywhere and Inlife) carry every unit of the landlord's account that is included in your feed, linked or not, except archived units and units in archived properties. A linked unit carries your ID; an unlinked one carries the VIVIN unit ID (a UUID).

Send the ID back exactly as the full feed exported it:

Partner	Full-feed field	Send it back as
Uniplaces	reference_id	offer_api_reference on the webhook
Housing Anywhere	listingReference	listing_external_reference on the webhook

• Those two webhooks accept a linked ID or a VIVIN unit ID.
• POST /<prefix>/bookings on the shared prefixes accepts only a linked ID of a unit that is included in your feed. An unlinked unit's UUID fails there, in the background.
• Inlife: the partial feed and POST /inlife-integration/bookings use the joined {propertyId}_{roomId}. The full feed splits it into id and room.id (Listing IDs).

Check your links

Read the partial feed with your partner token:

curl https://api.vivin.app/uniplaces-integration/listings \
  -H "Authorization: Bearer <partner-token>"

Each listing is one linked unit that is included in your feed. Trimmed to the fields that matter for mapping:

[
  {
    "externalId": "R-42",
    "landlordEmail": "[email protected]"
  }
]

• The list covers your whole platform, not one landlord. Tell landlords apart by landlordEmail, the Integration Email on their card, when they set one.
• The list is rebuilt about every 10 minutes, so a new link can take that long to appear. GET /<prefix>/listings/{externalId} is always live: use it to check one unit at once.
• A unit you expect but cannot see fails one of the rules in Which listings appear.

Troubleshooting

Symptom	Likely cause and fix
404 Listing not found for <platform> with externalId …	Not linked, linked with another ID (compare the unit's Channels URL with the table above), Excluded from feed, or the unit or its property is archived
404 Listing not available	The unit is linked but has no usable rent. Ask the landlord to set one
A booking was sent but never appeared	On the shared prefixes, an unknown externalId fails in the background and nobody is notified. Read GET /<prefix>/listings/{externalId} before you book
An ID stopped working	The landlord saved a different URL for your platform on that unit. Take the new ID from the feed
Two landlords linked the same ID	VIVIN blocks duplicates only within an account. The Uniplaces webhook then answers 409, and POST /<prefix>/bookings can land on either account. Ask the landlords to remove the wrong link

Related

• Listings and availability: every field of the partial feed
• Full listing feeds: per-landlord catalogues and landlordKey
• Creating bookings: the POST …/bookings body
• Webhooks and notifications: the Uniplaces and Housing Anywhere webhooks
• Integrations settings: the Booking Platforms cards landlords set up