TUI Group HolidayOffersController USL API

openapi: 3.2.0
info:
  title: HolidayOffersController USL API
  description: 'Supported versions for the X-API-VERSION header is: v1, v2'
  version: v1
  contact:
    name: Sales-Starlight-TEAM
    url: https://developer.tui/api-catalog/holidayofferscontroller-api
    email: starlight@TUIGroup.onmicrosoft.com
servers:
- url: https://prod.api.tui/search-holiday-offers
tags:
- name: HolidayOffersController USL API
paths:
  /search-holiday-offers/search/package/v1/offers:
    post:
      tags:
      - HolidayOffersController USL API
      summary: Get holiday offers (v1)
      description: "v1 is the USL version for the Holidays Offers API. Returns Package holidays based on \nthe search criteria in the request body. Support filter retention. More could find here:\nhttps://confluence.tuigroup.com/pages/viewpage.action?pageId=1474581073#DesignUSLAPIforlistofferproxysupportingWR/NR-ProposedStoriesfortheListOffersTeamtoimplementnewchanges\n"
      parameters:
      - name: x-source-application
        in: header
        required: true
        description: Source application for this request flow
        schema:
          type: string
          example: Search Results MFE
      - name: x-correlation-id
        in: header
        required: true
        description: UUID to identify a specific request in case of an issue. End to end tracing ID
        schema:
          type: string
          format: uuid
          example: 14bafa8a-182d-4390-bc91-11e79bdcaec0
      - name: x-environment
        in: header
        schema:
          $ref: '#/components/schemas/Environment'
      - name: x-ab-cookie-set
        in: header
        description: List of AB test cookies to be sent to NGS
        schema:
          type: string
          example: 1080:A,1081:B
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchOfferRequest'
        required: true
      responses:
        '200':
          description: Successful search of the offers 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchOfferResponse'
        '204':
          description: Successful search of the offers, but no offers is present
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '404':
          description: Resource Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error. Something went wrong on our end
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway. One or more backend systems not available
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '504':
          description: Gateway Timed Out
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    SearchOfferResponse:
      type: object
      x-field-extra-annotation:
      - '@Introspected'
      required:
      - filters
      - holidays
      properties:
        filters:
          type: array
          x-field-extra-annotation:
          - '@Valid'
          items:
            $ref: '#/components/schemas/Filter'
        holidays:
          x-field-extra-annotation:
          - '@Valid'
          $ref: '#/components/schemas/PackageHoliday'
    SearchRequestSortType:
      type: string
      description: Sort order to use before paging
      example: TOTALPRICEASC
      enum:
      - DEFAULT
      - TOTALPRICEASC
      - TOTALPRICEDESC
      - REVIEWDESC
      - CUSTOMERRATING
      - DISCOUNTDESC
      - FLIGHTDEPTIMESASC
    FilterType:
      type: string
      description: type of the filter
      example: TRIPRATING
      enum:
      - BOARDBASIS
      - TUIRATING
      - FACILITIES
      - CONCEPTS
      - HOLIDAYDEPARTUREDATE
      - HOLIDAYTYPE
      - ACCOMMODATIONTYPE
      - PRICE
      - PRICEPP
      - DISCOUNT
      - DESTINATIONS
      - DURATIONS
      - DISTANCETO
      - DEPARTUREAIRPORTS
      - CUSTOMERRATING
      - COMMISSIONMARKERS
      - TRIPRATING
      - CARRIER
      - BESTFOR
      - DEPARTURETIMEOUT
      - DEPARTURETIMEBACK
      - FREECHILDPLACES
      - ACCESSIBILITY
      - FLIGHTSTOPS
      - MOUNTAINFEATURES
      - FLIGHTTYPE
    StayDuration:
      required:
      - checkInDate
      - checkOutDate
      - numberOfNights
      type: object
      properties:
        numberOfNights:
          type: integer
          format: int32
          description: number of stay nights in the accommodation
          example: 7
        checkInDate:
          type: string
          format: date
          description: accommodation check in date
          example: '2025-07-07'
        checkOutDate:
          type: string
          format: date
          description: accommodation check out date
          example: '2025-07-14'
    TransferResponse:
      required:
      - transferType
      type: object
      properties:
        direction:
          $ref: '#/components/schemas/DirectionType'
        sourcingCategory:
          type: string
          description: Indicates the Sourcing Type of the Transfer
          example: CONTRACTED
        transferType:
          type: string
          description: url listing the details of the transfer type e.g. https://refdata.tui/transfer-types#SHARED, like SHARED, PRIVATE, WELFARE, OPT_OUT
          example: 'WR: PRIVATE NR: carHire'
    CancellationResponse:
      required:
      - isApplicable
      type: object
      properties:
        applicableTill:
          type: string
          format: date
          description: cancellation rule applicable till certain date
          example: '2025-05-06'
        cancellationRule:
          description: cancellation rule details
          type: array
          items:
            $ref: '#/components/schemas/CancellationRuleResponse'
        isApplicable:
          type: boolean
          default: false
          description: is the cancellation rule applicable for the offer
          example: true
    FlightSegment:
      required:
      - segmentId
      - journeyId
      - flightNo
      - marketingCarrier
      - departurePoint
      - arrivalPoint
      - departureDate
      - arrivalDate
      type: object
      properties:
        segmentId:
          type: string
          description: productUnitId for WR, transport atcomId for NR
          example: 'WR: 26929514-237c-11ed-861d-0242ac120002 NR: A156e11a1541d53c59e94ebad3037ef17'
        journeyId:
          type: string
          description: journeyId for WR, transport routeCd for NR
          example: 'WR: 26929514-237c-11ed-861d-0242ac120002 NR: DXBLGW4T'
        operatingCarrier:
          maxLength: 3
          minLength: 2
          type: string
          description: Operating carrier code as defined by flight sourcing service
          example: TOM
        marketingCarrier:
          maxLength: 3
          minLength: 2
          type: string
          description: Marketing carrier code as defined by flight sourcing service
          example: TB
        flightNo:
          type: string
          description: Flight number as defined by flight sourcing service
          example: 2501
        departurePoint:
          type: string
          description: Departure airport code
          example: LHR
        arrivalPoint:
          type: string
          description: Arrival airport code
          example: ESP
        departureDate:
          type: string
          format: date
          description: Local departure date
          example: 2025-07-22
        departureTime:
          type: string
          format: time
          description: Local departure time
          example: '14:35:00'
        arrivalDate:
          type: string
          format: date
          description: Local arrival date
          example: 2025-07-28
        arrivalTime:
          type: string
          format: time
          description: Local arrival time
          example: 64200
        duration:
          type: integer
          description: Flight duration in minutes
          example: 123
        legs:
          maxItems: 10
          minItems: 1
          type: array
          description: information of all flight 'legs' (including stop over codes)
          example: null
          items:
            $ref: '#/components/schemas/FlightLeg'
        sourcingCategory:
          $ref: '#/components/schemas/SourcingCategory'
    LuggageResponse:
      required:
      - allowance
      properties:
        allowance:
          type: string
          description: Allowed amount of KG for the luggage
          example: '20'
        price:
          type: number
          format: double
          description: Price for the luggage
          example: 75.98
    SearchRequestUnitAllocation:
      required:
      - number
      - paxAge
      - paxID
      - unitType
      type: object
      minItems: 1
      properties:
        paxID:
          minimum: 1
          type: number
          format: integer
          description: id of the pax
          example: 1
        paxAge:
          minimum: 0
          type: number
          format: integer
          description: age of the pax
          example: 18
        number:
          minimum: 1
          type: number
          format: integer
          description: in which room pax goes, room number
          example: 1
        unitType:
          $ref: '#/components/schemas/UnitAllocationType'
    SearchRequestDeparture:
      type: object
      properties:
        code:
          type: string
          description: Airport IATA code
          pattern: '[A-Z]{3}'
          example: BRU
        type:
          type: string
          pattern: (AIRPORT)
          description: type from where we go, currently it is only AIRPORT
          example: AIRPORT
    Filter:
      type: object
      example: '[{ "code": "DESTINATIONS", "value": "Destination", "options": [ { "code": "ESP", "available": true, "selected": false, "value": "Spain", "type": "COUNTRY", "options": [ { "code": "002894", "value": "Andalucia", "selected": false, "count": 66, "type": "REGION", "available": true, "options": [ { "code": "002894", "value": "Andalucia Child(example)", "selected": false, "count": 33, "type": "DESTINATION", "available": true }, { "code": "002894", "value": "Andalucia Child(example)", "selected": false, "count": 33, "type": "DESTINATION", "available": true } ] }, { "code": "000373", "value": "Barcelona", "selected": false, "count": 117, "type": "DESTINATION", "available": true } }]'
      required:
      - code
      - options
      properties:
        code:
          $ref: '#/components/schemas/FilterType'
        value:
          type: string
          example: Departure Points
          description: Naming of the filter, if the naming not present should be filter type then
        options:
          type: array
          x-field-extra-annotation:
          - '@Valid'
          - '@NotEmpty'
          items:
            $ref: '#/components/schemas/FilterOption'
    SearchRequestMetaInformation:
      required:
      - brand
      - medium
      - target
      - sourceMarket
      - locale
      - currency
      type: object
      properties:
        target:
          $ref: '#/components/schemas/SellingTarget'
        sourceMarket:
          $ref: '#/components/schemas/SourceMarket'
        brand:
          $ref: '#/components/schemas/Brand'
        provider:
          type: string
          default: TUI
          description: Provider Code, use "TUI" as a default unless specified otherwise WR only. //Could be removed?
          example: null
        medium:
          $ref: '#/components/schemas/Medium'
        agentId:
          type: string
          example: T|D2816,F|D2816
          description: one or more comma-separated agent or abta codes, required for 'retail' NR channel. Retail inhouse/3rd party agent id
        locale:
          type: string
          pattern: ^[a-z]{2}_[A-Z]{2}$
          example: nl_BE
          description: locale information
        currency:
          $ref: '#/components/schemas/Currency'
    FlightLeg:
      required:
      - id
      - arrivalPoint
      - departurePoint
      - departureDate
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Product unit id or transport id for that leg
          example: 26929514-237c-11ed-861d-0242ac120002
        departurePoint:
          type: string
          description: Departure point IATA code
          example: LHR
        departureDate:
          type: string
          format: date
          description: Local departure date
          example: 2024-03-28
        departureTime:
          type: string
          format: time
          description: Local departure time
          example: '10:30:00'
        arrivalPoint:
          type: string
          description: Arrival point IATA code
          example: LHR
        arrivalDate:
          type: string
          format: date
          description: Local arrival date
          example: 2024-03-28
        arrivalTime:
          type: string
          format: time
          description: Local arrival time
          example: '11:30:00'
    RoomBoardData:
      required:
      - boardType
      - travellers
      type: object
      properties:
        freeChildPlace:
          type: boolean
          default: false
          description: 'Defines if the freeChildPace is available for this offer

            '
          example: true
        roomId:
          type: string
          description: required attribute for WR (uuid) Product unit ID of the transfer as defined by product service / optional for NR (atcomId)
          example: 26929514-237c-11ed-861d-0242ac120002 or 1149172371
        sourcedUnitId:
          type: string
          description: Sourced unit ID of the transfer unit as defined by sourcing service
          example: 26929514-237c-11ed-861d-0242ac120002 or 1149172371
        roomType:
          type: string
          description: room type code as defined by sourcing
          example: 23bf71c4-2f92-4cdb-8862-e7de20ff897c or TW01
        boardType:
          $ref: '#/components/schemas/BoardCode'
        sourcingCategory:
          type: string
          description: Indicates the Sourcing Type of the Unit
          example: CONTRACTED
        travellers:
          type: array
          description: Travellers list offered this transfer
          items:
            $ref: '#/components/schemas/Traveller'
        availability:
          type: integer
          description: number of available rooms
          example: 20
    PackageOfferResponse:
      required:
      - holidayEndDate
      - holidayStartDate
      - prices
      - id
      - flight
      - accommodations
      type: object
      properties:
        id:
          type: string
          description: product id for WR / atcom pkg id for NR
          example: WR = "ad86b620-7085-45da-a8c3-37eb07d8763b"; NR = "3445560/3/559/7"
        code:
          type: string
          description: accommodation offer id (NR)
          example: WR = "ad86b620-7085-45da-a8c3-37eb07d8763b"; NR = "EGSH0019"
        name:
          type: string
          description: Accommodation name
          example: TUI BLUE Nastro Azzurro
        holidayStartDate:
          type: string
          format: date
          description: start date of the holiday offer
          example: '2025-07-15'
        holidayEndDate:
          type: string
          format: date
          description: end date of the holiday offer
          example: '2025-07-25'
        lowDeposit:
          type: boolean
          default: false
          description: is the low deposit information is available in offer. applicable only in NR
          example: true
        packageId:
          type: string
          deprecated: true
          description: id for the particular package for this unit - required only for NR | generation details https://confluence.tuigroup.com/pages/viewpage.action?spaceKey=ENGDO&title=Package+id+generation+logic
          example: 953925X810289616778016000001677801600000EZY238316784064000001678406400000EZY2384U00634421302486/3/426/7
        prices:
          type: array
          minItems: 1
          description: prices information for the offer
          items:
            $ref: '#/components/schemas/PackagePrice'
        accommodations:
          type: array
          description: accommodations included in the offer
          items:
            $ref: '#/components/schemas/AccommodationOfferResponse'
        flight:
          type: array
          items:
            $ref: '#/components/schemas/PackageOfferFlight'
        transfers:
          type: array
          description: transfers information of the offer
          items:
            $ref: '#/components/schemas/TransferResponse'
        luggage:
          type: array
          items:
            $ref: '#/components/schemas/LuggageResponse'
        freeCancellation:
          $ref: '#/components/schemas/CancellationResponse'
    SearchRequestDateRange:
      required:
      - from
      - to
      type: object
      properties:
        from:
          type: string
          example: '2026-11-01'
          description: start date from
        to:
          type: string
          example: '2026-11-11'
          description: start date to(till)
    FilterOption:
      type: object
      x-field-extra-annotation:
      - '@Valid'
      required:
      - code
      - selected
      properties:
        code:
          type: string
          description: Code of the filter option, for CARRIER filter type it could be - TOM for BOARDBASIS filter type it could be - AI etc
          example: G-000000703
        count:
          type: integer
          format: int32
          minimum: 0
          default: 0
          description: Number of hotel offers with this filter option
          example: 15
        available:
          type: boolean
          example: true
          description: Defines availability of the option, required for the filter retention, when for example certain options no longer part of the response from NGS, that it should be false
        selected:
          x-field-extra-annotation:
          - '@NotNull'
          type:
          - boolean
          - 'null'
          description: Defines what option is selected or not, selection value should be retained, selected values should be sent to the NGS as a filter criteria
          example: true
        value:
          type: string
          description: localised name of the filter option
          example: Balearic Islands
        options:
          type: array
          x-field-extra-annotation:
          - '@Valid'
          items:
            $ref: '#/components/schemas/FilterOption'
          description: hierarchy items
        type:
          $ref: '#/components/schemas/FilterOptionType'
        description:
          type: string
          description: description of the filter option
          example: For the SC code (board basis filter) - Meals aren’t included, but you’ll have catering facilities.
        shortDescription:
          type: array
          items:
            $ref: '#/components/schemas/ListOfferShortDescription'
    Currency:
      type: object
      description: currency information
      required:
      - currencyCode
      properties:
        currencyCode:
          type: string
          example: USD
          minLength: 3
          maxLength: 3
          description: 3 letter currency code
    PackagePrice:
      required:
      - value
      - level
      - category
      type: object
      properties:
        category:
          type: string
          description: type of the price, for the totalPrice - NET will be type and PER_ITEM - will be level >-  totalDiscountPerPerson - DISCOUNT will be type and PER_PAX - will be level
          example: DEPOSIT
          enum:
          - NET
          - DISCOUNT
          - DEPOSIT
        level:
          type: string
          description: per which item price is configured >- totalDiscountPerPerson - DISCOUNT will be type and PER_PAX - will be level >- totalPrice - NET will be type and PER_ITEM - will be level
          example: PER_PAX
          enum:
          - PER_PAX
          - PER_ITEM
        value:
          $ref: '#/components/schemas/Money'
    SellingTarget:
      type: string
      description: Selling target (channel=B2B or channel=B2C or channel=B2B2C)
      enum:
      - B2B
      - B2C
      - B2B2C
    Money:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
          format: double
          default: 0
          minimum: 0
          description: amount of the money
          example: 250.15
        currency:
          $ref: '#/components/schemas/Currency'
    AccommodationOfferResponse:
      required:
      - code
      - duration
      - overview
      type: object
      properties:
        code:
          type: string
          description: Accommodation code as defined by accommodation sourcing
          example: A0379208 or 029476
        duration:
          $ref: '#/components/schemas/StayDuration'
        rooms:
          type: array
          minItems: 1
          description: Number of rooms associated to the offer
          items:
            $ref: '#/components/schemas/RoomBoardData'
        isExternal:
          type: boolean
          default: false
          description: is the accommodation is sourced from external system
          example: true
    DirectionType:
      type: string
      description: type of the direction
      example: INBOUND
      enum:
      - INBOUND
      - OUTBOUND
    SearchOfferRequest:
      required:
      - numberOfNights
      - dateRange
      - alternateDurations
      - travellers
      - commercialProductType
      - sortBy
      - metaInformation
      type: object
      x-field-extra-annotation:
      - '@Introspected'
      properties:
        alternateDurations:
          type: array
          description: 'Alternative number of nights to find offers for. These should be in order of preference: first we should attempt the first duration, and we only consider duration index i+1 if we cannot find any offers for duration index i. Note that this list WILL include the `preferredNumberOfNights`!'
          example:
          - 8
          - 6
          - 7
          - 9
          - 5
          - 10
          - 11
          maxItems: 8
          minItems: 1
          items:
            type: integer
            example: 7
            minimum: 1
            maximum: 99
            description: Number of nights the customer would stay at the hotel.
        numberOfNights:
          minimum: 1
          type: number
          format: integer
          description: Selected number of nights
        from:
          type: array
          items:
            $ref: '#/components/schemas/SearchRequestDeparture'
        to:
          type: array
          items:
            $ref: '#/components/schemas/SearchRequestDestination'
        dateRange:
          $ref: '#/components/schemas/SearchRequestDateRange'
        unitAllocations:
          type: array
          items:
            $ref: '#/components/schemas/SearchRequestUnitAllocation'
        travellers:
          type: array
          items:
            $ref: '#/components/schemas/Traveller'
          x-field-extra-annotation: '@field:Size(min = 1, message = "Travellers is a mandatory field. Must contain at least one item")'
        commercialProductType:
          $ref: '#/components/schemas/CommercialProductType'
        sortBy:
          $ref: '#/components/schemas/SearchRequestSortType'
        pageSize:
          minimum: 1
          type: integer
          format: int32
          description: Number of results per page
        pageNumber:
          minimum: 1
          type: integer
          format: int32
          description: Number of requested page
        metaInformation:
          $ref: '#/components/schemas/SearchRequestMetaInformation'
        filters:
          type: array
          x-field-extra-annotation:
          - '@Valid'
          items:
            $ref: '#/components/schemas/Filter'
        excludeTypes:
          type: array
          items:
            type: string
            description: The holiday type which needs to be excluded from response
            example: TOUR
    Problem:
      type: object
      properties:
        type:
          type: string
        system:
          type: string
        title:
          type: string
        details:
          type: string
    PackageOfferFlight:
      type: object
      required:
      - type
      - segments
      properties:
        type:
          $ref: '#/components/schemas/DirectionType'
        segments:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/FlightSegment'
        duration:
          type: integer
          description: Flight duration in minutes
          example: 123
    CancellationRuleResponse:
      type: object
      properties:
        type:
          type: string
          description: type of the cancellation rule
          example: FREE
        amount:
          type: number
          format: double
          description: amount to pay if cancellation rule is not FREE
          example: 0
        daysAfterBooking:
          type: string
          description: amount of days after booking to allow free cancellation
          example: '15'
        daysBeforeDeparture:
          type: string
          description: applicable days before departure should be met to allow cancellation rule
          example: '70'
    Medium:
      type: string
      description: Medium code, WR required
      enum:
      - TUI_STORE
      - MOBILE_AGENT
      - THIRD_PARTY_AGENT
      - CSC
      - CUSTOMER_UI
      - OTA
      - TUI_PARTNER
      - TUI_STAFF
      - TUI_BUSINESS
      - SHARER
      - GDS
      - TUI_APP
    SourcingCategory:
      type: string
      description: flight sourcing either contracted or dynamic
      example: CONTRACTED
      enum:
      - CONTRACTED
      - DYNAMIC
    BoardCode:
      type: string
      description: 'board type code of the accommodation unit processed for offer

        '
      example: AI
      enum:
      - GT06-AO
      - GT06-BR
      - GT06-HB
      - GT06-FB
      - GT06-AI
      - GT06-HB_ST06-PL
      - GT06-FB_ST06-PL
      - GT06-AI_ST06-PL
      - A24
      - AB
      - AI
      - AI+
      - BB
      - CB
      - FB
      - FB+
      - HB
      - HB+
      - IT
      - PI
      - RO
      - SC
      - SC+
      - SSC
    Traveller:
      type: object
      required:
      - id
      - age
      properties:
        id:
          minimum: 1
          type: number
          format: integer
          description: passenger id
          example: 1
        age:
          minimum: 0
          type: number
          format: integer
          description: passenger age
          example: 30
    ValidationProblem:
      type: object
      properties:
        problem:
          $ref: '#/components/schemas/Problem'
        validationIssues:
          type: array
          items:
            type: string
    FilterOptionType:
      type: string
      enum:
      - HOTEL
      - COUNTRY
      - DESTINATION
      - RESORT
      - REGION
      - CONCEPT
      - ITINERARY
      - CONTINENT
      description: needed for the specifying destination type.
      example: COUNTRY
    Brand:
      type: string
      description: Brand code
      enum:
      - TUI_BE
      - TUI_NL
      - VIP_BE
      - TUI_UK
      - TUI_IE
      - FIRST_CHOICE
      - TUI_SE
      - TUI_DK
      - TUI_FI
      - TUI_NO
    SearchRequestDestination:
      required:
      - code
      - type
      type: object
      properties:
        code:
          type: string
          example: A0418356
          description: code of the destination, like country code or accommodation code
        type:
          $ref: '#/components/schemas/FilterOptionType'
    PackageHoliday:
      required:
      - totalItemsCount
      type: object
      properties:
        totalItemsCount:
          type: integer
          format: int32
          default: 0
          description: total number of the results for search criteria
          example: 316
        offers:
          type: array
          description: paginated offers response information
          items:
            $ref: '#/components/schemas/PackageOfferResponse'
    UnitAllocationType:
      type: string
      enum:
      - ROOM
      - VILLA
    CommercialProductType:
      type: string
      enum:
      - SUN_AND_BEACH
      - LAKES_AND_MOUNTAINS
      - CITY
    ListOfferShortDescription:
      type: object
      properties:
        markdown:
          type: string
        category:
          type: string
        title:
          type: string
    Environment:
      type: string
      description: Environment which is used to get request / response from backend inventory
      enum:
      - hybdv1
      - hybdv2
      - hybdv3
      - hybdv4
      - hybdv5
      - hybdv6
      - hybdv7
      - hybdv8
      - hybdv9
      - hybdv10
      - st3
      - st5
      - pprd
      - prdsup
      - dev
      - sit
      - prod
    SourceMarket:
      type: string
      description: This is the single brand indicator parameter.
      example: NL
      enum:
      - NL
      - BE
      - FR
      - MA
      - UK
      - IE
      - DE
      - PL
      - CH
      - AT
      - SE
      - 'NO'
      - DK
      - FI