AwardWallet Web Parsing API

Introduction

AwardWallet Web Parsing API supports retrieval of the following information from online loyalty accounts:

  • Loyalty information (e.g. account balance, expiration, elite level, etc.)
  • Travel itineraries listed under user’s profile
  • Account activity history

This is a restful API and is designed to work asynchronously.

Authentication

To authorize, use this code:

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

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

X-Authentication: YourUserName:YourPassword

Providers

List providers

Response Example

                            
[
  {
    "code": "aa",
    "displayName": "American Airlines (AAdvantage)",
    "kind": 1
  },
  {
    "code": "hhonors",
    "displayName": "Hilton (HHonors)",
    "kind": 2
  }
]
                            
                        

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

HTTP Request

GET https://loyalty.awardwallet.com/v2/providers/list

Response

Parameter Type Required Description

code

string true

Alpha-numeric value with no spaces that uniquely identifies any given provider. This code can be used to query all the details of that provider as follows: /providers/{code}

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. American Airlines (AAdvantage).

kind

integer true

Type of the provider. The possible values are:

1 - Airline

2 - Hotel

3 - Car rental

4 - Train

5 - Other

6 - Credit card

7 - Shopping

8 - Dining

9 - Survey

10 - Cruise

Supported providers information

Provider info

Response Example

                            
{
  "kind": 2,
  "code": "marriott",
  "displayName": "Marriott Rewards",
  "providerName": "Marriott",
  "programName": "Marriott Rewards, Ritz-Carlton",
  "login": {
    "code": "Login",
    "title": "Email or Rewards No.",
    "options": [
      
    ],
    "required": true,
    "defaultValue": ""
  },
  "login2": {
    "code": "Login2",
    "title": "Hotel",
    "options": [
      {
        "code": "",
        "name": "Select your hotel",
        "kind": "0"
      },
      {
        "code": "marriott",
        "name": "Marriott",
        "kind": "0"
      },
      {
        "code": "ritz",
        "name": "Ritz-Carlton",
        "kind": "0"
      }
    ],
    "required": true,
    "defaultValue": ""
  },
  "login3": {
    "code": "Login3",
    "options": [
      
    ],
    "required": false,
    "defaultValue": ""
  },
  "password": {
    "code": "Password",
    "options": [
      
    ],
    "required": true,
    "defaultValue": ""
  },
  "properties": [
    {
      "code": "Name",
      "name": "Name",
      "kind": "12"
    },
    {
      "code": "Number",
      "name": "Rewards #",
      "kind": "1"
    },
    {
      "code": "Level",
      "name": "Membership Level",
      "kind": "3"
    },
    {
      "code": "Nights",
      "name": "Nights this year",
      "kind": "8"
    },
    {
      "code": "LastActivity",
      "name": "Last qualifying activity",
      "kind": "13"
    },
    {
      "code": "YearBegins",
      "name": "Beginning of the Year",
      "kind": "0"
    },
    {
      "code": "PointsValue",
      "name": "Points Value",
      "kind": "0"
    },
    {
      "code": "ExpirationDate",
      "name": "Expiration Date",
      "kind": "2"
    }
  ],
  "autoLogin": true,
  "deepLinking": true,
  "canCheckConfirmation": true,
  "canCheckItinerary": true,
  "canCheckPastItinerary": false,
  "canCheckExpiration": 1,
  "confirmationNumberFields": [
    {
      "code": "RecordLocator",
      "title": "Confirmation #",
      "required": true,
      "defaultValue": ""
    },
    {
      "code": "FirstName",
      "title": "First Name",
      "required": true,
      "defaultValue": ""
    },
    {
      "code": "LastName",
      "title": "Last Name",
      "required": true,
      "defaultValue": ""
    },
    {
      "code": "CheckInDate",
      "title": "Check In Date",
      "required": true,
      "defaultValue": ""
    }
  ],
  "historyColumns": [
    {
      "kind": "Info",
      "name": "Type",
      "type": "string"
    },
    {
      "kind": "PostingDate",
      "name": "Date Posted",
      "type": "date"
    },
    {
      "kind": "Description",
      "name": "Description",
      "type": "string"
    },
    {
      "kind": "Miles",
      "name": "Points earned",
      "type": "decimal"
    },
    {
      "kind": "Info",
      "name": "Actions",
      "type": "string"
    },
    {
      "kind": "Bonus",
      "name": "Bonus points earned",
      "type": "decimal"
    }
  ],
  "eliteLevelsCount": 4,
  "canParseHistory": true,
  "canParseFiles": false
}
                            
                        

This method gives you all the details that you need to know about a given provider. For instance, this method will tell you what information you need to request from your users in order to update a given account and it also tells you what to expect in return once that account is updated. It tells you what features are supported for a given provider, such as if we support retrieving account history or travel reservations from that provider.

HTTP Request

GET https://loyalty.awardwallet.com/v2/providers/{code}

Query Parameters

Parameter Type Required Description
code string true

Alpha-numeric value with no spaces that uniquely identifies any given provider. Can be retrieved from the /providers/list method.

Response

Parameter Type Required Description

kind

integer false

Type of the provider. The possible values are:

1 - Airline

2 - Hotel

3 - Car rental

4 - Train

5 - Other

6 - Credit card

7 - Shopping

8 - Dining

9 - Survey

10 - Cruise

code

string false

Alpha-numeric value with no spaces that uniquely identifies any given provider.

displayName

string false

User friendly display name of the provider. Typically includes both the company name and the name of the loyalty program, i.e. American Airlines (AAdvantage).

providerName

string false

