API reference
The VIVIN API lets booking platforms and calendar tools read VIVIN listings and send bookings into a landlord's account, and lets landlords automate their own account.
Which API you need
| You are… | You use | Start with |
|---|---|---|
| A booking platform or marketplace partner | The partner API, with a partner token issued by VIVIN | Authentication |
| A calendar tool (Airbnb, Booking.com or any iCal client) | A per-unit iCal feed. It needs no token | iCal feeds |
| A landlord automating your own account | A management session: your VIVIN sign-in and an emailed code | Management session |
| A landlord connecting Claude or ChatGPT | OAuth for MCP connectors | MCP OAuth |
Base URL and Swagger
All routes live on https://api.vivin.app, over HTTPS only. Each partner integration has its own route prefix and its own live Swagger page:
- Swagger UI:
https://api.vivin.app/<prefix> - OpenAPI file:
https://api.vivin.app/<prefix>-json(or-yaml)
Swagger shows the full booking model as the response of POST …/bookings. The real response only confirms that the request was queued: see Creating bookings.
Route prefixes
Every partner path starts with the prefix, for example GET /uniplaces-integration/listings.
| Route prefix | Partner | Routes |
|---|---|---|
uniplaces-integration | Uniplaces | Partial and full feeds, bookings, inbound webhook |
housinganywhere-integration | Housing Anywhere | Partial feed (with costs), full feed, bookings, inbound webhook |
spotahome-integration | Spotahome | Partial and full feeds, the older /listings/feed, bookings |
inlife-integration | Inlife | Partial and full feeds, bookings |
roomless-integration | Spacest (formerly RoomLess) | Partial feed, bookings |
erasmus-life-integration | Erasmus Life Lisboa | Partial feed, bookings |
vivin-booking-engine-integration | Vivin Booking Engine | Partial feed, bookings, listing updates, property creation, housemates |
<landlord>-integration | Single-landlord feeds: one prefix per landlord, from VIVIN | Partial feed of one landlord's units, bookings |
ical-integration | Any calendar tool | One .ics calendar per unit |
Conventions
| Topic | Rule |
|---|---|
| Format | JSON bodies with Content-Type: application/json. Fields are camelCase, except where a partner's own format is snake_case |
| Dates | Calendar dates as YYYY-MM-DD. Timestamps (createdAt, updatedAt) are ISO 8601 in UTC |
| Amounts | The landlord account's currency, as plain numbers. The Housing Anywhere full feed and both webhooks use cents |
| IDs | externalId is your platform's ID for a unit (Property and unit mapping). VIVIN IDs are UUIDs |
| Errors | One JSON body for every error (Error handling) |
| Versioning | Partner routes are not versioned. New response fields can appear at any time: ignore fields you do not know |
| Rate limits | Partner and iCal routes are not rate-limited. Lists are rebuilt about every 10 minutes, so polling faster gains nothing |
| Push | VIVIN sends no outbound webhooks to partners, except listing updates to the Vivin Booking Engine. Poll the feeds to see changes (Webhooks and notifications) |
Getting access
- The landlord fills in the Integration Email on your platform's card under Settings → Integrations → Booking Platforms. VIVIN sets up single-landlord feeds directly.
- The landlord links each unit by adding its listing URL on your platform in the unit's Channels section. VIVIN reads your listing ID from that URL: it becomes the
externalId. - VIVIN issues your partner token and confirms your route prefix. Ask through Get help and support.
Reference guides
New partners usually read them in this order:
- Authentication: partner tokens, the other headers, every
401 - Error handling: the error body, status codes, retries
- Property and unit mapping: how your listing IDs map to VIVIN units
- Listings and availability: the partial feed, field by field
- Full listing feeds: catalogue feeds for Uniplaces, Spotahome, Housing Anywhere and Inlife
- iCal feeds: per-unit calendar export
- Creating bookings:
POST …/bookingsbody, response and errors - Booking lifecycle and validations: what happens after the
201 - Webhooks and notifications: inbound Uniplaces and Housing Anywhere webhooks
- Booking Engine API: Vivin Booking Engine write routes
Related
- Integrations settings: where landlords add and configure booking platforms
- Integrations and distribution: how channels, calendars and the booking engine fit together
- Connect Claude, ChatGPT or other AI tools: MCP connectors on a VIVIN account
- Get help and support: requesting API credentials