Skip to main content

Creating Bookings

First-time workspace setup

Submit POST /bookings only after Getting Started — Recommended Setup Sequence steps 11–14 — steps 11–12 set Integrations, Integration field capability, and Tenant categories default for integrations; step 13 maps each unit’s externalId (Property & Unit Mapping); step 14 validates how imported reservations appear in Bookings. Finish step 15 (Tenants) and Onboarding a New Property — Step 7 before production import volume. 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 Endpoint and Request Body, then Field Reference before your first POST /bookings. Send the mapped externalId from Property & Unit Mapping; read Booking Lifecycle & Validations for the enqueue pipeline after 201. Handle validation 400s with Error Handling; prefer Webhooks & Notifications over polling when callbacks are provisioned. 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: Creating Bookings section cross-reference · API Reference — API guide cross-reference.

When a tenant confirms a booking on your platform, submit it to Vivin using the booking creation endpoint. The endpoint queues the request; once the job runs successfully, Vivin creates the booking, blocks dates on connected channels, generates the payment schedule, and (if configured) triggers contract generation.

Endpoint​

Pair with other Creating Bookings sections

Authorize with Authentication before your first POST …/bookings call; inspect schemas in Try requests in Swagger. After enqueue, continue to Response and Booking Lifecycle & Validations. Full endpoint map: Creating Bookings section cross-reference.

POST /{platform}-integration/bookings HTTP/1.1
Host: api.vivin.app
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Inspect schemas live

Use Integration Swagger on your API host to expand the bookings (or your platform’s integration) group, open POST …/bookings, and use Try it out with a Bearer token. You will see the exact path prefix, required fields, and response models for your deployment. See API Reference index and Authentication.

Integration Swagger — POST …/bookings expanded with request body schema and Try it out

The capture shows a typical integration document (here Housing Anywhere): expand POST /{platform}-integration/bookings, use Try it out, and inspect required booking and tenant fields before you wire your client. Your provisioned prefix and path segment follow onboarding — see API Reference index.

Full pairing matrix: Creating Bookings section cross-reference.

Request Body​

Pair with other Creating Bookings sections

Confirm externalId in Listings & Availability and Property & Unit Mapping before you send tenant fields. Field-by-field rules: Field Reference. Full endpoint map: Creating Bookings section cross-reference.

{
  "checkInDate": "2026-09-01",
  "checkOutDate": "2027-01-31",
  "externalId": "abc-123",
  "bookingId": "550e8400-e29b-41d4-a716-446655440000",
  "numberOfExtraTenants": 2,
  "platformProviderPaymentValue": 150.0,
  "tenant": {
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "[email protected]",
    "phone": "+351912345678",
    "nationality": "PT",
    "identificationId": "12345678",
    "idDocumentType": "passport",
    "idDocumentCountry": "PT",
    "idDocumentExpiryDate": "2030-06-15",
    "fiscalId": "123456789",
    "fiscalAddress": "Rua Exemplo 123, Lisboa",
    "billingName": "Maria Silva",
    "billingFiscalId": "123456789",
    "billingAddress": "Rua Exemplo 123",
    "billingCity": "Lisboa",
    "billingPostalCode": "1000-001",
    "billingCountry": "PT"
  }
}

Full pairing matrix: Creating Bookings section cross-reference.

Field Reference​

Pair with other Creating Bookings sections

externalId must match Property & Unit Mapping; numberOfExtraTenants feeds operator pricing on Listings — Step 3 Extra payments. Post-enqueue validation: Booking Lifecycle & Validations. Full endpoint map: Creating Bookings section cross-reference.

Booking Fields​

