Overview

Buyers use the Avinode Marketplace to find suitable aircraft for their customers’ trips. Buyers normally send quote requests to multiple operators for each trip. Sellers can use the Avinode Marketplace to respond to these RFQs. This use case makes it possible to integrate into the workflow of receiving and responding to RFQs.

Implementing this use case enables RFQs to be downloaded into the software which can be used as an external quoting tool. The seller can then create a quote in the software and send it to the buyer by uploading it back to the Avinode Marketplace via the API connection. Alternatively, the RFQ can be declined if the operator has no availability for this trip or is unable to perform it for some other reason.

🚧

Please note

• In order for an application to be allowed to download RFQs, it must also upload responses back to the Avinode Marketplace
• In order to download and respond to RFQs, your aircraft availability must be up to date in Avinode.

Pre-requisites

Gaining an understanding of our APIs and fundamentals is essential to the success of your project. To do so, start by reading our introduction page, including the pages linked in the "Before you start developing" section.

Since this use case is heavily dependent on using webhook notifications, also make sure to read about how our webhooks work.

There should always be only one version of a quote in both Avinode and the integrating system and these should be kept in sync. Whenever there is an update or change to the quote, i.e. pricing, aircraft, airport fees, or other additional line items, etc. these should be sent to Avinode to reflect in the quote update API call. All line items should be sent, there is however the possibility to hide these from the buyer (read more here), if this is preferred by the seller.

Implementation and API Examples

Webhooks

Proper setup of webhooks is essential to ensure that the back-end of the API solution receives timely notifications regarding all relevant changes in Avinode. Read more here: Create webhook settings

For this use case, the following webhook events should be set up:

📘

Additional Event Notifications for Sub-chartering

Additional API permissions may be required to download on the following webhook notification events, as it may be related to the operator's membership level, such as sub-chartering of trips:

• Trip Request (My Company): Notifies you when someone in your company sends a trip request / cancellation
• Trip Request - Seller Response: Notifies you when a seller responds to your trip request
• Trip Chat - Seller: Notifies you on a trip chat message from a seller

Download RFQ

The application can call upon the following endpoints when downloading RFQ-related data for an RFQ that has not been previously downloaded.

Note: The last two types of RFQ data are optional, as they pertain to either obtaining more quote details about the requested lifts (Get quotes for requested lifts) or aiming to obtain more details about requested empty legs (Get information about requested empty legs).

Get basic RFQ details

The GET /rfqs/{id} operation is called to get the basic RFQ details.

The RFQ always contains:

• sellerCompany– Information about the company that this RFQ was sent to.
• buyerCompany– Information about the company that created this RFQ.
• buyerAccount– Information about the person that created this RFQ
• segments– Information about the requested itinerary.
• tripId– This is the ID of the requested trip. It is the same TripID that can be seen in the Marketplace Trips Selling/Buying pages. This ID can be displayed in the application.

The RFQ may also contain:

• links.tripmsgs – One or more chat messages related to this RFQ. This can be both buyer messages and your own response as a seller.
• sellerLift– Information about what specific lift the buyer has requested. The The API supports receiving requests on a specific aircraft tail, aircraft type, or aircraft category (the latter options suitable for floating fleets).
• canceled – If the trip has been canceled by the buyer, this property will be set to true. The request cannot be responded to in this state. Any text message from the buyer and the cancellation reason can be found in the associated buyer message listed in the RFQ. Read more under the Canceled trip section.

If the RFQ contains requested lift, then each requested lift may contain:

• sellerLift.links.quotes – Quotes for this lift.
• sellerLift.links.emptylegs – Empty legs related to this lift. This exists if the buyer has requested an empty leg.

📘

Additional quote data

Additional data may be requested through the use of sparse fields.

To obtain the price line items included in the initial quote generation, the sparse fields parameters aviquote and quotebreakdown should be sent in the RFQ download request.

The GET /rfqs/{id} page has more information about the data returned by this operation.

📘

API generated IDs

Unless specifically stated in this documentation, the format of any object’s identifier is unspecified and can change at any time. Therefor an operation that currently returns an ID that looks like “abc-12345678” may change to, for example, “1234-ABCD-5678-EF90”. So the application should not try to extract parts of these ID's for any reason. If the format of an ID changes, the API operations using this ID as input will continue to support previous formats.

The application should not display any API generated ID's to the user, unless this documentation specifically states that the particular ID can be displayed.

Get RFQ chat messages

By subscribing to the event type "TripChatFromBuyer" the operator will be notified each time a buyer responds with a chat message related to an RFQ. The GET /tripmsgs/{id} endpoint inside the notification message is called to get the details of each chat message (links.tripmsgs).

