Trip Ninja MSDP (Dynamic Packaging) API

openapi: "3.0.0"

info:
    version: 1.0.0
    title: Trip Ninja MSDP API Documentation
    description: |
        <h2>Introduction</h2>
        Trip Ninja uses a REST API with requests and responses in JSON format. For development and testing, the pre-production servers
        are to be used. Once ready for live use, access to the production servers will be provided. All search endpoints have both production
        and pre-production endpoints - these correspond to the GDS’s production and pre-production services, and can be used as desired.<br  />
        <h2>Trip Ninja API URLs</h2>
        
        Pre-Production: https://preprodapi.tripninja.io
        
        For security, Trip Ninja’s servers are only accessible from whitelisted IPs. Please contact your account manager to whitelist IPs you
        will be using.
        
        Before you start ensure that:<br  />
            - IP addresses have been provided to be whitelisted for our servers.<br  />
            - PCC / OfficeID emulation via Trip Ninja’s PCC/OfficeID has been set up.<br  />
            - API username and password have been provided by Trip Ninja.<br  />
        
        <h2>MSDP</h2>
        Multi Stop Dynamic Packaging (MSDP) provides an alternative to traditional, static packaging. 
        It allows users to build packages as they go. While users search for multi-destination flights, 
        MSDP will find eligible hotels with which to bundle.
        
        <h2>Authentication</h2>
        Trip Ninja uses Basic Authentication standards. Simply encode your username and password string using base64 and pass it in the
        authorization headers. See the python example below on how this is done. In the example, the payload and API endpoint url are not
        shown.
        
        Python Example:
        
        <pre>
        import base64
        auth = base64.b64encode("USERNAME:PASSWORD")
        headers = {
            'authorization': "Basic "+ auth,
        }
        response = requests.post(url, headers=headers, data=json.dumps(payload))
        </pre>

    x-logo:
        url: 'https://s3.amazonaws.com/tn-api-docs/trip_ninja_logo.png'
        altText: Trip Ninja logo
        href: 'https://www.tripninja.io/'

servers:
    -   url: https://preprodapi.tripninja.io
        description: Pre-Production server

