Introduction

AwardWallet Email Parsing API

The AwardWallet Email Parsing API retrieves travel reservations out of emails. Send any travel itinerary or reservation and the API will parse it and return the reservation data in a structured format (JSON) for your consumption. Parsing is done automatically and takes just a few seconds.

We support thousands of email formats (click to view the AwardWallet’s list of emails supported for parsing) and we have a dedicated team of developers who constantly work on improving the API by adding new parsers to support new email formats.

If you have an email reservation and want to do a quick test you can upload the .eml file or copy-paste the raw content of the email via our example test page. You should see the parsing results immediately after submitting the request at the bottom of the page.

For production mode, the API is designed to work asynchronously. Here is the workflow diagram explaining what happens to an email once it is received by the API:

At a high level, here is how the API works:

  • You submit an email message for parsing, and specify your callbackUrl (must be registered with us prior to using the API) in your request. Our API will respond with a queued status. At this point you don’t know if your message was parsed or not.

  • Your message will be processed by an automated parser. Shortly, typically within seconds, you will receive a response to your callbackUrl, with one of the status codes (which are described below). In most cases, you should get a success code and the results of the parsing will be returned to you in that callback response. For testing, instead of receiving the results to your callback URL, you may simply call the /getResults/{requestID} method to see the results.

  • If you get a review status - you should expect a subsequent callback with either success, invalid, restricted or skipped status. At this point we are not able to guarantee any time range for manual review process.

  • Typically, the emails that you send to us are stored on the AwardWallet’s servers for two weeks (in the Amazon AWS cloud). After that, the emails are permanently deleted from our servers. If it so happens that there will be emails in the review status at the two-week mark we will also send you a response to your callbackUrl with a status of timeout at the time when we purge the emails.

  • Every method that we make available as part of this API can be invoked through two endpoints, the ones that have the -eu in the URL point to our EU infrastructure, where all the data processing happens inside EU. The other one points to the servers hosted in the US.

Authentication

To authorize, use this code:

                    
# 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 authntiction token. This token is passed in the "X-Authentication" field with the https request header. The token is formed by concatinating the API username and API password with a ":" symbol. You need to contact us to get your API credentials.

X-Authentication: YourUserName:YourPassword

Email Parsing

Submit Email for Parsing

POST Request Example

                            
{
  "callbackUrl": "https://yoursite.com/receiver",
  "email": "X-Mailgun: Yes From: test@email.com ...",
  "userData": "any text",
  "returnEmail": "headers"
}
                            
                        

Response Example

                            
{
  "apiVersion": 2,
  "status": "queued",
  "errorMessage": "",
  "requestIds": [
    "fcb4e6c917e3d832fh365df0a821b7dc"
  ]
}
                            
                        

/parseEmail is going to be your main method that you are going to be calling to work with this API. This is where you will be sending your emails with travel reservations.

HTTP Request

POST https://service.awardwallet.com/email/json/v2/parseEmail

POST https://email-eu.awardwallet.com/email/json/v2/parseEmail

Query Parameters

Parameter Type Required Description

email

string true

Full email source, including MIME headers and MIME body

callbackUrl

string false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with us. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

returnEmail

string true

Indicates whether we should include the original email source in the response or not. There are three possible values:

  • headers - include only the headers of the email
  • all - include the entire email
  • none - do not include the email in the response

userData

string false

Any text. We will return this text in the response field untouched. You can send your internal message id, or any other data. It can also be used for troubleshooting with our support team as you can reference that value so that we can easily identify the email you are inquiring about.

Response

Parameter Type Required Description

apiVersion

int true

The version of the API being used

status

string true

The status of the request. Can have one of two values:

  • queued - the email has been placed into the AwardWallet’s queue, as soon as it is processed the results will be available and will be sent to your callback URL.
  • error - the email has not been placed into the AwardWallet’s queue, see the errorMessage field for more details.

errorMessage

string false

If you get an error in the status attribute the actual error message will be available in this field.

requestIds

array true

Collection of request IDs, which can be used to retrieve the parsing results using the /getResults/{requestID} method and also these request IDs will be sent with the response to your callback URL. Multiple request IDs could be returned if the submitted email contained one or more nested (attached) emails. Each ID can be used separately to retrieve the parsing results of each of these emails.

Response

Get Email Parsing Results

Response Example

                            
{
  "apiVersion": 2,
  "requestId": "7405fa3688970a6329a375c82384bd4a",
  "status": "success",
  "statusMessage": null,
  "rejectMethod": null,
  "missingFields": null,
  "providerCode": "expedia",
  "itineraries": [
    {
      "travelAgency": {
        "providerInfo": {
          "code": "expedia",
          "name": "Expedia.com",
          "accountNumbers": [
            {
              "number": "EXP-11298",
              "masked": false
            }
          ],
          "earnedRewards": "1 booking"
        },
        "confirmationNumbers": [
          {
            "number": "J3HND-8776",
            "description": "Trip Locator",
            "isPrimary": null
          }
        ],
        "phoneNumbers": [
          {
            "description": "Help Desk",
            "number": "+1-44-EXPEDIA"
          }
        ]
      },
      "pricingInfo": null,
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "delta",
        "name": "Delta Air Lines",
        "accountNumbers": [
          {
            "number": "1234****",
            "masked": true
          },
          {
            "number": "4321****",
            "masked": true
          }
        ],
        "earnedRewards": "300 award miles"
      },
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "airportCode": "LAX",
            "terminal": "A",
            "name": "Los Angeles International Airport",
            "localDateTime": "2030-01-01T13:30:00",
            "address": {
              "text": "LAX",
              "addressLine": "1 World Way",
              "city": "Los Angeles",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": "90045",
              "lat": 33.9415889,
              "lng": -118.40853,
              "timezone": -25200
            }
          },
          "arrival": {
            "airportCode": "SFO",
            "terminal": "2",
            "name": "San Francisco International Airport",
            "localDateTime": "2030-01-01T15:00:00",
            "address": {
              "text": "SFO",
              "addressLine": "San Francisco International Airport",
              "city": "San Francisco",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200
            }
          },
          "marketingCarrier": {
            "airline": {
              "name": "Delta Air Lines",
              "iata": "DL",
              "icao": "DAL"
            },
            "flightNumber": "0013",
            "confirmationNumber": "MRTG67",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-404-714-2300"
              }
            ],
            "isCodeshare": true
          },
          "operatingCarrier": {
            "airline": {
              "name": "British Airways",
              "iata": "BA",
              "icao": "BAW"
            },
            "flightNumber": "5566",
            "confirmationNumber": "CARR23",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-718-335-7070"
              }
            ]
          },
          "wetleaseCarrier": {
            "name": "Sky Express",
            "iata": null,
            "icao": null
          },
          "seats": [
            "3E",
            "3F"
          ],
          "aircraft": {
            "iataCode": "7M7",
            "name": "Boeing 737MAX 7 Passenger",
            "turboProp": false,
            "jet": true,
            "wideBody": false,
            "regional": false
          },
          "traveledMiles": "300mi",
          "cabin": "Coach",
          "bookingCode": "CL",
          "duration": "1h30min",
          "meal": "Snacks",
          "smoking": false,
          "status": "Confirmed",
          "stops": 0,
          "flightStatsMethodUsed": "ScheduleByFlight"
        },
        {
          "departure": {
            "airportCode": "SFO",
            "terminal": "2",
            "name": "San Francisco International Airport",
            "localDateTime": "2030-01-05T06:00:00",
            "address": {
              "text": "SFO",
              "addressLine": "San Francisco International Airport",
              "city": "San Francisco",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200
            }
          },
          "arrival": {
            "airportCode": "LAX",
            "terminal": "A",
            "name": "Los Angeles International Airport",
            "localDateTime": "2030-01-05T07:30:00",
            "address": {
              "text": "LAX",
              "addressLine": "1 World Way",
              "city": "Los Angeles",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": "90045",
              "lat": 33.9415889,
              "lng": -118.40853,
              "timezone": -25200
            }
          },
          "marketingCarrier": {
            "airline": {
              "name": "Delta Air Lines",
              "iata": "DL",
              "icao": "DAL"
            },
            "flightNumber": "0014",
            "confirmationNumber": "MRTG67",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-404-714-2300"
              }
            ],
            "isCodeshare": true
          },
          "operatingCarrier": {
            "airline": {
              "name": "British Airways",
              "iata": "BA",
              "icao": "BAW"
            },
            "flightNumber": "9009",
            "confirmationNumber": "CARR23",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-718-335-7070"
              }
            ]
          },
          "wetleaseCarrier": null,
          "seats": [
            "1B",
            "1C"
          ],
          "aircraft": {
            "iataCode": "7M7",
            "name": "Boeing 737MAX 7 Passenger",
            "turboProp": false,
            "jet": true,
            "wideBody": false,
            "regional": false
          },
          "traveledMiles": "300mi",
          "cabin": "First class",
          "bookingCode": "I",
          "duration": "1h30min",
          "meal": "Snacks",
          "smoking": null,
          "status": "Confirmed",
          "stops": null,
          "flightStatsMethodUsed": "ScheduleByAirport"
        }
      ],
      "issuingCarrier": {
        "airline": {
          "name": "Delta Air Lines",
          "iata": "DL",
          "icao": "DAL"
        },
        "confirmationNumber": "ISSD12",
        "phoneNumbers": [
          {
            "description": null,
            "number": "+1-404-714-2300"
          }
        ],
        "ticketNumbers": [
          {
            "number": "006 123321",
            "masked": false
          },
          {
            "number": "006 456654",
            "masked": false
          }
        ]
      },
      "type": "flight"
    },
    {
      "travelAgency": {
        "providerInfo": {
          "code": "expedia",
          "name": "Expedia.com",
          "accountNumbers": [
            {
              "number": "EXP-11298",
              "masked": false
            }
          ],
          "earnedRewards": "1 booking"
        },
        "confirmationNumbers": [
          {
            "number": "J3HND-8776",
            "description": "Trip Locator",
            "isPrimary": null
          }
        ],
        "phoneNumbers": [
          {
            "description": "Help Desk",
            "number": "+1-44-EXPEDIA"
          }
        ]
      },
      "pricingInfo": null,
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "spg",
        "name": "Starwood Hotels",
        "accountNumbers": [
          {
            "number": "xxxxxx345",
            "masked": true
          }
        ],
        "earnedRewards": "4 nights"
      },
      "confirmationNumbers": [
        {
          "number": "1122334455",
          "description": "Confirmation number",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Reference",
          "isPrimary": false
        }
      ],
      "hotelName": "Sheraton Philadelphia Downtown Hotel",
      "chainName": null,
      "address": {
        "text": "201 North 17th Street, Philadelphia, Pennsylvania 19103 United States",
        "addressLine": "201 North 17th Street",
        "city": "Philadelphia",
        "stateName": "Pennsylvania",
        "countryName": "United States",
        "postalCode": "19103",
        "lat": 39.9569828,
        "lng": -75.1674669,
        "timezone": -14400
      },
      "checkInDate": "2030-01-01T13:30:00",
      "checkOutDate": "2030-01-05T12:00:00",
      "phone": "+1-22-3333",
      "fax": "+1-66-77899",
      "guests": [
        {
          "name": "John D.",
          "full": false
        },
        {
          "name": "Jane D.",
          "full": false
        }
      ],
      "guestCount": 2,
      "kidsCount": 3,
      "roomsCount": 1,
      "cancellationPolicy": "Cancellation is free prior to check-in",
      "rooms": [
        {
          "type": "King bed",
          "description": "Traditional, TV, free wi-fi",
          "rate": "30$/night",
          "rateType": "King bed"
        }
      ],
      "type": "hotelReservation"
    }
  ],
  "loyaltyAccount": null,
  "pricingInfo": {
    "total": 251.41,
    "cost": 193.75,
    "discount": 40,
    "spentAwards": "10000 points",
    "currencyCode": "USD",
    "fees": [
      {
        "name": "Tax",
        "charge": 34.56
      },
      {
        "name": "Insurance",
        "charge": 23.1
      }
    ]
  },
  "fromProvider": false,
  "metadata": {
    "from": {
      "name": null,
      "email": "agency@test.awardwallet.com"
    },
    "to": [
      {
        "name": null,
        "email": "plans@awardwallet.com"
      }
    ],
    "cc": [
      
    ],
    "subject": "Composite reservation",
    "receivedDateTime": "2017-06-27T15:35:37",
    "userEmail": "agency@test.awardwallet.com",
    "nested": false,
    "mailboxId": null
  },
  "nestedEmailMetadata": null,
  "parsingMethod": "auto",
  "flightStatsMethodsUsed": [
    {
      "name": "ScheduleByFlight",
      "count": 1
    },
    {
      "name": "ScheduleByAirport",
      "count": 1
    }
  ],
  "userData": "any text",
  "email": null
}
                            
                        

