Documentation / Guides
Mapping behavior
Choose a policy, read placements and keep the right details on each offer.
What you get back
Each entry in rooms[] is one bookable room, with the supplier offers (rates) that sell it. Rooms that differ only in bed set-up or occupancy share a roomTypeId and roomTypeName; roomTypes[] lists them. So a hotel's "Deluxe Room, King Bed" and "Deluxe Room, 2 Twin Beds" are two rooms of one room type, and the King offers from every supplier sit together in the first.
hotel.roomFit (0 to 1) is how well the room names you sent fit the room list we hold for that hotel: one number for the whole call, not a score per room. A low value usually means the wrong hotel or a hotel whose rooms we know little about. hotel.confident is true when the fit is 0.5 or more, or when you sent our hotel ID.
| To show | Group offers by |
|---|---|
| One card per bookable room (Expedia style) | roomId |
| One card per room type, with bed choices inside (Booking.com style) | roomTypeId, then roomId |
This is the response for keys made from 13 Nov 2026 (response: "rooms", cardLevel: "exact"). Keys made earlier get the original full response with room-type cards; any request can choose with response and cardLevel.
Evaluating mlr-1
Score rooms[].roomId against labels of bookable rooms, under our room definition: tier, class, view, features, accessibility, bed set-up and occupancy separate rooms; meal plan, refundability, promotions, smoking and spelling do not. On 1,000 blind hotels that gives B³ F1 93.1, purity 94.4, completeness 91.8. To score room types, group by roomTypeId and use labels that ignore beds and occupancy.
Scoring room types against bookable-room labels (or the reverse) mixes two levels and reads as wrong merges (or missed ones): a room type holds its King and Twin rooms by design.
Request shapes
Use POST /v1/room-mappings with one hotel's complete inventory. Send the Plexe hotelId when known, or the hotel name with city and ISO two-letter country code. Supplier room IDs are not interchangeable with catalogue IDs.
| Original shape | Alternative shape |
|---|---|
hotelId or hotelName | hotel: {id} or hotel: {name, city, country} |
roomRates[] with unique index | rates[] with unique rateId |
mode, mergePolicy, onLowConfidence | placementPolicy, doubtfulHotelPolicy |
Keep roomName exactly as received. Send every offer, including repeated names, with supplier details where available. Both shapes accept include and contentPreference. Do not mix policy fields between shapes: a body containing roomRates uses the original shape and ignores unknown fields. The alternative shape rejects unknown fields and folds equivalent name spellings before the model call, so changing shapes can change results.
Mapping policies
| Option | Behavior |
|---|---|
mode: "standard" | Uses catalogue candidates. Default and the only batch mode. |
mode: "consolidated" | Uses website-derived categories when available, with catalogue fallback while loading or after failure. Categories can span saleable variants; read the warnings. |
mergePolicy: "strict" | Adds evidence-based picking for close calls and offer conflict checks. It can abstain or choose a different target, and can increase room counts. |
onLowConfidence: "ungrouped" | Holds the entire hotel inventory when the property's room fit is poor. This is not a per-offer score cutoff. |
In the alternative shape, placementPolicy is lenient, guarded (default) or strict; doubtfulHotelPolicy is place (default) or hold. It always uses standard mode.
Account policy can enable guards on standard calls or preserve a previously evaluated policy. Check policyVersion; additional supplier fields alone do not enable checks that the account's policy disables. A policy version describes rules, not a frozen model or catalogue snapshot.
There is no numeric mapping-threshold request parameter. Similarity is not a calibrated correctness probability. Strict mode does not mean every offer receives an LLM check: confident encoder matches can still use the fast path.
Evidence and reanchoring
The model proposes categories from room names. Enabled guards check recognized beds, views, wings and affirmative room-specific descriptions for conflicts, including offers with identical names. Missing values remain unknown. occupancy is the requested party size; it can rule out a room only against known maximum capacity.
Reviewed property records can recover a category or reanchor an offer to a different category. This uses exact names or explicitly reviewed variants within the resolved property. It preserves qualifiers rather than guessing equivalence from generic room names. Records supplement the catalogue and are not a complete supplier-code crosswalk.
A recovered placement remains tier: "inferred". placement.evidence carries category sources, review date, revision and match method. If the target changes, placement.similarity is null because the previous score measured a different target. Category changes or offer separation can change room IDs; keep rate IDs to reconcile updates.
Unsupported aliases can remain unresolved with reason room_ambiguous. Keep those offers visible. Repeating the same request does not supply missing evidence. Whole-hotel holds, active feedback and applicable offer-conflict checks still take precedence.
reason: "evidence_match" requires an acknowledged evidence-based picker result. Failed or invalid picker decisions can remain unresolved with reason: "undecided". An inferred match or a high similarity score is not a booking confirmation.
Content and prices
rooms[].name is the proposed category heading, not confirmation of every offer's benefits. For example, “Golf View” or “Lounge Access” in an inferred heading must not become a guaranteed badge on every rate. Keep the original roomName visible and use that offer's supplier details for booking attributes.
rooms[].supplierContent collects images, descriptions, amenities, beds and views from the supplied offers. Source rateIds identify where details came from. contentPreference controls supplier ordering for content; it does not establish room identity. The optional include: ["attributes"] returns extracted attributes where a reader is configured; it does not change grouping.
Send size ({"value": 32, "unit": "sqm"} or "sqft") and maxOccupancy ({"adults", "children", "total"}, the most guests the room holds) whenever your supplier gives them, often from its hotel content rather than its rates. Two offers whose sizes differ by more than 30%, or whose maximum adults differ by 2 or more, are never put in one bookable room; they can still share a room type. Offers that do not state them are grouped as before. Both come back in the room's content.
Send smokingAllowed: true or false only when explicitly known. Omit it otherwise. Room summaries return a smoking value only when every offer supplies the same boolean. Display labels omit smoking qualifiers without changing original supplier names or implying non-smoking.
nightlyPrice and currency order offers within a room cheapest first when priced offers share a currency. Prices are not converted. Check dates, occupancy, meals, taxes and cancellation terms before treating prices as comparable, and refresh prices and availability at shopping time. Aggregated occupancy is not maximum room capacity.
Correcting a mapping
Use POST /v1/feedback with the returned hotel ID and original supplier room names. Feedback is scoped to your API key.
not_in_room: supply the room ID that those names must leave.different_rooms: prevent the reported names from sharing a group.same_room: records your report; it does not currently merge rooms.
Applied separations return the affected offers on their own. List reports with GET /v1/feedback?hotelId=…, or withdraw one with DELETE /v1/feedback/{feedbackId}. Limits are 2,000 reports per key, including withdrawn reports, and 200 active reports per hotel. Repeated active reports return the existing report.
Compatibility
Build new displays on rooms[], per-rate placement, hotel.resolution and notices[]. Legacy groups[], matchedRoom, catalogued, decidedBy, encoderScore, warnings, timingsMs and usage remain available. Any removal date will be announced at least 30 days ahead.
Display-only label cleanup preserves IDs. Corrections to category identity can change them. A stored response is the result at submission time; submit a fresh complete inventory to evaluate current rules and evidence.