Listings and availability

The partial listing feed gives your platform the price, fees, stay rules and blocked nights of every unit a landlord has linked to you.

Before you start

Item	Value
Base URL	https://api.vivin.app/<prefix>, for example /uniplaces-integration (route prefixes)
Authentication	Authorization: Bearer <partner-token> (Authentication)
Units covered	Units linked to your platform in their Channels section (Property and unit mapping), from every landlord that works with you
Freshness	The list is rebuilt about every 10 minutes. The single-listing route and the Vivin Booking Engine list are always live
Not included	Photos, address, amenities and descriptions: use the Full listing feeds. Calendar only: use iCal feeds

Endpoints

Method	Path	Returns
GET	/<prefix>/listings	An array with every listing for your platform
GET	/<prefix>/listings/{externalId}	One listing, by your platform's ID for it

List listings

GET /<prefix>/listings returns the whole catalogue in one array. It takes no query parameters and has no pagination.

Example request

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

Response

200 OK with an array of listing objects. A unit with rent that varies by month and a one-month deposit:

[
  {
    "externalId": "unit-a-101",
    "availableFrom": "2027-02-01",
    "minStayPeriod": 3,
    "maxStayPeriod": 0,
    "isRentFixed": false,
    "rent": 1000,
    "capacity": 2,
    "extraPricePerTenant": 100,
    "cleaningFeeValue": 40,
    "billsIncluded": true,
    "billsIncludedMaxValue": 50,
    "adminFeeValue": 250,
    "adminFeeMode": "fixed",
    "adminFeeTiers": [],
    "depositValue": 1000,
    "landlordEmail": "[email protected]",
    "rentsPerMonth": [
      { "month": 1, "rent": 750 },
      { "month": 2, "rent": 750 },
      { "month": 3, "rent": 800 },
      { "month": 4, "rent": 850 },
      { "month": 5, "rent": 900 },
      { "month": 6, "rent": 950 },
      { "month": 7, "rent": 1000 },
      { "month": 8, "rent": 1000 },
      { "month": 9, "rent": 950 },
      { "month": 10, "rent": 850 },
      { "month": 11, "rent": 800 },
      { "month": 12, "rent": 750 }
    ],
    "unavailabilities": [
      { "from": "2026-10-01", "to": "2027-01-31", "reason": "Unavailable" }
    ],
    "bookingWindows": [
      {
        "minStartDate": "2027-02-01",
        "maxStartDate": "2027-06-30",
        "minEndDate": "2027-05-01",
        "maxEndDate": "2028-01-31"
      }
    ],
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2026-04-19T14:22:00.000Z"
  }
]

Every entry in rentsPerMonth, unavailabilities and bookingWindows also carries its own createdAt and updatedAt, left out above. The list only includes unavailabilities that end today or later.

Errors

Status	message	Cause	What to do
401	Missing integration credentials and others	Missing or wrong partner token	See Authentication
503	This integration is not configured yet. Contact VIVIN support.	Single-landlord feed not set up yet	Contact VIVIN. Retrying does not help
503	The service is busy. Please try again in a moment.	VIVIN is briefly overloaded	Retry after the seconds in the Retry-After header

Retrieve a listing

GET /<prefix>/listings/{externalId} returns one listing, read live. Use it right before you confirm a booking.

Path parameters

Name	Type	Required	Description
externalId	string	Yes	Your platform's ID for the unit, as in the list. On single-landlord feeds, only the VIVIN unit ID (a UUID) is accepted

Example request

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

Response

200 OK with one listing object, the same shape as an item of the list. Unlike the list, it can also return unavailabilities that ended in the past: ignore them.

Errors

Status	message	Cause	What to do
404	Listing not found for <platform> with externalId <id>	The ID is not linked to a unit for your platform, the unit is excluded from your feed, or the unit or its property is archived	Take the ID from the list. Ask the landlord to check the link
404	Listing not found for <platform> with listingId <id>	Single-landlord feeds: the UUID is not a unit of that account, or the unit is not exported	Take the ID from the list
404	Listing not available	The unit has no usable rent	Ask the landlord to set a rent
401, 503	As in List listings

<platform> is your platform's lowercase name, for example uniplaces.

Which listings appear

A unit is in your feed only when all of these are true:

1. The landlord linked it to your platform in the unit's Channels section (Property and unit mapping). Your ID becomes the externalId.
2. It is Included in feed for your platform, under the unit's Full integration tab, Integration listings section. Units are included by default.
3. The unit is not archived, and its property is not archived.
4. It has a usable rent. A fixed rent must be above 0. A rent that varies by month needs at least one entry in rentsPerMonth, and every entry must be above 0. You never receive rent: 0.

