Keep travelers informed with Traveler Trip Alerts

Traveler Trip Alerts is a collection of APIs that keep travelers informed of their flight status and updates.

This article shows you how to use the Trip Import API to send information to your internal systems so that you can then send information to your customers.

Audiences

  • Airlines
  • Online Travel Agencies (OTA)
  • Travel Management Companies (TMC)
  • Travel Tech

Platform

Trips and Waivers

Traveler Trip Alerts

Traveler Trip Alerts shorten your development time by removing the need to create and maintain business logic for when to send an alert and what to send. They connect all the individual flight segments into a single trip, which helps ensure travelers don’t miss connecting flights.

Traveler Trip Alerts allow you to send alerts to a traveler while on their trip. These alerts are sent to your internal systems via callbacks to your API endpoints. You can also request alerts at any time by using an API call to a Cirium endpoint.

In addition to the information provided by Cirium, your internal systems can provide additional processing. You can then send this information to the traveler using your preferred delivery partner.

Here are some advantages to using Traveler Trip Alerts:

  • They provide information about the traveler’s entire trip

  • Travelers receive contextually relevant messaging and aren’t over-messaged

  • You have multiple delivery options including API delivery (push or pull). You may also deliver information to the traveler using email or SMS

  • You may retrieve information at any time, including current flight status, by using the Trip Status API

  • You may include additional trip information by using solutions such as Waiver Alerts

  • All information about the traveler’s trip is displayed in the Cirium Trip Center

  • You may access trip history for troubleshooting and supporting customer issues

For a complete list of the information provided by Traveler Trip Alerts, see Traveler Trip Alerts.

Cirium also offers email alerts sent directly to the traveler. For more information, please contact us.

Setting up Traveler Trip Alerts

Use the following workflow to set up Traveler Trip Alerts.

1) Get an account key

To get started with Traveler Trip Alerts, you first need to get an account key. See Getting Started for more details.

2) Determine how the alerts are delivered

Explore the delivery options and determine which option is best suited for your application. We offer several options, each of which is explained in more detail below.

Direct API delivery via callbacks

In this scenario you provide Cirium with a HTTPS endpoint to call with each alert. When an alert is generated, we call your system with a payload containing the trip, current flight status for each leg in the trip, and details about the alert being generated.

The alert includes a unique reference number that you provide so that your own system can determine who the traveler is and how to deliver to them. It is then up to your system to deliver the message to the traveler.

In addition to the reference number, you can optionally include a list of attributes with the trip on import that are then passed along in the payload and can be used by your system to identify the traveler.

Direct API delivery via pull

In this scenario, when an alert is generated, we add a trip to queue for your account. Your system regularly calls Cirium via the Pull Trip Alerts API to retrieve up to 100 alert payloads. Each payload contains the trip, current flight status for each leg in the trip, and details about the alert being generated.

The alert includes a unique reference number that you provide so that your own system can determine who the traveler is and how to deliver information to them. It is then up to your system to deliver the message to the traveler.

In addition to the reference number, you can optionally include a list of attributes with the trip on import that are then passed along in the payload and can be used by your system to identify the traveler.

Direct delivery to the traveler via the traveler’s profile settings

We can host a profile for the traveler and use the profile to determine how (email or SMS) to send the message and where to send the email to. This is an advanced option and involves additional steps. If you would like to learn more about this option, please contact us.

3) Import the traveler’s trip

The Trip Import API is a Post request where the body of the request is a JSON structure that describes one or more trips and the delivery the options for that trip.

We recommend Trip Import API as the means for you to import trips. However, there are other ways that a trip can be imported into our trip monitoring system. We can read trips from GDS queues, back-office systems, or even via custom adapters. Importing trips via these systems are part of the onboarding process that can be included in your contract with Cirium. Contact us to learn more.

Here’s an example of a post:

Trip import

Multiple trips can be imported at once through the Trip Import API. The Trip Import Structure contains each individual trip and associated entities.

Pro tip

While the Cirium API can support up to 100 trips being imported in a single call, we don’t recommend doing this. Instead, we recommend importing a single trip with each request. This simplifies troubleshooting and increases overall timeliness of the system. In addition, if there is an issue with one or more trips, this can impact other trips within the payload being correctly imported and increases error-handling complexity.

Reference number

This is a unique string that identifies the trip. It’s most often set to the record locator from the PNR or a customer provided system key. The reference number is also used to update trips when trips change (see below for more information). When receiving an alert, this reference number can be used by your systems to match the trip with internal systems.

Delivery options

The alerting structure tells us where to deliver messages when something significant happens that should generate an alert. Multiple delivery points can be provided. However, the common use case is a single delivery option for directAPIDeliveries.

"alerting": {"directApiDeliveries": [{"url": "http://YOUR_ENDPOINT","alertSetting": "traveler","pullOnly": false}],]

URL

A valid HTTPS URL that we can deliver the message to.

Alert setting

This is set to the traveler for this use case.

Pull only

If you don’t want messages delivered, and would rather request or pull them yourself, set this to true. Otherwise we’ll make a call to the endpoint specified in the URL.

Flights