Provider company name, i.e. "American Airlines".

programName

string false

Loyalty program name, i.e. "AAdvantage".

login

object false

An array describing the login field of that provider. You can use this data to build your UI. For example, login.title gives you the caption that you need to provide in your interface.

login2

object false

An array describing the login2 field of that provider (whenever applicable). A common example would be a drop down list of countries that we support. For example, for BestBuy we may support the USA and the Canada regions (completely different websites). login2 would describe that.

login3

object false

Similar in concept to login2, needed when an extra piece of input data is required from the user.

password

object false

The password field caption you can use in your interface, i.e. Password, PIN, etc.

properties

array false

The array of account properties (secondary attributes) that we may gather from the account on top of the account balance.

autoLogin

boolean false

Tells you if our server-side auto login is supported for this provider. Unfortunately, you can’t rely on this attribute 100% as first of all it may change without us detecting it and second it may work in some browsers but not in others.

deepLinking

boolean false

Deep linking is an auto-login to a specific URL on the provider’s website. Similarly, to the autoLogin attribute it is not very reliable for the same reasons.

canCheckConfirmation

boolean false

Tells you if we are able to retrieve travel itineraries from this provider using a confirmation number

canCheckItinerary

boolean false

Tells you if we support retrieving travel reservations from this provider.

canCheckPastItinerary

boolean false

Tells you if a provider is capable of retrieving past reservations from the online account.

canCheckExpiration

integer false

Tells you if we support retrieving the expiration dates for accounts that belong to this provider. Possible values are:

0 - No

1 - Yes

2 - Balance never expires

confirmationNumberFields

array false

Array of fields that are required to retrieve itineraries by confirmation number

historyColumns

array false

Array of columns that you can expect in return for account history. Empty, if provider does not support history parsing.

eliteLevelsCount

integer false

The total number of elite statuses this provider has. Can be used in calculating elite status progress to the highest level.

canParseHistory

boolean false

Tells you if we support retrieving historical account transactions for accounts belonging to this provider.

canParseFiles

boolean false

Tells you if we support retrieving account statements in a pdf (or similar) format.

Supported provider definition

HistoryColumn

Parameter Type Required Description

type

string false

Each history column will have a type that is one of the following data types:

string

date

integer

decimal

kind

string false

Each history column will have a kind which tells you what kind of data it represents. Different providers have different history columns, here are the most common history column kinds:

PostingDate - the date when the transaction posted into the account

Description - Description of the transaction as it shows up on the provider's website.

Category - Only applicable to credit card transactions. It tells you the category of the merchant as it shows up on the bank's website.

Amount - Only applicable to credit card transactions. It tells you the amount that was spent as part of that transaction.

Miles - Tells you how many miles were earned or spent in this transaction.

Currency - - Only applicable to credit card transactions. It tells you the currency of the transaction.

Bonus - If a given transaction had a bonus, this field will show the number of bonus miles.

Info - Sometimes historical transactions have fields that don't fit into any of the kinds listed above, in that case, they will be returned as info

name

string false

Name of the column such as “Posting Date” or "Description" exactly as it shows up on the provider's website. You can show this value as a column name to your users.

Input

Parameter Type Required Description

code

string false

Field code is used by developers to identify the type of this field, i.e. “Login”

title

string false

Field title is a user-friendly name of the field that you can show as a caption in your UI.

options

array false

If there is a limited set of values that can go into this field, those options would be listed in this array. Use this array to create a drop down list in your UI.

required

boolean false

Even if the options array gives you an empty string as an option, if this field is set to true don’t accept an empty value from the user.

defaultValue

string false

The default value that we expect for this field.

PropertyInfo

Parameter Type Required Description

code

string false

Property code name – unique within a single provider. Can only have English numbers and letters with no spaces.

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

2 - Expiration

3 - Elite Status

4 - Lifetime points

5 - Member since

6 - Expiring balance (in some cases only a portion of the entire balance may expire)

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

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

9 - Next elite level

10 - Points / miles needed to get to the next elite level

11 - Flights / nights needed to get to the next elite level.

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

13 - Date of the last account activity.

14 - Points / miles needed to get the next reward

15 - Elite level expiration date

16 - Points / miles needed to retain the current elite level

17 - Segments / flights needed to retain the current elite level

Autologin

Autologin method

POST Request Example

                            
{
  "provider": "czech",
  "login": "12345678",
  "password": "password",
  "userId": "1",
  "userData": "blah",
  "targetUrl": "https://okplus.csa.cz/en/okp_my_profilee.htm",
  "supportedProtocols": [
    "http",
    "https"
  ]
}
                            
                        

Response Example

                            
{
  "response": "<!DOCTYPE html PUBLIC....",
  "userData": "blah"
}
                            
                        

Unfortunately, the auto-login method is not very reliable, many modern websites won’t allow users to login in this manner. Also, in some rare scenarios, the auto-login method may work for some browsers but not work for others. You can tell which providers support the auto-login method using the /providers/{code} method ("autoLogin" should be set to “true”)

HTTP Request

POST https://loyalty.awardwallet.com/v2/autologin

Query Parameters

Parameter Type Required Description

provider

string true

Alpha-numeric value with no spaces that uniquely identifies any given provider. Can be retrieved from the /providers/list method.

login

string true

User's login value to be used to login to the provider's website

login2

string false

Second login value. A common example would be a drop down list of countries that we support. For example, for BestBuy we may support the USA and the Canada regions (completely different websites). List of supported values can be retrieved from the /providers/list method.

login3

string false

Similar in concept to login2, needed when an extra piece of input data is required from the user.

password

