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. Once the outcome of the trip is known, you can also report back to Avinode whether the trip was booked and, if so, with which operator.

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

Correlating trips with your external system

When creating a trip using POST /trips, your application can include an externalTripId in the request body.

externalTripId is an identifier assigned by your own system. If provided, Avinode returns the same value in the response. This allows your application to correlate the Avinode trip with the corresponding trip, inquiry, or trip package in your system.

{
  "criteria": {
    "requiredLift": [
      {
        "aircraftCategory": "Heavy jet"
      }
    ]
  },
  "segments": [
    {
      "startAirport": {
        "icao": "ESGG"
      },
      "endAirport": {
        "icao": "EDDF"
      },
      "dateTime": {
        "date": "2027-05-20",
        "time": "09:00",
        "departure": true,
        "local": true
      },
      "paxCount": "2",
      "paxSegment": true
    }
  ],
  "sourcing": true,
  "externalTripId": "CRM-TRIP-1042"
}

Your application can therefore store externalTripId as the reference to the corresponding record in your own system while using the Avinode identifiers for subsequent Avinode API operations.

{
  "meta": {
    "errors": [],
    "warnings": [],
    "infos": []
  },
  "data": {
    "id": "atrip-71234567",
    "type": "trips",
    "tripId": "K7M2QX",
    "externalTripId": "CRM-TRIP-1042",
    "rfqs": []
  }
}

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.

When the user opens the searchInAvinode deep link, the search starts automatically in the Avinode Web UI. It uses the details provided in the POST /trips request, such as the itinerary, dates and times, number of passengers and aircraft category, so the user does not need to enter the trip again. Once the search has completed, the user can review the results and send RFQs to the selected operators.

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.

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.

Sparse Fields

For some operations, there is information available that will only be included in the operation output if it is requested when making the API call. This extra information is requested by specifying one or more values in the operation's field[operation] URL parameter. The API reference page for each operation have information about the available sparse fields (also knows as query params).

For more information, see: Sparse Fields under API Basics

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 updated quotes

When a seller accepts your RFQ, a webhook notification will be sent to the broker containing a seller message ID.
You can get the updated quote ID from the "sellerQuote" object in the response payload after sending a GET /tripmsgs/{messageId} request.
You can read the new quote with the GET /quotes/{id} endpoint.

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.

See more details and examples on each webhook notification type.

Responding to New Seller Message

Sellers can send chat messages on a trip, for example to ask a question about the request or to add information to their quote. Supporting chat in your own system is optional. However, your integration should always make the user aware that a new message is waiting in Avinode, for example with a notification or an indicator on the trip, and give them a way to read and reply to it.

You can implement this 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

If you choose not to support chat in your own system, your integration should still notify the user when a new message has been received, and use the viewInAvinode deep link to take them directly to that trip and message in the Avinode Web UI.

The deep link is 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-80123456",
    "href": "https://sandbox.avinode.com/api/tripmsgs/asellermsg-80123456",
    "type": "tripmsgs",
    "links": {
      ...snip...
    },
    "lift": [
      {
        // ...snip...

        "actions": {
          "viewInAvinode": {
            "type": "viewInAvinode",
            "description": "View in Avinode",
            "httpMethod": "GET",
            "href": "https://sandbox.avinode.com/marketplace/mvc/trips/buying/atrip-71234567?source=api#eyJleHBlZC1N0t-w0rKiN6ybGlmdjU4NTYifQ=="
          }
        },
        "aircraftCategory": "Heavy jet",
        "aircraftType": "Gulfstream G-V",
        "aircraftSuperType": "Gulfstream G-V",
        "suggestedByAvinode": false,
        "sourcingDisplayStatus": "Unanswered",
        "sourcingStatus": 1
      }
    ],
    ...snip...
  },

  "tripId": "K7M2QX"
}

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
• OTHER

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

Report the trip outcome

Close the loop between your CRM or back-office system and Avinode by reporting the final outcome of a trip. Once the outcome is known, use the PUT /trips/{id}/outcome endpoint to report whether the trip was CONVERTED or NOT_CONVERTED. If the trip was converted, you can also report which operator won the trip.

You do not need to build the URL yourself. Every trip response includes a reportOutcome action containing the URL and HTTP method to use.

"reportOutcome": {
  "type": "reportOutcome",
  "description": "Report outcome",
  "httpMethod": "PUT",
  "href": "https://sandbox.avinode.com/api/trips/atrip-71234567/outcome"
}

Why report trip outcomes?

Reporting outcomes provides a more complete picture of the sourcing workflow, from creating the trip and requesting quotes through to the final booking decision. The outcome is stored on the trip and returned whenever the trip is read through the API.

A typical integrated workflow looks like this:

1. Create the trip using POST /trips
2. Search and send RFQs in Avinode using the searchInAvinode deep link
3. Receive quotes from operators
4. Select the operator in your system
5. Report the outcome using PUT /trips/{id}/outcome

Converted trip: operator selected through Avinode

If the trip was booked with one of the operators you sourced through Avinode, include winningSellerLiftId in the request. This is the id of the operator's seller lift, which you will find under rfqs > sellerLift when reading the trip using GET /trips/{id}. Lifts the operator has quoted on have the sourcingDisplayStatus set to Accepted. Any seller lift on the trip can be reported as the winner, including lifts the operator declined or did not respond to, for example if the deal was agreed outside of the RFQ response.

"rfqs": [
  {
    "id": "arfq-130456789",
    "sellerCompany": {
      "displayName": "Acme Air Charter"
    },
    "sellerLift": [
      {
        "id": "asellerlift-171234567",
        "aircraftType": "Gulfstream G-V",
        "aircraftTail": "N123AB",
        "sourcingDisplayStatus": "Accepted"
      }
    ]
  }
]

Use the seller lift ID (asellerlift-...). Quote IDs and RFQ IDs are not accepted.

{
  "outcome": "CONVERTED",
  "winningSellerLiftId": "asellerlift-171234567"
}

Converted trip: booked outside of Avinode

If the trip was booked with an operator outside of Avinode, report the operator's name in winningTenantName. You can also include the tail number of the aircraft used in winningTailNumber.

{
  "outcome": "CONVERTED",
  "winningTenantName": "Example Jet Charter",
  "winningTailNumber": "N456CD"
}

Trip not converted

If the trip was not booked, report it as NOT_CONVERTED.

{
  "outcome": "NOT_CONVERTED"
}

Updating the outcome

The outcome can be updated at any time by calling the endpoint again, for example if the result changes after your initial report. reportedOn keeps the time of the first report, while updatedOn shows when the outcome was last changed.

Each request replaces the previously reported outcome. If you update a converted trip, include the winning operator again, otherwise it will be removed.

Outcome in the trip response

The endpoint returns the updated trip, and the outcome is included under outcome whenever you read the trip. The outcome object is not included until an outcome has been reported.

"outcome": {
  "outcome": "CONVERTED",
  "reportedOn": "2027-05-06T14:31:08.420153800Z",
  "updatedOn": "2027-05-07T09:12:44.095612000Z",
  "winningTenant": {
    "companyId": 12345,
    "displayName": "Acme Air Charter"
  }
}

When the operator was reported using winningTenantName, winningTenant only contains the displayName, and the tail number is returned in winningTailNumber.

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 requirements

Before your integration can be approved for production access, it must meet all the requirements outlined below. During your go-live demo, we'll review your implementation and verify that each requirement has been successfully met.