AwardWallet Email Parsing API

Introduction

Email Parsing API allows you to extract structured information from an unstructured email. Specifically, you can extract travel itineraries from virtually any travel provider using this REST API. The email parser API can automatically process incoming emails, it will extract data from incoming emails and using webhook integrations send the resulting structured data to your endpoint. The main benefit of this email scraping technology is that you can import travel reservations that belong to your users regardless of how these reservations were booked.

Technically here is what happens under the hood: when an email is received for parsing it gets put into a queue for processing, email workers grab emails out of that queue and send them for parsing. The actual process of parsing consists of applying tens of thousands of regular expressions against a given email until the right parser is found and the required data attributes are extracted from that email. Some of our clients have asked us: "What is the difference between email parsing and email scraping?" and the answer is: there is no difference, email scraping (or parsing), just like web scraping means retrieving structured format from unstructured text, be that a web page or body of an email. There are usually two ways to do that: (1) to run regular expressions against that body of text or (2) run XPath queries if the text body has proper HTML formatting.

With AwardWallet Email Parsing API you can send any travel itinerary or reservation to our endpoint and the parse API will extract the data 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.

  • You could use swagger schema to generate your API clients.

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

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

Request Example

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

Request

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

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

Request Parameters

Parameter Type Required Description

email

string true

Full email source, including MIME headers and MIME body

callbackUrl

string false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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 Example

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

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.

Get Email Parsing Results

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.

Request

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

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

Request Parameters

Parameter Type Required Description
requestId string true

You need to get the requestId from the /parseEmail method

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
}
                            
                        

Response

Parse result

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.

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

number false

Total cost of the reservation including all taxes and fees.

cost

number false

Cost of the reservation before taxes.

discount

number 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

number 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 is a monthly loyalty account statement (meaning it contains loyalty account information such as account balance, account number, elite status, etc.), 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

login

string false

Loyalty account username. If the loginMask attribute is set to center, the masked part will be replaced with **, i.e. 12**34. In any other case only the unmasked part will be returned.

login2

string false

Additional login value. A common example would be a country that the loyalty program supports.

loginMask

string false

This field indicates if the login attribute is masked (for left-hand masking i.e., 1234, the value will be left, for right-hand masking i.e., 1234, the value will be right, for masking the middle part, i.e. 12****34, the value will be 'center')

number

string false

Account number. If the numberMask attribute is set to center, the masked part will be replaced with **, i.e. 12**34. In any other case only the unmasked part will be returned.

numberMask

string false

This field indicates if the number attribute is masked (for left-hand masking i.e., 1234, the value will be left, for right-hand masking i.e., 1234, the value will be right, for masking the middle part, i.e. 12****34, the value will be 'center')

isMember

boolean false

This flag indicates that the email does not have any loyalty account attributes in it; however, it confirms that the user is a member of that loyalty program.

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.

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

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.

Request

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

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

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"
        }
      ]
    }
  ]
}
                            
                        

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.

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

We support scanning mailboxes via 4 different methods:

  • IMAP Protocol
  • Google API
  • Microsoft API
  • Yahoo API
  • Aol 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.

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}

Request 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 Example

                            
{
  "type": "microsoft"
}
                            
                        

Response

Parameter Type Required Description

type

string true

Tells you how this mailbox should be connected. Can be one of the options: imap, google, microsoft, yahoo, aol

Connect via IMAP

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/itinerary-receiver",
  "userData": "Testing the mailbox scanner API",
  "tags": [
    "test",
    "userid_1234"
  ],
  "onProgress": {
    "callbackUrl": "http://company.com/api/email/progress-receiver"
  }
}
                            
                        

Request

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

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

Request Parameters

Parameter Type Required Description

callbackUrl

uri true

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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.

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 true

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

password

string true

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 Example

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

Response

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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 true

The IMAP address of the server where mailbox is hosted.

login

string true

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.

Sample MailboxProgressEvent


{
  "event": "state_change",
  "mailbox": {
    "id": 3474,
    "creationDate": "2018-08-31T21:48:55+0000",
    "startFrom": "2018-07-05",
    "listen": true,
    "callbackUrl": "https://some.example.host/results",
    "returnEmail": "none",
    "onProgress": {
      "callbackUrl": "https://some.example.host/progress"
    },
    "userData": "Testing the connection via the Google API",
    "tags": [
      "test",
      "userid_1234"
    ],
    "state": "connecting",
    "email": "john@gmail.com",
    "type": "google"
  }
}

MailboxProgressEvent

Notification about mailbox scannining progress

Parameter Type Required Description

event

string true

Type of event

mailbox

object true

Mailbox information

Mailbox information

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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.

Example of Callback Data


[
  {
    "type": "state_change",
    "mailbox": {
      "state": "scanning",
      "id": 1234,
      "creationDate": "2018-08-01T10:09:49+0000",
      "startFrom": "2018-07-16",
      "listen": true,
      "tags": [
        "test",
        "userid_1234"
      ],
      "email": "john@gmail.com",
      "type": "google"
    }
  },
  {
    "type": "state_change",
    "mailbox": {
      "state": "listening",
      "id": 1234,
      "creationDate": "2018-04-03T20:09:49+0000",
      "startFrom": "2018-02-10",
      "listen": true,
      "tags": [
        "test",
        "userid_456"
      ],
      "email": "john@gmail.com",
      "type": "google"
    }
  }
]

OnProgress

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

Parameter Type Required Description

callbackUrl

uri true

If the onProgress object is set on a mailbox, you will receive an array of MailboxProgressEvent objects, as shown in the example, every time there is a change to the state attribute.

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks, we expect to receive code 200. If we get anything another than code 200, we will keep re-trying to send you the response. The page itself can be empty as long as we get code 200.

Connect via Google API

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.

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"
  ]
}
                            
                        

Request

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

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

Request Parameters

Parameter Type Required Description

callbackUrl

uri true

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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.

email

string true

The email address of the mailbox

accessToken

string true

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

refreshToken

string true

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

Response Example

                            
{
  "state": "connecting",
  "id": 3474,
  "creationDate": "2018-08-31T21:48:55+0000",
  "startFrom": "2018-07-05",
  "listen": true,
  "userData": "Testing the connection via the Google API",
  "tags": [
    "test",
    "userid_1234"
  ],
  "login": "john@gmail.com",
  "type": "google",
  "callbackUrl": "https://some.example.host/url1"
}
                            
                        

Response

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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 true

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

Connect via Microsoft API

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:

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"
  ]
}
                            
                        

Request

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

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

Request Parameters

Parameter Type Required Description

callbackUrl

uri true

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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.

email

string true

The email address of the mailbox

accessToken

string true

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

refreshToken

string true

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

Response Example

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

Response

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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 true

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

Connect via Yahoo API

This method is used to connect a Yahoo! mailbox. In order to be able to use this method you need to get approved by Verizon Media Mail API (mail-api @ verizonmedia.com) once approved you will be able to create an app under your Yahoo! developer account: https://developer.yahoo.com/apps/ If you wish to use our /mailboxes/start-auth method then you should use the following redirect URI: https://awardwallet.com/mailboxes/callback/oauth/yahoo and for permissions, you need to request Mail - Read and Profiles - Read Public Extended as follows:

Request Example

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

Request

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

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

Request Parameters

Parameter Type Required Description

callbackUrl

uri true

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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.

email

string true

The email address of the mailbox

accessToken

string true

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

refreshToken

string true

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

Response Example

                            
{
  "state": "connecting",
  "id": 3472,
  "creationDate": "2018-08-31T21:48:55+0000",
  "startFrom": "2018-07-05",
  "listen": true,
  "userData": "Testing the connection via the Yahoo API",
  "tags": [
    "test",
    "userid_1234"
  ],
  "login": "john@yahoo.com",
  "type": "yahoo"
}
                            
                        