A unit that fails a rule is missing from the list, and its single-listing request returns 404.

The listing object

Field	Type	Description
externalId	string	Your platform's ID for the unit, as the landlord linked it
listingInternalName	string, optional	The unit's name in VIVIN. Single-landlord feeds only
availableFrom	date or null	The first date a new stay can start (Reading availability)
minStayPeriod	integer or null	Minimum stay in months. 0 or null: no minimum
maxStayPeriod	integer or null	Maximum stay in months. 0 or null: no maximum
isRentFixed	boolean	true: the same rent every month. false: charge each month from rentsPerMonth
rent	number	Monthly rent with the landlord's markup for your platform. When isRentFixed is false, the highest month (Rent and markup)
rentsPerMonth	array	Rent per calendar month: month (1–12) and rent, with markup. Normally all 12 months; treat a missing month as unpriced and ask the landlord
capacity	integer	Maximum number of occupants
extraPricePerTenant	number	Extra monthly charge for each occupant after the first. Always 0 when capacity is 1
cleaningFeeValue	number	The property's cleaning fee. How often it is charged is not in this payload. Normally 0 when the fee is off
billsIncluded	boolean	Whether utility bills are included in the rent
billsIncludedMaxValue	number or null	Monthly amount of bills included. null: no cap is published, for example with All bills included (no cap). 0 is a real amount of zero
adminFeeValue	number	Flat admin fee, rounded up. 0 when the fee is off. Use it only when adminFeeMode is fixed
adminFeeMode	fixed or tiered	How the admin fee is set (Admin fee). fixed when the fee is off
adminFeeTiers	array	fromDays and value for each tier, by fromDays ascending, when adminFeeMode is tiered. Otherwise []
depositValue	number	Deposit for one occupant: the property's fixed amount, or a multiple of the unit's rent (its highest month when rent varies). No markup
landlordEmail	string	The Integration Email on your platform's card under Settings → Integrations → Booking Platforms. The same on every listing of that landlord. Missing or null if the landlord has not set one
unavailabilities	array	Blocked nights: from, to, reason (Reading availability)
bookingWindows	array	Allowed move-in and move-out ranges: minStartDate and maxStartDate (check-in), minEndDate and maxEndDate (check-out)
createdAt, updatedAt	timestamp	When the unit record was created and last edited in VIVIN. New bookings and blocks do not change updatedAt

• Amounts are in the landlord account's currency (EUR for most accounts). The payload has no currency field.
• Dates are YYYY-MM-DD. A few rows VIVIN generates carry a full timestamp at midnight UTC: read the date part only.
• The exit fee, the local rent cap (dual pricing) and the extra deposit per tenant are not in this payload, and rent is never split by the cap.

Rent and markup

Landlords can set a Markup (none, a percentage or a fixed amount) on your platform's card under Settings → Integrations → Booking Platforms. It is added to rent and to every rentsPerMonth[].rent, and the result is rounded up to a whole number, even with no markup. No other amount gets the markup: extra occupant charge, cleaning fee, deposit and admin fee are published as the landlord set them.

When isRentFixed is false, charge each month of the stay from rentsPerMonth. rent is only a headline, the highest month: in the example, a January stay costs 750 a month, not 1000.

Admin fee

adminFeeMode	Fee to charge
fixed	adminFeeValue. adminFeeTiers is []
tiered	A value from adminFeeTiers, by stay length. Ignore adminFeeValue, which may match no tier

{
  "adminFeeValue": 200,
  "adminFeeMode": "tiered",
  "adminFeeTiers": [
    { "fromDays": 0, "value": 250 },
    { "fromDays": 65, "value": 350 },
    { "fromDays": 95, "value": 400 }
  ]
}

1. Count the days between check-in and check-out in UTC, without the check-out day. From 1 to 4 September is 3 days.
2. Take the tier with the highest fromDays that is not above that count. The last tier has no upper limit.

In the example, a 70-day stay pays 350 and a 200-day stay pays 400. Tier values are published as set, without rounding.

Reading availability

Each unavailabilities row is a blocked range:

• from is the first blocked night.
• to is the last blocked night, included. The first night a new stay can start is the day after to.

Row in the example	Date
First blocked night (from)	1 October 2026
Last blocked night (to)	31 January 2027
First possible check-in	1 February 2027

avviso

Do not read to as a check-out or first free day. If you do, you offer a night that is still occupied: VIVIN queues your booking, then refuses it in the background for overlapping nights, and only the landlord is told.