string false

User's password value to be used to login to the provider's website

userId

string true

UserID that uniquely identifies the user in your system. Required for billing / accounting purposes.

userData

string false

Any data you wish to send. It will be returned untouched in the response. Could be used for matching requests to responses.

targetUrl

string false

This parameter allows you to do so called “deep linking”, in other words after we perform the auto-login we will navigate the logged in user to the URL that you specify in this attribute.

startUrl

string false

This attribute allows you to first navigate the user to some page (typically some type of an affiliate link) and then proceed to the targetURL or whatever the default page that users sees after they login.

supportedProtocols

array true

When we load the auto-login page we need to know which protocols your website supports, do you support http only or https only or both? Ideally your domain supports both protocols, and we will always try to use https whenever possible.

Response

Parameter Type Required Description

response

string false

The response attribute will contain an entire html page that you need to embed into a hidden iframe on your website. Once loaded, it will open up the provider’s website where the user will be logged in. As the page is getting loaded we recommend you to show some sort of “Please wait” message to the end user. All of this is designed so that the user will not know that AwardWallet is performing the auto-login for them.

userData

string false

This field returns whatever data you put in it when you made your request as is. Can be used for some sort of tracking.

AutoLogin results

Loyalty Accounts

Update one account

POST Request Example

                            
{
  "provider": "spg",
  "login": "JSMith",
  "login2": "USA",
  "password": "password",
  "userId": "123",
  "userData": "blah",
  "browserState": "v1:YZFsNRWtg7...",
  "priority": 9,
  "timeout": 300,
  "callbackUrl": "http://hostname/callback",
  "retries": 2,
  "parseItineraries": true,
  "answers": [
    {
      "question": "What is your verbal password?",
      "answer": "verbalpassword"
    }
  ],
  "history": {
    "range": "incremental",
    "state": "q0CoctQQ5yqbsEJFs2C+W9pUcRnyvBk/8xraBg=="
  }
}
                            
                        

Response Example

                            
{
  "requestId": "580d54da7s34d8ee39e29584"
}
                            
                        

This method allows you to place a single loyalty account into a queue for data to be retrieved.

HTTP Request

POST https://loyalty.awardwallet.com/v2/account/check

Query Parameters

Parameter Type Required Description

provider

string false

Alpha-numeric value with no spaces that uniquely identifies any given provider. Can be retrieved from the /providers/list method.

userId

string true

UserID that uniquely identifies the user in your system. Required for billing / accounting purposes.

userData

string false

Any data you wish to send. It will be returned untouched in the response. Could be used for matching requests to responses.

priority

integer true

Request priority values range from 1 to 9, where 1 is the lowest priority and 9 is the highest priority. In some cases, we throttle requests with priorities lower than X (default is 9). Please use this attribute to separate background account updates from the foreground account updates. In other words, background updating could have priority of 1 and accounts that are updated when an actual user is actually waiting for the results with priority of 9. This way your background updating will never negatively affect your updates when someone is actually waiting for the results.

callbackUrl

string false

All callback URLs must be registered with us prior to 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 when sending callbacks to that URL.

retries

integer false

Defines how many times we will retry account updating in case of an unknown error. If the user provided us with invalid credentials and we detect that, we will not keep retrying as that may lock out the user. Possible values are 0 to 4. The default is 4.

timeout

integer false

Time in seconds which determines how long the account is allowed to sit in the queue. If that time passes and we have not retrieved the account details we will throw a "timeout" error. This way, if someone is waiting for an account update (staring at their device) and if it takes too long we will remove that account from the queue and will give a meaningful error (thus freeing up our resources) to update other accounts.

login

string true

User's login value to be used to login to the provider's website

login2

string false

Second login value. A common example would be a drop down list of countries that we support. For example, for BestBuy we may support the USA and the Canada regions (completely different websites).

login3

string false

Similar in concept to login2, needed when an extra piece of input data is required from the user.

password

string false

User's password value to be used to login to the provider's website

answers

array false

Array with security questions and answers.

browserState

string false

When you update accounts that have security questions for the first time you will get a browserState attribute back from us. Please store it on your end and send it with your next account update so that the user doesn’t get prompted for security questions again.

parseItineraries

boolean false

Tells us if you also wish to retrieve itineraries from the loyalty account. It takes time (and therefore resources) to retrieve itineraries so please set this parameter to false if you don’t need to pull reservations during account updating.

parsePastItineraries

boolean false

Set to true if you wish us to also retrieve past itineraries from this account.

history

object false

Object that defines if (and what) history should be gathered from the account.

Response

Parameter Type Required Description

requestId

string true

An ID that uniquely identifies this request. You can use this value to get the results of this update request using the /account/check/{id} method

Loyalty program information and itineraries

RequestItemHistory

History items are the individual transactions (Account Activity) that show up on a loyalty account. It takes time to gather this information, please don’t request it unless you really need it.

Parameter Type Required Description

range

string false

There are two possible values that can be sent in this attribute:

complete - this means that you want AwardWallet to return a complete history of all transactions on for this account. In this scenario, you don’t need to send the state attribute to us. Also, please note that updating will take more time this way.

incremental - this means you already have the account transactions history on your end and you are only interested in receiving the additional (incremental) transactions that happened since the last time you updated this account.

state

string false

This attribute is only applicable if you set the range attribute to incremental. For this attribute, you need to send us the same state string value that we sent to you in the previous account update response.

Answer

Some programs require users to answer security questions to get into their loyalty accounts. In those cases, you will receive a response from the /account/check method that will have a question string. You need to get the answer from the user and send it to us along with the question. Each account may have multiple questions and answers. Please store all of them on your end and send them with each account update request.

Parameter Type Required Description

question

string true

Security question that is unique to that specific account

answer

string true

Security answer that is unique to that specific account which corresponds to the security question.

Update multiple accounts

POST Request Example

                            
{
  "package": [
    {
      "provider": "marriott",
      "login": "9988776655",
      "login2": "marriott",
      "password": "password1234",
      "userId": "1",
      "priority": 9
    },
    {
      "provider": "spg",
      "login": "JSmith",
      "login2": "USA",
      "password": "password1234",
      "userId": "123",
      "userData": "blah",
      "priority": 9,
      "retries": 4
    }
  ]
}
                            
                        

Response Example

                            
{
  "package": [
    {
      "requestId": "58e7ea288296d8d296d53d5ac"
    },
    {
      "requestId": "5296d8d296d53d5829d53d5ad"
    }
  ]
}
                            
                        

This method allows you to group account requests into a package (array) and send them with a single request. So if you need to update 300 accounts instead of making 300 requests you can make one request that has all 300 accounts. Here is what a sample request would look like:

HTTP Request

POST https://loyalty.awardwallet.com/v2/account/check/package

Query Parameters

Parameter Type Required Description

package

array false

An array of accounts to be updated by the service. The individual accounts in this array need to be defined the same way you would define a single account.

Response

Parameter Type Required Description

package

array false

In response you will get an array of request ids in the same order in which you sent the accounts in the request object. You can use these request ids to get the results of the account updates using the /account/check/{id} method in case if you are not using callback URLs.

Loyalty program information and itineraries

Get account results

Response Example

                            
{
  "requestId": "57d6884c312adced79a213c8",
  "debugInfo": "",
  "state": 1,
  "message": "",
  "errorReason": "",
  "checkDate": "2016-09-12T16:50:59+00:00",
  "requestDate": "2016-09-12T16:50:53+00:00",
  "login": "995883915",
  "login2": "marriott",
  "balance": 22816,
  "expirationDate": "2018-01-13",
  "properties": [
    {
      "code": "Name",
      "name": "Name",
      "kind": "12",
      "value": "John Smith"
    },
    {
      "code": "Number",
      "name": "Rewards #",
      "kind": "1",
      "value": "1122334455"
    },
    {
      "code": "Level",
      "name": "Membership Level",
      "kind": "3",
      "value": "Member"
    },
    {
      "code": "Nights",
      "name": "Nights this year",
      "kind": "8",
      "value": "8"
    },
    {
      "code": "LastActivity",
      "name": "Last qualifying activity",
      "kind": "13",
      "value": "01/13/16"
    },
    {
      "code": "YearBegins",
      "name": "Beginning of the Year",
      "value": "1451606400"
    }
  ],
  "history": {
    "range": "complete",
    "state": "q0CCioctQQ5yqbsEkIWfe3vCzoFV6lw==",
    "rows": [
      {
        "fields": [
          {
            "name": "Post Date",
            "value": "1445904000"
          },
          {
            "name": "Type",
            "value": "Stay"
          },
          {
            "name": "Points earned",
            "value": "+8,508"
          },
          {
            "name": "Description",
            "value": "Nashville Airport Marriott 09/13/15 - 09/18/15"
          }
        ]
      }
    ],
    "subAccounts": [
      {
        "code": "SubAcc1",
        "rows": [
          {
            "fields": [
              {
                "name": "Post Date",
                "value": "1445904000"
              },
              {
                "name": "Type",
                "value": "Bonus"
              },
              {
                "name": "Points earned",
                "value": "+2,500"
              },
              {
                "name": "Description",
                "value": "POINTS PURCHASE - 2015"
              }
            ]
          }
        ]
      }
    ]
  }
}
                            
                        

This method allows you to pull the results of the account information retrieval from AwardWallet. Typically, AwardWallet will have this data cached for up to two hours after you send your request.

HTTP Request

GET https://loyalty.awardwallet.com/v2/account/check/{id}

Query Parameters

Parameter Type Required Description
id string true

requestId that you got from the /account/check or the /account/check/package methods.

Response

Parameter Type Required Description

requestId

string false

An ID that uniquely identifies this request.

userData

string false

This field returns whatever data you put in it when you made your request as is. Can be used for some sort of tracking.

provider

string false

Alpha-numeric value with no spaces that uniquely identifies any given provider, i.e. "marriott"

message

string false

Human readable error message. You can show this message to your users.

errorReason

string false

Technical error reason. Something like "AwardWallet sign-in attempt was blocked by the provider" or "We could not recognize captcha". Do not show this message to the end user.

checkDate

date-time false

Date and time when this account information was retrieved from the provider’s website.

requestDate

date-time false

Date and time of when the request was sent to us, i.e. when the account was put into our queue for updating.

login

string true

User's login value that was used to login to the provider's website

login2

string false

Second login value such as a geographical region. Empty in most cases.

login3

string false

Third login value. Empty in most cases.

state

integer true

0 – The account data has not yet been retrieved from the provider’s website. Please repeat your request again later to get the results.

1 - Account information has been successfully retrieved.

2 - Error. The provider did not accept the credentials for this account.

3 - Error. The provider has locked this account out due to multiple invalid login attempts.

4 - Error. The provider has returned some error or requires some additional user action, such as to update personal information.

5 - This provider has been disabled on AwardWallet.

6 - An Unknown Error occurred, something unexpected happened and AwardWallet failed to retrieve the data.

9 - Account information was successfully retrieved; however, there was some type of a warning. The warning message is returned in the message field.

10 - The end user needs to answer a security question in order for this account information to be retrieved. The actual question is returned in the question field.

11 - Retrieving this account took too much time. The request timed out.

question

string false

Security question to be shown to the end user to get the answer.

balance

number true

Account balance. In some cases, you may get a null value which means that this account doesn’t have a main account balance. The most common scenario for this is when there are multiple sub accounts under this account, each having its own balance.

expirationDate

date false

Account balance expiration date

properties

array false

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

eliteLevel

integer false

The elite level of this account in the loyalty program.

noItineraries

boolean false

Sometimes our service may return zero itineraries even though there are itineraries on the account. This could happen if the prover’s website changed and our parsers are not aware of it. This doesn’t mean you should delete all user itineraries on your end. However, if we are able to detect with very high probability that there are indeed no itineraries on the account (i.e. it is explicitly stated on the website: “No future reservations”) we will set this parameter to true. Meaning that we are certain there are no future reservations for this account.

neverExpires

boolean false

The loyalty balance on this account never expires.

subAccounts

array false

Array of subaccounts

detectedCards

array false

Designed for credit card accounts. This array will list all the credit cards that we found under this account.

browserState

string false

Browser state such as cookies and other info. Please store this data on your end with the account and always send it back to us for any subsequent /account/check requests. This will make your accounts updating much faster.

itineraries

array false

If you set parseItineraries to true in your request you will get an array of all the itineraries listed under the account. There are different types of itineraries, such as air, hotel, rental car, etc. They all have slightly different schemas and they are all defined below.

history

object false

Object that defines history items which are the individual transactions (account activity) that show up on a loyalty account.

files

array false

Array of files such as PDF statements or e-receipts from an account.

filesVersion

integer false

Files cache version. Retrieving files, such as pdf statements from an account is an experimental feature that we have. Most likely you don’t use it and don’t need to worry about any of the “files…” attributes. In case if you do, store this value on your side for subsequent requests to /account/check, to populate the CheckAccountRequest.FilesVersion field. Could be null if there are no files.

filesCacheValid

boolean false

true - means the files array contains partial response, such as only the latest pdf statements, add those statements to the ones you already have for this account instead of overwriting the statements that you have on your end.

false - means you should discard the files (pdf statements) that you have on your end, the files array will contain a full set of files for that account.

null - means you have not filled the filesVersion and the filesLastDate fields in your request

invalidAnswers

array false

An array of answers to security questions that we tried and determined that the answers are not valid. You should mark these answers as invalid on your end.

options

string false

This is a reserved field. Please ignore unless our support tells you otherwise.

Account information

File

This is an experimental feature we played around with. It allows you to retrieve pdf statements or e-folios from accounts. For example, it could return credit card statements in a pdf format. Unfortunately, currently this feature is not implemented but could be implemented in the future.

Parameter Type Required Description

date

string false

File date

name

string false

File name

extension

string false

File extension, i.e. "pdf"

kind

string false

The only file kind that we support is statement but we may support other file types in the future. This field would identify those types.

accountNumber

string false

In case of credit cards each statement is related to a specific account number. Most users have multiple banking accounts / credit cards under a single login name. This account number identifies the account to which this statement is related to.

accountName

string false

In case of credit cards, accounts may have user friendly names. This value shows that name.

accountType

string false

In case of credit cards this could be “checking”, “savings”, etc.

contents

string false

The actual file content, base 64 encoded.

History

History object returns you the individual transactions that are listed under a given loyalty account, a.k.a. “Account Activity”.

Parameter Type Required Description

range

string false

Identifies if the response contains complete or incremental history. There are only two possible values:

  • complete
  • incremental

state

string false

Please store this string value on your end along with this account and send it to us with consequent account update requests and set the range value to incremental

rows

array false

This is where the actual transactions history data will be (the information you would normally see under the “Account Activity” section of a loyalty account). This is an array of account history items.

subAccounts

array false

In some cases, sub-accounts may have their own transactions history, when they do, they will be returned in this attribute as an array of subAccounts history items.

SubAccountHistory

In some cases, sub-accounts may have their own transactions history, when they do, they will be returned in this object.

Parameter Type Required Description

code

string false

Each sub-account has a unique code value. You will need to use this code value to match up sub-account history with individual sub-accounts.

rows

array false

The rows array for sub-accounts has the same structure as the rows array for accounts (above). So basically, this is where the actual transactions history data will be.

HistoryRow

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.

HistoryField

Think of a single row of data that describes a historical transaction. fileds 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

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 "1/25/2016"

DetectedCard

There are typically multiple credit cards under a single online account. Some cards may not be earning miles or may be earning miles for other loyalty programs and should be tracked separately. For example, a user may have a British Airways Chase card – those miles should be tracked via British Airways account, instead of the Chase account; however, we will still detect that the user has that BA card and will list it in this array of detected cards.

Parameter Type Required Description

code

string false

Card code is a value that uniquely identifies a specific credit card within an account, i.e. chase.4321 where 4321 are the last four digits of the card.

displayName

string false

The display name of the card as we show it on AwardWallet. May not be exactly what you are looking for. An example would be: “Personal Card ending with 4321 (Sapphire Preferred / Ultimate Rewards):”

cardDescription

string false

Card description is what we show to our users about that specific card as it pertains to tracking loyalty points on that card. So we created this description ourselves. For example, for the Amex SPG card the description may be: "Should be tracked separately as a separate Starwood account added to AwardWallet".

SubAccount

Some loyalty programs have multiple loyalty balances that users want to track. For example, a single banking account may have multiple credit cards, each earning its own loyalty points. We would present those individual loyalty balances as sub-accounts.

