AwardWallet Flight Award Search API

Introduction

The AwardWallet Flight Award Search API enables developers to search for airline reward availability and mileage pricing across major airline loyalty programs. It is designed for applications that need reliable, up-to-date award inventory data to power flight search, comparison, and booking experiences.

This RESTful API operates asynchronously. Developers submit a flight search request, which is processed in the background, and retrieve results once available via callback or polling. The API returns detailed itinerary information, including available routes, cabin classes, mileage requirements, taxes and fees, layovers, flight segments, and airline-specific fare details.

The API supports flexible search parameters such as origin and destination airports, travel dates, cabin preferences, passenger counts, currencies, and loyalty account credentials. It also supports optional award calendar searches, enabling applications to surface flexible-date pricing and availability across supported airline programs.

Authentication

To authorize, use this code:

                    
                        # TODO: With php. Build php example

                    
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "X-Authentication: userapikey"

Every API call needs to be authenticated with an API authentication token. This token is passed in the "X-Authentication" field in the HTTPS request header. The token is formed by concatenating the API username and API password with a ":" symbol. You need to contact us to get your API credentials.

X-Authentication: YourUserName:YourPassword

Providers

List supported providers

The /providers/list method gives you all the providers that we support at any given point in time under this API. This list will change over time, so you need to periodically call this method to get any changes.

Request

GET https://ra.awardwallet.com/v1/providers/list

Response Example

                            
{
  "apiVersion": 1,
  "providers": [
    {
      "code": "aeroplan",
      "displayName": "Air Canada (Aeroplan)",
      "shortName": "Air Canada",
      "supportedCurrencies": [
        "CAD"
      ],
      "priceCalendar": {
        "cabins": [
          "firstClass",
          "business",
          "premiumEconomy",
          "economy",
          "unknown"
        ]
      },
      "loginRequired": true,
      "login": {
        "code": "Login",
        "title": "Login (Aeroplan number or Email)",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      },
      "password": {
        "code": "Password/PIN",
        "title": "Password/PIN",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      }
    },
    {
      "code": "korean",
      "displayName": "Korean Air (SkyPass)",
      "shortName": "Korean Air",
      "supportedCurrencies": [
        "EUR",
        "KRW",
        "USD"
      ],
      "priceCalendar": {
        "cabins": [
          "firstClass",
          "premiumEconomy",
          "economy",
          "unknown"
        ]
      },
      "loginRequired": true,
      "login": {
        "code": "Login",
        "title": "User ID or SKYPASS #",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      },
      "login2": {
        "code": "Login2",
        "title": "Login type",
        "options": [
          {
            "code": "",
            "name": "Select your login type",
            "kind": "0"
          },
          {
            "code": "sky",
            "name": "SKYPASS No.",
            "kind": "0"
          },
          {
            "code": "uid",
            "name": "User ID",
            "kind": "0"
          }
        ],
        "required": true,
        "defaultValue": ""
      },
      "password": {
        "code": "Password",
        "title": "Password",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      }
    }
  ]
}

Response

Supported providers information

Parameter	Type	Required	Description
apiVersion	integer	true	Shows the version of the API that is being used
providers	array	true	An array of providers for which we support parsing reward availability data

ProviderItem

Parameter	Type	Required	Description
code	string	true	Alpha-numeric value with no spaces that uniquely identifies any given provider
displayName	string	true	User-friendly display name of the provider. Typically includes both the company name and the name of the loyalty program, i.e. British Airways (Executive Club)
shortName	string	true	Short name of the provider, typically without the name of the loyalty program, i.e. British Airways
supportedCurrencies	array	false	List of currencies in which we can retrieve prices (taxes, fees, etc). For example: ["USD", "EUR", "GBP"]
priceCalendar	object	false	Tells you if this provider supports gathering a price calendar in addition to single-date flights and types of cabins that are available for searching
loginRequired	boolean	true	Indicates whether a loyalty account is required to perform a search. If no account is provided, a fake account will be used to do the search
login	object	true	An object that describes the `loyaltyAccount.login` input parameter
login2	object	false	An object that describes the `loyaltyAccount.login2` input parameter
password	object	true	An object that describes the `loyaltyAccount.password` input parameter

InputParameter

Parameter	Type	Required	Description
code	string	true	Field code is used by developers to identify the type of this field, i.e. “Login”
title	string	true	Field title is a user-friendly name of the field
options	array	false	If there is a limited set of values that can go into this field, those options would be listed in this array
required	boolean	true	Even if the options array gives you an empty string as an option, if this field is set to true, the `login2` parameter is required
defaultValue	string	false	The default value that we expect for this field

InputParameterOption

