MAQAMI Travel

Cancel a confirmed tour or activity booking. First show the customer the refund from `getExperienceBookingCancelPreview` and wait for a clear yes. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

Cancel a confirmed hotel booking. First check the cancellation policy with `get_bookings_bookingid` and confirm with the customer: a non-refundable booking, or one past its free-cancellation deadline, can be charged in full. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

Look up a tour or activity booking: status, booking details and the voucher once it is confirmed. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

## Overview Preview the refund amount and cancellation fee for a booking before committing to cancel it. ## When to Use - **Cancellation confirmation screens** - Show the guest exactly what they'll be refunded - **Support tooling** - Check whether a booking is still cancellable before offering a refund ## What You Get - **`cancellable`** - Whether the booking can currently be cancelled - **`policy`** - `cancellationFee`, `refundAmount`, `refundType`, `estimateConfidence`, `currency`, `sellingPrice` ## Quick Start Use this with the `bookingId` from `POST /experiences/bookings`. This does not cancel the booking - `cancelExperienceBooking` cancels it. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

## Overview Returns the tax schema of a hotel as normalized static data, independent of the supply provider the rules were learned from. Each entry describes one tax or fee: whether it is already included in the room rate, whether it is a percentage of the rate or a fixed amount, and how fixed amounts scale (per adult and/or per night). ## When to Use - **Price transparency** - Show guests which taxes and fees apply at a property - **Amount-due-at-property estimates** - Excluded taxes are typically collected at the hotel - **Tax auditing** - Compare supplier-declared taxes against the reference schema ## Notes - Fixed amounts are expressed in USD - Percentage rates apply to the room rate (e.g. 13.5 means 13.5%) - The schema is learned by an offline pipeline; hotels without learned data return 404 - When the direct (hotel-declared) source is enabled, taxes declared by the hotel in MAQAMI Cloud take precedence over learned rules and each entry carries `source`, `chargeType`, `appliedPer`, `appliedOn`, `payAtProperty` and validity dates

Look up a confirmed hotel booking: status, hotel, dates, rooms, guests, price and cancellation policy. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

## Overview Get all available hotel chains (e.g., Marriott, Hilton, IHG). Use chain IDs to filter hotel searches by brand. ## When to Use - **Chain filters** - Filter hotels by chain/brand - **Brand selection** - Let users search for specific hotel chains - **Reference data** - Get chain IDs for use in search filters ## What You Get - **Chain list** - All available hotel chains - **Chain IDs** - Numeric IDs for use in search filters - **Chain names** - Hotel chain/brand names ## Quick Start No parameters required. Returns all hotel chains with IDs. Use chain IDs in hotel search filters.

## Overview Get a list of all cities within a specific country. Perfect for building location dropdowns and city selection interfaces. ## When to Use - **City dropdowns** - Populate city selection lists - **Location filters** - Filter hotels by city - **Geographic data** - Get city lists for specific countries - **Form autocomplete** - Build city autocomplete features ## What You Get - **City list** - All cities in the specified country - **City names** - Formatted city names ready for display ## Quick Start Provide the `countryCode` in ISO-2 format (e.g., "US", "GB"). Returns all cities in that country. Use the [Get Country List endpoint](/v3.0.0/reference/get_data-countries) to get country codes.

## Overview Get a complete list of all countries available in the system with their ISO-2 country codes. Essential for building country selection interfaces. ## When to Use - **Country dropdowns** - Populate country selection lists - **Location filters** - Filter hotels or searches by country - **Form inputs** - Build country selection forms - **Reference data** - Get country codes for use in other endpoints ## What You Get - **Country list** - All available countries - **ISO-2 codes** - Standard country codes (e.g., "US", "GB", "FR") - **Country names** - Full country names ## Quick Start No parameters required. Returns all countries with their ISO-2 codes.

