Download and Respond to RFQs
Download and respond to Avinode RFQs from within your system. There is also a possibility to initiate a compare search in Avinode based on an incoming trip request.
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 introductions page, including the pages linked in the "Before you start" section. Also read about our webhooks.
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:
| Event Type String | Name | Description |
|---|---|---|
| "TripRequest" | Trip Request | Notifies you on a new trip request, update or cancellation from a buyer |
| "TripRequestSellerResponseMine" | Trip Request - Seller Response (My Company) | Notifies you when someone in your company responds to, or in any way updates, a trip request |
| "TripChatFromBuyer" | Trip Chat - Buyer | Notifies you on a trip chat message from a buyer |
| "TripChatMine" | Trip Chat (My Company) | Notifies you when someone in your company chats on a trip |
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.
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 RFQ may also contain:
- links.tripmsgs – One or more text messages related to this RFQ.
- 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.
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.
The GET /rfqs/{id} page has more information about the data returned by this operation.
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
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.
Action input
- 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 will add a new lift with an associated quote to the original RFQ
Quote a specifically requested lift
The application should call the sellerLift.actions.submitQuote action, using the lift ID.
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.
Decline a specifically requested lift
The application should call the sellerLift.actions.decline action, using the lift ID.
Quote or decline a specific tail using the seller lift ID
Add an additional quote
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.
Decline the entire RFQ
The application should call the actions.decline action, using the RFQ ID.
Quote an additional tail or decline the entire RFQ at once using the RFQ ID
Specification of price line items and total price
When responding to a quote, it is important to accurately specify any modified or newly added price line items. 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. 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.
Please note
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.
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 then be notified that the RFQ has been updated/canceled. 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.
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.
Go Live!
Let's see if you are ready to go to production.
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.
- The application must comply with the Basic Go Live requirements.
- All necessary webhook notifications are correctly set up and utilized, as required for the use case (trip request and trip chat messages).
- RFQs are downloaded and presented to the user, as per webhook notification.
- 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).
- 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.
- The application sends updated price line items within the quote, keeping it in sync within both the application and Avinode.
- The application has support for sending and receiving trip messages using appropriate chat endpoints.
- 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.
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.
The 'searchInAvinode' action
A browser window will open with the itinerary data from the RFQ already filled out, and the search will run automatically.
Search In Avinode deep-link pop-up in Avinode
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
Updated 13 days ago
Check out the API reference for all the endpoint details: