HOS AIHOS AI
Cloudbeds API v1.3 → HOS Events 0.1 · Unofficial · Synthetic data

Mapping · Experimental

The same early arrival, with the PMS speaking Cloudbeds.

The PMS side of the arrival scenario now starts as Cloudbeds API v1.3 payloads. Webhooks that name what happened and when, then the reservation or housekeeping status the integration fetches. A reference adapter turns them into 6 HOS facts, and the projection reaches the same outcome as the synthetic corpus.

Unofficial and experimental.

Written from Cloudbeds's published documentation and packages, listed below. HOS AI is not affiliated with Cloudbeds, and Cloudbeds has not reviewed or endorsed this mapping. Every payload is synthetic, and the adapter has not yet run against a live Cloudbeds environment. 2 webhook payloads are reconstructed, and each says so.

Delivered to HOS, in this order

0 / 13

Arrival-readiness projection

Waiting for facts

No situation

Deliver the first event, or play the whole scenario.

13 facts for the scenario's 13. Delivery 7 has no Cloudbeds counterpart. Cloudbeds adds a fact the corpus does not have. Occupancy: vacant, from getHousekeepingStatus. The condition event does not date it, so hostimebasis is recorded. The manifest makes the PMS the occupancy authority; readiness does not depend on it. Housekeeping and messaging facts are unchanged. Times are shown in the property time zone (Europe/Paris).

Mapping

From Cloudbeds payloads to HOS facts.

The adapter never forwards a PMS payload. It compares each fetched entity with what it already published and emits only the facts that changed, with ids that stay the same when a webhook is delivered again.

Cloudbeds to HOS Events 0.1 mapping
Cloudbeds eventWhenHOS Events 0.1How
reservation/createdconfirmed, not_confirmedreservation.created, stay.expectedtime is the webhook timestamp. One stay per booked room. The main guest's id becomes a pseudonymous guest_id; the planned check-in combines the room's startDate with the property's standard check-in time.
reservation/status_changedconfirmedreservation.updatedstatus confirmed, at the webhook timestamp.
reservation/status_changedchecked_in, checked_outstay.checked_in, stay.checked_outAt the webhook timestamp. The webhook's actor becomes a pseudonymous hosactor.
reservation/status_changedcanceled, no_showreservation.cancelled, reservation.updatedCloudbeds gives no cancellation reason; no-show becomes status no_show.
reservation/dates_changedDates movedreservation.updated, stay.expectedOnly the changed fields travel.
reservation/accommodation_changedA room is assigned or releasedstay.unit_assigned, stay.unit_unassignedThe room comes from getReservation; time is the webhook timestamp.
housekeeping/room_condition_changeddirty, clean, inspectedunit.status_changed · housekeepingThe same three conditions as HOS, read from getHousekeepingStatus.
housekeeping/*roomOccupiedunit.status_changed · occupancyDated when the occupancy event reports it; otherwise hostimebasis is recorded.
housekeeping/*roomBlockedunit.status_changed · commercialA blocked room is not sellable; Cloudbeds does not say whether maintenance is why.
roomblock/created, details_changedout_of_service, blocked_datesunit.maintenance_scheduledOne window per room of the block. Its days become instants like a stay's: from the first day's check-in time to the check-out time after the last day. out_of_service: out_of_service and not_sellable; blocked_dates: not_sellable.
roomblock/removed, or a room left the block—unit.maintenance_cancelledAt the webhook timestamp. Courtesy holds are commercial holds, not maintenance, and are left out.
Other eventsguest/*, accounting, notes, custom fields…Not mappedGuest profiles are personal data and stay in Cloudbeds; the others have no HOS 0.1 counterpart yet.

Findings

What Cloudbeds taught us about HOS 0.1.

Mapping a real PMS is the test the synthetic corpus could not provide. These are the gaps it exposed, in the source and in the specification.

Stays are planned in days.

startDate and endDate have no time. HOS Core now gives the Property standard check-in and check-out times, which getHotelDetails reports, to make them instants.

Events are precise; fetches are not always.

A webhook timestamp dates what its event reports. A fact only noticed in a fetch, such as occupancy during a condition change, gets hostimebasis recorded: HOS 0.1 already had the right tool.

Housekeeping already speaks HOS.

Cloudbeds has the same three room conditions as HOS, inspected included.

Who did it now has a place.

Status webhooks name the user who acted. HOS 0.1 now carries it as hosactor, a pseudonymous reference such as user:staff_r7.

One reservation, several rooms.

A Cloudbeds reservation can hold several rooms. Each room is now a stay of its own, as HOS Core allows, with its own dates and unit.

Payload spelling varies.

Reservation events say propertyID, guest events propertyId. The adapter accepts both, and the recording marks the two payloads it had to reconstruct.

A block's last day is an assumption.

Block dates are days. The adapter reads endDate as the last blocked night, as getRoomBlocks' filter on blocks that include a date suggests; a live property must confirm it.

Tasks are out of reach.

Cloudbeds assigns housekeepers to rooms rather than publishing tasks. This integration publishes no tasks.

Mapping kit

Check the mapping yourself.

The recording pins the PMS payloads, the adapter configuration and every difference from the synthetic corpus. The unit tests replay it and compare the outcome with the scenario's expected.json.

arrival-readiness.jsonThe 4 Cloudbeds deliveries: webhooks, what the integration fetched for them, the adapter configuration and every documented difference.
README.mdField-by-field mapping, its sources and limits, and what it taught us about HOS 0.1.

Sources