## Overview Get all available currencies with their codes, names, and the countries where each currency is used. Perfect for building currency selection interfaces. ## When to Use - **Currency dropdowns** - Populate currency selection lists - **Price display** - Show prices in different currencies - **Currency conversion** - Get currency information for conversion - **Reference data** - Get currency codes for use in booking endpoints ## What You Get - **Currency list** - All available currencies - **Currency codes** - ISO currency codes (e.g., "USD", "EUR", "GBP") - **Currency names** - Full currency names - **Country mapping** - Countries where each currency is used ## Quick Start No parameters required. Returns all currencies with codes, names, and country mappings.

## Overview Get all available hotel facilities (amenities) with multi-language translations. Use these facility IDs to filter hotel searches by amenities. ## When to Use - **Facility filters** - Build amenity filtering in hotel searches - **Facility display** - Show available facilities with translated names - **Multi-language support** - Display facilities in user's language - **Reference data** - Get facility IDs for use in search filters ## What You Get - **Facility list** - All available hotel facilities - **Facility IDs** - Numeric IDs for use in search filters - **Multi-language names** - Facility names in multiple languages - **Translations** - Localized facility names ## Quick Start No parameters required. Returns all facilities with IDs and multi-language translations. Use facility IDs in hotel search filters.

## Overview Retrieve a list of airlines with optional filtering by name, alliance, and active status. ## When to Use - **Airline directory** - Build a searchable list of airlines for display or filtering - **Alliance filtering** - Filter airlines by alliance membership (Star Alliance, oneworld, SkyTeam) - **Active airlines** - Retrieve only currently operating airlines ## What You Get - **Full airline records** including name, IATA/ICAO codes, country, alliance, and logo URL - **Alliance membership** for each airline - **Active status** to identify currently operating carriers - **Filtered results** based on query, alliance, and active status parameters ## Quick Start Call with no parameters to get all airlines. Use `q` to search by name, `alliance` to filter by alliance, and `activeOnly=true` to exclude inactive carriers.

## Overview Retrieve a lightweight list of airline IATA codes with names for autocomplete and lookup purposes. ## When to Use - **Autocomplete dropdowns** - Populate airline search inputs with a minimal list - **Client-side filtering** - Download the full list once and filter locally - **Code validation** - Build a lookup table of valid airline codes ## What You Get - **IATA codes** for all airlines in the database - **Airline names** paired with each code - **Active filtering** available via the `activeOnly` parameter ## Quick Start Call with no parameters to get all airline IATA codes and names. Use `activeOnly=true` to filter out inactive airlines.

## Overview Retrieve full details for a specific airline using its 2-letter IATA code. ## When to Use - **Airline display** - Show airline name, logo, and alliance for a given IATA code - **Flight result enrichment** - Fetch airline details to display alongside search results - **Data validation** - Verify an airline code and retrieve its metadata ## What You Get - **Airline details** including name, IATA/ICAO codes, and country - **Alliance membership** (Star Alliance, oneworld, SkyTeam, or Vanilla Alliance) - **Logo URL** for displaying the airline's logo in your UI - **Active status** indicating whether the airline is currently operating ## Quick Start Provide the 2-letter IATA code (e.g., `AA` for American Airlines) in the URL path.

## Overview Search for airports by name, city, or IATA code using a text query. Returns matching airports for use in autocomplete and search inputs. ## When to Use - **Airport autocomplete** - Power origin/destination search inputs with type-ahead suggestions - **Airport discovery** - Find airports in a city or region by name - **Search validation** - Look up airports before constructing a flight search request ## What You Get - **Matching airports** ranked by relevance to the query - **IATA codes** for `legs[].origin` and `legs[].destination` in `post_flights_rates` - **City and country** details for display purposes - **Geographic coordinates** for map-based interfaces ## Quick Start Provide a `q` query string (minimum 2 characters) to search by airport name, city, or code. Returns matching airports ordered by relevance.