Parameter Type Required Description

balance

number false

Account balance. In some cases, you may get a null value which means that balance is not applicable for this type of subaccount.

expirationDate

date false

Subaccount balance expiration date.

code

string false

Some value that uniquely identifies this specific sub-account. I.e. 11234-HH-471

displayName

string false

The subaccount display name defines this subaccount to the user. For example, “Bank of America Companion Fare”

properties

array false

Just like accounts, subaccounts also can have additional properties that are specific to each subaccount.

neverExpires

boolean false

Just like with accounts this field tells if you the balance on this subaccount never expires.

Property

We try to standardize the secondary properties as much as possible. For that reason we have the property kind value which identifies what type of attribute this is.

Parameter Type Required Description

code

string false

This is usually a short codename of the property as described in the in the /providers/{provider code} method. I.e. "LastActivity"

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

2 - Expiration

3 - Elite Status

4 - Lifetime points

5 - Member since

6 - Expiring balance (in some cases only a portion of the entire balance may expire)

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

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

9 - Next elite level

10 - Points / miles needed to get to the next elite level

11 - Flights / nights needed to get to the next elite level.

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

13 - Date of the last account activity.

14 - Points / miles needed to get the next reward

15 - Elite level expiration date

16 - Points / miles needed to retain the current elite level

17 - Segments / flights needed to retain the current elite level

value

string false

The actual property value, such as “Silver”

Get account queue size

Response Example

                            
{
  "queues": [
    {
      "provider": "spg",
      "itemsCount": 3
    },
    {
      "provider": "turkish",
      "itemsCount": 1
    },
    {
      "provider": "amtrak",
      "itemsCount": 5
    }
  ]
}
                            
                        

If you ever need to do troubleshooting, you can always check how many of your account update requests are sitting in our queue using this method.

HTTP Request

GET https://loyalty.awardwallet.com/v2/account/queue

Response

Parameter Type Required Description

queues

array false

Array of queue items grouped by provider.

Check account queue state

QueueInfoItem

Parameter Type Required Description

provider

string false

Provider code

priority

integer false

Request priority

itemsCount

integer false

Total number of update requests for your API account waiting to be processed by our service for a given provider.

Reservations Via Conf#

Get reservation by conf #

POST Request Example

                            
{
  "provider": "alaskaair",
  "userId": "123",
  "userData": "blah",
  "priority": 9,
  "fields": [
    {
      "code": "ConfNo",
      "value": "ABC123"
    },
    {
      "code": "LastName",
      "value": "Smith"
    }
  ]
}
                            
                        

Response Example

                            
{
  "requestId": "580d54da9d44d8ee39e29584"
}
                            
                        

This method allows you to pull reservations from providers’ websites using a confirmation number without having to login using user credentials. Typically, you have to supply confirmation number and the traveler’s last name in order to retrieve a reservation but each website is different so requests will vary from provider to provider.

HTTP Request

POST https://loyalty.awardwallet.com/v2/confirmation/check

Query Parameters

Parameter Type Required Description

provider

string false

Alpha-numeric value with no spaces that uniquely identifies any given provider. Can be retrieved from the /providers/list method.

userId

string true

UserID that uniquely identifies the user in your system. Required for billing / accounting purposes.

userData

string false

Any data you wish to send. It will be returned untouched in the response. Could be used for matching requests to responses.

priority

integer true

Request priority values range from 1 to 9, where 1 is the lowest priority and 9 is the highest priority. In some cases, we throttle requests with priorities lower than X (default is 9). Please use this attribute to separate background account updates from the foreground account updates. In other words, background updating could have priority of 1 and accounts that are updated when an actual user is actually waiting for the results with priority of 9. This way your background updating will never negatively affect your updates when someone is actually waiting for the results.

callbackUrl

string false

All callback URLs must be registered with us prior to 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 when sending callbacks to that URL.

retries

integer false

Defines how many times we will retry account updating in case of an unknown error. If the user provided us with invalid credentials and we detect that, we will not keep retrying as that may lock out the user. Possible values are 0 to 4. The default is 4.

timeout

integer false

Time in seconds which determines how long the account is allowed to sit in the queue. If that time passes and we have not retrieved the account details we will throw a "timeout" error. This way, if someone is waiting for an account update (staring at their device) and if it takes too long we will remove that account from the queue and will give a meaningful error (thus freeing up our resources) to update other accounts.

fields

array true

Each provider may have different fields / values that need to be submitted to retrieve reservations by confirmation number. To know what filed names to pass you need to call the /providers/{code} method and look at the confirmationNumberFields array.

Response

Parameter Type Required Description

requestId

string true

qAn ID that uniquely identifies this request. You can use this value to get the results of this update request using the /confirmation/check/{id} method

Loyalty program information and itineraries

InputField

Parameter Type Required Description

code

string false

To know what filed code to pass you need to call the /providers/{code} method and look at the confirmationNumberFields array.

value

string false

Value, such as travelers last name or confirmation number.

Get reservation results

Response Example

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

If you are not using a callbackUrl you can get the results of your /confirmation/check request using the requestId that you got from that request.

HTTP Request

GET https://loyalty.awardwallet.com/v2/confirmation/check/{id}

Query Parameters

Parameter Type Required Description
id string true

The ID that uniquely identifies this request that you got from the /confirmation/check method

Response

Parameter Type Required Description

requestId

string false

An ID that uniquely identifies this request.

userData

string false

This field returns whatever data you put in it when you made your request as is. Can be used for some sort of tracking.