paths:
    /msdp/search/prod:
        post:
            summary: "MSDP Search"
            description: |
                This endpoint initiates a msdp search for one or more flights and one or more hotels, and returns a list of available flights and hotels options. A separate endpoint needs to be called to obtain information about flight details, hotel room types, etc.
            operationId: MSDPSearch
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/Requests/MSDPSearchRequest"
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/Responses/ItineraryNoHotelResultsSearchResponse"
                                    - $ref: "#/components/schemas/Responses/ItineraryHotelResultsSearchResponse"
                                    - $ref: "#/components/schemas/Responses/SegmentNoHotelResultsSearchResponse"
                                    - $ref: "#/components/schemas/Responses/SegmentItineraryHotelResultsSearchResponse"

                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/MSDPSearchErrorDetails/MISSING_MSDP_SEARCH_FIELD"
                                    - $ref: "#/components/schemas/MSDPSearchErrorDetails/INVALID_MSDP_SEARCH_REQUEST"
                                    - $ref: "#/components/schemas/MSDPSearchErrorDetails/INVALID_MSDP_ID"
                                    - $ref: "#/components/schemas/MSDPSearchErrorDetails/INVALID_MSDP_PACKAGE_DATES"
                401:
                    description: Unauthorized
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        description: Error code and 0 for success response
                                        example: "IE44"
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "User is not authorized"
                206:
                    description: Partial Content (no Flight/Hotel found)
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        description: Error code and 0 for success response
                                        example: "IE23"
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "No availability found: Try changing dates"
                500:
                    description: Server Error
    /msdp/results/flights/?trip_id={trip_id}:
        get:
            parameters:
                -   in: path
                    name: trip_id
                    required: true
                    schema:
                        type: string
                        example: 04187ebd88c965919a2b8d54ca98390a56cd48c5
                    description: Parameter to retrieve the flight results
            summary: "MSDP Get Flight Results"
            description: |
                This endpoint retrieves all the flight results from the prior msdp search
            operationId: MSDPGetFlightResults
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/Responses/MSDPGetFlightResultsItineraryResponse"
                                    - $ref: "#/components/schemas/Responses/MSDPGetFlightResultsSegmentResponse"
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        description: Error code and 0 for success response
                                        example: "IE38"
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "Trip ID not found"
                401:
                    description: Unauthorized
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        description: Error code and 0 for success response
                                        example: "IE44"
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "User is not authorized"
                500:
                    description: Server Error

    /results/hotels/?hotel_trace_id={hotel_trace_id}&rating={rating}&area={area}&min_price={min_price}&max_price={max_price}&min_distance={min_distance}&max_distance={max_distance}&hotel_chain={hotel_chain}&amenities={amenities}&sort_by={sort_by}:
        get:
            parameters:
                -   in: path
                    name: hotel_trace_id
                    required: true
                    schema:
                        type: string
                        example: 4f499298b303c55a1ee522118afce28abe2f68e4
                    description: Parameter to retrieve the hotel results
                -   in: path
                    name: rating
                    schema:
                        type: array of strings or string
                        example: 1
                    description: Parameter to filter the hotel results
                -   in: path
                    name: area
                    schema:
                        type: array of strings or string
                        example: Bedford
                    description: Parameter to filter the hotel results
                -   in: path
                    name: min_price
                    schema:
                        type: string
                        example: 100
                    description: Parameter to filter the hotel results
                -   in: path
                    name: max_price
                    schema:
                        type: string
                        example: 1000
                    description: Parameter to filter the hotel results
                -   in: path
                    name: min_distance
                    schema:
                        type: string
                        example: 10
                    description: Parameter to filter the hotel results (in km)
                -   in: path
                    name: max_distance
                    schema:
                        type: string
                        example: 100
                    description: Parameter to filter the hotel results (in km)
                -   in: path
                    name: hotel_chain
                    schema:
                        type: array of strings or string
                        example: WA
                    description: Parameter to filter the hotel results
                -   in: path
                    name: amenities
                    schema:
                        type: array of strings or string
                        example: Air Conditioner,Wifi
                    description: Parameter to filter the hotel results
                -   in: path
                    name: sort_by
                    schema:
                        type: string
                        example: price_low_to_high
                    description: |
                        Parameter to filter the hotel results<br />
                        Available Options:<br />
                            `closest`<br />
                            `price_low_to_high`<br />
                            `price_high_to_low`<br />
                            `rating_high_to_low`<br />
                            `rating_low_to_high`<br />
            summary: "MSDP Get Hotel Results"
            description: |
                This endpoint retrieves a specific MSDP hotel search result from the prior MSDP search
                Example URL: `/results/hotels/?hotel_trace_id=4f499298b303c55a1ee522118afce28abe2f68e4&rating=1,2,3&area=Bedford,Dartmouth&min_price=100&max_price=1000&min_distance=2&max_distance=50&hotel_chain=WA&amenities=Air Conditioning,Wifi&sort_by=closest`
            operationId: MSDPGetHotelResults
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SearchComponents/Hotel/ShouldIncludeHotelResultsResponse/items"
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "hotel_trace_id is not found"
                401:
                    description: Unauthorized
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        description: Error code and 0 for success response
                                        example: "IE44"
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "User is not authorized"
                500:
                    description: Server Error

    /msdp/search/removehotel/:
        patch:
            summary: "MSDP Remove Hotel Result"
            description:  This endpoint removes a specific hotel result from the prior msdp search. All msdp packages must have at least 1 hotel. An error will be thrown if you attempt to remove the final hotel from a package.
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/Requests/MSDPSearchRemoveHotelRequest"
            operationId: MSDPRemoveHotelResult
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/Responses/ItineraryNoHotelResultsSearchResponse"
                                    - $ref: "#/components/schemas/Responses/ItineraryHotelResultsSearchResponse"
                                    - $ref: "#/components/schemas/Responses/SegmentNoHotelResultsSearchResponse"
                                    - $ref: "#/components/schemas/Responses/SegmentItineraryHotelResultsSearchResponse"
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/MSDPRemoveHotelErrorDetails/INVALID_REQUEST"
                                    - $ref: "#/components/schemas/MSDPRemoveHotelErrorDetails/INVALID_NUM_OF_HOTELS"
                401:
                    description: Unauthorized
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        description: Error code and 0 for success response
                                        example: "IE44"
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "User is not authorized"
                500:
                    description: Server Error

    /msdp/detail/hotel/prod:
        post:
            summary: "MSDP Get Hotel Details"
            description: |
                This endpoint initiates a hotel search to get all the available rooms in a hotel, and returns a list of available hotel rooms options.
            operationId: MSDPGetHotelDetails
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/Requests/MSDPGetHotelDetailsRequest"
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Responses/MSDPGetHotelDetailsResponse"
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/MSDPHotelDetailErrorDetails/MISSING_FIELDS"
                                    - $ref: "#/components/schemas/MSDPHotelDetailErrorDetails/INVALID_IATA"
                                    - $ref: "#/components/schemas/MSDPHotelDetailErrorDetails/INVALID_FIELD_TYPE"
                                    - $ref: "#/components/schemas/MSDPHotelDetailErrorDetails/INVALID_FIELD_VALUE"
                                    - $ref: "#/components/schemas/MSDPHotelDetailErrorDetails/HOTEL_LOCATION_MISSING_TYPE_R"
                401:
                    description: Unauthorized
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        description: Error code and 0 for success response
                                        example: "IE44"
                                    message:
                                        type: string
                                        description: Contains the error message
                                        example: "User is not authorized"
                500:
                    description: Server Error

    /msdp/pre-booking/prod:
        post:
            summary: "MSDP Price Confirmation Report"
            description: "When performing an availability or price confirmation request - when a user has selected their MSDP package or is arriving on the site from
        metasearch - please send a request to the following endpoint. This provides valuable data to our revenue management system in
        determining markups for trips."
            operationId: "MSDPPriceConfirmationReport"
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Requests/PriceConfirmationReportRequest'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Responses/MSDPPreBookingResponse"
                206:
                    description: Partial Content
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/MSDPOTAPreBookingErrorDetails/NO_ROOM_AVAILABLE"
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/MSDPOTAPreBookingErrorDetails/MISSING_DATASOURCE"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/NOT_BOOKED"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/INVALID_FIELD_TYPE"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/MISSING_FIELDS"
                500:
                    description: Server Error


    /msdp/booking/:
        post:
            summary: "MSDP Booking Report"
            description: "When a booking is completed from a trip generated by Trip Ninja, report the booking to Trip Ninja via the booking endpoint."
            operationId: "MSDPBookingReport"
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Requests/BookingReportRequest'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: "success"
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/GeneralErrorDetails/NOT_BOOKED"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/INVALID_FIELD_TYPE"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/MISSING_FIELDS"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/INVALID_TRIP_ID"
                                    - $ref: "#/components/schemas/MSDPOTABookingErrorDetails/UNABLE_TO_RETRIEVE_ITINERARY_PROFILE"
                500:
                    description: Server Error

    /msdp/ticketing/:
        post:
            summary: "MSDP Ticketing Report"
            description: |
                When tickets are issued for a trip, please hit the following endpoint
            operationId: "MSDPTicketingReport"
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Requests/TicketingReportRequest'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: "success"
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/GeneralErrorDetails/NOT_BOOKED"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/INVALID_FIELD_TYPE"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/MISSING_FIELDS"
                                    - $ref: "#/components/schemas/GeneralErrorDetails/INVALID_TRIP_ID"
                                    - $ref: "#/components/schemas/MSDPOTATicketingCancelErrorDetails/INVALID_MSDP_PACKAGE_ID"
                500:
                    description: Server Error
    /msdp/cancel/:
        post:
            summary: "MSDP Cancel Booking Report"
            description: "To cancel a booking you have previously booked, report it to the Trip Ninja Service endpoint: “/msdp/cancel/”"
            operationId: "MSDPCancelBookingReport"
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/Requests/CancelRequest'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: "Trip has been cancelled."
                400:
                    description: Invalid Input
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/MSDPOTATicketingCancelErrorDetails/INVALID_MSDP_PACKAGE_ID"
                500:
                    description: Server Error