For each chat message the following information is always included:

• sellerCompany– Information about the company that this message was sent to. For this use case, it will always be the same as the sellerCompany in the RFQ.
• buyerCompany– Information about the company which created the message. For this use case, it will always be the same as the buyerCompany in the RFQ.
• buyerAccount– Information about the user which created the message. This can be a different user than the user which originally created the RFQ.
• message– The chat message content.

The GET /tripmsgs/{id} page has more information about the data returned by this endpoint.

List all buyer messages in an RFQ

To avoid having to make an extra request call to fetch each new buyer message, you can list all current buyer messages directly in the RFQ response by adding the sparse field buyermessages to the GET /rfqs/{id} call.

Get quotes for requested lifts

Using the quote ID found in the RFQ response (sellerLift.links.quotes), the GET /quotes/{id} endpoint is called to get the details of each quote.

The GET /quotes/{id} page has more information about the data returned by this endpoint.

Get information about requested empty legs

Using the emptyleg ID found in the RFQ response (sellerLift.links.emptylegs), the GET /emptylegs/{id} endpoint is called to get the details of any requested empty legs.

The GET /emptylegs/{id} page has more information about the data returned by this endpoint.

Respond to RFQ

This section will explain how to implement the possibility of responding to an RFQ. The application should use the different actions that were returned when the RFQ was downloaded with the GET /rfqs/{id} operation.

• All submit quote actions should use the input described on the POST /tripmsgs/{requestId}/submitQuote page.
• All decline actions should use the input described on the POST /tripmsgs/{requestId}/decline page.

📘

Remember

The requestId used as path param is either a:

• lift ID - using this will decline or submit a quote for a specific requested lift in the RFQ. If the RFQ contains other requested lifts, not yet declined or quoted, then these will still be considered unanswered.
• RFQ ID - using this will decline the entire RFQ, including any requested lift, or if , it will add a new lift with an associated quote to the original RFQ

Quote or decline a specifically requested lift

The application should call the sellerLift.actions.submitQuote or the sellerLift.actions.decline** action, using the lift ID. See screenshot below.

Add an additional quote

To add a quote for a tail that was not originally requested, the application should call the actions.submitQuote action, using the RFQ ID. The additional tail should be specified in the request body under quote.lift.aircraftTail. See screenshot below.

Decline the entire RFQ

To decline all of the requested lifts in an RFQ, the application should call the actions.decline action, using the RFQ ID. See screenshot below.

Decline reasons

When declining a quote, either a specific lift or the entire RFQ, it's possible to send the declineReason value with the call, to specify a specific reason for not accepting the request. See the table below for the predefined values. If none of the predefined values match the decline reason then _OTHER _should be selected.

This feature allows for more detailed mapping of quote declines and enhances the reporting capabilities in Avinode by categorizing the reasons for decline in the Operator Request-Response report.

In addition to the decline reason, the message string can be used to provide further details to the recipient, to enhance clarity and communication.

{
   "message": "The aircraft owner didn't approve the charter.",
   "declineReason": "OWNER_DECLINED"
}

Quote attachments

The quote response payload message may include supplementary details, such as PDF files encompassing a quote, terms and conditions, and more. For further details regarding quote attachments, kindly refer to the documentation provided here: POST /tripmsgs/{requestId}/submitQuote.

Specification of price line items and total price

When responding to a quote, it's important to accurately specify any modified or newly added price line items.

Note! To obtain the price line items included in the initial quote generation, the sparse fields parameters aviquote and quotebreakdown should be sent in the initial RFQ download request.

Additionally, please keep in mind that the total price sent through the API response should reflect the net amount, excluding any applicable sales tax. If there are sales taxes to be included, they should be presented as separate price line items within the quote

📘

Price line items and total net price

When including separate price line items within the quote, it is NOT necessary for their sum to match the total net price. The individual price line items can represent various components or charges, and their cumulative total may differ from the overall net price.

Below is an example of a typical payload using the POST /tripmsgs/{requestId}/submitQuote where line items are defined and the buyer visibility ("visibleToBuyer" : boolean) is toggled on and off.

