--- title: "Search Reservations" method: GET path: "/reservations-v3/search" tags: ["Reservations Open Api [Beta]"] --- # Search Reservations `GET /reservations-v3/search` Search reservations with flexible filtering, sorting and pagination. ## Filters Filters use **bracket notation** in the query string: - `filter[]=` — shorthand (defaults to `eq`, or implicit `in` when comma-separated). - `filter[][]=` — explicit operator. Multiple operators on the same field are combined with logical AND, e.g. `filter[checkIn][gte]=2026-01-01&filter[checkIn][lt]=2026-02-01` returns reservations checking in during January 2026. ### Identifier fields (string equality / set membership) | Field | Operators | Notes | |---|---|---| | `status` | `eq`, `ne`, `in`, `nin` | Comma-separated value implies `in` | | `listingId` | `eq`, `in` | Matches `unitId` or `unitTypeId` on the first stay segment | | `confirmationCode` | `eq`, `in` | Comma-separated value implies `in` | | `source` | `eq`, `in` | e.g. `airbnb`, `booking.com`, `manual` | ### Date / range fields (operator required) | Field | Operators | Format | |---|---|---| | `checkIn` | `eq`, `gte`, `gt`, `lte`, `lt` | Localized date `YYYY-MM-DD`, e.g. `2026-01-15` | | `checkOut` | `eq`, `gte`, `gt`, `lte`, `lt` | Localized date `YYYY-MM-DD` | | `createdAt` | `eq`, `gte`, `gt`, `lte`, `lt` | ISO 8601 datetime, e.g. `2026-01-01T00:00:00Z` | ## Sorting Use the `sort` query parameter. Prefix the field with `-` for descending order. Allowed fields: `_id`, `checkIn`, `checkOut`, `createdAt`. Default: `-_id`. ## Pagination Use `skip` (default `0`) and `limit` (default `25`, max `100`). The response includes a `pagination.hasMore` flag. ## Query parameters - `skip` number - `limit` number - `sort` '_id' | '-_id' | 'checkIn' | '-checkIn' | 'checkOut' | '-checkOut' | 'createdAt' | '-createdAt' - `filter[source]` string - `filter[confirmationCode]` string - `filter[listingId]` string - `filter[status][ne]` string - `filter[status]` string - `filter[createdAt][lt]` string - `filter[createdAt][gte]` string - `filter[checkOut][lte]` string - `filter[checkOut][gte]` string - `filter[checkIn][lt]` string - `filter[checkIn][gte]` string ## Response `200` Success - object - `results` object[], required — List of reservations matching the search criteria - `reservationId` string, required - `confirmationCode` string, required - `status` string, required - `guestId` string, required — Booker/guest id. - `checkIn` string, date-time, required — Planned arrival datetime in UTC (includes the listing check-in time). Derived from the first stay. - `checkOut` string, date-time, required — Planned departure datetime in UTC (includes the listing check-out time). Derived from the last stay so it spans the whole reservation for mid-stays. - `checkInDateLocalized` string, required — Local check-in date (YYYY-MM-DD) from the first stay. This is the exact value the `filter[checkIn]` query parameter compares against. - `checkOutDateLocalized` string, required — Local check-out date (YYYY-MM-DD) from the last stay. This is the exact value the `filter[checkOut]` query parameter compares against. - `source` string, required — Platform source identifier (e.g. "manual", "airbnb", "Booking Engine"). - `channel` string, required — Channel name (aliased from `reservation.platform`). Same semantic as the `channel` field on the non-search Open API reservation response. - `createdAt` string, date-time, required — Reservation creation timestamp. - `bookingDate` string, date-time — Real-world booking date. Equals createdAt unless explicitly set. - `reservedExpiresAt` string, date-time — When set, the reservation is in "reserved" status and will auto-expire at this time. - `creationInfo` object — Creation context (e.g. owner details for owner-confirmed reservations). Same shape as on the non-search Open API reservation response. - `notes` object, required — Reservation notes. Always present (schema-level required). Defaults to `{}` when no notes have been set. Includes operational notes (`other`, `cleaning`), guest-facing messaging (`guest`), and previously top-level `specialRequests` / `keyCode` fields that have been moved here. - `other` string - `cleaning` string - `guest` string - `specialRequests` string - `keyCode` string - `customFields` object[] — Account-level custom field values attached to the reservation. Only populated when the reservation has at least one custom-field value set. The `value` type depends on the corresponding custom-field definition (string, number, boolean, date, or ObjectId). - `_id` string, required - `fieldId` string, required - `value` object, required - `groupId` string — Group-reservation id (mongo ObjectId, stringified). Present only when the reservation is part of a group reservation; absent for standalone reservations. - `sendQuoteId` string — Send-quote id (mongo ObjectId, stringified). Present only when the reservation originated from a send-quote flow; absent for direct/channel bookings. - `pointOfSale` string — Point-of-sale identifier (e.g. "BE-API", "Booking Engine", a custom website name). Use together with `secondarySource` semantics from the non-search Open API reservation response. Only present when set. - `guestStay` object — Operational guest-stay state (used by check-in/check-out flows). Tracks the lifecycle status, who last transitioned it, and when. Only present when set on the reservation. - `doneBy` object - `id` string - `name` string - `type` string, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `status` 'not_set' | 'checked_in' | 'checked_out' | 'no_show', required - `uploadedAt` string, date-time — Timestamp of when the reservation was imported via the reservations-upload feature. Only present for reservations created through that flow. - `unifiedId` string — Cross-reservation identifier used by unified-booking flows (e.g. linking sibling reservations on the same booking). Only present when set. - `channelMetadata` object — Channel-specific metadata for the reservation. Present only for reservations originated from an OTA/channel (e.g. Airbnb, Booking.com, Expedia, hotel chains). Absent for direct, manual, and website reservations. Carries the channel-side ids (`externalReservationId`, `externalListingId`), lifecycle timestamps (`createdAt`, `confirmedAt`, `updatedAt`, `canceledAt`), rate-plan and cancellation-terms info, channel-specific flags (`isGroupReservation`, `loyaltyProgram`, …), and `guestPreferences` (also channel-sourced). - `guestPreferences` object — Guest-supplied preferences for the stay (e.g. smoking). Sourced from the channel reservation payload (e.g. Booking.com). Only present when at least one preference has been recorded on the reservation. - `smoking` boolean - `externalReservationId` string, required - `externalListingId` string, required - `hotelId` string - `stayId` string - `hostRole` string - `loyaltyProgram` 'genius' - `createdAt` string, date-time, required - `confirmedAt` string, date-time - `updatedAt` string, date-time - `canceledAt` string, date-time - `canceledBy` string - `ratePlan` object - `name` string - `id` string - `childId` string - `cancellationTerms` object - `penaltyAmount` string - `reasons` string[] - `cancellationPolicy` string - `isGroupReservation` boolean - `isFullReservationData` boolean - `cancellationFee` number - `stay` object[], required — Full stay array. Always present — for single-stay reservations it contains exactly one element (mirroring the top-level fields); for mid-stay reservations it contains every segment in chronological order. Each segment carries its own `listingId` / `parentListingId` derived with the same rule as the top-level fields, so callers do not need to re-apply it. - `listingId` string, required — Assigned listing id for this stay segment (= unitId ?? unitTypeId). Matches UnitTypeMapper.mapUnitTypeToListingId. - `parentListingId` string — Parent MTL id for this segment. Present only when the segment is on a Multi-Unit listing (either unassigned or assigned to a child unit). Absent for single-unit listings. - `ratePlanId` string — Rate plan id for this stay segment. - `checkIn` string, date-time, required — Planned arrival datetime for this segment in UTC (includes the listing check-in time). - `checkOut` string, date-time, required — Planned departure datetime for this segment in UTC (includes the listing check-out time). - `checkInDateLocalized` string, required — Local check-in date for this segment (YYYY-MM-DD). - `checkOutDateLocalized` string, required — Local check-out date for this segment (YYYY-MM-DD). - `guestsCount` number, required - `numberOfGuests` object - `numberOfChildren` number — Number of children - `numberOfInfants` number — Number of infants - `numberOfPets` number — Number of pets - `numberOfAdults` number, required — Number of adults - `pagination` object, required — Pagination information - `skip` number, required — Number of records skipped - `limit` number, required — Maximum number of records returned - `hasMore` boolean, required — Whether there are more records available ## Other responses - `400` — Returned when an unsupported filter field, operator, or sort value is provided - `500` — Indicates server-side error while processing the request --- [API](https://skmtc.net/guesty/apis/guesty-open-api.md) · [All operations](https://skmtc.net/guesty/apis/guesty-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/guesty/guesty-open-api/versions/7c62644070f2/schema)