Overview

By implementing this use case, you can quickly access and view available options for a trip without having to manually switch to the Avinode system and enter trip details. This feature enables seamless retrieval and display of available options for a specific trip through the Avinode API, saving valuable time and streamlining the buying process. Additionally, the integration allows for the downloading of leads, quotes, and launching a search in Avinode based on an inquiry from your end client.

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.

📘

Please note

When initiating a trip search this will need to be conducted within the Avinode Web UI via the deep-link explained below.

Implementation and API Examples

Initiate a Search in Avinode from Your System

The application should call the POST /trips operation with the needed trip information such as itinerary, number of passengers, aircraft category, date and time.
If the exact departure time is not known at the time this value can be marked as "TBD" (to be determined), see the API reference page for more details.

In the response from this API call there will be a deep link to use for opening a new browser window with the Avinode search, which will be initiated immediately. Read more about using deep links here.

Opening Deep Links in the Avinode Marketplace iOS App

The Avinode Marketplace iOS app supports searchInAvinode and viewInAvinode deep links provided by your application's back-end. When a deep link is opened, whether clicked or redirected from another app, it automatically launches the Avinode Marketplace app. If the user isn't logged in, they will be prompted to do so. Once logged in, the app directly displays the relevant search results, including itinerary details, passenger numbers, and aircraft categories specified in the deep link.

This feature streamlines the user's sourcing workflow, ensuring a smooth integration experience.

🚧

Please note

Avinode does not allow any business to business integrations to use the POST /searches operation, this API endpoint is only used by integrations from business to End-client.

Download RFQ for Requested trip

Once sourcing has been done within the Avinode Web UI, the application will be notified via webhook on where to fetch the appropriate RFQ via the GET /rfqs/{id} call. The RFQ(s) should be fetched by the calling application's back end upon webhook notification.

Webhook notifications

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:

See more details and examples on each webhook notification type.

Responding to New Seller Message

You can implement the feature to respond to new seller messages using one of two workflows.

1. Respond from your own system

This option allows your system to download and respond to chat messages via the API. To implement this, you will need to use the following endpoints: Read a trip message and Send a message.

2. Respond from Avinode Web UI via chat deep-link

You can also respond to chat messages through a deep link provided in the API response body when reading a seller message or downloading an RFQ.

By calling the "viewInAvinode" deep link found in the chat message response body (data.lift.actions.viewInAvinode) or the RFQ response body (data.sellerLift.actions.viewInAvinode), your system can redirect the user directly to the specific chat message within the Avinode Web UI in a new browser window.

{
   
    "data": {
        "id": "asellermsg-70609223",
        "href": "https://services.avinode.com/api/tripmsgs/asellermsg-70609223",
        "type": "tripmsgs",
        "links": {
        ...snip...
        
        },
      {
        "lift": [
            {
              ...snip...
            },
                "actions": {
                    "viewInAvinode": {
                        "type": "viewInAvinode",
                        "description": "View in Avinode",
                        "httpMethod": "GET",
                        "href": "https://marketplace.avinode.com/marketplace/mvc/trips/buying/atrip-50646110?source=api#eyJleHBlZE-N0t-w0rKiN6ybGlmdjU4NTYifQ=="
                    }
                },
                "aircraftCategory": "Super midsize jet",
                "aircraftType": "Challenger 350",
                "aircraftSuperType": "Challenger 350",
                "suggestedByAvinode": false,
                "sourcingDisplayStatus": "Unanswered",
                "sourcingStatus": 1
            }
        ],
				...snip...
        },

        "tripId": "USUKHG"
    }
}

Trip Cancellation

In the event that a trip needs to be canceled, use the PUT /trips/{id}/cancel endpoint. The request body should include a cancellation reason and a chat message explaining the cancellation. The cancellation reason must be one of the following: "BY_CLIENT", "CHANGED", "BOOKED", or "OTHER".

{
  "id": "atrip-1686310600",
  "messageToSeller": "Sorry, the client has requested to cancel this trip.",
  "reason": "BY_CLIENT"
}

Posting Trips to Avinode Trip Board

The Trip Board is a dynamic Avinode marketplace feature where brokers can post charter trip requests, and operators can browse and submit quotes for those trips. It enables efficient matching of flight demand with available aircraft, optimizing operations for both brokers and operators.

When creating a trip in Avinode you have the option to also simultaneously post it to the Trip Board. This is done by utilizing the POST /trips API endpoint and including the following parameters in your API call:

• postToTripBoard: Set this parameter to true in the POST /trips API call to ensure the created trip is posted to the Trip Board.
• tripBoardPostMessage: Optionally, include this parameter to add a custom message when posting the trip to the Trip Board.

Workflow diagram: Search in Avinode from Your System

Go Live!

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

👍

Implementation checklist

All items on this check list must be implemented in order for an application with 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. The application has correct eventTypes webhook notification settings configured for the use case, i.e.
   TripRequestSellerResponse, TripRequestMine, TripChatFromSeller, TripChatMine
3. The receiving webhook server responds with a HTTP 200 status upon accepting the webhook notification
4. The application is calling the POST /trips endpoint with valid itinerary payload
5. The application is utilising the searchInAvinode deeplink to run an automatic search in Avinode based on the trip payload
6. Sourcing activity, i.e. RFQ is sent to operator/s from within the Avinode Web UI
7. The application back-end successfully downloads the RFQ data, upon webhook notification
8. The application has support for sending and receiving trip messages using appropriate chat endpoints, alternatively, responds from within the Avinode Web UI by utilising the "viewInAvinode" deep-link
9. Updates (accept/decline/cancellation/chat messages) to the trip are sent to Avinode via appropriate API endpoints
10. The applicaton has support for when a trip gets cancelled, the appropriate PUT /trips/{id}/cancel endpoint is called containing a cancellation message and a cancellation reason.