Response

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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 true

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

Connect via Aol API

This method is used to connect a Aol mailbox. In order to be able to use this method you need to get approved by Verizon Media Mail API (mail-api @ verizonmedia.com) once approved you will be able to create an app under your Yahoo! developer account: https://developer.yahoo.com/apps/ If you wish to use our /mailboxes/start-auth method then you should use the following redirect URI: https://awardwallet.com/mailboxes/callback/oauth/aol and for permissions, you need to request email and `mail-r

Request Example

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

Request

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

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

Request Parameters

Parameter Type Required Description

callbackUrl

uri true

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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.

email

string true

The email address of the mailbox

accessToken

string true

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

refreshToken

string true

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

Response Example

                            
{
  "state": "connecting",
  "id": 3472,
  "creationDate": "2018-08-31T21:48:55+0000",
  "startFrom": "2018-07-05",
  "listen": true,
  "userData": "Testing the connection via the Aol API",
  "tags": [
    "test",
    "userid_1234"
  ],
  "login": "john@aol.com",
  "type": "aol"
}
                            
                        

Response

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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 true

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

Begin Authentication

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

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/"
}
                            
                        

Request

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

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

Request Parameters

Parameter Type Required Description

callbackUrl

uri true

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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.

provider

string true

Mailbox provider, against which you wish to authenticate. Can be one of the values: google, microsoft, yahoo, aol.

redirectUrl

string true

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 will receive the following parameters: state=error&errorCode=someCode&errorMessage=error+message The errorCode and errorMessage attributes are specific to a provider and, in most cases, returned as-is from Google or Microsoft. In case the user did not check the checkbox granting access to their Google mailbox, the error will be custom, as follows: ?state=error&errorCode=missing_mailbox_access&errorMessage=The+user+has+not+granted+the+necessary+read+access+to+this+mailbox It is not recommended to display these values to the end user.

intermediateRedirectUrl

string false

Optional URL, which you would set up on your domain. You need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. Your end user's browser will be redirected to this URL (after the OAuth authorization is complete). You should then redirect the user from this URL to our endpoint https://service.awardwallet.com/email/v2/mailboxes/auth/callback while preserving all of the query string parameters intact. For example, you should redirect https://your-domain.com/google-callback?code=xxx&error=some+message to https://service.awardwallet.com/email/v2/mailboxes/auth/callback?code=xxx&error=some+message

host

string false

Optional host name which you would set up on your end as a CNAME record pointing to service.awardwallet.com. You only need to do this if you wish to hide a redirect to service.awardwallet.com as part of your users' authentication process. You then need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID.

Response Example

                            
"33bdffdcef607e625agpxe3d470b0d9cbc752184"
                            
                        

Response

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.

Update Authentication

This method can be used to update any given mailbox that we already have connected. You need to pass the mailboxId in the URL and the rest of the parameters described below as JSON payload. Please note that there is nothing stopping the user from authenticating a different mailbox. In that case, instead of updating the mailboxId that you provided, we will create a new mailbox connecting for the new email address.

Request Example

                            
{
  "startFrom": "2018-07-16",
  "redirectUrl": "http://mycompany.com/emailscanner/welcome/"
}
                            
                        

Request

POST https://service.awardwallet.com/email/json/v2/mailboxes/{mailboxId}/update-auth

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

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

redirectUrl

string true

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 will receive the following parameters: state=error&errorCode=someCode&errorMessage=error+message The errorCode and errorMessage attributes are specific to a provider and, in most cases, returned as-is from Google or Microsoft. In case the user did not check the checkbox granting access to their Google mailbox, the error will be custom, as follows: ?state=error&errorCode=missing_mailbox_access&errorMessage=The+user+has+not+granted+the+necessary+read+access+to+this+mailbox It is not recommended to display these values to the end user.

intermediateRedirectUrl

string false

Optional URL, which you would set up on your domain. You need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. Your end user's browser will be redirected to this URL (after the OAuth authorization is complete). You should then redirect the user from this URL to our endpoint https://service.awardwallet.com/email/v2/mailboxes/auth/callback while preserving all of the query string parameters intact. For example, you should redirect https://your-domain.com/google-callback?code=xxx&error=some+message to https://service.awardwallet.com/email/v2/mailboxes/auth/callback?code=xxx&error=some+message

host

string false

Optional host name which you would set up on your end as a CNAME record pointing to service.awardwallet.com. You only need to do this if you wish to hide a redirect to service.awardwallet.com as part of your users' authentication process. You then need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID.

Response Example

                            
"33bdffdcef607e625agpxe3d470b0d9cbc752184"
                            
                        

Response

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 Google, Microsoft, or Yahoo 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.

Request

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

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

Request Parameters

Parameter Type Required Description

code

string true

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

Get Mailbox Info

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

Request

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

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

Request 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 Example

                            
{
  "id": 3474,
  "creationDate": "2018-08-31T21:48:55+0000",
  "startFrom": "2018-07-05",
  "listen": true,
  "callbackUrl": "https://some.example.host/results",
  "returnEmail": "none",
  "onProgress": {
    "callbackUrl": "https://some.example.host/progress"
  },
  "userData": "Testing the connection via the Google API",
  "tags": [
    "test",
    "userid_1234"
  ],
  "state": "connecting",
  "email": "john@gmail.com",
  "type": "google"
}
                            
                        

Response

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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.

Update Mailbox Info

This method allows you to update the settings of any given mailbox. You can use it to update mailbox tags for example or if you need to re-authenticate a mailbox you can use this call to provide us with a new access and refresh tokens. Please note that the mailboxId is passed as a GET parameter while the request object is passed as JSON in the payload.

Request Example

                            
{
  "userData": "some new user data",
  "tags": [
    "test2",
    "userid_1236"
  ],
  "onProgress": {
    "callbackUrl": "https://some.example.host/new-progress-url"
  },
  "access_token": "xxx",
  "referesh_token": "yyy",
  "returnEmail": "none"
}
                            
                        

Request

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

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

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

request

object true

You need to pass this object as JSON in the payload body. It can be one of the two structures already defined in this documentation:

Response Example

                            
{
  "state": "listening",
  "id": 1234,
  "creationDate": "2018-08-03T20:09:49+0000",
  "startFrom": "2018-07-16",
  "listen": true,
  "userData": "some new user data",
  "tags": [
    "test2",
    "userid_1236"
  ],
  "email": "john@gmail.com",
  "type": "google",
  "callbackUrl": "https://some.example.host/url1"
}
                            
                        

Response

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

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 values: imap, google, microsoft, yahoo, aol.

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.

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.

Update IMAP Mailbox Request

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

Update OAuth (google, microsoft, yahoo) Mailbox Request

Parameter Type Required Description

callbackUrl

uri false

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

returnEmail

string false

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

onProgress

object false

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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_]).

accessToken

string false

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

List Mailboxes

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. Response count will be limited to 500 records. Use scroll method to fetch larger datasets

Request

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

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

Request Parameters

Parameter Type Required Description

tags

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. Filter the results using mailbox tags. You can separate different tags with a comma.

states

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the Mailbox state attribute for the list of possible states.

types

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox type attribute for the list of possible types.

errorCodes

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox errorCode attribute for the list of possible error codes.

emails

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. You can specify more than 1 email address (comma separated) such as &emails=John@email.com,Jen@email.com and we will return all the connected mailboxes with this email address as the login value. If a mailbox was connected via IMAP then the login value could be different from the email address; in that case, you would need to specify the login value instead, but this is not common.

Response Example

                            
[
  {
    "state": "listening",
    "id": 1234,
    "creationDate": "2018-08-03T20:09:49+0000",
    "startFrom": "2018-07-16",
    "listen": true,
    "userData": "Testing the connection via the Google API",
    "tags": [
      "test",
      "userid_1234"
    ],
    "email": "john@gmail.com",
    "type": "google",
    "callbackUrl": "https://some.example.host/url1"
  },
  {
    "state": "listening",
    "id": 1235,
    "creationDate": "2018-08-30T15:54:27+0000",
    "startFrom": "2018-07-16",
    "listen": true,
    "userData": "Testing the connection via the Microsoft API",
    "tags": [
      "test",
      "userid_1234"
    ],
    "email": "john@hotmail.com",
    "type": "microsoft",
    "callbackUrl": "https://some.example.host/url2"
  }
]
                            
                        

Response

Parameter Type Required Description

items

array false

An array of Mailbox objects.

List Mailboxes with Pagination

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/scroll/?tags=tag1,tag2

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

If you have many connected mailboxes (hundreds or thousands), you should be using this method to list them. On your first call, you would request this method without the pageToken attribute, but on the consequent requests, to fetch the next page, you need to pass the nextPageToken from the response body of your previous request. When you stop receiving the nextPageToken, it means that there are no more records to fetch.

Request

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

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

Request Parameters

Parameter Type Required Description

tags

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. Filter the results using mailbox tags. You can separate different tags with a comma.

states

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the Mailbox state attribute for the list of possible states.

types

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox type attribute for the list of possible types.

errorCodes

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox errorCode attribute for the list of possible error codes.

emails

array true

This parameter is passed as a GET parameter in the URL string, not as JSON payload. You can specify more than 1 email address (comma separated) such as &emails=John@email.com,Jen@email.com and we will return all the connected mailboxes with this email address as the login value. If a mailbox was connected via IMAP then the login value could be different from the email address; in that case, you would need to specify the login value instead, but this is not common.

pageToken

string true

The value that you got in the nextPageToken attribute from the previous request.

Response Example

                            
{
  "items": [
    {
      "state": "listening",
      "id": 1234,
      "creationDate": "2018-08-03T20:09:49+0000",
      "startFrom": "2018-07-16",
      "listen": true,
      "userData": "Testing the connection via the Google API",
      "tags": [
        "test",
        "userid_1234"
      ],
      "email": "john@gmail.com",
      "type": "google",
      "callbackUrl": "https://some.example.host/url1"
    },
    {
      "state": "listening",
      "id": 1235,
      "creationDate": "2018-08-30T15:54:27+0000",
      "startFrom": "2018-07-16",
      "listen": true,
      "userData": "Testing the connection via the Microsoft API",
      "tags": [
        "test",
        "userid_1234"
      ],
      "email": "john@hotmail.com",
      "type": "microsoft",
      "callbackUrl": "https://some.example.host/url2"
    }
  ],
  "nextPageToken": "abc"
}
                            
                        

Response

Parameter Type Required Description

items

array false

An array of Mailbox objects.

nextPageToken

string false

Please pass this value to the next pageToken parameter of the subsequent request to fetch the next page.

Disconnect Mailbox

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

Request

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

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

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

revoke boolean false

Revoke tokens for oauth mailboxes, default false

Response Example

                            
"successfully deleted"
                            
                        

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "Transfer shuttle will be located at the terminal exit",
      "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",
              "countryCode": "US",
              "postalCode": "90045",
              "lat": 33.9415889,
              "lng": -118.40853,
              "timezone": -25200,
              "timezoneId": "America/Los_Angeles"
            }
          },
          "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",
              "countryCode": "US",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200,
              "timezoneId": "America/Los_Angeles"
            }
          },
          "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,
            "registrationNumber": "N345DL"
          },
          "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",
              "countryCode": "US",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200,
              "timezoneId": "America/Los_Angeles"
            }
          },
          "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",
              "countryCode": "US",
              "postalCode": "90045",
              "lat": 33.9415889,
              "lng": -118.40853,
              "timezone": -25200,
              "timezoneId": "America/Los_Angeles"
            }
          },
          "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,
            "registrationNumber": "N345DL"
          },
          "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

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

type

string true

Type of reservation. Value: flight

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

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, as we gathered it from the provider's website.

calculatedTraveledMiles

integer false

Estimated number of miles traveled on this flight segment, calculated based on the destination and arrival airports

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.

calculatedDuration

integer false

Flight duration in minutes, calculated based on the departure and arrival times

status

string false

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

cancelled

boolean false

Will be set to “true” if this flight was canceled

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

registrationNumber

string false

Registration number of the 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 true

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 either Google API or another authoritative source.

city

string false

Name of the city validated either by Google API or another authoritative source

stateName

string false

Name of the state validated either by Google API or another authoritative source

countryName

string false

Name of the country validated either by Google API or another authoritative source

countryCode

string false

2 letter country code validated either by Google API or another authoritative source

postalCode

string false

Zip / postal code validated either by Google API or another authoritative source

lat

number false

Latitude coordinate of the address

lng

number false

Longitude coordinate of the address

timezone

integer false

Time zone in which this address is located.

timezoneId

string false

Name of the time zone

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

type

string false

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

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

Car Rental

Rental car reservation

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"
      },
      "cancelled": false,
      "cancellationPolicy": "$50 penalty if cancelled",
      "notes": "Make a note of any damages before leaving the pickup area",
      "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",
          "countryCode": "US",
          "postalCode": "33415",
          "lat": 26.6857475,
          "lng": -80.0928165,
          "timezone": -14400,
          "timezoneId": "America/New_York"
        },
        "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",
          "countryCode": "US",
          "postalCode": "33415",
          "lat": 26.6857475,
          "lng": -80.0928165,
          "timezone": -14400,
          "timezoneId": "America/New_York"
        },
        "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"
    }
  ]
}
                            
                        
Parameter Type Required Description

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

type

string true

Type of reservation. Value: carRental

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

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Cancellation is free 24 hours prior to check-in",
      "cancellationDeadline": "2029-12-31T13:30:00",
      "isNonRefundable": null,
      "notes": "Use the secondary entrance if you're carrying large luggage",
      "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",
        "countryCode": "US",
        "postalCode": "19103",
        "lat": 39.9569828,
        "lng": -75.1674669,
        "timezone": -14400,
        "timezoneId": "America/New_York"
      },
      "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"
    }
  ]
}
                            
                        
Parameter Type Required Description

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

cancellationNumber

string false

Cancellation number if the reservation has been cancelled

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.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

type

string true

Type of reservation. Value: hotelReservation

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.

freeNights

integer false

Number of free nights obtained via a certificate or a promo

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

Bus ride

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "Keep your ticket at your person at all times",
      "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",
              "countryCode": "US",
              "postalCode": "02111",
              "lat": 42.3504505,
              "lng": -71.0561242,
              "timezone": -14400,
              "timezoneId": "America/New_York"
            }
          },
          "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,
              "countryCode": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null,
              "timezoneId": 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"
    }
  ]
}
                            
                        
Parameter Type Required Description

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

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

type

string true

Type of reservation. Value: bus

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

boolean 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

Train ride

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "Taxi will be waiting for you in the parking area",
      "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",
              "countryCode": "US",
              "postalCode": "02111",
              "lat": 42.3504505,
              "lng": -71.0561242,
              "timezone": -14400,
              "timezoneId": "America/New_York"
            }
          },
          "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,
              "countryCode": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null,
              "timezoneId": 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"
    }
  ]
}
                            
                        
Parameter Type Required Description

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

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

type

string true

Type of reservation. Value: train

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

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

ticketLinks

array false

Array of links to train tickets or boarding passes for this segment

Parameter Type Required Description

link

string false

Link to a downloadable ticket, which is usually a PDF file with a QR code

name

string false

Name of the ticket owner

Transfer