Whenever you are testing or troubleshooting our API it may be inconvenient to work with a callbackurl to analyze the results. For this reason, you can simply call this method to get the parsing results for any given email that you sent to us in the last two weeks.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/getResults/{requestId}

GET https://email-eu.awardwallet.com/email/json/v2/getResults/{requestId}

Query Parameters

Parameter Type Required Description
requestId string true

You need to get the requestId from the /parseEmail method

Response

Parameter Type Required Description

apiVersion

string true

Version of the API being used.

requestId

string true

RequestID that corresponds to this email.

status

string true

Status of the parsing results. The possible values are:

success - The email was successfully parsed

queued - The email is sitting in the queue, waiting to be processed by the parser you can call this method again in a few seconds or you can wait to receive the results to the callbackUrl that you specified.

invalid - It was determined that this email does not contain a valid travel itinerary or reservation. See the statusMessage for more details.

review - The automated parsers failed to parse this email, at this point the message is going to be placed into the manual queue for someone at AwardWallet to check it and decide if we should adjust a parser and re-run it again through the parsing process. You should not expect successful parsing results quickly (in under 1 hour) as someone manually has to review the email and adjust the parsers.

restricted - This is a restricted provider that AwardWallet is not allowed to parse at this point.

skipped - This email was reviewed and we determined that this is an itinerary and for one reason or another we did not parse this reservation. This email was not counted against your license count.

timeout - We were not able to review this email in a timely fashion, thus we don’t know if this is a valid reservation or not. This email was purged from our queue automatically and was not counted against your license count.

statusMessage

string false

If you get invalid as the returned value in the status field, this field will have additional information for you.

rejectMethod

string false

This field indicates the reason why our system determined that an email does not contain a valid travel reservation in it. The possible values are:

auto - The system automatically (using built-in filters) determined that the email does not contain a valid itinerary.

manual - This email was reviewed by our support staff and it was determined that it does not contain a valid travel reservation.

incomplete - This email might contain a travel reservation, but some required fields are missing from it.

missingFields

array false

If the rejectMethod field returns the incomplete value, this field will return an array of names of missing fields. For example if segments.arrival.airportCode is a required field and is missing in the email, this value will be returned here, so you know exactly why this email failed to parse.

providerCode

string false

Alpha-numeric value with no spaces that uniquely identifies any given provider within the AwardWallet interface.

fromProvider

boolean false

Indicates if this email was sent directly by the provider as opposed to the user forwarding that message.

loyaltyAccount

object false

If the email contains loyalty information (i.e. account balance, account number, elite status, etc.) like a monthly statement, then we will return all that loyalty information in this object. We typically do this for United, Delta and Southwest statements.

itineraries

array false

An array of all itineraries parsed out of the email

email

string false

Returns the email headers, the entire email, or nothing at all, depending on the value of returnEmail parameter in the request. The value is be base64 encoded.

metadata

object true

Some email headers and other metadata will be returned in this object. If you need to get the full headers, please set the returnEmail attribute to headers and you will get them via the email attribute.

nestedEmailMetadata

object false

Same as the metadata attribute above, except nestedEmailMetadata is present only when the metadata.nested attribute is set to true. It means that this email was received as an attachment to another email that was submitted to us. In that case, the metadata field will contain the headers of the parent email (the one that was actually submitted to the API) and this nestedEmailMetadata field will contain the headers of the nested email, which parsing results are actually presented in this response.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

parsingMethod

string false

The method of parsing that was used. There are two possible values:

auto - for automatically parsed emails

manual – for emails that were parsed manually by the AwardWallet team

flightStatsMethodsUsed

array false

If we needed to call FlightStats to retrieve some fields that are required and are missing in the email all such FlightStats calls will be listed in this array.

userData

string false

Returns whatever text you sent (as is) in the userData attribute when you created the request.

Parse result

FlightStats Methods Used

Parameter Type Required Description

name

string true

The name of the FlightStats API method that was called during the parsing. Here are the possible values:

  • ScheduleByFlight
  • ScheduleByRoute
  • ScheduleByAirport
  • HistoricalByFlight
  • HistoricalByRoute
  • HistoricalByAirport

count

integer true

Number of calls made to this method.

Pricing Info

Parameter Type Required Description

total

double false

Total cost of the reservation including all taxes and fees.

cost

double false

Cost of the reservation before taxes.

discount

double false

Total amount of discounts, if any.

spentAwards

string false

Frequent flier miles, points, or other kinds or bonuses spent on this reservation.

currencyCode

string false

Currency code as gathered from the website. I.e. USD.

fees

array false

Various fees associated with the reservation.

Fee

Parameter Type Required Description

name

string true

Fee description.

charge

double true

Fee amount.

Email Metadata

Parameter Type Required Description

from

object false

The sender’s name (if exists) and the email address of the sender.

to

array false

An array of email recipients listed in the To: field of the email.

cc

array false

An array of email recipients listed in the Cc: field of the email (if any).

subject

string false

Email subject.

receivedDateTime

string false

Date and time when the email was received in the mailbox in the YYYY-MM-DDThh:mm:ss format. The time will be in UTC+0 time zone.

nested

boolean false

Set to ‘true’ if this email was received as an attachment to another email, that was actually submitted, and ‘false’ otherwise.

userEmail

string false

Presumable email address of the actual end user. This email address may be parsed from the email headers (from, to, cc) or from the email body.

mailboxId

integer false

Filled in with mailbox id, if this message was downloaded from mailbox added with /mailboxes/ api

Email Address

Parameter Type Required Description

name

string false

The name that is associated with the email address.

email

string true

The actual email address.

Loyalty Information

If the email contains loyalty information (i.e. account balance, account number, elite status, etc.) like a monthly statement, then we will return all that loyalty information in this object. We typically do this for United, Delta and Southwest statements.

Parameter Type Required Description

balance

double false

Loyalty account balance, i.e. how many miles or points the user has.

balanceDate

string false

In some cases, the statement email may have a balance date (basically stating that this was the balance as of some specific date). If we see such a date it will be returned in this field.

expirationDate

string false

Account balance expiration date

properties

array false

We gather as much data as possible from any given account on top of the main attributes like the account balance and its expiration date. These secondary properties will be available in this array.

history

array false

Email may contain account transaction history. If that is the case the actual account transactions will be returned in this array. Please note that we only support specific formats for specific providers, if you wish to use this feature you would need to contact our support team to better understand which email formats are supported.

providerCode

string false

Alpha-numeric value with no spaces that uniquely identifies any given provider within the AwardWallet interface. You can get a list of all available providers here.

History Row