...snip...
    
	"lineItems": [{
            "visibleToBuyer": false,
            "displayName": "Crew Swap",
            "description": "International crew swap, due to flight duty limitations.",
            "type": "CREW",
            "price": 7500,
            "formattedUnitPrice": "7500",
            "formattedQuantity": "1"
        },
        {
            "visibleToBuyer": false,
            "displayName": "Positioning",
            "description": "Aircraft repositioning KMIA-KLAS",
            "type": "POSITIONING",
            "price": 12000,
            "formattedUnitPrice": "4000",
            "formattedQuantity": "3"
        },
        {
            "visibleToBuyer": true,
            "displayName": "Catering",
            "description": "Exclusive catering arrangements, as per client request.",
            "type": "CATERING",
            "price": 900,
            "formattedUnitPrice": "450",
            "formattedQuantity": "2"
        },
        {
            "visibleToBuyer": true,
            "displayName": "Consierge",
            "description": "Limousine service from hotel to aircraft",
            "type": "OTHER",
            "price": 1100,
            "formattedUnitPrice": "1100",
            "formattedQuantity": "1"
        }
 	]
	
...snip...

Floating Fleet quoting options

With the addition of Floating Fleet support, the Avinode API is now able to allow quoting on a category or type of aircraft instead of, as previously, only on a tail. This will give you greater flexibility and control over how to structure, and use, the data available through the Avinode API. See input example below.

📘

Please note!

It is important to note that the request for a quote submittal should be done via POST /tripmsgs/asellerlift-{id}/submitQuote, providing the same asellerlift-{id} as in the initial request to be correctly responded to. Other lifts within the RFQ will remain unanswered unless quoted by calling on their specific asellerlift-{id} in the quote submittal call.

A request for a quote submittal using arfq-{id} by calling on POST /tripmsgs/arfq-{id}/submitQuote will simply add an additional lift, along with its quote, within the pre-existing RFQ, thus leaving the original requested lift in an "unanswered" state.

Answer ALL RFQs

For each RFQ the operator should ideally complete at least one of these:

• Answer all requested lifts by either calling the sellerLift.actions.submitQuote action or the sellerLift.actions.decline action, using the lift ID.
• Decline entire RFQ by calling the actions.decline action, using the RFQ ID.

As long as the operator hasn’t completed this, the broker will see the RFQ as unanswered or partially unanswered, and the broker would still expect more information from the operator.

🚧

Don't leave them hanging!

Leaving an RFQ unanswered or partly unanswered will negatively affect the operator response statistics in Avinode.

Get information about an updated RFQ

With the webhook notifications correctly set up, the API solution's back end will be notified by Avinode upon a change or update of an RFQ as soon as it occurs. When the application calls the GET /rfqs/{id} operation for an RFQ that has been previously downloaded, then it should look for the following updates:

• sellerLift– Additional lift requested by the buyer.
• sellerLift.links.quotes – If an additional lift has been requested, then these may have quotes.
• sellerLift.links.emptylegs – If an additional lift has been requested, then these may be requests for empty legs.
• tripmsgs– Additional text messages related to this RFQ.
• canceled– If the trip has been canceled by the buyer, this property will be set to true. The request cannot be responded to in this state. Any text message from the buyer and the cancellation reason can be found in the associated buyer message listed in the RFQ. Read more under the Canceled trip section.

Identifying quote source and integration software

As quoting can be done through various integrations or directly within the Avinode Marketplace, the GET /tripmsgs/{messageId} endpoint provides additional details regarding the quoting channel and the specific integration used. This information is available by including the sparse field fields[quotes]=channel in the trip message request.

The channel object may contain the following properties:

• channel: Specifies the origin of the quote, with possible values being "API" or "DESKTOP".
• softwarePartner: Provides additional information about the integration software. This object contains:
  • partnerId: The fixed, globally unique ID for this partner as a string.
  • partnerName: The name of the integration software used.

For reference, the structure of the response payload is shown below:

{
    ...
        "channel": {
            "softwarePartner": {
                "partnerId": string,
                "partnerName": string
            }
        }
    ...
}

This additional data helps identify the quoting method, offering insights into whether the quote originated from an API integration or the Avinode Marketplace interface.

Responding to a trip chat message

You have the option to choose between two workflows when implementing the feature to respond to a trip chat message.

Respond from your own system

This will enable your system to download and respond to chat messages via the API connection. Your system will have to call on the following endpoints: GET /tripmsgs/{messageId} and POST /tripmsgs/{requestId}/chat.

Chat messages sent via API can be up to 5 kilobytes of raw text data. The message content also accepts ASCII line breaks by using the \n for a new line.

Respond from Avinode Web UI via chat deep-link

Responding to chat messages via a deep-link provided in the API response body is possible when reading a buyer message. By calling on the viewInAvinode deep-link within the chat message response body, your system user will be taken directly to the particular chat message within the Avinode Web UI via a new browser window.

Canceled trip