• Rows cover bookings, the landlord's manual blocks and Airbnb or Booking.com stays. When the landlord uses preparation days between stays, to already includes them.
• Honour every row, whatever its reason. Rows stored in VIVIN say Unavailable; Housing Anywhere adds Booking window restriction rows.
• A stay can start on the day after a row's to and end on a row's from.
• availableFrom is the first date from which a stay of at least minStayPeriod months fits before the next block, pushed back by the landlord's advance notice if one is set. It can be null. VIVIN recalculates it when the calendar changes and every few hours, so paint your calendar from unavailabilities.

Stay rules and booking windows

Show minStayPeriod, maxStayPeriod, capacity and bookingWindows on your platform and enforce them there. A booking from your platform that breaks the stay length or capacity rules is still created, with a warning for the landlord. VIVIN does not check booking windows or availableFrom at all: of the calendar rules, it only refuses overlapping nights (Booking lifecycle and validations).

Blocks VIVIN adds to the feed

Some rows exist only in your feed, not on the landlord's calendar:

Row	When
Calendar Block	The landlord set Calendar Block (days) on your platform's card, and the unit's latest block ends more than that many days from today. The row runs from that block's last night to two years later, so far-future stays are not sold
Before availableFrom	Spacest only: when availableFrom is in the future, a row from today to the day before it
Booking window	Housing Anywhere only: see Housing Anywhere

Platform differences

Housing Anywhere

GET /housinganywhere-integration/listings and /listings/{externalId} return the same listing object with these differences:

• adminFeeValue, depositValue, cleaningFeeValue, billsIncludedMaxValue and extraPricePerTenant are rounded up to whole numbers.
• A costs array lists the fees, in the same currency units as the rest of the listing. Each line has type, value, payableAt, payableBy, refundable, estimated and mandatory.

type	Taken from	payableAt
security-deposit	depositValue	move-in
administration-fee	adminFeeValue	move-in
cleaning-fee	cleaningFeeValue	monthly
utility-bills	billsIncludedMaxValue	monthly

• A line with value 0 has payableBy: "landlord". A line with no amount has value: null.
• When bills are not included, utility-bills is an estimated monthly line paid by the tenant. When they are included, it has payableBy: "included-in-rent", and internet-bill, gas-bill, electricity-bill and water-bill lines are added as included-in-rent with value: null.
• Booking windows: VIVIN takes the earliest window that can still be used (its latest check-in is today or later, and no block covers all of its check-in dates). It adds a Booking window restriction row from today to the day before its earliest check-in (when that is in the future), and another from the day after its latest check-out to about ten years from today. It also replaces minStayPeriod and maxStayPeriod with the window's length in months, rounded down and up, so a window shorter than a month shows 0 and 1.
• The Housing Anywhere full feed uses a different shape, in cents.

Single-landlord feeds

A single-landlord feed serves one landlord. VIVIN sets it up and gives you its prefix (<landlord>-integration).

• It returns all of that landlord's units, linked or not. Rules 3 and 4 of Which listings appear still apply.
• externalId is your ID when the unit is linked, otherwise the VIVIN unit ID (a UUID). Each listing also has listingInternalName, so you can match units by name.
• GET /listings/{externalId} accepts only a VIVIN unit ID, even for a linked unit. Any other value returns 404.
• Every route answers 503 This integration is not configured yet. Contact VIVIN support. until VIVIN has finished setting the feed up.

Keeping in sync

VIVIN does not push listing or availability changes to your platform: polling is the only way to stay current. The Vivin Booking Engine is the one exception (Updates VIVIN sends to the engine).

1. Pull the list on a schedule, for example every 15 to 30 minutes. Polling more often than every 10 minutes returns the same data.
2. For each listing, replace your stored calendar with the new unavailabilities. Do not detect changes with updatedAt: new bookings and blocks do not change it.
3. Treat a listing that disappears from the list as no longer for sale.
4. Before you confirm a booking, read GET /<prefix>/listings/{externalId} for live availability and price.

Listing routes are not rate-limited. A failed list read can wait for your next poll; see Retries.

Troubleshooting

Symptom	Likely cause and fix
A unit the landlord expects is missing	It fails a rule in Which listings appear. Its single-listing request tells you which: Listing not available is the rent
A unit linked minutes ago is missing from the list	The list is up to about 10 minutes old. The single-listing request already has it
Your calendar sells a night that VIVIN then refuses	to was read as the check-out day. It is the last blocked night
Prices are slightly higher than the landlord's rent	The landlord's Markup for your platform, rounded up
The unit is blocked two years ahead	The Calendar Block (days) row. The landlord can change the setting on your platform's card

Related

• Property and unit mapping: how units are linked to your IDs
• Full listing feeds: photos, address and descriptions in your platform's format
• iCal feeds: calendar-only export
• Creating bookings: send a booking back to VIVIN
• Error handling: the error body and retries