FieldTypeRequiredDescription
checkInDatestring (ISO 8601)YesMove-in date (format: YYYY-MM-DD).
checkOutDatestring (ISO 8601)YesMove-out date (format: YYYY-MM-DD).
externalIdstringYesThe external listing ID on your platform. Must match a listing mapped in Vivin (see Property & Unit Mapping).
bookingIdstring (UUID)RecommendedStable identifier for this reservation on your side. Must be a UUID when supplied (per request validation). On success it is stored on the Vivin booking as the external integration id (integrationId) for correlation. Retries after a successful 201 can still enqueue another job unless your client deduplicates; overlapping stays on the same listing are rejected when the worker creates the booking.
numberOfExtraTenantsintegerNoTotal number of occupants for the stay, including the lead tenant. Omit the field or send 0 for a single occupant. For n ≥ 2, Vivin stores n - 1 as internal “extra tenants”, which feeds extraPricePerTenant / extraDepositPerTenant calculations on the created booking. Sending 1 is therefore treated the same as a solo booking (0 stored). The JSON name is historical; think of it as headcount, not “extras only”.
platformProviderPaymentValuenumberNoAmount (EUR) that your platform has already collected as commission or that the platform will pay directly. This is recorded in Vivin for reconciliation but does not affect the tenant's payment schedule.

Tenant Fields​

FieldTypeRequiredDescription
firstNamestringYesTenant's first name (minimum 2 characters).
lastNamestringYesTenant's last name (minimum 2 characters).
emailstringYesTenant's email address. Used for communications and tenant portal access.
phonestringNoPhone number with country code (e.g. +351912345678).
nationalitystringNoISO 3166-1 alpha-2 country code (e.g. PT, BR, DE).
identificationIdstringNoID document number.
idDocumentTypestringNoType of ID document (e.g. passport, id_card, residence_permit).
idDocumentCountrystringNoCountry that issued the ID document (ISO 3166-1 alpha-2).
idDocumentExpiryDatestringNoExpiry date of the ID document (YYYY-MM-DD).
fiscalIdstringNoTax identification number (NIF in Portugal).
fiscalAddressstringNoFiscal/tax address.

Billing Fields (Optional)​

If your platform collects billing information, include it to pre-populate invoicing in Vivin.

FieldTypeDescription
billingNamestringName for billing/invoicing.
billingFiscalIdstringTax ID for billing.
billingAddressstringBilling street address.
billingCitystringBilling city.
billingPostalCodestringBilling postal code.
billingCountrystringBilling country (ISO 3166-1 alpha-2).
useCompanyBillingbooleanIf true, billing is issued to a company rather than the individual.

Bank Details (Optional)​

If the tenant provides bank details for deposit refund or direct debit purposes.

FieldTypeDescription
tenantIBANstringTenant's IBAN.
tenantSwiftBicstringSWIFT/BIC code.
tenantInterbankCodestringInterbank code (where applicable).
tenantBankstringBank name.
tenantBranchstringBank branch.
tenantBankAddressstringBank address.
tenantBankCitystringBank city.
tenantBankCountrystringBank country (ISO 3166-1 alpha-2).

Full pairing matrix: Creating Bookings section cross-reference.

Response​

Pair with other Creating Bookings sections

Treat 201 Created as enqueue acknowledgement — not proof the booking exists yet. Async pipeline: Booking Lifecycle & Validations; prefer booking.* events in Webhooks & Notifications over blind retries. Full endpoint map: Creating Bookings section cross-reference.

Success (201 Created)​

A successful call accepts the payload and inserts a scheduled create-booking job (status: "new"). The response body is not the final Booking resource. It is an enqueue acknowledgement from persistence, typically including:

  • identifiers — e.g. [{ "id": "<scheduled-row-uuid>" }], the id of the queued row
  • generatedMaps — driver-dependent map of generated column values (often mirrors inserted fields)
  • raw — driver-specific payload

Exact shape can vary slightly by database driver; treat it as an acknowledgement that the request was persisted for background processing, not as the created booking’s id or lifecycle state.

Background processing​

After the HTTP response:

  1. A worker picks up scheduled rows and runs listing/account resolution, availability, booking rules, and tenant creation.
  2. If validation succeeds, a real booking is created, dates are blocked, and the payment schedule is generated (and contract automation may run according to account settings).
  3. If validation fails, the job is marked failed internally; the HTTP client has already received 201 for the enqueue step, so you should not assume success from 201 alone.

