Article

Milefy API integration guide

The idea, that lies behind Milefy API can’t be simpler — you send intormation about your flights and we send you frequent flyer data for these flights back. But there is more to it — personalization, mileage tracking, status benefits, cabin upgrades, namely all features, that can maximize the user engagement with your platform.

This article is to help you to choose what do you need most, scope your integration, execute it and plan ahead to make your application even more profitable and your users even more happy.

Why do I need to plan anything?

Of course you can just open our API documentation and start coding right away, but that’s the fastest way to get into developer’s nightmare with a lot of frustration and postponed deadlines, which in turn results in poor user experience in your final application. Instead, you can plan the integration today with us, launch your first version tomorrow and then release more features day after day.

There are a few reasons why step-by-step approach works usually better, than integration with all features included at once:

  1. It’s easier to fit small chunks of integration work into your busy product pipeline,
  2. You can release new features faster, maintaining competitive edge over your competitors,
  3. You can hear your users’ feedback earlier, A/B test your solution and use this data to plan further steps.

Based on these arguments and our experience with many customer integrations, we prepared a sample integration roadmap for you. It always starts with MVP and then you may pick whatever features your users need most, implement them and release independently.

Table of contents
  1. MVP
  2. Personalization
  3. Status benefits
  4. Mileage tracking
  5. Cabin upgrades
  6. Gamification

Release 1: MVP

What’s included?

Award miles for every flight result

Number of award miles is what most of travelers are familiar with. It can provide a lot of value to wide range of audience and it’s very easy to implement. In this example award miles are named Basic Points, which is a name used in SAS Eurobonus frequent flyer program.

This stage includes flight search results with embedded number of award miles earned to default frequent flyer program. Default frequent program is automatically chosen based on flight’s marketing airline, for example for Lufthansa it is Miles & More program.

All types of earned miles

Different types of miles and traveler’s earnings in flight details. They may be displayed in different form, for example in a tooltip. This information is valuable for travelers interested in reaching higher status tier in frequent flyer program, which is the case for vast majority of business travelers.

All types of miles can be displayed on user request, containing number of miles earned per every type of mile (status miles, status segments etc.)

How to try this out?

Visit our API demo and tick only features listed below. Then run a search and see the result of MVP in action.

Select features from the marked section and try it out.

Features:
  • Miles
  • Upgrades
  • Benefits
  • Membership tracking
  • Alt. personalization

Try in API demo

How much time does it take?

The most basic integration can be accomplished in just a few hours by a team of 3-4 people consisting of at least one developer, one UX/graphic designer and a project manager.

That was proven by teams participating in NDC Hackathon co-organized by 30K and can be easily verified with completing our Getting Started tutorial.

Of course in reality developers are more constrained, designers need to test and refine their proposals and managers need to split their focus on many different tasks, but in robust environment 2 weeks should be more than enough to deliver MVP release.

Project manager UX designer Developers Duration
Scoping 1 day 1 day 1 day
Interface design 2 days 2 days
Prototyping 1 day 2 days 2 days
A/B testing 1 day 2 days 2 days
Beta version development 1 day 5 days 5 days
QA tests 1 day 1 day
Final version development 1 day 3 days 3 day
30K certification 1 day 1 day 1 day 1 day
Deployment to production 1 day 1 day
Total 5 days 7 days 12 days 18 days

Disclaimer: Total duration of 18 working days mean, that less than a month is needed to complete the integration. We assume, that there are 4 people in the team working partly on this project and the best industry practices in the software development are followed.

What are the key use cases?

Calculate mileage earnings

Algorytm in pseudocode using JavaScript syntax:


// User as recognized by the application
var user = getUser();

// Results of user flight search query
var flights = getFlightSearchResults();

if(!user.travelerId){

  // First-time visitor
  var traveler = milefyApi.createTraveler(user.countryCode);
  user.travelerId = traveler.id;

  // Store traveler ID for the next visit, for example in a cookie
  user.save();

}

// Calculate miles
var calculation = milefyApi.calculateFrequentFlyerInfo(user.travelerId, flights);
var searchResults = addMileageEarningsToFlights(flights, calculation);

// Show flight search results
showResults(searchResults);

user.on('books-flight', function(flight){

  // When user books a flight...  
  milefyApi.createBookingEvent(user.travelerId, calculation.id, flight.id, flight.bookings);

});

 

What are the key API methods invoked?

Calculate frequent flyer info
Needed to receive mileage earnings for submitted set of flights. Open documentation.
Create traveler
Individual traveler profile is necessary for every user, that performs a flight search. Reference to the traveler profile (traveler ID) is a required parameter of the Calculate frequent flyer info request. Open documentation.
Create booking event
Records an occurrence of the flight booking. Open documentation.

Release 2: Personalization

Requires: MVP

What’s included?

Mileage earnings personalization

Depends on the application, the personalization can take place: within the flight search form, on flight results page, as a callout in the flight details or inside user profile — read more about different solutions.

Traveler can select his frequent flyer programs and status tier for every each of them. This in turn allows to display the exact number of miles, that the traveler is going to earn for his programs. This way you can provide the most relevant information to the traveler and collect data about his preferences.

How to try this out?

Visit our API demo, tick only features listed below and add at least one frequent flyer program to your profile.

  • Miles
  • Upgrades
  • Benefits
  • Membership tracking
  • Alt. personalization

How much time does it take?

Project manager UX designer Developers Duration
Scoping 1 day 1 day 1 day
Interface design 3 days 3 day
Prototyping 1 day 2 days 2 days
A/B testing 2 days 3 day 3 days
Beta version development 1 day 3 days 3 days
QA tests 1 day 1 day
Final version development 1 days 1 day
Deployment to production 1 day 1 day
Total 5 days 8 days 7 days 15 days

What are the key use cases?

Add frequent flyer membership

var user = getUser();

if(!user.travelerId){

  // Creates traveler
  var traveler = milefyApi.createTraveler(user.countryCode);
  user.travelerId = traveler.id;
  user.save();

}

// User wants to add frequent flyer program membership to his profile or session
user.on('add-membership', function(programCode, statusTierCode){

  // Creates membership and assigns to the traveler
  milefyApi.createMembership(user.travelerId, {
    program: programCode,
    statusTier: statusTierCode
  });

});

 

What are the key API methods invoked?

Create membership
Creates new frequent flyer program membership and assigns it to the existing traveler’s profile. It the most simple form it requires only a frequent flyer program code, but we strongly recommend to request from traveler his status tier too. Otherwise basic status tier is assumed for mileage calculations performed in Calculate frequent flyer info method. Open documentation.
Edit membership
It can be used by the traveler, who has recently reached the next status tier. Using this method, he can manually update his frequent flyer membership selecting current status tier. Open documentation.

Release 3: Status benefits

Requires: Personalization

What’s included?

Status benefit summary

Small icons can provide a short summary of the most important status benefits, that traveler is eligible during any flight in a particular itinerary.

Traveler can be eligible for certain status benefits such as lounge access, priority check-in or extra baggage allowance. This information applies to specific flight segments being a part of a one flight result. The summary on a result level gives traveler just an overview of more detailed information, that can be found in flight details.

Status benefits in flight details

Besides benefit name, there might be a disclaimer available too.

List of eligible status benefits can be displayed for every flight segment with additional information.

How to try this out?

Visit our API demo and tick only features listed below. Add at least one membership to your profile and select non-basic status tier.

  • Miles
  • Upgrades
  • Benefits
  • Membership tracking
  • Alt. personalization

How much time does it take?

Project manager UX designer Developers Duration
Scoping 1 day 1 day 1 day
Interface design 4 days 4 day
Prototyping 1 day 2 days 2 days
A/B testing 1 day 2 days 2 days
Beta version development 3 days 3 days
QA tests 1 day 1 day
Final version development 1 day 1 day 1 day
Deployment to production 1 day 1 day
Total 4 days 8 days 7 days 15 days

What are the key use cases?

See releases: MVP and Personalization.

What are the key API methods invoked?

No additional API method needs to be used. Status benefits are available in Calculate frequent flyer info method response.

Release 4: Mileage tracking

Requires: Personalization

What’s included?

Wallet with traveler’s memberships

Traveler’s wallet with all his frequent flyer memberships. Connected memberships can be updated with new mileage balances automatically.

Wallet with traveler’s frequent flyer memberships stored permanently as a part of user profile is the easiest way for him to keep track of his mileage earnings. This way traveler’s earnings can be updated automatically with username and password being securely stored on behalf of the traveler.

How to try this out?

Visit our API demo and tick only features listed below. Then add a membership to your profile and connect to start tracking your miles.

  • Miles
  • Upgrades
  • Benefits
  • Membership tracking
  • Alt. personalization

How much time does it take?

Project manager UX designer Developers Duration
Scoping 2 days 1 day 2 days
Interface design 3 days 3 days
Prototyping 1 day 2 days 2 days
A/B testing 1 day 3 days 3 days
Beta version development 1 day 3 days 3 days
QA tests 2 days 2 days
Final version development 1 day 3 days 3 days
Deployment to production 1 day 1 day
Total 6 days 11 days 9 days 19 days

What are the key use cases?

Create and connect a membership of an existing traveler

var user = getUser();

// User creates membership and authenticates it with his frequent flyer account credentials
user.on('add-membership', function(programCode, formInputs){

  // Creates membership and assigns to the traveler
  milefyApi.createMembership(user.travelerId, {
    program: programCode,
    statusTier: statusTierCode
  });

  // Encrypt user credentials using SHA algorithm
  formInputs.forEach(function(credentials){
    credentials.value = encryptUsingSHA(credentials.value);
  });

  // Validates credentials and updates membership
  milefyApi.authenticateMembership(user.travelerId, programCode, formInputs);

  // Retrieves updated mileage balances
  var membership = milefyApi.getMembership(user.travelerId, programCode);

  // Displays to the user his mileage earnings in requested frequent flyer program
  showMileageEarnings(membership.mileageEarnings);

});

 

Update mileage earnings in a particular membership

var user = getUser();

// Request to update mileage earnings in traveler membership
user.on('update-membership', function(programCode){

  var membership = milefyApi.getMembership(user.travelerId, programCode);

  if(membership.authentication.storedCredentials){

    // Credentials are stored securely on behalf user by 30K
    // Easy, automatic update
    membership = milefyApi.updateMembership(user.travelerId, programCode);

  }else{

    // User decided not to store his credentials
    // Application requests from user login and password for one-time update
    user.requestMembershipCredentials().then(function(formInputs){

      formInputs.forEach(function(credentials){
        credentials.value = encryptUsingSHA(credentials.value);
      });

      // Updates mileage earnings
      milefyApi.editMembershipAuthentication(user.travelerId, perogramCode, formInputs);

      // Retrieves updated earnings
      membership = milefyApi.getMembership(user.travelerId, programCode);

    });

  }

  showMileageEarnings(membership.mileageEarnings);

});

 

What are the key API methods invoked?

Create simple authentication
The method connects an existing traveler’s membership to his real account in the frequent flyer program. It validates traveler’s credentials and updates the membership with the latest mileage balances, award miles expiration date and other information. After connection is established, the membership no longer can be manually edited using Edit membership method. Open documentation.
Update membership collection
This method can be used to update automatically all connected traveler’s memberships at once with minimum effort.

Release 5: Cabin upgrades

Requires: MVP

What’s included?

Cabin upgrades summary

Traveler can easily learn which flight is eligible for cabin upgrade and how much does it cost.

With this addition you can display on your flight search results which flight is eligible for upgrade, to which cabin and how many miles does traveler need to redeem for a particular upgrade.

How to try this out?

Visit our API demo and tick only features listed below.

  • Miles
  • Upgrades
  • Benefits
  • Membership tracking
  • Alt. personalization

How much time does it take?

Project manager UX designer Developers Duration
Scoping 1 day 1 day
Interface design 1 days 1 days
Prototyping 1 day 1 day 1 day
A/B testing 1 day 2 days 2 days
Beta version development 2 days 2 days
QA tests 1 day 1 day
Final version development 1 day 1 day 1 day
Deployment to production 1 day 1 day
Total 4 days 4 days 5 days 13 days

What are the key use cases?

See releases: MVP

What are the key API methods invoked?

No additional API method needs to be used. Cabin upgrades are available already in Calculate frequent flyer info method response.

Release 6: Gamification

Status progression

Requires: Mileage tracking

You can encourage traveler to purchase more expensive flights by showing him his progress towards next status tier in his program(s).

Using combined data from Get program and Get membership method you can visualize traveler’s progress towards his next status tier (either qualification or re-qualification). This can serve as an incentive for user to purchase more expensive flights, especially when the end of qualification period is approaching.

This feature may also used as an argument to encourage travelers to add and connect their memberships.

Best deal recommendation

Requires: at least MVP

You can suggest to the traveler a flight, that’s not only very good in terms of schedule, but also gives him more frequent flyer benefits.

There are many travelers willing to spend a few more dollars to earn more miles. Knowing which frequent flyer memberships traveler uses, clearly indicates which airlines and airline alliances he prefers. All this can be used to provide tailor made offer, that’s a real best deal comparing to the cheapest fare available.

Our best deal algorithm used in the API demo takes under account such variables as:

  • Price,
  • Number of stops,
  • Duration of the flight,
  • Number of earned award miles,
  • Progress towards next status tier,
  • Various applicable status benefits with different weights,
  • Cabin upgrade eligibility and cost.

Advanced user onboarding

Requires: Personalization, preferably Mileage tracking too.

One way of on-boarding user is to utilize flights loading screen, where traveler can input his first frequent flyer membership.

Unlike other services you may integrate into your flight search engine, value of frequent flyer information greatly depends on user engagement. In order to display baggage fees, on-time performance or wi-fi availability on the particular flight, you don’t need user context. But you need such to provide accurate and relevant information about traveler’s mileage earnings or his progress towards next status tier.

And that implies a challenge - how to encourage a user to share information about his frequent flyer memberships? When and how to request this information? We prepared a standalone guide, that addresses this problem. It contains some of the best user-experience patterns we discovered, that can be easily adjusted to your application.

Check it, be inspired and build your own, great traveler on-boarding workflow.

Questions?

Visit section for developers, check resources there or give as a shout: support@30k.com.