## Overview Retrieve a lightweight list of airport IATA codes with names for autocomplete and lookup purposes. ## When to Use - **Autocomplete dropdowns** - Populate airport search inputs with a full list of codes and names - **Client-side filtering** - Download the full list once and filter locally - **Code validation** - Build a lookup table of valid airport codes ## What You Get - **IATA codes** for all airports in the database - **Airport names** paired with each code - **Filtered results** when the `q` query parameter is provided ## Quick Start Call with no parameters to get all airport codes and names. Use the `q` parameter to filter by name or code.

## Overview Retrieve detailed information for a specific airport using its 3-letter IATA code. ## When to Use - **Airport display** - Show airport name, city, and country for a given IATA code - **Flight result enrichment** - Fetch airport details to display alongside origin/destination in search results - **Autocomplete validation** - Verify an airport code and retrieve its full details ## What You Get - **Airport details** including name, city, country, and timezone - **IATA and ICAO codes** for the airport - **Geographic coordinates** (latitude and longitude) - **Country and city** information for display purposes ## Quick Start Provide the 3-letter IATA code (e.g., `JFK` for John F. Kennedy International) in the URL path.

## Overview Get comprehensive details about a specific hotel including descriptions, amenities, images, location, and ratings. Perfect for displaying hotel detail pages. ## When to Use - **Hotel detail pages** - Show complete hotel information - **Booking pages** - Display hotel details before booking - **Hotel profiles** - Build rich hotel information pages - **Content display** - Show descriptions, amenities, and images ## What You Get - **Complete hotel information** - Name, address, description, and ratings - **Amenities list** - All available facilities and services - **Image gallery** - Hotel photos and images - **Location details** - Address, coordinates, and location information - **Hotel metadata** - Star rating, chain information, and classifications ## Quick Start Provide the `hotelId` as a query parameter. Returns complete hotel details including all metadata, amenities, and images.

## Overview **Beta Feature** - Ask natural language questions about a specific hotel and get AI-powered answers based on the hotel's information. ## When to Use - **Hotel Q&A** - Answer customer questions about hotels - **Information lookup** - Get specific details about amenities, services, or features - **Conversational interfaces** - Build chat interfaces for hotel information - **Detailed inquiries** - Ask about specific aspects like restaurants, parking, or amenities ## What You Get - **AI-generated answers** - Relevant responses to your questions - **Hotel-specific information** - Answers based on the hotel's actual data - **Natural language responses** - Human-readable answers ## Example Questions - "What amenities does this hotel have?" - "Is there parking available?" - "What does a meal at the restaurant look like?" ## Key Features - **Web search option** - Enable `allowWebSearch` to get additional information from the web - **Hotel context** - Answers are specific to the hotel you're asking about - **Natural language** - Ask questions conversationally ## Quick Start Provide the `hotelId` and your `question`. Optionally enable `allowWebSearch` for web-enhanced answers. **Note:** This is a beta feature and may be subject to changes.

Find hotels by name or place with a semantic text search. Returns up to 5 matches (set `limit` for more) with name, address, city, country and a relevance score. Check the name and city before using an `id`. For an exact hotel name, `get_data_hotels` with `hotelName` and `cityName` or `countryCode` is more precise.

## Overview Search and retrieve hotel listings based on various criteria. Get hotel metadata including names, addresses, ratings, amenities, and images for display in your application. ## When to Use - **Hotel listings** - Display hotel search results - **Location-based search** - Find hotels by city, coordinates, or Place ID - **Hotel discovery** - Browse hotels in specific areas - **Metadata retrieval** - Get hotel information for display ## What You Get - **Hotel list** - Matching hotels with complete metadata - **Basic information** - Names, addresses, ratings, and locations - **Amenities** - Available facilities and features - **Images** - Hotel photos for display - **Identifiers** - Hotel IDs for use in rate searches ## Search Options - **By city** - Search hotels in a specific city - **By coordinates** - Find hotels near latitude/longitude with radius - **By Place ID** - Get hotels within a specific place boundary - **By hotel IDs** - Retrieve specific hotels by their IDs ## Quick Start Provide search criteria (city, coordinates+radius, placeId, or hotelIds). Returns matching hotels with complete metadata.