A buyer has the possibility to cancel a trip. The operator will be notified through a webhook message that the RFQ has been updated. When fetching the updated RFQ, the property canceled at the bottom of the response will be set to true. Note! A canceled request cannot be responded to, so this should be highlighted to the user, saving them from quoting trips that are no longer valid.

Any text message from the buyer and the cancellation reason can be found in the associated buyer message listed in the RFQ. Buyer messages need to be fetched separately if sparse field buyermessages was not used when fetching the RFQ.

Data model

This data model shows the top level operator trip messaging related objects and their relationships. It should be used when storing this type of data. This model enables the buyer and operator to use messages to communicate with each other to share information and ask and answer any questions that may arise around this trip. It also enables the operator to, not only respond to the actual requested lift, but to also add additional quotes for alternate aircraft or routes.

RFQ

An RFQ is what a buyer sends to the operator when they want to ask for quotes for a specific trip. It contains information about who the buyer is and the itinerary of the trip. One RFQ can:

• have zero to many lifts
• have zero to many messages
• have zero to many quotes
• get additional message, lift and quote objects over time

Lift

Each lift represents something the buyer has specifically asked to get a quote for. It can be an actual aircraft (i.e. a tail number) , a type (e.g. Falcon 7X) or a category (e.g. Heavy Jet). One lift can:

• have zero to many quotes
• only belong to one RFQ
• be associated to zero or one empty leg. Either it has an empty leg object or it doesn’t. This cannot change over time

Empty Leg

A lift can be associated to an empty leg that the operator previously have published in the Avinode Marketplace. This indicates that the buyer would like to utilize this empty leg for this trip. One empty leg can:

• be associated to zero to many lift. These lift objects can be lift objects belonging to separate RFQs

Message

A message is a text message from either the buyer or the operator. It contains information about when the message was added and by which person at what company. A message can:

• only belong to one RFQ

Quote

Quotes are offers that the operator has communicated to the buyer. A quote contains information about what kind of lift the quote is for, the itinerary (may differ from the requested itinerary in the RFQ) and the price offered to the buyer. A quote may be “Avinode Generated”. This means that Avinode has used the aircraft performance and pricing information, provided by the operator, to generate a quote on behalf of the operator. A quote can:

• belong to one RFQ or belong to one lift

Workflow diagram: Download and Respond to RFQs

The following picture visualizes the common workflow between buyers and sellers in Avinode Marketplace.

Let's see if you are ready to go to production.

Optional features

Compare in Avinode

Use the data in your incoming trip requests (RFQs) to initiate a compare search in Avinode. This is a way to benchmark yourself against the market when evaluating an RFQ.

Initiate a search from the RFQ response

After you download your RFQs from Avinode, see Download RFQ, it is easy to initiate an automatic search by using the "searchInAvinode" action link. It will be present in the RFQ response data as shown below.

A browser window will open with the itinerary data from the RFQ already filled out, and the search will run automatically.

Flight Time Calculations

The Avinode Flight Time Calculation API facilitates the possibility of calculating the track and distance between various airports given an aircraft category, type, or specific tail.

Aircraft operators in Avinode can select the wind models to be applied under the Aircraft performance profiles in the settings for an individual tail. These winds, along with the aircraft's performance profile, will be taken into account when the flight times API endpoint is called with an aircraft tail specified. If only an aircraft category or type is specified in the call, the API will return a generic system calculation for that particular aircraft category or type.

For more information about this endpoint see POST /flighttimes

Go Live!

👍

Implementation checklist

All items on this checklist must be true in order for an application implementing this use case to be allowed to call the live Avinode Marketplace environment.

1. The application must comply with the Basic Go Live requirements.
2. All necessary webhook notifications are correctly set up and utilized, as required for the use case (trip request and trip chat messages).
3. RFQs are downloaded and presented to the user, as per webhook notification.
4. The application can handle responses from the GET /rfqs/{id} operation containing multiple sellerLift objects (i.e. the buyer has requested quotes for more than one of the operator's aircraft for this trip).
5. The application enables the user to respond to RFQs. This in the form of accepted, or declined quote(s) for some, or all of the lifts requested by the broker. The status of these should also be visible to the user of the application.
6. The application does not display API generated ID’s to the user, unless this documentation specifically states that the particular ID can be displayed. Read more here.
7. The application sends updated price line items within the quote, keeping it in sync within both the application and Avinode.
8. The application has support for sending and receiving trip messages using appropriate chat endpoints.
9. The application keeps data in sync, by utilizing webhook notifications. The application submits updated versions of the quote as needed, including all the quote price line items.