provider

string false

Alpha-numeric value with no spaces that uniquely identifies any given provider, i.e. "marriott"

message

string false

Human readable error message. You can show this message to your users.

errorReason

string false

Technical error reason. Something like "AwardWallet sign-in attempt was blocked by the provider" or "We could not recognize captcha". Do not show this message to the end user.

checkDate

date-time false

Date and time when this account information was retrieved from the provider’s website.

requestDate

date-time false

Date and time of when the request was sent to us, i.e. when the account was put into our queue for updating.

state

integer false

1 - Reservation was successfully retrieved.

6 - AwardWallet failed to parse the provider’s website.

100 – The provider did not accept the parameters you sent, i.e. last name and confirmation number combination is not valid

itineraries

array false

If you set parseItineraries to true in your request you will get an array of all the itineraries listed under the account. There are different types of itineraries, such as air, hotel, rental car, etc. They all have slightly different schemas and they are all defined below.

Confirmation information

Get reservation queue size

Response Example

                            
{
  "queues": [
    {
      "provider": "spg",
      "itemsCount": 3
    },
    {
      "provider": "turkish",
      "itemsCount": 1
    },
    {
      "provider": "amtrak",
      "itemsCount": 5
    }
  ]
}
                            
                        

If you ever need to do troubleshooting, you can always check how many of your /confirmation/check requests are sitting in our queue using this method.

HTTP Request

GET https://loyalty.awardwallet.com/v2/confirmation/queue

Response

Parameter Type Required Description

queues

array false

Array of queue items grouped by provider.

Check confirmation queue state

Itineraries

Flight

Example

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

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object 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

Number

This object represents a ticket or an account number.

Parameter Type Required Description

number

string true

Number as it was parsed from the email

masked

boolean true

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

Flight Segment

Parameter Type Required Description

departure

object true

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

arrival

object true

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

marketingCarrier

object true

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

operatingCarrier

object false

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

wetleaseCarrier

object false

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

seats

array false

Assigned passenger seats.

aircraft

object false

Object defining the aircraft.

traveledMiles

string false

Number of miles traveled on this flight segment.

cabin

string false

Cabin class, i.e. “Economy”

bookingCode

string false

Booking class code, i.e. “T”

duration

string false

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

status

string false

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

meal

string false

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

smoking

boolean false

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

stops

integer false

Number of stops this flight has.

flightStatsMethodUsed

string false

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

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

Aircraft

Parameter Type Required Description

iataCode

string false

Aircraft IATA code

name

string true

Aircraft name

turboProp

boolean false

Indicates if this is a turboprop aircraft

jet

boolean false

Indicates if this is a jet engine aircraft

wideBody

boolean false

Indicates if this is a wide-body aircraft

regional

boolean false

Indicates if this is a regional aircraft

Operating Carrier

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

Parameter Type Required Description

airline

object false

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

flightNumber

string false

Operating airline flight number

confirmationNumber

string false

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

phoneNumbers

array false

Contact phone numbers

Marketing Carrier

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

Parameter Type Required Description

airline

object true

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

flightNumber

string true

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

confirmationNumber

string false

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

phoneNumbers

array false

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

isCodeshare

boolean false

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

Airline

Parameter Type Required Description

name

string true

Airline name

iata

string false

IATA code of the airline

icao

string false

International Civil Aviation Organization airline code.

Flight Departure or Arrival

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

Parameter Type Required Description

airportCode

string false

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

terminal

string false

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

name

string true

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

localDateTime

string true

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

address

object true

Object defining the address of this location.

Address

Parameter Type Required Description

text

string true

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

addressLine

string false

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

city

string false

Name of the city validated by the Google API

stateName

string false

Name of the state validated by the Google API

countryName

string false

Name of the country validated by the Google API

postalCode

string false

Zip / postal code validated by the Google API

lat

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.

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

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.

Travel Agency

Parameter Type Required Description

providerInfo

object false

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

confirmationNumbers

array false

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

phoneNumbers

array false

Phone numbers of the travel agency.

Phone Number

Parameter Type Required Description

description

string false

Description of the phone number.

number

string true

Phone number

Confirmation Numbers

Parameter Type Required Description

number

string true

Confirmation number

description

string false

Confirmation number description

isPrimary

boolean false

Indicates whether this confirmation number can be considered as primary

Provider Info

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

Parameter Type Required Description

name

string false

Loyalty program name

code

string false

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

accountNumbers

array false

Array of related loyalty program account numbers

earnedRewards

string false

Rewards earned for booking the reservation

Car Rental

Example

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

Rental car reservation

Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object 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

Example

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

Hotel reservation

Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

cancellationDeadline

string false

Deadline date for changing or cancelling the reservation without additional penalties

isNonRefundable

boolean false

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

type

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

Room

Parameter Type Required Description

type

string false

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

description

string false

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

rate

string false

Room rate per night.

rateType

string false

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

Bus

Example

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

Bus ride

Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object true

Type of reservation. Value: transportation

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

object 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

string false

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

stops

integer false

Number of stops this transportation segment has.

Vehicle

This object describes the vehicle used to trasport a passenger

Parameter Type Required Description

type

string false

Short description

model

string false

Model of the vehicle

Transportation Departure or Arrival

This object describes the transportation departure and arrival events

Parameter Type Required Description

stationCode

string false

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

name

string true

Station or location name

localDateTime

string true

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

address

object true

Object defining the address of this location.

Train

Example

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

Train ride

Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object true

Type of reservation. Value: transportation

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

object 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

string false

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

stops

integer false

Number of stops this transportation segment has.

Transfer

Example

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