Unfortunately, most providers present their history differently, as much as we want to unify this information it doesn’t seem to be possible, so when presenting a single history row, we define each field separately with three values as described below.

Parameter Type Required Description

fields

array false

History fields as described below.

History Field

Think of a single row of data that describes a historical transaction. fields are the individual values that comprise that transaction. Instead of just providing you with a text value we provide you with an array of metadata that define what this value is.

Parameter Type Required Description

code

string false

We have four predefined filed codes; they are:

PostingDate – date-time value of the transaction

Description – text value of the transaction description

Miles – the number of miles added or subtracted from the account

Info – any other column that we see as part of the history on the prover’s website.

name

string false

User-friendly name of the field, i.e. “Posting Date” that you can show as the column heading to your end users.

value

string false

The actual field value, such as "10,000"

Property

In case if the email contains a loyalty account statement that we are able to parse, the individual loyalty account properties will be returned in this array.

Parameter Type Required Description

code

string false

This is a short, alphanumeric codename do describe this attribute.

name

string false

User friendly name of the property such as “Account number”. You can display this to your end users.

kind

string false

Type of property, the possible values are:

0 - Basic property

1 - Account number

3 - Elite Status

4 - Lifetime points

7 - Points / miles earned year-to-date (YTD).

8 - Segments earned year-to-date (YTD).

12 - Name of the account holder, as listed on the account.

13 - Date of the last account activity.

101 - Login information

102 - Partial login information if it was masked in the email

103 - Partial account number if it was masked in the email

value

string false

The actual property value, such as “Silver”

List providers

Response Example

                            
{
  "apiVersion": 2,
  "list": [
    {
      "code": "delta",
      "displayName": "Delta Air Lines (SkyMiles)",
      "shortName": "Delta Air Lines",
      "supportedLanguages": [
        "en",
        "es",
        "de",
        "zh",
        "ja",
        "ko",
        "pt",
        "it",
        "fr"
      ],
      "supportedFormatCount": 32,
      "properties": [
        {
          "code": "Level",
          "name": "Membership Level",
          "kind": "3"
        },
        {
          "code": "Login",
          "name": "Login",
          "kind": "101"
        }
      ],
      "historyColumns": [
        {
          "code": "PostingDate",
          "name": "Posting Date",
          "kind": "0"
        },
        {
          "code": "Description",
          "name": "Description",
          "kind": "0"
        },
        {
          "code": "Info",
          "name": "Miles",
          "kind": "0"
        }
      ]
    },
    {
      "code": "mileageplus",
      "displayName": "United Airlines (Mileage Plus)",
      "shortName": "United",
      "supportedLanguages": [
        "en",
        "es",
        "pt",
        "zh",
        "ja",
        "fr",
        "de"
      ],
      "supportedFormatCount": 64,
      "properties": [
        {
          "code": "EliteMiles",
          "name": "YTD Premier Miles",
          "kind": "7"
        },
        {
          "code": "EliteSegments",
          "name": "YTD Premier Segments",
          "kind": "8"
        }
      ],
      "historyColumns": [
        {
          "code": "PostingDate",
          "name": "Activity Date",
          "kind": "0"
        },
        {
          "code": "Description",
          "name": "Description",
          "kind": "0"
        }
      ]
    }
  ]
}
                            
                        

In addition to travel itineraries, we are able to retrieve loyalty information, such as loyalty account balance, elite status and expiration by parsing data out of email account statements for a select number of loyalty programs. All of the programs that we support and the properties we are able to retrieve are listed using this method.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/providers/list

GET https://email-eu.awardwallet.com/email/json/v2/providers/list

Response

Parameter Type Required Description

apiVersion

string true

Version of the API being used.

providers

array false

An array of individual providers (that we support with our Email Parsing API) for which we can retrieve travel itineraries (and in some rare cases loyalty information) from emails.

Response

Providers

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. Delta Air Lines (SkyMiles).

shortName

string false

Shortened display name of the provider.

supportedLanguages

array false

Array of ISO 639-1 2-letter language codes which are supported for email parsing for this provider

supportedFormatCount

integer false

Estimated number of email formats supported for email parsing for this provider

properties

array false

Array of account properties (secondary attributes) that we may gather from email account statements.

historyColumns

array false

Array of account transaction history columns that we may gather from emails.

Properties

Parameter Type Required Description

code

string true

Property code name. Can only have English numbers and letters with no spaces.

name

string true

User friendly name of a property such as “Account number”. You can display this to your end users.

kind

string true

Type of property, the possible values are:

0 - Basic property

1 - Account number

3 - Elite Status

4 - Lifetime points

7 - Points / miles earned year-to-date (YTD).

8 - Segments earned year-to-date (YTD).

12 - Name of the account holder, as listed on the account.

13 - Date of the last account activity.

101 - Login information

102 - Partial login information if it was masked in the email

103 - Partial account number if it was masked in the email

Email Scanner

Detect Mailbox Type

Response Example

                            
{
  "type": "microsoft"
}
                            
                        

We support scanning mailboxes via 3 different methods:

  • IMAP Protocol
  • Google API
  • Microsoft API

Since both Google and Microsoft APIs support custom domains (for businesses) you can’t easily tell if a specific email address is managed by either Google Apps or Microsoft Office 365 cloud services. This call will perform the necessary queries to determine if this mailbox is managed by either Google or Microsoft. If it is not, then you need to connect this type of mailbox via the IMAP protocol.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/mailboxes/detect-type/{email}

GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/detect-type/{email}

Query Parameters

Parameter Type Required Description

email

string true

Any email address to be tested. This email doesn’t need to be already added to AwardWallet.

Response

Parameter Type Required Description

type

string true

Tells you how this mailbox should be connected. Can be one of three options: imap, google or microsoft

Response

Connect via IMAP

POST Request Example

                            
{
  "login": "JohnSmith@yahoo.com",
  "password": "SecretPassword1234",
  "host": "imap.mail.yahoo.com",
  "port": 993,
  "secure": true,
  "startFrom": "2018-07-05",
  "listen": true,
  "callbackUrl": "http://company.com/api/email/receiver.php",
  "userData": "Testing the mailbox scanner API",
  "tags": [
    "test",
    "userid_1234"
  ]
}
                            
                        

Response Example

                            
{
  "state": "connecting",
  "id": 3473,
  "creationDate": "2018-08-31T21:48:55+0000",
  "startFrom": "2018-07-05",
  "listen": true,
  "tags": [
    "test",
    "userid_1234"
  ],
  "login": "JohnSmith@yahoo.com",
  "type": "imap"
}
                            
                        

HTTP Request

POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/imap

POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/imap

Query Parameters

Parameter Type Required Description

startFrom

date false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

string false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

userData

string false

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

host

string false

The IMAP address of the server where we should establish connection. If you omit this parameter we will attempt to detect the IMAP server address automatically for this specific mailbox.

port

integer false

The IMAP server port. If you omit this parameter we will try to detect the port automatically.

login

string false

The IMAP server login, in most cases it will be the email address.

password

string false

The IMAP account password.

secure

boolean false

Set to true if you want us to use ssl/tls encryption for this mailbox connection and false if you don’t. If you omit this parameter, we will attempt to detect if encryption should be used automatically and will make this decision on our own.

Response

Parameter Type Required Description

id

string true

The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the /mailboxes/ call.

type

string true

The type of the established connection. Could be one of three values: imap, google, or microsoft.

state

string true

The current state of the mailbox, there are 5 options:

  • connecting - you should see this if you just connected a valid mailbox.
  • error - indicates there was an error while connecting to the mailbox.
  • scanning - indicates that we are actively scanning messages in the mailbox.
  • listening - indicates that there are no messages to scan at the moment, so we are listening for new emails to arrive.
  • finished - indicates that we finished scanning the mailbox and we are not listening for new messages.

errorCode

string false

If the state parameter returns a value of error, this parameter will return one of three error codes:

  • connection - indicates an error connecting to the mailbox.
  • authentication - indicates an error authenticating to the mailbox.
  • unknown - indicates an unknown error.

errorMessage

string false

If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter.

tags

array false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

creationDate

string true

Date and time in UTC when this mailbox was added for scanning.

startFrom

string false

If the startFrom parameter was passed in the request it will be returned here.

listen

boolean false

Shows the value (true or false) that you passed to us when adding the mailbox.

host

string false

The IMAP address of the server where mailbox is hosted.

login

string false

The IMAP server login to connect to the mailbox. In most cases it should be the email address.

secure

boolean false

Shows the value (true or false) for connection type that you passed to us when adding the mailbox. If it was not set then it is true by default.

Connect via Google API

POST Request Example

                            
{
  "email": "john@gmail.com",
  "accessToken": "abcd",
  "refreshToken": "efgh",
  "startFrom": "2017-06-01",
  "listen": true,
  "callbackUrl": "https://api.yoursite.com/callback",
  "userData": "Testing the connection via the Google API",
  "tags": [
    "test",
    "userid_1234"
  ]
}
                            
                        

Response Example

                            
{
  "state": "connecting",
  "id": 3474,
  "creationDate": "2018-08-31T21:48:55+0000",
  "startFrom": "2018-07-05",
  "listen": true,
  "tags": [
    "test",
    "userid_1234"
  ],
  "login": "john@gmail.com",
  "type": "google"
}
                            
                        

This method should be used to connect any Google mailbox, not just the @gmail.com mailboxes but also any mailboxes hosted by Google Apps. In case you are unsure if a given mailbox is hosted by Google you can call the /mailboxes/detect-type/{email} method.

This method utilizes native Google API to connect to the mailbox. The end user will get a message requesting access to his or her mailbox which looks like this:

If you don’t want to have AwardWallet mentioned in this message to the end user, you need to create and verify your own app with Google API this way you will get your own googleClientId, googleClientSecret, and googlePubSubTopic. You need to provide those values to our support so that we can have your account updated.

Here are the rough steps that you need to take to create your own verified Google app:

You can send this client_id.json to our support or just send us the client_id and the client_secret

  • Then you need to enable the Pub/Sub API as follows:

  • Once it has been enabled you need to create a Pub/Sub Topic. You should also review the Google’s documentation on this subject matter:

  • After the Pub/Sub topic has been created you need to create a subscription:

  • If you have not yet verified your domain, you would need to do that:

The easiest way to verify the domain would be to do it via the CNAME records:

You would need to give us the CNAME records to add:

Once set up, you should verify your domain ownership and you should get a confirmation from Google that it worked:

  • At the end of it you should see at least one Pub/Sub topic subscription enabled:

  • Finally, you need to set up Pub/Sub Topic permissions:

Make the gmail-api-push@system.gserviceaccount.com account Pub/Sub Publisher:

here is what it should look like:

This is it, after you finish these steps you should be all set to get access to Gmail accounts.

HTTP Request

POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/google

POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/google

Query Parameters

Parameter Type Required Description

startFrom

date false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

string false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

userData

string false

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

email

string false

The email address of the mailbox

accessToken

string false

The access_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

refreshToken

string false

The refresh_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

Response

Parameter Type Required Description

id

string true

The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the /mailboxes/ call.

type

string true

The type of the established connection. Could be one of three values: imap, google, or microsoft.

state

string true

The current state of the mailbox, there are 5 options:

  • connecting - you should see this if you just connected a valid mailbox.
  • error - indicates there was an error while connecting to the mailbox.
  • scanning - indicates that we are actively scanning messages in the mailbox.
  • listening - indicates that there are no messages to scan at the moment, so we are listening for new emails to arrive.
  • finished - indicates that we finished scanning the mailbox and we are not listening for new messages.

errorCode

string false

If the state parameter returns a value of error, this parameter will return one of three error codes:

  • connection - indicates an error connecting to the mailbox.
  • authentication - indicates an error authenticating to the mailbox.
  • unknown - indicates an unknown error.

errorMessage

string false

If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter.

tags

array false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

creationDate

string true

Date and time in UTC when this mailbox was added for scanning.

startFrom

string false

If the startFrom parameter was passed in the request it will be returned here.

listen

boolean false

Shows the value (true or false) that you passed to us when adding the mailbox.

email

string false

The email address of the mailbox that was added as part of the request.

Response

Connect via Microsoft API

POST Request Example

                            
{
  "email": "john@hotmail.com",
  "accessToken": "wxyz",
  "refreshToken": "hijk",
  "startFrom": "2017-06-01",
  "listen": true,
  "callbackUrl": "https://api.yoursite.com/callback",
  "userData": "Testing the connection via the Microsoft API",
  "tags": [
    "test",
    "userid_1234"
  ]
}
                            
                        

Response Example

                            
{
  "state": "connecting",
  "id": 3472,
  "creationDate": "2018-08-31T21:48:55+0000",
  "startFrom": "2018-07-05",
  "listen": true,
  "tags": [
    "test",
    "userid_1234"
  ],
  "login": "john@hotmail.com",
  "type": "microsoft"
}
                            
                        

This method should be used to connect any Micosoft mailbox, not just the @live.com, @hotmail.com, or @outlook.com mailboxes but also any mailboxes hosted by Microsoft Office 365. In case you are unsure if a given mailbox is hosted by Microsoft you can call the /mailboxes/detect-type/{email} method.

This method utilizes the native Microsoft API to connect to the mailbox. The end user will get a message requesting access to his or her mailbox which looks like this:

If you don’t want to have AwardWallet mentioned in this message to the end user, you need to create and verify your own app with the Microsoft API this way you will get your own Microsoft Client Id and Microsoft Client Secret. You need to provide those values to our support so that we can have your account updated.

Here are the steps that you need to take to create your own verified Microsoft app. Fisrt, login with your Microsoft account and create a new app if you have not already done so:

You don’t really need to do the guided setup, unless you want to:

Next, generate a new password for your application:

Make sure you safely copy the password, you will need to provide this password to our support in order to allow us to scan your user’s mailboxes:

Then, you need to add a platform, you should select “Web” as the platform:

For the Redirect URLs, you should put https://service.awardwallet.com/email/v2/mailboxes/auth/callback we will handle the response to update this mailbox connection and then will redirect the user to the redirectUrl that you specified in the /mailboxes/start-auth request. You can set the logout URL to be whatever you like on your domain. If you don’t wish to have AwardWallet listed in the Redirect URL you can set that to be your domain, i.e. https://yourdoamin.com/email/callback and then proxy requests sent to this URL to our callback URL. In the end your settings should looks something like this:

For Microsoft Graph Permissions please add profile and User.Read:

Then set the rest of the application profile attributes:

HTTP Request

POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/microsoft

POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/microsoft

Query Parameters

Parameter Type Required Description

startFrom

date false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

string false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

userData

string false

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

email

string false

The email address of the mailbox

accessToken

string false

The access_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

refreshToken

string false

The refresh_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

Response

Parameter Type Required Description

id

string true

The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the /mailboxes/ call.

type

string true

The type of the established connection. Could be one of three values: imap, google, or microsoft.

state

string true

The current state of the mailbox, there are 5 options:

  • connecting - you should see this if you just connected a valid mailbox.
  • error - indicates there was an error while connecting to the mailbox.
  • scanning - indicates that we are actively scanning messages in the mailbox.
  • listening - indicates that there are no messages to scan at the moment, so we are listening for new emails to arrive.
  • finished - indicates that we finished scanning the mailbox and we are not listening for new messages.

errorCode

string false

If the state parameter returns a value of error, this parameter will return one of three error codes:

  • connection - indicates an error connecting to the mailbox.
  • authentication - indicates an error authenticating to the mailbox.
  • unknown - indicates an unknown error.

errorMessage

string false

If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter.

tags

array false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

creationDate

string true

Date and time in UTC when this mailbox was added for scanning.

startFrom

string false

If the startFrom parameter was passed in the request it will be returned here.

listen

boolean false

Shows the value (true or false) that you passed to us when adding the mailbox.

email

string false

The email address of the mailbox that was added as part of the request.

Response

Begin Authentication

POST Request Example

                            
{
  "startFrom": "2018-07-16",
  "listen": true,
  "callbackUrl": "http://mycompany.com/api/email/receiver/",
  "userData": "userID: 1234",
  "tags": [
    "test",
    "userid_1234"
  ],
  "provider": "google",
  "redirectUrl": "http://mycompany.com/emailscanner/welcome/"
}
                            
                        

Response Example

                            
"33bdffdcef607e625agpxe3d470b0d9cbc752184"
                            
                        

Use this method to begin authenticating your user against the Google or the Microsoft APIs. This method will return a code (valid for 1 hour), that you will then use to redirect your user.

HTTP Request

POST https://service.awardwallet.com/email/json/v2/mailboxes/start-auth

POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/start-auth

Query Parameters

Parameter Type Required Description

startFrom

date false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

string false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

userData

string false

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

provider

string false

Mailbox provider, against which you wish to authenticate. Can be one of two values: google or microsoft.

redirectUrl

string false

Upon authentication we will return the user to this URL. We will also pass the following GET parameters in URL state=success&mailboxId=123. In case on an error you wull receive the following parameters: state=error&errorCode=someCode&errorMessage=error+messasge. The errorCode and errorMessage attributes are specific to a provider and returned as-is from Google or Microsoft. It is not recommended to display these values to the end user.

Response

Parameter Type Required Description

response

string true

The code that you will need to pass into the user OAuth redirect, i.e. when you send your user to https://service.awardwallet.com/email/v2/mailboxes/auth/{code} for authentication.

User OAuth Redirect

This method can be used to authenticate your users against the Google or Microsoft OAuth APIs. This is not a method you need to call from your servers, instead you need to send your users (via browser) to this URL, it will, then redirect your users to either Google or Microsoft automatically for authentication. After authentication you can see this mailbox being connected to your account via the List Mailboxes (/mailboxes/) method. After the authentication completes, the user will be redirected to the redirectUrl, specified in /mailboxes/start-auth method. You will then receive the following parameters in the URL:

  • state: error or success.
  • errorCode and errorMessage: Technical details about the error. You should not display these fields to the end user, they are designed more for support and troubleshooting purposes.
  • mailboxId - You will receive this field in case of a successful connection. You could use this field to call the Get Mailbox Info (/mailboxes/{mailboxId}) method.

HTTP Request

GET https://service.awardwallet.com/email/v2/mailboxes/auth/{code}

GET https://email-eu.awardwallet.com/email/v2/mailboxes/auth/{code}

Query Parameters

Parameter Type Required Description

code

string true

This is the code that you got from the /mailboxes/start-auth method.

Get Mailbox Info

Response Example

                            
{
  "state": "listening",
  "id": 2509,
  "creationDate": "2018-08-03T20:09:49+0000",
  "startFrom": "2018-07-16",
  "listen": true,
  "tags": [
    "test",
    "userid_1234"
  ],
  "email": "JohnSmith@gmail.com",
  "type": "google"
}
                            
                        

Get information about a specific mailbox that was added to our mailbox scanner.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/mailboxes/{mailboxId}

GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/{mailboxId}

Query Parameters

Parameter Type Required Description

mailboxId

integer true

This is the ID that you received from either one of the following methods: List Mailboxes (/mailboxes/), Connect via Google API (/mailboxes/connect/google), Connect via Microsoft API (/mailboxes/connect/microsoft), or the User OAuth Redirect method.

Response

Any of MicrosoftMailbox, GoogleMailbox, ImapMailbox

List Mailboxes

Response Example

                            
[
  {
    "state": "listening",
    "id": 1234,
    "creationDate": "2018-08-03T20:09:49+0000",
    "startFrom": "2018-07-16",
    "listen": true,
    "tags": [
      "test",
      "userid_1234"
    ],
    "email": "john@gmail.com",
    "type": "google"
  },
  {
    "state": "listening",
    "id": 1235,
    "creationDate": "2018-08-30T15:54:27+0000",
    "startFrom": "2018-07-16",
    "listen": true,
    "tags": [
      "test",
      "userid_1234"
    ],
    "email": "john@hotmail.com",
    "type": "microsoft"
  }
]
                            
                        

List all the mailboxes you have aded to the scanner. You can filter the results by tags. To do that, Separate the tags by comma ",", for example:

GET /json/v2/mailboxes/?tags=tag1,tag2

This will return all the mailboxes that have both tag1 and tag2.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/mailboxes/

GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/

Query Parameters

Parameter Type Required Description

tags

array true

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

Response

Parameter Type Required Description

Response

Disconnect Mailbox

Response Example

                            
"successfully deleted"
                            
                        

This method allows you to remove a mailbox that was previously added for scanning.

HTTP Request

POST https://service.awardwallet.com/email/json/v2/mailboxes/disconnect/{mailboxId}

POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/disconnect/{mailboxId}

Query Parameters

Parameter Type Required Description

mailboxId

integer true

This is the ID that you received from either one of the following methods: List Mailboxes (/mailboxes/), Connect via Google API (/mailboxes/connect/google), Connect via Microsoft API (/mailboxes/connect/microsoft), or the User OAuth Redirect method. You need to pass this parameter in the URL.

Itineraries

Flight

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 150,
        "cost": 100,
        "discount": 28.34,
        "spentAwards": "3 segments",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 30
          },
          {
            "name": "Seat selection",
            "charge": 5.5
          },
          {
            "name": "Baggage fee",
            "charge": 14.5
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "delta",
        "name": "Delta Air Lines",
        "accountNumbers": [
          {
            "number": "1234****",
            "masked": true
          },
          {
            "number": "4321****",
            "masked": true
          }
        ],
        "earnedRewards": "300 award miles"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "airportCode": "LAX",
            "terminal": "A",
            "name": "Los Angeles International Airport",
            "localDateTime": "2030-01-01T13:30:00",
            "address": {
              "text": "LAX",
              "addressLine": "1 World Way",
              "city": "Los Angeles",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": "90045",
              "lat": 33.9415889,
              "lng": -118.40853,
              "timezone": -25200
            }
          },
          "arrival": {
            "airportCode": "SFO",
            "terminal": "2",
            "name": "San Francisco International Airport",
            "localDateTime": "2030-01-01T15:00:00",
            "address": {
              "text": "SFO",
              "addressLine": "San Francisco International Airport",
              "city": "San Francisco",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200
            }
          },
          "marketingCarrier": {
            "airline": {
              "name": "Delta Air Lines",
              "iata": "DL",
              "icao": "DAL"
            },
            "flightNumber": "0013",
            "confirmationNumber": "MRTG67",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-404-714-2300"
              }
            ],
            "isCodeshare": true
          },
          "operatingCarrier": {
            "airline": {
              "name": "British Airways",
              "iata": "BA",
              "icao": "BAW"
            },
            "flightNumber": "5566",
            "confirmationNumber": "CARR23",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-718-335-7070"
              }
            ]
          },
          "wetleaseCarrier": {
            "name": "Sky Express",
            "iata": null,
            "icao": null
          },
          "seats": [
            "3E",
            "3F"
          ],
          "aircraft": {
            "iataCode": "7M7",
            "name": "Boeing 737MAX 7 Passenger",
            "turboProp": false,
            "jet": true,
            "wideBody": false,
            "regional": false
          },
          "traveledMiles": "300mi",
          "cabin": "Coach",
          "bookingCode": "CL",
          "duration": "1h30min",
          "meal": "Snacks",
          "smoking": false,
          "status": "Confirmed",
          "stops": 0,
          "flightStatsMethodUsed": "ScheduleByFlight"
        },
        {
          "departure": {
            "airportCode": "SFO",
            "terminal": "2",
            "name": "San Francisco International Airport",
            "localDateTime": "2030-01-05T06:00:00",
            "address": {
              "text": "SFO",
              "addressLine": "San Francisco International Airport",
              "city": "San Francisco",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200
            }
          },
          "arrival": {
            "airportCode": "LAX",
            "terminal": "A",
            "name": "Los Angeles International Airport",
            "localDateTime": "2030-01-05T07:30:00",
            "address": {
              "text": "LAX",
              "addressLine": "1 World Way",
              "city": "Los Angeles",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": "90045",
              "lat": 33.9415889,
              "lng": -118.40853,
              "timezone": -25200
            }
          },
          "marketingCarrier": {
            "airline": {
              "name": "Delta Air Lines",
              "iata": "DL",
              "icao": "DAL"
            },
            "flightNumber": "0014",
            "confirmationNumber": "MRTG67",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-404-714-2300"
              }
            ],
            "isCodeshare": true
          },
          "operatingCarrier": {
            "airline": {
              "name": "British Airways",
              "iata": "BA",
              "icao": "BAW"
            },
            "flightNumber": "9009",
            "confirmationNumber": "CARR23",
            "phoneNumbers": [
              {
                "description": null,
                "number": "+1-718-335-7070"
              }
            ]
          },
          "wetleaseCarrier": null,
          "seats": [
            "1B",
            "1C"
          ],
          "aircraft": {
            "iataCode": "7M7",
            "name": "Boeing 737MAX 7 Passenger",
            "turboProp": false,
            "jet": true,
            "wideBody": false,
            "regional": false
          },
          "traveledMiles": "300mi",
          "cabin": "First class",
          "bookingCode": "I",
          "duration": "1h30min",
          "meal": "Snacks",
          "smoking": null,
          "status": "Confirmed",
          "stops": null,
          "flightStatsMethodUsed": "ScheduleByAirport"
        }
      ],
      "issuingCarrier": {
        "airline": {
          "name": "Delta Air Lines",
          "iata": "DL",
          "icao": "DAL"
        },
        "confirmationNumber": "ISSD12",
        "phoneNumbers": [
          {
            "description": null,
            "number": "+1-404-714-2300"
          }
        ],
        "ticketNumbers": [
          {
            "number": "006 123321",
            "masked": false
          },
          {
            "number": "006 456654",
            "masked": false
          }
        ]
      },
      "type": "flight"
    }
  ]
}
                            
                        
Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

travelers

array false

Names of the people listed on the reservation

segments

array true

An array describing individual flight segments of the itinerary.

issuingCarrier

object false

Object that defines the airline that issued the ticket, could be the same as the marketingCarrier or could be different.

Issuing Carrier

Any air ticket is always issued by some airline, this object defines the airline that actually issued the ticket.

Parameter Type Required Description

airline

object false

Object describing the airline that issued the ticket.

confirmationNumber

string false

PNR which corresponds to the airline that issued the ticket.

ticketNumbers

array false

In case if there are multiple travelers, all of their ticket numbers will be listed in this array.

phoneNumbers

array false

Contact phone numbers

Number

This object represents a ticket or an account number.

Parameter Type Required Description

number

string true

Number as it was parsed from the email

masked

boolean true

Will be set to true if the number is partially masked (i.e."XXXX1234", "****5678").

Flight Segment

Parameter Type Required Description

departure

object true

An object describing the departure event such as the departing airport (code, name, address, etc.) as well as the time of the departure.

arrival

object true

An object describing the arrival event such as the arriving airport (code, name, address, etc.) as well as the time of the arrival.

marketingCarrier

object true

Object that defines the flight as it was ticketed. In other words, this is the information that the users would see on their ticket or boarding pass.

operatingCarrier

object false

If an email contains information about an “operating airline” that is different from the airline listed under the marketingCarrier object, that airline would be defined here. Don’t confuse it with wet lease airline, sometimes wet lease airlines are listed as “operated by” but they are technically not codeshares and would be listed separately in the wetleaseCarrier object.

wetleaseCarrier

object false

Wet lease airline is an airline that is DBA (doing business as) the operating airline. It wouldn’t have its own flight number or ticket numbers or confirmation numbers but you may see the wet lease airline listed on the ticket as “ExpressJet” or “KLM Cityhopper”, etc.

seats

array false

Assigned passenger seats.

aircraft

object false

Object defining the aircraft.

traveledMiles

string false

Number of miles traveled on this flight segment.

cabin

string false

Cabin class, i.e. “Economy”

bookingCode

string false

Booking class code, i.e. “T”

duration

string false

Flight duration, as a string, as we gathered it from the provider’s website. Don’t expect to be able to use it programmatically to add or subtract time without some type of transformation on your end that would be specific to each provider.

status

string false

Status of the segment. I.e. cancelled, confirmed, etc.

meal

string false

Meal, if any, that will be offered on the flight.

smoking

boolean false

Most flights nowadays are non-smoking; however, in case if the airline identifies the flight as a smoking flight it would be identified in this field.

stops

integer false

Number of stops this flight has.

flightStatsMethodUsed

string false

If FlightStats API was called to retrieve some missing files that are not present in the email and are required for this flight segment the name of the FlightStats API call will be returned in this field. The possible values are:

  • ScheduleByFlight
  • ScheduleByRoute
  • ScheduleByAirport
  • HistoricalByFlight
  • HistoricalByRoute
  • HistoricalByAirport

Aircraft

Parameter Type Required Description

iataCode

string false

Aircraft IATA code

name

string true

Aircraft name

turboProp

boolean false

Indicates if this is a turboprop aircraft

jet

boolean false

Indicates if this is a jet engine aircraft

wideBody

boolean false

Indicates if this is a wide-body aircraft

regional

boolean false

Indicates if this is a regional aircraft

Operating Carrier

Whenever the operating airline is different from the airline listed on the ticket (next to the flight number), that operating airline flight info would be listed in this object as the operating carrier. Don’t confuse this with a wet lease airline.

Parameter Type Required Description

airline

object false

Object describing the operating airline if this airline is different from the one that was listed on the passenger’s ticket.

flightNumber

string false

Operating airline flight number

confirmationNumber

string false

PNR issued by the operating airline, in most cases will be unknown, i.e. null

phoneNumbers

array false

Contact phone numbers

Marketing Carrier

The flight and airline information as it shows up on the ticket.

Parameter Type Required Description

airline

object true

Object describing the airline that is listed on the ticket, sometimes it is the 2 letter prefix that goes before the flight number as listed on the issued ticket.

flightNumber

string true

Flight number that is listed on the passenger’s ticket.

confirmationNumber

string false

Passenger name record, a.k.a. PNR that is associated with the airline the passenger was ticketed for.

phoneNumbers

array false

Airline phone numbers as shown in the email or the number(s) could be populated by AwardWallet automatically based on the airline even if the numbers were not present in the email.

isCodeshare

boolean false

If this is a codeshare flight and we know the actual operating airline, we would set this attribute to true and then list the actual operating airline (only if it is different from the marketingCarrier.airline) in the operatingCarrier object.

Airline

Parameter Type Required Description

name

string true

Airline name

iata

string false

IATA code of the airline

icao

string false

International Civil Aviation Organization airline code.

Flight Departure or Arrival

This object is describing the arrival or departure events of air travel.

Parameter Type Required Description

airportCode

string false

If this location happened to be an airport this field will return a Validated IATA airport code.

terminal

string false

In cases when terminal is known it will be returned in this field.

name

string true

Train station name or airport name such as “John F. Kennedy International Airport”.

localDateTime

string true

Local date and time of arrival or departure (depending on the type of this location).

address

object true

Object defining the address of this location.

Address

Parameter Type Required Description

text

string true

Non-validated address string. You can usually use this line to search some API (i.e. Google API) to get detailed / structured information about that address. We usually just grab this text as-is from the provider’s website.

addressLine

string false

Validated address line of the address (without the city, state, country and zip code) that we got from Google API.

city

string false

Name of the city validated by the Google API

stateName

string false

Name of the state validated by the Google API

countryName

string false

Name of the country validated by the Google API

postalCode

string false

Zip / postal code validated by the Google API

lat

double false

Latitude coordinate of the address

lng

double false

Longitude coordinate of the address

timezone

integer false

Time zone in which this address is located.

Person

Parameter Type Required Description

name

string true

Name of the person listed on the reservation.

full

boolean false

Sometimes passenger or guest names are shortened on the reservation, if we are able to detect it, this field will reflect that. It will be set to true if the we know the name is full (for example John J Smith) and false if the name is shortened, for example (John S.).

Travel Agency

Parameter Type Required Description

providerInfo

object false

This object describes the travel agency, specifically the loyalty information as it pertains to this travel agency.

confirmationNumbers

array false

Confirmation numbers that were assigned to this trip by the travel agency. Different from the PNRs assigned by the airline.

phoneNumbers

array false

Phone numbers of the travel agency.

Phone Number

Parameter Type Required Description

description

string false

Description of the phone number.

number

string true

Phone number

Confirmation Numbers

Parameter Type Required Description

number

string true

Confirmation number

description

string false

Confirmation number description

isPrimary

boolean false

Indicates whether this confirmation number can be considered as primary

Provider Info

If there is a loyalty program associated with this reservation, the details specific to that program will be listed in this object.

Parameter Type Required Description

name

string false

Loyalty program name

code

string false

Alpha-numeric value with no spaces that uniquely identifies any given loyalty program within AwardWallet.

accountNumbers

array false

Array of related loyalty program account numbers

earnedRewards

string false

Rewards earned for booking the reservation

Car Rental

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 251.41,
        "cost": 193.75,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 34.56
          },
          {
            "name": "Insurance",
            "charge": 23.1
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "avis",
        "name": "Avis",
        "accountNumbers": [
          {
            "number": "AVS454545",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "$50 penalty if cancelled",
      "confirmationNumbers": [
        {
          "number": "1122334455",
          "description": "Confirmation number",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Reference",
          "isPrimary": false
        }
      ],
      "pickup": {
        "address": {
          "text": "Palm Beach Intl Airport,PBI, 2500 Turnage Boulevard, West Palm Beach, FL 33406 US",
          "addressLine": "1000 James L Turnage Boulevard",
          "city": "West Palm Beach",
          "stateName": "Florida",
          "countryName": "United States",
          "postalCode": "33415",
          "lat": 26.6857475,
          "lng": -80.0928165,
          "timezone": -14400
        },
        "localDateTime": "2030-01-01T13:30:00",
        "openingHours": "Sun - Sat open 24 hrs",
        "phone": "+1-13-PICKUP",
        "fax": "+1-14-FAX"
      },
      "dropoff": {
        "address": {
          "text": "Palm Beach Intl Airport,PBI, 2500 Turnage Boulevard, West Palm Beach, FL 33406 US",
          "addressLine": "1000 James L Turnage Boulevard",
          "city": "West Palm Beach",
          "stateName": "Florida",
          "countryName": "United States",
          "postalCode": "33415",
          "lat": 26.6857475,
          "lng": -80.0928165,
          "timezone": -14400
        },
        "localDateTime": "2030-01-05T13:30:00",
        "openingHours": "Sun - Sat open 24 hrs",
        "phone": "+1-13-DROPOFF",
        "fax": "+1-14-FAX"
      },
      "car": {
        "type": "Regular",
        "model": "Ford Edge or similar",
        "imageUrl": "http://car.image/url"
      },
      "discounts": null,
      "driver": {
        "name": "John Doe",
        "full": true
      },
      "pricedEquipment": null,
      "rentalCompany": null,
      "type": "carRental"
    }
  ]
}
                            
                        

Rental car reservation

Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers.

pickup

object true

Object defining the pickup event (time and location) of the rental car.

dropoff

object true

Object defining the dropoff event (time and location) of the rental car.

car

object false

Object defining the rental car.

discounts

array false

An array of various discounts that were applied to the reservation.

driver

object false

Object describing the driver of the car.

pricedEquipment

array false

An array of additional equipment that was added to the reservation.

rentalCompany

string false

Name of the rental company.

Car Rental Discount

Parameter Type Required Description

name

string true

Discount name, such as “Your Rate has been discounted based on the Hertz CDP provided”.

code

string true

Discount code, such as “AAA SOUTHERN NEW ENGLAND”

Car

Parameter Type Required Description

type

string false

Type of the rental car, i.e. “Intermediate SUV”.

model

string false

Model of the rental car, i.e. “Ford Escape or similar”.

imageUrl

string false

URL of the image of the car.

Car Rental Location

Pickup or drop off location of the rental car.

Parameter Type Required Description

address

object true

Rental car facility address.

localDateTime

string true

Scheduled date and time of the car pickup or drop-off in the time zone of the location of the rental car facility.

openingHours

string false

Rental car facility hours of operation.

phone

string false

Rental car facility phone number.

fax

string false

Rental car facility fax number.

Hotel Reservation

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 300,
        "cost": 200,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 100
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "spg",
        "name": "Starwood Hotels",
        "accountNumbers": [
          {
            "number": "xxxxxx345",
            "masked": true
          }
        ],
        "earnedRewards": "4 nights"
      },
      "cancellationPolicy": "Cancellation is free 24 hours prior to check-in",
      "cancellationDeadline": "2029-12-31T13:30:00",
      "isNonRefundable": null,
      "confirmationNumbers": [
        {
          "number": "1122334455",
          "description": "Confirmation number",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Reference",
          "isPrimary": false
        }
      ],
      "hotelName": "Sheraton Philadelphia Downtown Hotel",
      "chainName": null,
      "address": {
        "text": "201 North 17th Street, Philadelphia, Pennsylvania 19103 United States",
        "addressLine": "201 North 17th Street",
        "city": "Philadelphia",
        "stateName": "Pennsylvania",
        "countryName": "United States",
        "postalCode": "19103",
        "lat": 39.9569828,
        "lng": -75.1674669,
        "timezone": -14400
      },
      "checkInDate": "2030-01-01T13:30:00",
      "checkOutDate": "2030-01-05T12:00:00",
      "phone": "+1-22-3333",
      "fax": "+1-66-77899",
      "guests": [
        {
          "name": "John D.",
          "full": false
        },
        {
          "name": "Jane D.",
          "full": false
        }
      ],
      "guestCount": 2,
      "kidsCount": 3,
      "roomsCount": 1,
      "rooms": [
        {
          "type": "King bed",
          "description": "Traditional, TV, free wi-fi",
          "rate": "30$/night",
          "rateType": "King bed"
        }
      ],
      "type": "hotelReservation"
    }
  ]
}
                            
                        

Hotel reservation

Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

cancellationDeadline

string false

Deadline date for changing or cancelling the reservation without additional penalties

isNonRefundable

boolean false

Set to true if the reservation is non-refundable. Set to null if we don’t know if the reservation is refundable or non-refundable.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

hotelName

string true

Name of the hotel, i.e. “Hilton Garden Inn Atlanta Perimeter Center”

chainName

string false

Name of the hotel chain.

address

object true

An object describing all the details of the address of the hotel.

checkInDate

string true

Check-in date.

checkOutDate

string true

Check-out date.

phone

string false

Hotel’s phone number.

fax

string false

