Light Booking

Light booking is a special booking method enabled on a per-partner basis by agreement with Joivy sales. It relaxes the set of mandatory fields required to place a booking, allowing a room to be reserved with minimal tenant data while the remaining information is gathered post-reservation.

ℹ

Availability: light booking must be explicitly enabled for your webhook configuration by the Joivy sales team. It is not available by default. Contact your Joivy account manager to request activation.

How it works #

A standard booking immediately activates the contract in the Joivy platform — the tenant data is complete and the room transitions to an occupied state automatically. Light booking follows a different lifecycle:

Partner submits a light booking

The partner sends POST /Booking with the reduced mandatory field set. The room is immediately blocked — no other booking can claim it.

Room reserved, contract pending

The booking is registered but the contract is not automatically activated. The tenant record exists in a pending state.

Joivy sales completes the tenant data

The Joivy sales team contacts the tenant directly to collect the missing mandatory information (identity documents, tax code, address, etc.) required for contract activation.

Contract activated

Once all information is gathered and validated, Joivy activates the contract. The room transitions from reserved to fully occupied.

⚠

The room is blocked from the moment the light booking is accepted. Even though the contract is not yet active, the unit is no longer available to other callers. Treat the light booking call as a binding reservation.

Required fields #

The following fields must be present in a light booking request. Fields marked conditional are required only when the corresponding commercial condition has a value.

Top-level booking fields

bedCode string required Bed code identifier for the unit being reserved

externalReference string · min 1 required Your invoice number or unique booking ID

checkinDate date-time required Tenant check-in date (RFC 3339)

checkoutDate date-time required Tenant check-out date (RFC 3339)

deposit number required From commercialConditions.depositAmount

price number required Monthly base price — from commercialConditions.price

discountedPrice number conditional Required when commercialConditions.discountedPrice is present — must pair with discountUntil

discountUntil date-time conditional Required when discountedPrice is provided — from commercialConditions.discountUntil

downPayment number required Confirmation deposit — from commercialConditions.confirmationDeposit

feeTaxIncluded number required Portal fee including VAT (fee + VAT)

userData fields

A userData object is required with the following sub-fields populated. All other userData fields (tax code, address, nationality, etc.) may be omitted and will be completed by Joivy sales before contract activation.

userData.eMailAddress string required Tenant email address

userData.phonePrefix string required International dialling prefix, e.g. +39

userData.phoneNumber string required Tenant phone number (without prefix)

userData.name string required Tenant first name

userData.surname string required Tenant last name

userData.birthDate date-time required Tenant date of birth [YYYY-MM-DD]

Standard vs light booking #

The table below summarises the key differences between a standard booking and a light booking.

Aspect	Standard booking	Light booking
Availability	All partners	By sales agreement only
Room blocked on submission	Yes	Yes
Contract auto-activated	Yes	No — manual activation by sales
Full tenant data required	Yes	Partial — minimum set only
Missing data collected by	Partner / tenant at booking time	Joivy sales post-reservation
Endpoint used	`POST /Booking`	`POST /Booking` (same endpoint)
Response schema	`BookingResultDTO`	`BookingResultDTO` (same)

✓

Light booking uses the same POST /Booking endpoint and returns the same BookingResultDTO. The difference is in how the server processes the request — determined by your webhook configuration — not by a separate endpoint or a flag in the request body.

Example request #

The following is a minimal valid light booking request. All fields not listed here are optional for this booking method.

JSON · POST /Booking

{
  "bedCode":            "BED-00123",
  "externalReference": "PORTAL-INV-2024-0042",
  "checkinDate":       "2024-09-01T00:00:00Z",
  "checkoutDate":      "2025-08-31T00:00:00Z",
  "price":             750.00,
  "deposit":           750.00,
  "downPayment":       200.00,
  "feeTaxIncluded":    30.00,
  "userData": {
    "eMailAddress": "jane.doe@example.com",
    "phonePrefix":  "+39",
    "phoneNumber":  "3401234567",
    "name":         "Jane",
    "surname":      "Doe",
    "birthDate":    "1998-04-15T00:00:00Z"
  }
}

If the commercial conditions include a discounted price, also include:

JSON · with discount fields

{
  // ... other required fields ...
  "discountedPrice": 680.00,
  "discountUntil":   "2024-12-31T00:00:00Z"
}

Response

A successful light booking returns the same BookingResultDTO as a standard booking:

Response 200 / 201

{
  "tenantId":      "123e4567-e89b-12d3-a456-426614174000",
  "contractId":    "123e4567-e89b-12d3-a456-426614174000",
  "company":       null,
  "paymentIntent": null
}

Booking lifecycle #

A light booking moves through the following states after submission:

State	Who acts	What happens
Reserved	System (immediate)	Room is blocked; `contractId` is assigned; no other booking can claim the bed.
Pending activation	Joivy sales	Sales contacts the tenant to collect identity documents, tax code, home address, and other legally required fields.
Active	Joivy sales	All required data collected; contract formally activated in the platform. Tenant receives confirmation.

Do not re-submit if no immediate confirmation is received. The room is blocked from the first accepted request. Submitting the same booking a second time may result in duplicate entries or a 400 Bad Request. Use the contractId from the initial response to track the reservation status.

← back to guide Booking (standard) return to reference → xfeedreference.joivy.com