End Client Empty Leg Subscription

Designed for brokers, this use case allows easy integration of Avinode Marketplace empty leg data into end client applications.

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" section.

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 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.

Restrictions

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 form the latest state in Avinode.
• Remove and no longer store any empty legs that are no longer exist or are no longer published (published: false)

Go Live!

👍

Implementation checklist

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.