Hotel’s fax number.

guests

array false

An array describing guests that are listed on the reservation.

guestCount

integer false

Number of guests on the reservation.

kidsCount

integer false

Number of kids listed on the reservation.

roomsCount

integer false

Number of rooms listed on the reservation.

rooms

array false

An array describing the room(s) listed on the reservation.

Room

Parameter Type Required Description

type

string false

Room type, i.e. “2 QUEEN BEDS NONSMOKING”

description

string false

Room description, i.e. “Non-Smoking Room Confirmed”

rate

string false

Room rate per night.

rateType

string false

Room rate type, i.e. “2 QUEEN BEDS NONSMOKING”.

Bus

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 251.41,
        "cost": 193.75,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 34.56
          },
          {
            "name": "Insurance",
            "charge": 23.1
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "boltbus",
        "name": "BoltBus",
        "accountNumbers": [
          {
            "number": "BB3398",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "scheduleNumber": "2023",
          "departure": {
            "stationCode": null,
            "name": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
            "localDateTime": "2030-01-01T13:30:00",
            "address": {
              "text": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
              "addressLine": "700 Atlantic Avenue",
              "city": "Boston",
              "stateName": "Massachusetts",
              "countryName": "United States",
              "postalCode": "02111",
              "lat": 42.3504505,
              "lng": -71.0561242,
              "timezone": -14400
            }
          },
          "arrival": {
            "stationCode": null,
            "name": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
            "localDateTime": "2030-01-01T20:34:00",
            "address": {
              "text": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null
            }
          },
          "busInfo": {
            "type": "Regular",
            "model": "Mercedes"
          },
          "seats": [
            "11",
            "12"
          ],
          "traveledMiles": "43mi",
          "cabin": null,
          "bookingCode": null,
          "duration": "7h",
          "meal": null,
          "smoking": null,
          "stops": null
        }
      ],
      "ticketNumbers": [
        {
          "number": "345667",
          "masked": false
        },
        {
          "number": "345668",
          "masked": false
        }
      ],
      "type": "bus"
    }
  ]
}
                            
                        

Bus ride

Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

travelers

array false

Names of the people listed on the reservation

segments

array true

An array describing individual travel segments of the itinerary.

ticketNumbers

array false

There may be different ticket numbers associated with an itinerary. All the ticket numbers that we gather would be presented as an array in this field.

Bus segment

Parameter Type Required Description

scheduleNumber

string false

ScheduleNumber is similar in concept to FlightNumber but applicable to Trains or Busses, etc. So it is designed to define a route number for various types of transportation itineraries.

departure

object true

An object describing the departure event of this trip segment, such as a bus stop location and the time of departure.

arrival

object true

An object describing the arrival event of this trip segment, such as a bus stop location and the time of arrival.

busInfo

object false

And object describing the bus

seats

array false

Assigned passenger seats.

traveledMiles

string false

Number of miles traveled on this segment.

cabin

string false

Cabin class, i.e. “Economy”

bookingCode

string false

Booking class code, i.e. “SL” for “Sleeper class” booking code.

duration

string false

Trip duration

meal

string false

Meal, if any, that will be offered on the train, ferry, bus, etc.

smoking

string false

Most transporation services nowadays are non-smoking; however, in case if the provider identifies the car / train / bus as smoking it would be listed in this field.

stops

integer false

Number of stops this transportation segment has.

Vehicle

This object describes the vehicle used to trasport a passenger

Parameter Type Required Description

type

string false

Short description

model

string false

Model of the vehicle

Transportation Departure or Arrival

This object describes the transportation departure and arrival events

Parameter Type Required Description

stationCode

string false

This attribute shows the bus station or train station or port code as it shows up on the email. This field is not validated.

name

string true

Station or location name

localDateTime

string true

Local date and time of arrival or departure (depending on the type of this location).

address

object true

Object defining the address of this location.

Train

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 251.41,
        "cost": 193.75,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 34.56
          },
          {
            "name": "Insurance",
            "charge": 23.1
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "amtrak",
        "name": "Amtrak",
        "accountNumbers": [
          {
            "number": "AM3398",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "stationCode": "BBSS",
            "name": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
            "localDateTime": "2030-01-01T13:30:00",
            "address": {
              "text": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
              "addressLine": "700 Atlantic Avenue",
              "city": "Boston",
              "stateName": "Massachusetts",
              "countryName": "United States",
              "postalCode": "02111",
              "lat": 42.3504505,
              "lng": -71.0561242,
              "timezone": -14400
            }
          },
          "arrival": {
            "stationCode": "NNYW",
            "name": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
            "localDateTime": "2030-01-01T20:34:00",
            "address": {
              "text": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null
            }
          },
          "scheduleNumber": "2023",
          "serviceName": "Amtrak Express",
          "trainInfo": {
            "type": "Regular",
            "model": null
          },
          "car": "4",
          "seats": [
            "11",
            "12"
          ],
          "traveledMiles": "43mi",
          "cabin": "coach",
          "bookingCode": null,
          "duration": "7h",
          "meal": null,
          "smoking": null,
          "stops": null
        }
      ],
      "ticketNumbers": [
        {
          "number": "345667",
          "masked": false
        },
        {
          "number": "345668",
          "masked": false
        }
      ],
      "type": "train"
    }
  ]
}
                            
                        

Train ride

Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

travelers

array false

Names of the people listed on the reservation

segments

array true

An array describing individual travel segments of the itinerary.

ticketNumbers

array false

There may be different ticket numbers associated with an itinerary. All the ticket numbers that we gather would be presented as an array in this field.

Train segment

Parameter Type Required Description

scheduleNumber

string false

ScheduleNumber is similar in concept to FlightNumber but applicable to Trains or Busses, etc. So it is designed to define a route number for various types of transportation itineraries.

departure

object true

An object describing the departure event of this trip segment, such as a train station and the time of departure.

arrival

object true

An object describing the arrival event of this trip segment, such as a train station and the time of arrival.

serviceName

string false

Short name of the particular service or route

trainInfo

object false

And object describing the train

car

string false

Train car number.

seats

array false

Assigned passenger seats in a car

traveledMiles

string false

Number of miles traveled on this segment.

cabin

string false

Cabin class, i.e. “Economy”

bookingCode

string false

Booking class code, i.e. “SL” for “Sleeper class” booking code.

duration

string false

Trip duration

meal

string false

Meal, if any, that will be offered on the train, ferry, bus, etc.

smoking

string false

Most transporation services nowadays are non-smoking; however, in case if the provider identifies the car / train / bus as smoking it would be listed in this field.

stops

integer false

Number of stops this transportation segment has.

Transfer

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 251.41,
        "cost": 193.75,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 34.56
          },
          {
            "name": "Insurance",
            "charge": 23.1
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "uber",
        "name": "Uber.com",
        "accountNumbers": [
          {
            "number": "AM3398",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "airportCode": "SFO",
            "name": "San Francisco International Airport",
            "localDateTime": "2030-01-01T13:30:00",
            "address": {
              "text": "SFO",
              "addressLine": "San Francisco International Airport",
              "city": "San Francisco",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200
            }
          },
          "arrival": {
            "airportCode": null,
            "name": "315 Walnut Ave, South San Francisco, CA 94080, USA",
            "localDateTime": "2030-01-01T14:34:00",
            "address": {
              "text": "315 Walnut Ave, South San Francisco, CA 94080, USA",
              "addressLine": "315 Walnut Avenue",
              "city": "South San Francisco",
              "stateName": "California",
              "countryName": "United States",
              "postalCode": "94080",
              "lat": 37.6569251,
              "lng": -122.4143844,
              "timezone": -25200
            }
          },
          "vehicleInfo": {
            "type": "Regular",
            "model": "Ford Focus",
            "imageUrl": "http://car.image/url"
          },
          "adults": 1,
          "kids": 0,
          "traveledMiles": "4.3mi",
          "duration": "7h"
        }
      ],
      "type": "transfer"
    }
  ]
}
                            
                        

Car or shuttle bus ride

Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

travelers

array false

Names of the people listed on the reservation

segments

array true

An array describing individual travel segments of the itinerary.

Transfer segment

Parameter Type Required Description

departure

object true

An object describing the departure event of this trip segment, such as an address or an airport and the time of departure.

arrival

object true

An object describing the arrival event of this trip segment, such as an address or an airport and the time of arrival.

vehicleInfo

object false

And object describing the vehicle

adults

integer false

kids

integer false

traveledMiles

string false

Number of miles traveled on this segment.

duration

string false

Trip duration

Transfer Departure or Arrival

This object describes the transfer departure and arrival events

Parameter Type Required Description

airportCode

string false

Iata code of an airport.

name

string true

Location name

localDateTime

string true

Local date and time of arrival or departure (depending on the type of this location).

address

object true

Object defining the address of this location.

Cruise

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 251.41,
        "cost": 193.75,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 34.56
          },
          {
            "name": "Insurance",
            "charge": 23.1
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "disneycruise",
        "name": "Disney Cruise Line",
        "accountNumbers": [
          {
            "number": "AM3398",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "stationCode": null,
            "name": "PORT CANAVERAL",
            "localDateTime": "2030-01-01T13:30:00",
            "address": {
              "text": "PORT CANAVERAL",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null
            }
          },
          "arrival": {
            "stationCode": null,
            "name": "NASSAU",
            "localDateTime": "2030-01-02T08:00:00",
            "address": {
              "text": "NASSAU",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": 25.0479835,
              "lng": -77.355413,
              "timezone": -14400
            }
          }
        },
        {
          "departure": {
            "stationCode": null,
            "name": "NASSAU",
            "localDateTime": "2030-01-02T12:00:00",
            "address": {
              "text": "NASSAU",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": 25.0479835,
              "lng": -77.355413,
              "timezone": -14400
            }
          },
          "arrival": {
            "stationCode": null,
            "name": "PORT CANAVERAL",
            "localDateTime": "2030-01-03T14:00:00",
            "address": {
              "text": "PORT CANAVERAL",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null
            }
          }
        }
      ],
      "cruiseDetails": {
        "description": "Long cruise",
        "class": "Regular",
        "deck": "3",
        "room": "342",
        "ship": "Disney Dream",
        "shipCode": "SHCD",
        "voyageNumber": "K229"
      },
      "type": "cruise"
    }
  ]
}
                            
                        
Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