## Overview **Beta Feature** - Search hotel rooms using visual and text-based queries. Uses image search technology to match your query against room images and find hotels with rooms that match your visual preferences, amenities, or style. ## When to Use - **Visual room search** - Find rooms based on visual characteristics like "luxury modernist comfort" or "blue accessible bathroom" - **Style-based search** - Search for rooms by design style like "art deco hotel room" or "brutalist room" - **Amenity-focused search** - Find rooms with specific features like "twin room with a city view" or "room with a skylight" - **Geographic filtering** - Limit results to hotels near a specific location using coordinates or Place ID - **City and country filtering** - Filter results by city and/or country ## What You Get - **Matching hotels** - Hotels grouped by hotel ID with rooms that match your query - **Room details** - Room name, image URL, and similarity score (rounded to 3 decimals) for each matching room - **Hotel metadata** - ID, name, address, city, country, and rating for each hotel - **Geographic filtering** - Optionally limit results to a specific area using coordinates or Place ID - **City and country filters** - Filter results by city and/or country code ## Example Queries - "luxury modernist comfort" - "an extremely fun room or art deco hotel room" - "luxurious accessible bathroom or blue accessible bathroom with walk in shower" - "twin room with a city view" - "a room filled with paintings" - "a hotel room with a skylight" ## Geographic Filtering You can optionally limit search results to a specific geographic area: - **Using coordinates**: Provide `latitude`, `longitude`, and optionally `radius` (in kilometers, default: 12km) - **Using Place ID**: Provide `placeId` - the place's location will be automatically fetched and the search will use the place's viewport boundaries (or the provided `radius` if viewport is unavailable) - **Using city/country**: Provide `city` and/or `country` to filter results by location ## Quick Start Provide a `query` parameter describing the room you're looking for. Optionally add geographic filtering with `latitude`/`longitude` or `placeId` to limit results to a specific area. **Note:** This is a beta feature and may be subject to changes.

## Overview **Beta Feature** - Search hotels using natural language queries. Uses AI to understand search intent and find hotels that match the meaning, not just keywords. ## When to Use - **Natural language search** - Let users search with phrases like "romantic getaway in London" - **Intent-based matching** - Find hotels matching the vibe or style, not just location - **Conversational search** - Support natural language hotel discovery - **Semantic matching** - Get hotels that semantically match the query ## What You Get - **Matching hotels** - Hotels that semantically match your query - **Semantic attributes** - Tags, persona, style, location_type, and story for each hotel - **Relevance scores** - How well each hotel matches the query - **Hotel metadata** - ID, name, photos, address, city, country ## Example Queries - "Romantic getaway in London with Italian vibes" - "Hotels near Paris" - "Family-friendly beachfront hotels" ## Quick Start Provide a natural language `query` parameter. Returns hotels with semantic matching scores and attributes. **Note:** This is a beta feature and may be subject to changes.

## Overview Get all available hotel type classifications (e.g., resort, boutique, business hotel). Use type IDs to filter hotel searches. ## When to Use - **Type filters** - Filter hotels by type in search - **Type display** - Show hotel type classifications - **Reference data** - Get hotel type IDs for filtering ## What You Get - **Hotel type list** - All available hotel types - **Type IDs** - Numeric IDs for use in search filters - **Type names** - Hotel type classifications ## Quick Start No parameters required. Returns all hotel types with IDs. Use type IDs in hotel search filters.