Car or shuttle bus ride

Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object true

Type of reservation. Value: transportation

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

object 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"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "stationCode": null,
            "name": "PORT CANAVERAL",
            "localDateTime": "2030-01-01T13:30:00",
            "address": {
              "text": "PORT CANAVERAL",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null
            }
          },
          "arrival": {
            "stationCode": null,
            "name": "NASSAU",
            "localDateTime": "2030-01-02T08:00:00",
            "address": {
              "text": "NASSAU",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": 25.0479835,
              "lng": -77.355413,
              "timezone": -14400
            }
          }
        },
        {
          "departure": {
            "stationCode": null,
            "name": "NASSAU",
            "localDateTime": "2030-01-02T12:00:00",
            "address": {
              "text": "NASSAU",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": 25.0479835,
              "lng": -77.355413,
              "timezone": -14400
            }
          },
          "arrival": {
            "stationCode": null,
            "name": "PORT CANAVERAL",
            "localDateTime": "2030-01-03T14:00:00",
            "address": {
              "text": "PORT CANAVERAL",
              "addressLine": null,
              "city": null,
              "stateName": null,
              "countryName": null,
              "postalCode": null,
              "lat": null,
              "lng": null,
              "timezone": null
            }
          }
        }
      ],
      "cruiseDetails": {
        "description": "Long cruise",
        "class": "Regular",
        "deck": "3",
        "room": "342",
        "ship": "Disney Dream",
        "shipCode": "SHCD",
        "voyageNumber": "K229"
      },
      "type": "cruise"
    }
  ]
}
                            
                        
Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object 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"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "address": {
        "text": "132 West 58th Street New York, NY 10019",
        "addressLine": "132 West 58th Street",
        "city": "New York",
        "stateName": "New York",
        "countryName": "United States",
        "postalCode": "10019",
        "lat": 40.7653771,
        "lng": -73.9779742,
        "timezone": -14400
      },
      "eventName": "Loi Estiatorio",
      "eventType": 1,
      "startDateTime": "2030-01-01T18:00:00",
      "endDateTime": "2030-01-01T23:00:00",
      "phone": "+1-23-44556",
      "fax": "+1-99-33434",
      "guestCount": 2,
      "guests": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "seats": [
        "table 13"
      ],
      "type": "event"
    }
  ]
}
                            
                        
Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object 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

Example

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

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

Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object 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"
      },
      "cancellationPolicy": "Ticket is non-refundable",
      "confirmationNumbers": [
        {
          "number": "A04-33984-12",
          "description": "Confirmation #",
          "isPrimary": true
        },
        {
          "number": "887756",
          "description": "Transaction number",
          "isPrimary": false
        }
      ],
      "travelers": [
        {
          "name": "John Doe",
          "full": true
        },
        {
          "name": "Jane Doe",
          "full": true
        }
      ],
      "segments": [
        {
          "departure": {
            "stationCode": "NO OSL",
            "name": "Oslo, Norway",
            "localDateTime": "2030-01-01T14:00:00",
            "address": {
              "text": "Akershusstranda 19, 0102 Oslo, Norway",
              "addressLine": "Akershusstranda 19",
              "city": "Oslo",
              "stateName": null,
              "countryName": "Norway",
              "postalCode": "0102",
              "lat": 59.904139,
              "lng": 10.738278,
              "timezone": null
            }
          },
          "arrival": {
            "stationCode": "DEKEL",
            "name": "Kiel, Germany",
            "localDateTime": "2030-01-02T10:00:00",
            "address": {
              "text": "Norwegenkai, 24143 Kiel, Germany",
              "addressLine": null,
              "city": "Kiel",
              "stateName": null,
              "countryName": "Germany",
              "postalCode": null,
              "lat": 54.316333,
              "lng": 10.138806,
              "timezone": null
            }
          },
          "accommodations": [
            "4-Bed inside cabin, shower/WC",
            "4-Bed inside cabin, shower/WC"
          ],
          "carrier": "ANEK SUPERFAST",
          "vessel": "Hellenic Spirit",
          "traveledMiles": "10km",
          "duration": "2h",
          "meal": "none",
          "smoking": false,
          "adultsCount": 2,
          "kidsCount": 1,
          "pets": "1 cat",
          "vehicles": [
            {
              "type": "Auto",
              "model": "Audi",
              "length": "<5m",
              "height": "1.8",
              "width": "1.8-3m"
            }
          ],
          "trailers": [
            {
              "type": "Regular",
              "model": "Standard",
              "length": "<=2m",
              "height": "<=2",
              "width": "<=2"
            }
          ]
        }
      ],
      "ticketNumbers": [
        {
          "number": "345667",
          "masked": false
        },
        {
          "number": "345668",
          "masked": false
        }
      ],
      "type": "ferry"
    }
  ]
}
                            
                        
Parameter Type Required Description

travelAgency

object false

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

pricingInfo

object false

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

status

string false

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

reservationDate

string false

Date when the reservation was booked

providerInfo

object false

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

cancellationPolicy

string false

Cancelation policy of this specific reservation.

type

object true

Type of reservation. Value: transportation

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

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

smoking

boolean false

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

vehicles

array false

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

trailers

array false

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

Vehicle or Trailer

This object describes a vehicle/trailer

Parameter Type Required Description

type

string false

Short description

model

string false

Model of the vehicle/trailer

length

string false

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

height

string false

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

width

string false

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

Cancelled

Example

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

type

string true

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

itineraryType

string true

Type of reservation. Possible options are:

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

confirmationNumber

string true

Confirmation number of the canceled reservation.

Errors

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