Overview

This use case is ideal for brokers aiming to stay informed about published or updated empty legs within the Avinode Marketplace, either from a specific company or for a designated route of interest. By subscribing to notifications, brokers can seamlessly download and integrate empty leg data into their end client application, facilitating convenient displaying of available empty leg flights matching certain criteria.

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.

It's also important to be familiar with the concept of webhooks and how they work.

Implementation

The application gets notified and downloads empty legs from Avinode which match certain pre-set criteria. To implement this use case, the integrating application needs to be capable of receiving webhook notifications and responding to these by calling on appropriate endpoints with valid payload data.

Workflow

1. Webhook settings are created to include the notification event "Empty Legs" by calling POST /webhooks/settings with a valid payload.
2. An Empty Leg Watchlist is created by calling POST /emptylegs/watches with a valid payload.
3. After the initial creation of the Empty Leg Watchlist, a call to GET /emptylegs/watches/{watchId}/getall is made once to get a response containing all the currently available empty legs matching the watchlist.
   Please note: Calling this endpoint more than ONCE on the initialisation of the Empty Leg watch list is not allowed.
4. When any Empty Legs that match the watchlist are updated/removed, a webhook notification is sent with the Empty Leg ID for which the change is concerned. A GET /emptylegs/{emptyLegId} call should be made to retrieve the status of the Empty Leg in question.
5. The application backend updates/removes the affected Empty Leg as required from the internal record of Empty Legs to ensure it is always kept up-to-date.

Setting up webhook notifications

Webhook notifications are used to send out the message of a new, updated or removed empty leg. See the Avinode Webhooks page for more details on how to create these settings, and the "empty legs" section for how to specifically subscribe to empty leg notifications. Webhook settings for the notification event "Empty Legs" will have to be set up by calling on the POST /webhooks/settings endpoint with valid payload.

Setup an Empty Leg Watchlist subscription using the API

The Empty Leg subscription, also known as an "empty leg watch configuration", is setup using the API. Once created the settings can also be viewed inside the Avinode web UI by navigating to Company -> Settings -> Empty Leg Notifications or by calling on the GET /emptylegs/watches/{watchId}.

The Empty Leg watch configuration is created using endpoint POST /emptylegs/watches and should contain some of the following criteria, where specifying at least one segment is required.

• List of segments (region to region pairs) where at least one should match to send a notification. A segment can be defined using either an airport code, an ICAO prefix (to define the airport region) or a country code (also province code is available but only for the US and Canada)
• Aircraft category, type or tail number
• Should the empty leg be priced
• Should the empty leg be verified by the seller
• Number of days out are you looking for (a rolling calculation of if the empty leg departure is within NOW + the configured days out (Avinode will only notify of Empty Legs within this span).

Downloading Empty Leg details

When an Empty Leg matching the watchlist is published or updated in Avinode, a webhook notification will be sent and the details of the Empty Leg can be downloaded by calling on the GET /emptylegs/{emptyLegId} endpoint.

The current status of a specific Empty Leg will be reflected by the "published" : boolean parameter within the response payload, where the value true indicates the Empty Leg being available, and false indicating it is no longer available. A HTTP 404 - Not found response should also be interpreted as the Empty Leg no longer being available.

End client requests

This part of the implementation deals with when the end client wants to create a booking request from one of the trip options presented. The booking request will be available as a client lead in the Avinode Marketplace for the company owning the API connection that was used. From here the Avinode member can perform the final sourcing of aircraft to suit the end client's needs.

The generated client lead data can be downloaded into an external quoting tool, to store the customer information etc. Using the deep links provided in the response from the lead request, it's possible to initiate a pre-filled aircraft search in Avinode, directly from the external system, avoiding any double entry. See the Deep links section below for more details.

Create the end client lead

The application should call the POST /leads endpoint with details about what the end client has requested, and also the end client’s contact information. This lead will show in the broker's Trips - Client Leads page in Avinode Marketplace, and from here it's easy to send a request on the chosen empty leg or alternatively to initiate an aircraft search from the given itinerary.

Client lead push notifications

There is also the option as a broker to subscribe to notifications for every incoming client lead that your application generates. Once notified, the lead data can be downloaded into an external quoting tool.

Read more about how to setup Avinode webhook notifications.

Deep links

When downloading the client lead to your backend system, there will be two deep links available in the response data (see screenshot below), to use for opening up a new browser window with Avinode:

• viewInAvinode - takes the broker directly to the newly created lead inside Avinode, showing all the trip request and customer information
• searchInAvinode - opens up an aircraft search in Avinode (based on the lead itinerary) that will be initiated immediately for further sourcing

Read more about working with deep links here.

Restrictions

Data displayed to the end client

Without explicit approval from Avinode, any information that can easily identify operators may not be displayed to the end client.

🚧

Updating Empty Legs

The application can download and store empty legs when notified through webhooks. However, it must promptly update any changes received through webhooks, including removing empty legs no longer published. This means the application must:

• Promptly update empty legs stored with any changes received through webhooks
• Not store or show empty legs that are different from the latest state in Avinode.
• Remove and no longer store any empty legs that no longer exist or are no longer published (published: false)

Go Live!

👍

Implementation checklist

All items on this checklist must be implemented for an application of this type to be allowed to call the live production environment of Avinode Marketplace:

1. The application must comply with the Basic Go Live requirements.
2. The application sets up the webhook settings successfully with the notification event "EmptyLegs" by calling POST /webhooks/settings with valid payload
3. The receiving webhook server responds with a HTTP 200 status upon receiving and accepting the webhook notification
4. The application sets up the Empty Leg watchlist successfully by calling on the POST /emptylegs/watcheswith valid payload
5. The initial call to GET /emptylegs/watches/{watchId}/getall is only made ONCE to get a response containing all the currently available empty legs matching the watchlist
6. The application successfully downloads new or updated empty legs when notified via webhook by calling on the URI specified within the notification payload
7. The application maintain its internal empty leg data up-to-date, and must promptly update any changes received through webhooks, including removing empty legs no longer published.
8. The application does not display any information (seller name, aircraft tail number, etc.) or images from the empty leg data that could easily identify the seller/operator.
9. The application does not allow the end client to send out a request RFQ directly to an operator based on the empty leg data. The empty leg preferred by the end client should be used to generate a lead in Avinode Marketplace.
10. The application calls on the appropriate POST /leads endpoint with valid parameters, which will generate a Client Lead in Avinode Marketplace.