## Overview Get IATA (International Air Transport Association) airport codes with airport names, coordinates, and country information. Useful for airport-based hotel searches. ## When to Use - **Airport searches** - Find hotels near airports - **Location selection** - Let users search by airport codes - **Geographic data** - Get airport locations and coordinates - **Reference data** - Get IATA codes for use in hotel searches ## What You Get - **Airport list** - All available airports with IATA codes - **Airport names** - Full airport names - **Coordinates** - Latitude and longitude for each airport - **Country codes** - ISO-2 country codes for each airport ## Quick Start No parameters required. Returns all airports with IATA codes, names, coordinates, and country information.

## Overview Get all supported languages for hotel translations and content localization. Use language codes to request hotel data in specific languages. ## When to Use - **Language selection** - Display available languages to users - **Content localization** - Get language codes for API requests - **Multi-language support** - Build language switchers in your application - **Reference data** - Validate language codes before making requests ## What You Get - **Language list** - All supported and enabled languages - **Language codes** - ISO 639-1 codes (e.g., 'en', 'es', 'fr') - **Language names** - Human-readable language names in English ## Quick Start No parameters required. Returns all supported languages with codes and names. Use language codes in hotel search and detail requests.

## Overview Retrieve guest reviews and ratings for a specific hotel. Display authentic feedback from previous guests to help users make informed booking decisions. ## When to Use - **Review display** - Show guest reviews on hotel detail pages - **Rating aggregation** - Display average ratings and review counts - **Trust building** - Show authentic guest feedback - **Decision support** - Help users evaluate hotels before booking ## What You Get - **Guest reviews** - Individual review text and ratings - **Review dates** - When each review was written - **Ratings** - Numerical and textual ratings - **Guest feedback** - Detailed comments from previous guests ## Quick Start Provide the `hotelId` as a query parameter. Returns all reviews for that hotel with ratings and comments.

Look up a confirmed flight booking: status, passengers, flights, booking references, fare rules and price. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

## Overview Returns refund eligibility, estimated refund amounts, and penalty details for a booking **without actually cancelling it**. Useful before `post_flights_bookings_bookingid_cancellations` to understand the financial impact of cancellation. ## When to Use - **Pre-cancellation review** — Show the customer the potential maximum refund (not guaranteed) before they confirm cancellation - **Refund estimation** — Display potential maximum refund and penalty amounts in the booking management UI (refund is not granted until cancel completes) - **Eligibility check** — Determine whether the booking is within the void window (`isVoidable`) or eligible for a partial refund (`isRefundable`) ## What You Get - **`confidence`** — How reliable the quote is (`confirmed`, `estimated`, `heuristic`, `unknown`) - **`isRefundable` / `isVoidable`** — Quick eligibility flags - **`refund` / `penalty`** — Aggregate amounts with margin applied. `refund` is the potential maximum the airline may refund — not a granted/guaranteed amount - **`penalties[]`** — Itemised penalty breakdown when available - **`tickets[]`** — Per-ticket detail when available - **`destination`** — Where the refund goes - **`vouchers[]`** — Airline travel vouchers / credit-shells when `destination` is `voucher`; omitted when absent. Distinct from MAQAMI discount `voucherCode` on prebook ## Concurrent cancellation If a cancellation was already submitted and is still awaiting provider confirmation, this endpoint returns **HTTP 409** with code `49007` (`CONCURRENT_OPERATION`). A new quote is not available until that cancellation completes or fails. ## Refund amount caveat The `refund` amount on a cancellation quote is the **potential maximum** the airline may refund if cancellation proceeds under the quoted conditions. It is an estimate for decision-making only and is **not granted** — the final refund (if any) is determined when cancellation completes and may be lower or zero. The refund may arrive asynchronously once the airline determines the final amount. ## Key Features - **Non-destructive** — Does not cancel the booking; safe to call before user confirmation - **Margin-applied pricing** — All amounts (including voucher `pricing.display`) reflect the same margin applied at booking time ## Quick Start Provide the `bookingId` from the flight booking confirmation. Each call checks the airline live. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

## Overview Retrieve the ancillary services (seats, baggage) for an existing flight booking: services that are **already booked** together with the live catalog of services that **can still be booked**. ## When to Use - **Post-booking upsell** - Show the passenger which seats and bags they can still add after the booking was created - **Booking management** - Display the services already attached to the booking with the prices that were charged - **Availability refresh** - The bookable catalog is fetched live from the provider on every call ## What You Get - **`groups`** - Bookable services grouped by category (seat, baggage) with post-margin prices and encoded `serviceId`s - **`bookedServices`** - Services already attached to the booking; entries booked through the API carry the exact price that was charged at attach time - **`expiresAt`** - Validity window of the bookable catalog ## Key Features - **Read-only**: Safe to call at any time; the catalog reflects live availability - **Consistent pricing**: Booked services echo the post-margin amounts the user actually paid ## Quick Start Provide the `bookingId` from the flight booking confirmation. On a ticketed booking (status `CONFIRMED`) `groups` lists only what can be sold after ticketing (provider-dependent, usually baggage) and only when `canAddServicesAfterTicketing` is true; buy them with `POST /flights/bookings/{bookingId}/services` and `/services/confirm`. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

Retrieve a hotel prebook by its `prebookId`: final price, cancellation terms, room details and the `checkoutUrl` (`https://book.maqami.co/booking?prebookId=...`). Bookings are paid and confirmed only on MAQAMI's website, through the `checkoutUrl`.

Find a customer's hotel bookings by the email address and last name used to book. Both must match the booking holder; nothing is returned otherwise. Returns each booking with its `bookingId`, status, hotel, dates, guests, price and cancellation policy. To look up, change or cancel one booking, use its `bookingId` with the same `email` in the booking tools.

## Overview **Hard Amendment** — Search for alternative rates at the same hotel and create prebook sessions for a confirmed booking. Used when the guest needs to change their check-in/check-out dates or room occupancy. ## When to Use - **Date changes** — Guest needs different check-in or check-out dates - **Occupancy changes** — Guest needs a different number of adults or children - **Hard amendments** — Situations where the booking must be cancelled and re-booked with new parameters ## How It Works 1. The system searches for live availability at the same hotel with the new parameters. 2. Up to `maxPrebooks` alternative rates are selected (sorted by price ascending). Defaults to 3 when omitted; capped at 10 (any larger value is silently clamped to 10). 3. A prebook session is created for each rate. 4. The caller receives a list of `prebookId` values with prices to show the guest. ## What You Get - **Up to `maxPrebooks` prebook sessions** — Each with a `prebookId`, final pricing, cancellation policies, and room details - **Price comparison** — `priceDifferencePercent` shows how each alternative compares to the **original booking's selling price** (negative = cheaper than what the guest paid, positive = more expensive) - **Policy change flags** — `cancellationChanged` and `boardChanged` highlight any policy differences ## Key Notes - The booking must be in **CONFIRMED** status. - If the original booking is non-refundable, only non-refundable alternatives are returned (unless overridden with `refundableRatesOnly`). - The nationality and currency of the original booking are used for the availability search. ## Quick Start 1. Call this endpoint with the `bookingId` and new `occupancies`/dates — get back up to `maxPrebooks` `prebookId` values. **On this server**: rebooking is not available, so use this only to show the guest alternative prices. To change a booking, cancel it if its policy allows and make a new booking, or contact MAQAMI support. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