Parameter	Type	Required	Description
code	string	true	Option code name – unique within a single provider. Can only have English numbers and letters with no spaces
name	string	true	User friendly name of the option such as “Account number”
kind	string	true	Type of property

PriceCalendar

Parameter Type Required Description

Parameter	Type	Required	Description
cabins	array	true	List of cabin types that are potentially available for searching in the price calendar. Allowed values are `firstClass` `business` `premiumEconomy` `economy` `unknown`

cabins

array

true

List of cabin types that are potentially available for searching in the price calendar. Allowed values are

firstClass
business
premiumEconomy
economy
unknown

Search

Submit a flight search request

This method allows you to place a single flight search request into a queue for data to be retrieved

Request Example

                            
{
  "provider": "turkish",
  "departure": {
    "airportCode": "IST",
    "date": "2021-05-24"
  },
  "arrival": "CDG",
  "cabin": "economy",
  "passengers": {
    "adults": 1
  },
  "callbackUrl": "https://your.callback.url/get/results",
  "responseTypes": [
    "singleDate",
    "calendar"
  ],
  "priceCalendar": {
    "callbackUrl": "https://your.callback.url/get/calendarResults"
  },
  "currency": "USD",
  "timeout": 300,
  "priority": 9,
  "userData": "some_test_value",
  "loyaltyAccount": {
    "login": "1234ABCD",
    "login2": "Smith",
    "password": "Password1234",
    "answers": [
      {
        "question": "We've sent a security code to your email",
        "answer": "1234"
      }
    ],
    "browserState": "x7hxa87s87as\u2026xm89s"
  }
}

Request

POST https://ra.awardwallet.com/v1/search

Request Parameters

Parameter	Type	Required	Description
provider	string	true	Alpha-numeric value with no spaces that uniquely identifies any given provider. Can be retrieved from the `/providers/list` method
departure	object	true	An object describing all the attributes related to the departure of the flight to be searched
arrival	string	true	Three letter code of the arrival airport, i.e. JFK
cabin	array	false	The desired cabin of service to search for. Acceptable values are: `firstClass` `business` `premiumEconomy` `economy` Please note that we will return all available cabins if it doesn’t require additional searches. So you may search for cabin=”business” but if the provider returns economy, business, and first-class cabins, then we will return flights for all of them
passengers	object	true	Lists the types and number of passengers to search tickets for. At the moment only `adults` are supported
currency	string	true	Three-letter currency code in which you want the taxes and fees to be returned. I.e. USD. You can receive the full list of supported currencies for each provider by calling the `/providers/list` method. If the currency you are requesting is not supported, we will convert whatever currency is on the website to the one you requested
responseTypes	array	false	List of requested gathering types. If it contains a string `singleDate` then we will search for flights on that date. If it contains a `calendar` string, then we will gather information about available flights in a wider range but with limited details. The latter is only available if the corresponding flag is set to true in the ListProviders call
priority	integer	true	Request priority values range from 1 to 9, where 1 is the lowest priority and 9 is the highest priority. In some cases, we throttle requests with priorities lower than X (default is 9). Please use this attribute to separate background searches from foreground searches. In other words, background searches could have a priority of 1 (lowest), and flight searches when an actual user is waiting for search results should be run with the priority of 9 (highest). This way your background searches will never negatively impact your live users
callbackUrl	uri	false	All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. Here is how it works. You send us a request for a flight search and we send you the response as soon as we finished parsing the website to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks: Content-type: 'application/json' Authorization: 'Basic YXdhcmR3YWxsZXQ6cGFzc3dvcmQ=' where `YXdhcmR3YWxsZXQ6cGFzc3dvcmQ=` is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password When we send our callbacks, we expect to receive code 200. If we get anything other than code 200, we will keep re-trying to send you the response. The page itself can be empty as long as we get code 200
priceCalendar	object	false	Additional parameters related to gathering price calendars
timeout	integer	false	The maximum number of seconds a request is allowed to sit in the queue. When that time passes (assuming we have not retrieved the results yet) we will throw a "timeout" error. The timeout should be shorter for all “foreground” requests (priorirty=9), i.e. when the user is looking at the screen waiting for the results, and much higher for background requests (priorirty=1) when no one is waiting for the results in real-time
userData	string	false	Any data you wish to send. It will be returned untouched in the response. Could be used for matching requests to responses
loyaltyAccount	object	false	Loyalty program account credentials to use in the search

Response Example

                            
{
  "requestId": "12345678900987654321"
}

Response

Search response

Parameter	Type	Required	Description
requestId	string	true	An ID that uniquely identifies this request. You can use this value to get the results of this update request using the `/getResults/{id}` method

LoyaltyAccount

Parameter	Type	Required	Description
login	string	true	User's login value to be used to login to the provider's website
login2	string	false	Second login value. I.e. “Last name”
password	string	true	User's password value to be used to login to the provider's website
answers	array	false	List of `answer` objects, containing information about security questions or one-time codes
browserState	string	false	When you update accounts that have security questions for the first time you will get a `browserState` attribute back from us. Please store it on your end and send it with your next account update so that the user doesn’t get prompted for security questions again

Answer

Parameter	Type	Required	Description
question	string	true	Security question that is unique to that specific account
answer	string	true	Security answer that is unique to that specific account which corresponds to the security question

PriceCalendarRequest

Parameter	Type	Required	Description
callbackUrl	uri	false	Separate callback URL for sending data parsed from a price calendar. Works the same way as the main `callbackUrl` attribute

Passengers

Parameter	Type	Required	Description
adults	integer	false	Number of adult passengers

Departure

Parameter	Type	Required	Description
airportCode	string	true	Three letter code of the departure airport, i.e. JFK
date	string	true	Departure date in the following format `2021-04-16`

Retrieve flight search results

This method allows you to query our API using the requestId attribute you received from the /search method, it should only be used during testing or debugging. For production use, a callback URL should be used instead to receive the results as soon as we have them

Request

GET https://ra.awardwallet.com/v1/getResults/{requestId}

Request Parameters

Parameter	Type	Required	Description
requestId	string	true	The unique request ID returned by the `/search` endpoint

Response Example

                            
{
  "requestId": "12345678900987654321",
  "userData": "some_test_value",
  "state": 1,
  "message": "",
  "requestDate": "2021-03-22T18:08:18+00:00",
  "routes": [
    {
      "numberOfStops": 1,
      "tickets": 3,
      "awardTypes": "Economy Award Ticket",
      "times": {
        "flight": "29:40",
        "layover": "15:05"
      },
      "mileCost": {
        "program": "turkish",
        "miles": 52500
      },
      "cashCost": {
        "currency": "USD",
        "taxes": 216.37,
        "fees": 2.37,
        "originalCurrency": "CAD",
        "conversionRate": 0.79
      },
      "segments": [
        {
          "departure": {
            "dateTime": "2021-05-24T19:25:00+00:00",
            "airport": "CDG",
            "terminal": "3"
          },
          "arrival": {
            "dateTime": "2021-05-24T23:55:00+00:00",
            "airport": "IST"
          },
          "meal": "Snacks for Purchase",
          "cabin": "economy",
          "fareClass": "X",
          "tickets": 3,
          "flightNumbers": [
            "TK1828"
          ],
          "airlineCode": "TK",
          "aircraft": "N32",
          "times": {
            "flight": "3:30",
            "layover": "15:05"
          }
        },
        {
          "departure": {
            "dateTime": "2021-05-25T15:00:00+00:00",
            "airport": "IST"
          },
          "arrival": {
            "dateTime": "2021-05-25T19:05:00+00:00",
            "airport": "IAD"
          },
          "meal": "Snacks for Purchase",
          "cabin": "economy",
          "fareClass": "X",
          "tickets": 9,
          "flightNumbers": [
            "TK0007"
          ],
          "airlineCode": "TK",
          "aircraft": "789",
          "times": {
            "flight": "11:05"
          }
        }
      ]
    }
  ],
  "calendar": [
    {
      "miles": 33000,
      "cashCost": {
        "currency": "USD",
        "originalCurrency": "CAD",
        "conversionRate": 0.79,
        "taxes": 4.5
      },
      "standardItineraryCOS": "economy",
      "brandedItineraryCOS": "Lowest possible",
      "date": "2021-05-24"
    }
  ],
  "progress": {
    "singleDate": {
      "state": 1,
      "message": ""
    },
    "calendar": {
      "state": 1,
      "message": ""
    }
  },
  "question": "Please enter the verification code that was sent to you",
  "browserState": "jxaAS78cs0DAS\u20268cjSDH7sd2DHS"
}

Response

Search result response

Parameter	Type	Required	Description
requestId	string	true	An ID that uniquely identifies this request
userData	string	true	This field returns whatever data you put in it when you made your request as is. Can be used for some sort of tracking
state	integer	true	0 – The flight search data has not yet been retrieved from the provider's website. Please repeat your request again later to get the results 1 - Flight search data has been successfully retrieved 2 - The provider did not accept user credentials that are being used to perform the searches 4 - Error. The provider has returned some error or requires some additional user action, such as updating personal information 6 - An Unknown Error occurred, something unexpected happened and AwardWallet failed to retrieve the data 9 - Flight search data was successfully retrieved; however, there was some type of warning. The warning message is returned in the message field 10 - The provider requires an answer to a security question or a 2-factor authorization 11 - Retrieving flight search results took too much time. The request timed out
message	string	true	Human readable error message
requestDate	date-time	true	Date and time of when the request was sent to us, i.e. when the reward availability search was put into our queue
routes	array	false	An array of available routes that we found for this search
calendar	array	false	An array of available flights that we found in a price calendar search
progress	object	true	An object that displays the current state and progress of the request
question	string	false	Security question
browserState	string	false	Browser state, such as cookies and other info. Please store this data on your end with the account, and always send it back to us for any subsequent requests