travelers

array false

Names of the people listed on the reservation

segments

array true

An array describing individual travel segments of the itinerary.

cruiseDetails

object false

Cruise Details

Cruise Details

Parameter Type Required Description

description

string false

Cruise description, such as “7-Day Eastern Caribbean from Orlando (Port Canaveral)”

class

string false

Room class

deck

string false

Name of the deck, i.e. “The Haven Stateroom”

room

string false

Room number

ship

string false

The name of the ship, i.e. “Norwegian Epic”

shipCode

string false

This is usually a two-letter code that identifies the ship

voyageNumber

string false

Voyage number

Cruise Segment

Parameter Type Required Description

departure

object true

Object describing the departure port

arrival

object true

Object describing the arrival port

Event

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 251.41,
        "cost": 193.75,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 34.56
          },
          {
            "name": "Insurance",
            "charge": 23.1
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "opentable",
        "name": "OpenTable.com",
        "accountNumbers": [
          {
            "number": "AM3398",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "address": {
        "text": "132 West 58th Street New York, NY 10019",
        "addressLine": "132 West 58th Street",
        "city": "New York",
        "stateName": "New York",
        "countryName": "United States",
        "postalCode": "10019",
        "lat": 40.7653771,
        "lng": -73.9779742,
        "timezone": -14400
      },
      "eventName": "Loi Estiatorio",
      "eventType": 1,
      "startDateTime": "2030-01-01T18:00:00",
      "endDateTime": "2030-01-01T23:00:00",
      "phone": "+1-23-44556",
      "fax": "+1-99-33434",
      "guestCount": 2,
      "guests": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "seats": [
        "table 13"
      ],
      "type": "event"
    }
  ]
}
                            
                        
Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers.

address

object true

The address of the event.

eventName

string true

Event name such as the name of the restaurant.

eventType

integer true

Type of the event. The possible values are:

1 - for “Restaurant”

2 - for “Meeting”

3 - for “Show”

4 - for “Event”

startDateTime

string true

Date and time when the event starts.

endDateTime

string false

Date and time when the event ends.

phone

string false

Phone number associated with the event, such as restaurant’s phone number.

fax

string false

Fax number associated with the event, such as show organizer’s fax number.

guestCount

integer false

Number of guests participating in the event.

guests

array false

Arrays of guests participating in the event.

seats

array false

Array of reserved seats

Parking

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 105.15,
        "cost": 99.12,
        "discount": null,
        "spentAwards": null,
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Taxes",
            "charge": 6.03
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "parkingspot",
        "name": "The Parking Spot",
        "accountNumbers": [
          {
            "number": "AM3398",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Transcation number",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Invoice number",
          "isPrimary": false
        }
      ],
      "address": {
        "text": "132 West 58th Street New York, NY 10019",
        "addressLine": "132 West 58th Street",
        "city": "New York",
        "stateName": "New York",
        "countryName": "United States",
        "postalCode": "10019",
        "lat": 40.7653771,
        "lng": -73.9779742,
        "timezone": -14400
      },
      "locationName": "Downtown 2 hr",
      "spotNumber": "4",
      "licensePlate": "ABC GHY",
      "startDateTime": "2030-01-01T18:00:00",
      "endDateTime": "2030-01-01T23:00:00",
      "phone": "+1-234-56789",
      "owner": {
        "name": "John Doe",
        "full": true
      },
      "rateType": "STANDARD SPOT",
      "carDescription": "Volkswagen white",
      "type": "parking"
    }
  ]
}
                            
                        

Parking spot reservations (usually for airport long-term parking)

Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the parking provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers.

address

object false

The address of the parking location.

locationName

string false

Parking location name.

spotNumber

string false

Parking spot number.

licensePlate

string false

Licanse plate.

startDateTime

string true

Parking start date and time.

endDateTime

string true

Parking end date and time.

phone

string false

Parking facility phone number.

owner

object false

Car owner's name.

rateType

string false

Rate type.

carDescription

string false

Information about the parked vehicle

Ferry

Example

                            
{
  "itineraries": [
    {
      "travelAgency": null,
      "pricingInfo": {
        "total": 251.41,
        "cost": 193.75,
        "discount": 40,
        "spentAwards": "10000 points",
        "currencyCode": "USD",
        "fees": [
          {
            "name": "Tax",
            "charge": 34.56
          },
          {
            "name": "Insurance",
            "charge": 23.1
          }
        ]
      },
      "status": "Confirmed",
      "reservationDate": "2000-01-01T00:00:00",
      "providerInfo": {
        "code": "aferry",
        "name": "AFerry",
        "accountNumbers": [
          {
            "number": "AM3398",
            "masked": false
          }
        ],
        "earnedRewards": "50 points"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "stationCode": "NO OSL",
            "name": "Oslo, Norway",
            "localDateTime": "2030-01-01T14:00:00",
            "address": {
              "text": "Akershusstranda 19, 0102 Oslo, Norway",
              "addressLine": "Akershusstranda 19",
              "city": "Oslo",
              "stateName": null,
              "countryName": "Norway",
              "postalCode": "0102",
              "lat": 59.904139,
              "lng": 10.738278,
              "timezone": null
            }
          },
          "arrival": {
            "stationCode": "DEKEL",
            "name": "Kiel, Germany",
            "localDateTime": "2030-01-02T10:00:00",
            "address": {
              "text": "Norwegenkai, 24143 Kiel, Germany",
              "addressLine": null,
              "city": "Kiel",
              "stateName": null,
              "countryName": "Germany",
              "postalCode": null,
              "lat": 54.316333,
              "lng": 10.138806,
              "timezone": null
            }
          },
          "accommodations": [
            "4-Bed inside cabin, shower/WC",
            "4-Bed inside cabin, shower/WC"
          ],
          "carrier": "ANEK SUPERFAST",
          "vessel": "Hellenic Spirit",
          "traveledMiles": "10km",
          "duration": "2h",
          "meal": "none",
          "smoking": false,
          "adultsCount": 2,
          "kidsCount": 1,
          "pets": "1 cat",
          "vehicles": [
            {
              "type": "Auto",
              "model": "Audi",
              "length": "<5m",
              "height": "1.8",
              "width": "1.8-3m"
            }
          ],
          "trailers": [
            {
              "type": "Regular",
              "model": "Standard",
              "length": "<=2m",
              "height": "<=2",
              "width": "<=2"
            }
          ]
        }
      ],
      "ticketNumbers": [
        {
          "number": "345667",
          "masked": false
        },
        {
          "number": "345668",
          "masked": false
        }
      ],
      "type": "ferry"
    }
  ]
}
                            
                        
Parameter Type Required Description

type

string true

Type of reservation. Possible values are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry
  • cancelled

travelAgency

object false

If this reservation was booked through a travel agency this object would define the properties of that travel agency.

pricingInfo

object false

An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

status

string false

Status of the reservation. I.e. cancelled, confirmed, etc.

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

This object describes the provider, specifically the loyalty information as it pertains to this provider.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

confirmationNumbers

array false

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

travelers

array false

Names of the people listed on the reservation

segments

array true

An array describing individual travel segments of the itinerary.

ticketNumbers

array false

There may be different ticket numbers associated with an itinerary. All the ticket numbers that we gather would be presented as an array in this field.

Ferry segment

Parameter Type Required Description

carrier

string false

The name of the company operating the ferry.

vessel

string false

Name or type of the vessel / ferry.

departure

object true

An object describing the departure event of this trip segment, such as a port and the time of departure.

arrival

object true

An object describing the arrival event of this trip segment, such as a port and the time of arrival.

adultsCount

integer false

Number of adults listed on the reservation.

kidsCount

integer false

Number of kids listed on the reservation.

pets

string false

Information about the pets listed on the ticket.

accommodations

array false

Assigned passenger accommodations on a ferry

traveledMiles

string false

Number of miles traveled on this segment.

duration

string false

Trip duration.

meal

string false

Meal, if any, that will be offered on the ferry.

smoking

boolean false

If accomodation is identified as a smoking place it would be identified in this field.

vehicles

array false

An array describing the vehicle(s) listed on the reservation.

trailers

array false

An array describing the trailer(s) listed on the reservation.

Vehicle or Trailer

This object describes a vehicle/trailer

Parameter Type Required Description

type

string false

Short description

model

string false

Model of the vehicle/trailer

length

string false

Length of the vehicle/trailer (size description, includes number, e.g. "Less than 6.00 metres")

height

string false

Height of the vehicle/trailer (size description, includes number, e.g. "Less than 1.80 metres")

width

string false

Width of the vehicle/trailer (size description, includes number.)

Cancelled

Example

                            
{
  "itineraries": [
    {
      "type": "cancelled",
      "itineraryType": "flight",
      "confirmationNumber": "ABC321"
    }
  ]
}
                            
                        
Parameter Type Required Description

type

string true

In case of a canceled reservation type will always be set to canceled

itineraryType

string true

Type of reservation. Possible options are:

  • flight
  • carRental
  • hotelReservation
  • bus
  • train
  • transfer
  • cruise
  • event
  • parking
  • ferry

confirmationNumber

string true

Confirmation number of the canceled reservation.

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