## Overview Generate short, AI-written "Smart Highlight" cards for a hotel. Each highlight is a title plus a one or two sentence description, generated directly in the requested language. **Pricing**: $0.02 per request **Rate Limiting**: This endpoint is rate-limited to **10 requests per minute**. Exceeding this limit will result in a `429 Too Many Requests` response. ## When to Use - **Hotel detail pages** - Show a few compelling reasons to consider a property - **Partner-specific tone** - Adjust voice and emphasis per surface via `tone`, `style` and per-highlight `context` ## What You Get - Exactly `count` highlights, always, in the requested order - `type` echoed back from the request so you can map each card to your own UI - `generated` indicating whether the copy is AI-generated or template fallback ## Behaviour Hotel facts are resolved server-side from `hotelId`; the caller never supplies them. The model sees the name, city, country, street address, parking, and description, plus a sample of facilities, rooms, policies, and nearby places (with a server-computed distance phrase: on the property, short walk, short drive, or longer drive; farther places are omitted), guest sentiment strengths when stored (not drawbacks), and classification (star rating, hotel type, chain). Generated copy is grounded in those facts. Straight apostrophes in titles and descriptions are normalized to typographic apostrophes. Enterprise API keys also omit wifi and the phrase modern amenities from the facts and from the copy, and they omit review-style wording such as guests say. Other API keys still return wifi and connectivity copy when the request asks for it. When `tone` or `style` specify length or format, those rules override the default title and description lengths. If AI generation fails, the endpoint still returns `200` with the requested number of neutral template highlights and `generated: false`. It never returns an empty array for a valid hotel. Results are cached, so repeated calls with an identical request body return identical copy. `tone` and `style` are truncated to 200 characters (5,000 for enterprise accounts). Each highlight `context` is truncated to 300 characters (10,000 for enterprise accounts).

Cancel a confirmed flight booking. First show the customer the refund estimate from `get_flights_bookings_bookingid_cancellations` and wait for a clear yes. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.

## Overview Search for available flights with real-time pricing from multiple providers. The itinerary **must** be sent as a non-empty `legs` array. Each leg follows the provider **SearchLeg** shape: required `origin`, `destination`, and `date` (YYYY-MM-DD); optional `direction` (`OUTBOUND` or `INBOUND`); optional per-leg `filters` that override global `filters` for that leg only. **Not supported:** top-level `origin`, `destination`, `departureDate`, or `returnDate` — use `legs` only. ## When to Use - **Listings** — live prices for search results UI - **One-way, round-trip, or multi-city** — one leg per segment, in order - **Filtering** — cabin class, stops, price, refundability, times (globally or per leg) ## What You Get - Offers from multiple providers - Itineraries with segments, layovers, and durations - Price breakdown (fares, taxes, fees) and baggage hints ## Key Features - Multi-provider aggregation in one request - Global `filters`, `sort` ## Quick Start **Required:** `legs` (at least one object with `origin`, `destination`, `date`), `adults` (≥ 1), `currency` **Date limit:** each leg `date` must not be more than 11 months from today. **Round-trip:** two legs (e.g. outbound then return with `direction` `OUTBOUND` / `INBOUND`). **One-way:** one leg. ## Booking The response includes `searchUrl`, the same search on book.maqami.co. Flights are booked and paid only on MAQAMI's website: `post_flights_verify` re-prices the chosen offer and returns its `checkoutUrl`.

## Overview Confirm a flight offer is still available and retrieve the latest pricing before proceeding to booking. Returns the checkout link for the verified offer. ## When to Use - **Pre-booking validation** - Confirm offer availability after user selects a flight - **Price confirmation** - Show users the guaranteed price - **Fare rule retrieval** - Get the latest cancellation and change policies ## What You Get - **Verified pricing** with up-to-date fare breakdown - **`changes`** (when present) — cabin/fare flags, human-readable `messages`, and **`pricing`** (`old` / `new` full OfferPricing) instead of deprecated scalar currency/prices - **Journey `pricing`** — `original` (provider/PCC) and `display` (customer) price breakdown per provider FlattenedJourney - **Fare family details** including name and included amenities - **Baggage policy** for each passenger type and segment - **Booking terms** including cancellation and change fee rules ## Key Features - **Real-time price check**: Confirms current availability and price with the provider - **Updated baggage info**: Returns the latest baggage allowances at time of verification - **Fare rules**: Includes cancellation and change fee policies before commitment ## Quick Start Provide the `offerId` from `post_flights_rates` search results. The verified offer data gives the customer a booking summary. ## Booking The response includes `checkoutUrl` (`https://book.maqami.co/flights/booking?offerId=...`). Flights are booked and paid only on MAQAMI's website: the `checkoutUrl` opens checkout for this fare, where the customer enters passenger details, pays securely and receives the confirmation. This tool takes no card or passport details.

