SearchRequest

Request payload for availability search

criteria objectrequired

Search criteria for availability

checkInstring<date-time>required

Check-in civil date encoded as UTC midnight: YYYY-MM-DDT00:00:00Z. Only the date prefix is honoured; time-of-day and offsets are ignored (2026-06-01T00:00:00+02:00 searches 1 June, not 31 May). Do not send Date.toISOString() of a local-midnight Date outside UTC — that yields the previous UTC day (e.g. 2026-05-31T22:00:00.000Z for 1 June in Europe) and cannot be recovered. Missing, empty, or unusable dates (including strings protojson cannot parse as Timestamp) return HTTP 200 with errors[] (ERR_CODE_BAD_REQUEST, ERR_TYPE_CLIENT), not 400/5XX. Check-in more than one day before today's UTC civil date, or checkOut not after checkIn, is the same client error and is not forwarded to providers. Today's and yesterday's UTC dates are always forwarded: yesterday's date is still today for a hotel west of UTC, and whether a stay is still bookable is the hotel's answer, not a calendar the aggregator can evaluate. When a time-of-day is stripped on an otherwise valid stay, the response includes a STAY_DATE_NORMALIZED warning with received and used.

Example: 2024-12-16T00:00:00Z

checkOutstring<date-time>required

Check-out civil date encoded as UTC midnight: YYYY-MM-DDT00:00:00Z. Same contract as checkIn: only the date prefix is honoured.

Example: 2024-12-18T00:00:00Z

hotelsstring[]

List of hotel codes to search. There is no destination field on availability criteria — resolve a destination via Content API (places / hotels/filter) and pass the resulting codes here.

Example: ["123","456"]

occupancies object[]required

Room occupancies

Possible values: >= 1

Array [

paxes object[]

Guests in the room (age only on search)

Array [

ageinteger<int32>required

Guest age

]

]

languagestring

Response language code (ISO 639-1)

Example: en

currencystring

Currency code (ISO 4217)

Example: USD

nationalitystring

Guest nationality code

Example: US

businessRules object

Business rules for search

businessRulesTypestring

Type of business rule

Example: CHEAPER_AMOUNT

optionsQuotainteger<int32>

Maximum number of options to return

Example: 5

exclusions object[]

Exclusion filters

Array [

typestring

Exclusion type

Example: connectionCode

keystring

Exclusion key

valuesstring[]

Exclusion values

]

additionalParams object

Additional parameters passed to the search.

Supported parameters:

• skipMarkup: When set to "true", skip margin calculation and return suggested price equal to net price. Useful for testing or when markup is handled externally. If no markup is configured for a connection and skipMarkup is false, a warning will be emitted in the response.
• skipHotelCodesMapping: When set to "true", hotel codes are sent directly to providers without mapping.

property name*string

resultFilters object

Optional post-processing filters applied after suppliers respond, before the response is returned to the client. They reduce response size and remove options that do not match your selection criteria. All fields are optional; omitting resultFilters (or sending an empty object) is a no-op.

Filters are stackable: when several are set they are evaluated in a single pass as a logical AND (refundable AND boardCodes AND cheapestOnly).

cheapestOnlyboolean

When true, keep at most one option per (connectionCode, hotelCode) group — the cheapest one according to cheapestStrategy. Use this to reduce payload size on broad searches where the UI only needs one rate per hotel.

Example: true

refundableFilterRefundableFilter (string)

Tri-state filter on the cancellation policy of each option.

• REFUNDABLE_FILTER_UNSPECIFIED (or omitted) — no filter.
• REFUNDABLE_FILTER_ONLY_REFUNDABLE — keep only options whose cancelPolicy.refundable is true.
• REFUNDABLE_FILTER_ONLY_NON_REFUNDABLE — keep only options whose cancelPolicy.refundable is false (or missing).

Possible values: [REFUNDABLE_FILTER_UNSPECIFIED, REFUNDABLE_FILTER_ONLY_REFUNDABLE, REFUNDABLE_FILTER_ONLY_NON_REFUNDABLE]

boardCodesstring[]

Whitelist of board codes (e.g. BB, HB, RO, AI). Comparison is case-insensitive (bb matches BB) against boardCode, falling back to providerBoardCode when the mapped code is empty. Empty array, null, or only-blank entries are treated as no filter. Up to 100 distinct codes are honored; extra entries are ignored defensively.

Example: ["BB","HB"]

cheapestStrategyCheapestStrategy (string)

Selects which price field is used to compare options when cheapestOnly is true.

• CHEAPEST_STRATEGY_UNSPECIFIED — same as CHEAPEST_STRATEGY_SUGGESTED (default).
• CHEAPEST_STRATEGY_SUGGESTED — compare by price.suggested (price after markup). Recommended for B2C displays where the customer-facing price drives the choice.
• CHEAPEST_STRATEGY_NET — compare by price.net (supplier net price). Useful when markup configurations vary across hotels and you want the lowest supplier cost. When the requested currency is set, options matching it are preferred over options in a different currency, regardless of nominal price. Currency comparison is case-insensitive (eur and EUR are equivalent).

Possible values: [CHEAPEST_STRATEGY_UNSPECIFIED, CHEAPEST_STRATEGY_SUGGESTED, CHEAPEST_STRATEGY_NET]

settings objectrequired

Common settings for all requests

requestIdstring

Unique request identifier for tracking

Example: req-123456789

connectionCodesstring[]required

List of provider connection codes to query

Possible values: >= 1

Example: ["testb-conn-1876","testb-conn-1877"]

auditTransactionsboolean

When true, responses may include auditData.transactions with supplier-level traces for debugging. Use sparingly in production; redact sensitive data in logs.

Default value: false

timeoutinteger<int32>

Client timeout hint in milliseconds; platform and supplier minimums may still apply (especially for book). For availability it is also clamped to the server maximum (60000 by default), and the clamped value is the budget forwarded to the connections, so a larger figure is silently reduced rather than honoured. No schema-level default is declared on purpose: this object is shared by every operation and the effective fallback is per-operation (availability uses 10000, book is considerably higher). Omit the field to take the server's fallback for the operation you are calling rather than sending one that would cut a longer operation short.

testModeboolean

When true, enables non-production / sandbox-oriented behaviour where supported for the connection.

Default value: false

debugData object

Additional debug data

property name*any

Additional debug data

SearchRequest

{
  "criteria": {
    "checkIn": "2024-12-16T00:00:00Z",
    "checkOut": "2024-12-18T00:00:00Z",
    "hotels": [
      "123",
      "456"
    ],
    "occupancies": [
      {
        "paxes": [
          {
            "age": 0
          }
        ]
      }
    ],
    "language": "en",
    "currency": "USD",
    "nationality": "US",
    "businessRules": {
      "businessRulesType": "CHEAPER_AMOUNT",
      "optionsQuota": 5
    },
    "exclusions": [
      {
        "type": "connectionCode",
        "key": "string",
        "values": [
          "string"
        ]
      }
    ],
    "additionalParams": {
      "skipMarkup": "true",
      "skipHotelCodesMapping": "true"
    },
    "resultFilters": {
      "cheapestOnly": true,
      "refundableFilter": "REFUNDABLE_FILTER_UNSPECIFIED",
      "boardCodes": [
        "BB",
        "HB"
      ],
      "cheapestStrategy": "CHEAPEST_STRATEGY_UNSPECIFIED"
    }
  },
  "settings": {
    "requestId": "req-123456789",
    "connectionCodes": [
      "testb-conn-1876",
      "testb-conn-1877"
    ],
    "auditTransactions": false,
    "timeout": 0,
    "testMode": false,
    "debugData": {}
  }
}