Progress

Parameter	Type	Required	Description
singleDate	object	false	Represents the state and progress of single date flight search
calendar	object	false	Represents the state and progress of the price calendar parsing

ProgressItem

Parameter	Type	Required	Description
state	integer	true	The same state code as in the top level state field
message	string	true	Human readable error message

CalendarEntry

Parameter	Type	Required	Description
miles	integer	true	The cost of this route in miles
cashCost	object	true	An object that describes the additional to the miles cost in cash that needs to be paid for this ticket
standardItineraryCOS	string	true	Standardized class of service for the itinerary. Possible values are: `firstClass` `business` `premiumEconomy` `economy` `unknown`
brandedItineraryCOS	string	false	Class of service of the itinerary, as it is displayed by the airline’s website, i.e., Delta One
date	string	true	Departure date of this route

Route

Parameter	Type	Required	Description
numberOfStops	integer	false	The number of stops this route has to get to the destination
tickets	integer	false	The number of tickets that are available on the provider’s website for this particular route
times	object	false	An object that describes total flight and layover times
mileCost	object	true	An object that describes the cost of this route in miles
cashCost	object	true	An object that provides cost in cash that needs to be paid for this ticket which is in addition to the `mileCost`
segments	array	true	An array of flight segments which make up this route

Segment

Parameter	Type	Required	Description
departure	object	true	An object which describes the departure part of this segment
arrival	object	true	An object which describes the arrival part of this segment
cabin	string	true	Cabin class for this ticket. Possible values are `firstClass` `business` `premiumEconomy` `economy` `unknown`
fareClass	string	false	Letter code fare class of this ticket, i.e. G
flightNumbers	array	true	An array of flight numbers for this segment. Usually should just be a single flight number but in the case of codeshare flights, there may be multiple flight numbers. Example “KL1010”
airline	string	true	Two letter IATA code of the airline that is operating the flight, i.e. DL
aircraft	string	false	Name of the aircraft
times	object	false	An object describing either just the flight time (it if is the last segment) or the flight time and the layover time
numberOfStops	integer	false	The number of stops this segment has to get to the destination

AirportDateTime

Parameter	Type	Required	Description
dateTime	date-time	true	Departure or arrival date and time with timezone, i.e. “2021-04-17T11:45:00+00:00”
airport	string	true	Three-letter airport code

CashCost

Parameter	Type	Required	Description
currency	string	true	Three-letter currency code, such as USD
originalCurrency	string	false	If we are not able to get the prices in the currency that you requested, we will convert whatever currency that shows up on the website to the one you requested and put the original currency in this attribute
conversionRate	float	false	If we converted the prices from one currency to another, we will specify the conversion rate in this attribute
taxes	float	true	How much the taxes are for this ticket in addition to the cost in miles
fees	float	false	If there are additional fees for this route, the amount will be listed here

MileCost

Parameter	Type	Required	Description
program	string	false	Alpha-numeric value with no spaces that uniquely identifies any given provider. Additional information about this provider could be found under the `/providers/list` method
miles	integer	true	How much this ticket costs in miles

RouteTimes

Parameter	Type	Required	Description
flight	string	false	The total duration of the combined flights as shown on the provider website
layover	string	false	The total duration of the combined layover times as shown on the provider website

Errors

Error Code	Meaning
400	Bad Request
401	Unauthorized – Your API key is wrong
403	Forbidden
404	Not Found
405	Method Not Allowed – You tried to access an API with an invalid method
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable

Suchen Sie AwardWallet-Logos, -Banner oder -Screenshots?

Wie haben sie alle für Sie auf dieser Seite ordentlich angeordnet:

AwardWallet Flight Award Search API

Introduction

Authentication

Providers

List supported providers

Request

Response

ProviderItem

InputParameter

InputParameterOption

PriceCalendar

Search

Submit a flight search request

Request

Request Parameters

Response

LoyaltyAccount

Answer

PriceCalendarRequest

Passengers

Departure

Retrieve flight search results

Request

Request Parameters

Response

Progress

ProgressItem

CalendarEntry

Route

Segment

AirportDateTime

CashCost

MileCost

RouteTimes

Errors