Car or shuttle bus ride

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "You may be asked to provide an ID",
      "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",
              "countryCode": "US",
              "postalCode": null,
              "lat": 37.615215,
              "lng": -122.389881,
              "timezone": -25200,
              "timezoneId": "America/Los_Angeles"
            }
          },
          "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",
              "countryCode": "US",
              "postalCode": "94080",
              "lat": 37.6569251,
              "lng": -122.4143844,
              "timezone": -25200,
              "timezoneId": "America/Los_Angeles"
            }
          },
          "vehicleInfo": {
            "type": "Regular",
            "model": "Ford Focus",
            "imageUrl": "http://car.image/url"
          },
          "adults": 1,
          "kids": 0,
          "traveledMiles": "4.3mi",
          "duration": "7h"
        }
      ],
      "type": "transfer"
    }
  ]
}
                            
                        
Parameter Type Required Description

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

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

type

string true

Type of reservation. Value: transfer

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "Do not forget to check in with the receptionist at the main deck",
      "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,
              "countryCode": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null,
              "timezoneId": null
            }
          },
          "arrival": {
            "stationCode": null,
            "name": "NASSAU",
            "localDateTime": "2030-01-02T08:00:00",
            "address": {
              "text": "NASSAU",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "countryCode": null,
              "postalCode": null,
              "lat": 25.0479835,
              "lng": -77.355413,
              "timezone": -14400,
              "timezoneId": "America/Nassau"
            }
          }
        },
        {
          "departure": {
            "stationCode": null,
            "name": "NASSAU",
            "localDateTime": "2030-01-02T12:00:00",
            "address": {
              "text": "NASSAU",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "countryCode": null,
              "postalCode": null,
              "lat": 25.0479835,
              "lng": -77.355413,
              "timezone": -14400,
              "timezoneId": "America/Nassau"
            }
          },
          "arrival": {
            "stationCode": null,
            "name": "PORT CANAVERAL",
            "localDateTime": "2030-01-03T14:00:00",
            "address": {
              "text": "PORT CANAVERAL",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "countryCode": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null,
              "timezoneId": null
            }
          }
        }
      ],
      "cruiseDetails": {
        "description": "Long cruise",
        "class": "Regular",
        "deck": "3",
        "room": "342",
        "ship": "Disney Dream",
        "shipCode": "SHCD",
        "voyageNumber": "K229"
      },
      "type": "cruise"
    }
  ]
}
                            
                        
Parameter Type Required Description

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

type

string true

Type of reservation. Value: cruise

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "Receipt will be available in your mobile application",
      "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",
        "countryCode": "US",
        "postalCode": "10019",
        "lat": 40.7653771,
        "lng": -73.9779742,
        "timezone": -14400,
        "timezoneId": "America/New_York"
      },
      "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

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

type

string true

Type of reservation. Value: event

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

Parking spot reservations (usually for airport long-term 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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "Look at the overhead signs for directions to the desired spot",
      "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",
        "countryCode": "US",
        "postalCode": "10019",
        "lat": 40.7653771,
        "lng": -73.9779742,
        "timezone": -14400,
        "timezoneId": "America/New_York"
      },
      "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"
    }
  ]
}
                            
                        
Parameter Type Required Description

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

type

string true

Type of reservation. Value: parking

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"
      },
      "cancelled": false,
      "cancellationPolicy": "Ticket is non-refundable",
      "notes": "Access to your vehicle will be restricted during the trip",
      "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",
              "countryCode": "NO",
              "postalCode": "0102",
              "lat": 59.904139,
              "lng": 10.738278,
              "timezone": null,
              "timezoneId": 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",
              "countryCode": "DE",
              "postalCode": null,
              "lat": 54.316333,
              "lng": 10.138806,
              "timezone": null,
              "timezoneId": 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",
          "cabin": "economy",
          "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

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.

cancelled

boolean false

Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

notes

string false

This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions.

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

type

string true

Type of reservation. Value: ferry

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.

cabin

string false

Cabin class, i.e. “Economy”

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

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