Request schema validation (required fields, formats) runs with the HTTP request. Business validation (availability, windows, capacity, etc.) happens in the background step above.

bookingId and retries

Treat 201 Created as “accepted into the processing queue”, not as proof the booking already exists in Vivin. For transport retries, use the same bookingId (UUID) you would have used for that reservation so any successfully created booking lines up with your id; avoid blindly retrying after a timeout without checking Vivin or deduplicating on your side, because each accepted request inserts a new scheduled job.

Full pairing matrix: Creating Bookings section cross-reference.

Minimal Example​

Pair with other Creating Bookings sections

Use this payload only when you lack billing or bank fields — expand to the full Field Reference before production traffic. Operator follow-up after success: Processing a New Booking. Full endpoint map: Creating Bookings section cross-reference.

If you only have basic information about the booking, you can submit a minimal payload:

{
  "checkInDate": "2026-09-01",
  "checkOutDate": "2027-01-31",
  "externalId": "abc-123",
  "tenant": {
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "[email protected]"
  }
}

The three required tenant fields are firstName, lastName, and email. The API also enforces a minimum length of 2 characters on firstName and lastName. All other tenant fields are optional but recommended for a complete booking record.

Full pairing matrix: Creating Bookings section cross-reference.

Creating Bookings section cross-reference​

Use this table when one endpoint group naturally leads into operator UI, another API guide, or a downstream workflow — each row links to the docs you should read before or after wiring POST …/bookings.

API topic / sectionPair with these docs
EndpointAuthentication, Error Handling (401 / 403), Try requests in Swagger
Request BodyProperty & Unit Mapping (externalId), Listings & Availability (verify unit before enqueue)
Field ReferenceBooking Lifecycle & Validations, Settings > Tenant categories, Listings — Step 3 Extra payments
ResponseBooking Lifecycle & Validations, Webhooks & Notifications (booking.* events), Error Handling (async validation failures), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent)
Minimal ExampleProcessing a New Booking, Creating Bookings — Field Reference (production payloads), Notifications — Payment overdue alerts → Handling a Late Payment — Step 1, Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent)

| Lockout catch-up after password recovery | Import enqueue backlog after sign-in recovery | Common Workflows — Lockout catch-up, Webhooks & Notifications, Processing a New Booking | | Pending manual receipt approval | Imported stays with pending confirmation receipts | Common Workflows — Pending manual receipt approval, Managing a Check-in — Step 3b, Finance — Pending manual payments | | Reject/revert mistaken receipts | Duplicate enqueue or wrong-booking receipts | Common Workflows — Reject/revert mistaken receipts, Cancelling a Booking, Payment Allocation — Correcting mistaken receipts | | Portfolio segmentation by tenant category | Segment triage on imported bookings | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Bookings — Other filters | | Notification row-click navigation | Enqueue creates in-app operator rows | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | payment overdue after POST /bookings | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Booking created on first imports | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Receivables after import alert triage | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Partner import payment overdue → collections Steps 1–6 after row-click | | Finance Income status drill-down | Scheduled skew after enqueue | 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 | Collections bars after import settlement | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Creating Bookings guide sections

Related below links POST /bookings enqueue 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: Creating Bookings section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Creating Bookings guide sections

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

Documentation map & escalation​

Pair with other Creating Bookings guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Full pairing matrix: Creating Bookings section cross-reference.

Companion API guides​

Pair with other Creating Bookings guide sections

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

  • Listings & Availability — GET /listings partial pulls to verify externalId before enqueue
  • Booking Lifecycle & Validations — Step-by-step validation table after enqueue (availability, windows, stay length, duplicate bookingId handling)
  • Webhooks & Notifications — Optional push events (booking.created, booking.cancelled, calendar blocks) when Vivin configures callbacks for your platform
  • Property & Unit Mapping — How externalId and listing keys map before POST …/bookings accepts a payload
  • Error Handling — 409 overlap and 422 business-rule responses on enqueue
  • Authentication — Bearer token required on every POST …/bookings call
  • Booking engine integration — White-label POST /bookings on the same queue and validation pipeline
  • Full listing feeds — Rich catalogue context partners validate against before enqueue
  • iCal feeds — Calendar retrofeed imports that may need a separate POST /bookings confirmation after availability blocks land
  • Management session — Operator JWT contrast; integration Bearer keys return 401 on AI usage