## Overview Get the cheapest available rate for each hotel in your list. Perfect for displaying price comparisons without loading full rate details. ## When to Use - **Show price ranges** on hotel listing pages - **Quick price comparisons** across multiple hotels - **Optimize performance** when you only need the lowest price, not all rate options - **Build price filters** or sorting by price ## What You Get - **Minimum rate per hotel** - the cheapest available room option - **Basic rate information** - price, currency, and availability - **Fast response** - optimized for quick price lookups ## Key Features - **Lightweight** - Returns only the minimum rate, not all options - **Same parameters** as the main rates endpoint for consistency - **Perfect for listings** - Ideal when displaying multiple hotels where users just need to see starting prices ## Quick Start Provide a list of hotel IDs, dates, and guest occupancy. The endpoint returns the cheapest rate available for each hotel.

## Overview Search for hotel rates and availability across multiple hotels. This is your primary endpoint for finding bookable hotel rooms with real-time pricing. ## When to Use - **Display hotel listings** with prices on your search results page - **Show detailed rate options** for specific hotels users are viewing - **Support multi-room bookings** for families or groups - **Filter hotels** by location, amenities, ratings, or AI-powered semantic search ## What You Get - **Real-time rates** with availability and pricing - **Multiple room options** per hotel, sorted by price - **Complete booking details** including cancellation policies, meal plans, and room types - **Hotel information** (name, photos, address, ratings) when searching by filters ## Key Features - **Multiple search methods**: Search by hotel IDs, city/country, coordinates, Place ID, IATA code, or natural language (AI search) - **Flexible filtering**: Filter by star rating, facilities, hotel chains, accessibility, and more - **Multi-room support**: Book multiple rooms with different guest configurations in one request - **Performance optimized**: Default limit of 200 hotels (expandable to 5,000), recommended timeout of 6-12 seconds - **Price consistency**: Optional `sessionId` ensures rates stay consistent across listing and detail searches within a user session ## Quick Start **Required fields**: `checkin`, `checkout`, `currency`, `guestNationality`, `occupancies`, plus one location method (hotel IDs, city/country, coordinates, Place ID, or IATA code) **Tip**: When searching by filters (like `aiSearch` or `cityName`), hotel data is automatically included. For direct hotel ID searches, set `includeHotelData=true` to include hotel names and photos. **Price consistency**: Generate a unique `sessionId` per user search session and include it on every rates request in that session, using the same `checkin`, and `checkout`.

## Overview Locks the chosen hotel rate and returns the final price, cancellation terms and a checkout link on MAQAMI's website. ## When to Use When the customer has chosen a hotel, room, dates and guests and reviewed the price and cancellation terms. ## Quick Start Pass the `offerId` from `post_hotels_rates` exactly as it was returned. ## What You Get - **prebookId** - The locked rate - **Final price and cancellation terms** - For the customer to review - **checkoutUrl** - `https://book.maqami.co/booking?prebookId=...` ## Payment Bookings are paid and confirmed only on MAQAMI's website. The `checkoutUrl` opens checkout for this exact rate, where the customer enters guest details, pays securely and receives the confirmation. This tool takes no payment details and does not confirm the booking.

Correct the booking holder's name, email or phone on a confirmed hotel booking, for example to fix a typo. It does not change dates, rooms or guests. To show the customer prices for other dates or guests, use `post_bookings_bookingid_alternative_prebooks`. Pass the `bookingId`, the `email` currently on the booking and the corrected `holder` (`firstName`, `lastName`, `email`, optional `phone`). Confirm the new details with the customer before calling. Requires the `bookingId` and the `email` used to book: the server only returns or changes a booking when they match.