components:
    schemas:
        Requests:
            MSDPSearchRequest:
                description: Contains the searched parameters for the MSDP package search
                required:
                    - currency
                    - hotel_data
                    - flight_data
                    - credentials
                properties:
                    currency:
                        description: Currency to make the search in.
                        type: str
                        example: "AUD"
                    hotel_data:
                        description: parameters to search for 1 or more hotels
                        type: object
                        required:
                            - hotels
                            - traveller_total
                            - rooms_total
                            - rooms
                        properties:
                            hotels:
                                description: parameters for each hotel search
                                type: array
                                items:
                                    type: object
                                    required:
                                        - id
                                        - hotel_location
                                        - check_in_date
                                        - check_out_date
                                        - hotel_itinerary_reference
                                    properties:
                                        id:
                                            description: matching id from the flight id for the msdp package
                                            type: int
                                            example: 1
                                        hotel_location:
                                            $ref: "#/components/schemas/SearchComponents/Hotel/HotelLocation"
                                        check_in_date:
                                            type: string
                                            format: date
                                            description: "Date of check-in. format: YYYY-MM-DD."
                                            example: "2023-06-20"
                                        check_out_date:
                                            type: string
                                            format: date
                                            description: "Date to checkout from the hotel. format: YYYY-MM-DD."
                                            example: "2023-06-25"
                                        next_result_reference:
                                            $ref: "#/components/schemas/SearchComponents/Hotel/HotelNextResultReference"
                                        hotel_itinerary_reference:
                                            $ref: "#/components/schemas/SearchComponents/Hotel/HotelItineraryReference"
                            traveller_total:
                                description: Number of people that will be staying at the hotel.
                                type: int
                                example: 3
                            rooms_total:
                                description: The number of rooms required for the above travellers.
                                type: int
                                example: 2
                            rooms:
                                $ref: "#/components/schemas/SearchComponents/Hotel/HotelRooms"
                    flight_data:
                        description: parameters to search for 1 or more flights
                        type: object
                        required:
                            - flights
                            - travellers
                        properties:
                            flights:
                                $ref: "#/components/schemas/SearchComponents/Flight/Flights"
                            travellers:
                                description: "Array of passenger types, values include ‘ADT’, ’MIL’, ’CHD’ and ‘INF’"
                                required: true
                                type: array
                                example: [ 'ADT', 'ADT', 'CHD' ]
                            max_cache:
                                default: 24
                                description: |
                                    Hours to retain data queried from provider to be cached for use in future requests.
                                    Higher values result in:<br  />
                                        1) faster queries as more data is available for re-use<br  />
                                        2) lower look-to-book ratios from the GDS perspective which may lower costs<br  />
                                        3) less accurate pricing data which may cause issues in AirPriceReq when ticketing.<br  />
                                    Minimum value is 0.04 hours, maximum value is 720 hours.
                                    Please discuss with your Trip Ninja Account Manager if you need
                                    access to caching outside these limits.
                                type: integer
                            country_code:
                                description: "Country code where search came from (For example: CA, US)"
                                example: "CA"
                                type: string
                            cabin_class:
                                default: "E"
                                description: "Parameter toggles the permitted cabin class for your query. Alternatively, it can be set for each segment."
                                example: "E"
                                type: string
                            time_value:
                                default: 0
                                description: |
                                    This parameter helps set the value of a passenger’s time, in
                                    terms of the currency selected. It is used to trade off flight
                                    prices versus flight durations. The parameter is in units of
                                    [currency]/hour. Flight durations are calculated as the difference
                                    in minutes from the arrival time of the last flight in a leg to
                                    the departure time of the first flight in the leg.
                                    
                                    True Cost of Flight = [Flight Price] * [time_value/60] * [Flight Duration]
                                    
                                    The itinerary which provides the lowest True Cost of Flight is
                                    what is returned in the response. If you provide a time_value
                                    of 0 or do not provide the parameter, it will sort by price.
                

# --- truncated at 32 KB (157 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webjet/refs/heads/main/openapi/webjet-tripninja-msdp-openapi.yml