Upstream & downstream workflows​

Pair with other Creating Bookings guide sections

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

Operator UI & settings​

Pair with other Creating Bookings guide sections

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

Deeper concept reads​

Pair with other Creating Bookings guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Creating Bookings section cross-reference · API guide cross-reference.

Deeper workflow reads​

Pair with other Creating Bookings 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: Creating Bookings section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Creating Bookings guide sections

Partner POST /bookings may continue during operator lockout — reconcile import alerts and status filters after sign-in recovery. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: creating-bookings-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Creating Bookings guide sections

Partner enqueue creates Layer 1 schedules; confirmation receipts on imported Upcoming stays pair with Payment Allocation. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: creating-bookings-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Creating Bookings guide sections

Duplicate POST /bookings enqueue and mistaken OTA receipts pair with Cancelling a Booking and Reject / Revert. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: creating-bookings-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Creating Bookings guide sections

Send tenant segment context via account default for integrations — pair with Settings > Tenant categories and Field Reference. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: creating-bookings-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Creating Bookings guide sections

Successful POST /bookings enqueue surfaces operator /notifications rows — row-click after 201 to validate imported reservation shape. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Creating Bookings section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Creating Bookings guide sections

Ongoing/Ended payment overdue in-app rows after partner imports — confirm booking balance before Finance → Overview → Debt Aging. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Creating Bookings section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Creating Bookings guide sections

First POST /bookings volume often triggers Upcoming Booking created alerts — pair with Processing a New Booking — Step 5b. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Creating Bookings section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Creating Bookings guide sections

Partner POST /bookings imports that enqueue payment overdue rows need portfolio Top debtors after single-booking triage. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Creating Bookings section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner POST /bookings imports that enqueue payment overdue rows still need operator Handling a Late Payment — Steps 1–6 after receivables triage. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: creating-bookings-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Creating Bookings guide sections

Partner imports may inflate Scheduled segments — reconcile Income chart segment-click with Debt Aging before high-volume traffic. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Creating Bookings section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Creating Bookings guide sections

Partner-import collections may lag Cash flow forecast month bars until enqueue jobs finish and operators approve receipts. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Creating Bookings section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Creating Bookings guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Creating Bookings section cross-reference.

Module documentation hubs​

Pair with other Creating Bookings guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen operator follow-up. Full pairing matrix: Creating Bookings section cross-reference.

  • Bookings module — Operator UI for reservations created via POST /bookings (hub)
  • Tenants module — Operator enrichment of imported tenant profiles (fiscal ID, categories) after enqueue succeeds (hub)
  • Utilities module — Bills Included ceiling model, Connections, AI bill upload, and tenant overage charges on payment plans (hub)
  • Operations module — Maintenance tickets, cash flows, check-in/out coordination, Draft ticket queues, and linked cash flows (hub)
  • Dashboard module — Post-login Today, Total debt, Vacant Units, and forecast KPI snapshot with bell notification triage (hub)
  • Analytics module — Month-range portfolio KPI charts (Overview, Revenue, Occupancy, ADR, RevPAR, Maintenance) with rankings and heatmaps (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 (Overview, Income, Contract Values, Transactions, Payouts, Deposits) with payment approval and deposit settlement (hub)
  • Sales module — Portfolio availability, monthly rent editing, and channel manager connections (hub)
  • Inbox module — Portfolio-wide WhatsApp workspace with Dashboard bell Inbox sub-tab deep links (hub)
  • Notifications module — Full /notifications history with search, filters, and row-click navigation (hub); Payment overdue alerts when imported schedules are overdue
  • AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools for portfolio Q&A (hub)
  • Audit module — Portfolio-wide Manual Blocks and Discounts contract-value review (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)