The trip must contain one or more flights. A flight is identified by an airline code and flight number from a departure at a specified time and arriving at another airport at a specified time. We’ll match the flights with real flights and might adjust information in the underlying trip data model that we’ll send as part of the delivery.

We’ll attempt to match the flight up until the point of departure. If the provided flights aren’t valid, you’ll receive messages such as Trip Reminder. However, there won’t be any status information associated with it.

Pro tip

If your application allows user-submitted flights or trips that aren’t loaded from a GDS or other PNR source, we recommend validating the existence of the flights by calling our Flight Schedules API services before importing the trip. This ensures that the flight is valid, which means you won’t be charged for monitoring a flight that doesn’t exist.

Attributes

Using this information is optional.

Attributes is a map of name/value pairs. This is only used for API delivery by push or pull. It’s used to store additional keys that help identify the trip and/or travelers in their own internal systems in those cases where reference number is not enough.

Passengers and loyalty programs

Using this information is optional.

This is a list of passengers and their frequent flyer numbers. We don’t recommend you provide this information as it includes personally identifiable information (PII).

It’s a common practice when displaying a traveler’s trip to include this additional information as part of the trip. If provided, this information is available with the rest of the trip information when receiving trip alerts via API or retrieving the trip using the Trip Status API. Your system could then match the trip with internal information and detail the trip yourself, without us knowing the information.

Another reason to provide this information is if your company is using Cirium Trip Center and you want your employees to be see the passengers on a particular trip using the UI.

Tickets

Using this information is optional.

Tickets isn’t used by Traveler Trip Alerts. We use this information in the Waiver solution as part of the matching logic. This information isn’t necessary if you aren’t using Waivers

Updating a trip

The same trip can be imported again at a later point if any of the information has changed, assuming that the reference number is the same. The new trip information overrides anything you provided previously.

Once you import a trip, you can’t delete. If you want to tell us to not monitor a previous imported trip, you need to import the same trip again and set the Canceled boolean to true. The trip can be retrieved at a later point using the Trip Status API.

Receive alerts based on the delivery choices

If Traveler Trip Alerts has been configured to send messages directly to the traveler, we’ll send information to the traveler when there is a relevant message.

For direct API deliveries via push, you need to ensure that the HTTPS endpoint that you specified is active. Use the Test Delivery API to send simulated alerts to your endpoint and make sure that the endpoint is properly coded to handle each case.

For direct API deliveries via pull, you’re responsible for routinely calling the Pull Alerts API to retrieve relevant alerts and process them. You can’t simulate alerts using this approach, so you should track the various types of alerts received during development to ensure that you have properly coded against each type. We recommended that you log any parsing errors that you encounter and regularly check your log files to find and fix problems.

Request the traveler’s trip

This is an optional task.

Once a trip has been imported into Cirium, you can retrieve that trip with the most up to date flight information by calling the Trip Status API. This request/response API allows for ad hoc retrievals of the trip. An example is if the traveler uses a mobile application that displays the user’s trip.

Pro tip

The Trip Status API is a useful API for troubleshooting purposes, or to periodically refresh trips.

Additional information

Here's some information that will broaden your understanding of Agent Trip Alerts.

Endpoint delivery timeliness

We make callbacks to your endpoint URLs. They're expected to be reliable and should respond within 2-300 milliseconds. Slower endpoints can slow down delivery. Unreliable endpoints can cause missed messages. If these requirements are of concern, we recommend the pull-based approach.

Message staleness

We typically retry sending the alert to the customer for up to 30 minutes. After that, we mark it as failed and stop trying to send the alert. Stale data is not helpful for the traveler.

Airline and airport codes

Unlike the FlightStats APIs, airport and airline codes in the Trip Import API are IATA codes, not FS codes or ICAO codes.

The one exception to this is in the Loyalty Programs array. In that case the airline code is a FS code (not IATA nor ICAO).

Unmatched flights

We attempt to match the flights within a given trip to actual flights. When we’re unable to match, no operational type messages (delay updates. canceled, departed, etc.) are triggered. However, any scheduled events (Trip Reminder, Leg Departure Info) are sent. These messages don’t contain flight status information.

How to code for the various message types

It can be challenging to code for all the different alert types since the triggers are based on trips with actual flights. Operational type messages such as cancelations, reinstatements, delays, etc. are dependent on those events happening on the flights you’re monitoring.

As an alternative, we recommend using the Test Delivery method. This triggers event types to a delivery endpoint you specify. It also allows you to code for the various situations that might arise.

Additional options

If you want more information than what’s provided by Traveler Trip Alerts, you have the following solutions:

Waivers

The Waiver Alerts notifies the traveler when their trip applies to airline travel waiver.

Weather information

The Weather APIs provides information about the weather at the traveler’s destination.

Airport Delay Index

The Airport Delay Index informs the traveler if their departure airport is experiencing delays.

Resources

See Traveler Trip Alerts for information on the types of alerts that Traveler Trip alerts deliver.

Trip Status API provides access to the latest trip status.

Trip Import API provides access for developers to import rips into the FlightStats Trip platform.

Waiver Alerts is an add-on service that matches trips and notifies travelers or agents depending on how it's configured.

Weather APIs provide current weather conditions at airports.

Pull trip alerts allows you to receive trip alerts via a request/response mechanism.