Introduction

AwardWallet Web Parsing API

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

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": [
    {
      "code": "Info",
      "name": "Type",
      "kind": "0"
    },
    {
      "code": "PostingDate",
      "name": "Date Posted",
      "kind": "0"
    },
    {
      "code": "Description",
      "name": "Description",
      "kind": "0"
    },
    {
      "code": "Miles",
      "name": "Points earned",
      "kind": "0"
    },
    {
      "code": "Info",
      "name": "Actions",
      "kind": "0"
    },
    {
      "code": "Bonus",
      "name": "Bonus points earned",
      "kind": "0"
    }
  ],
  "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/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

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.

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

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/account/check

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.

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.

options

array false

This is a reserved field. Please leave it empty unless our support tells you otherwise.

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

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

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",
  "warnings": [
    "At the moment we don't support gathering of itineraries from this provider's online accounts, if you believe it is possible, please contact our support and we may develop this functionality."
  ],
  "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": [
          {
            "code": "PostingDate",
            "name": "Post Date",
            "value": "1445904000"
          },
          {
            "code": "Info",
            "name": "Type",
            "value": "Stay"
          },
          {
            "code": "Miles",
            "name": "Points earned",
            "value": "+8,508"
          },
          {
            "code": "Description",
            "name": "Description",
            "value": "Nashville Airport Marriott 09/13/15 - 09/18/15"
          }
        ]
      }
    ],
    "subAccounts": [
      {
        "code": "SubAcc1",
        "rows": [
          {
            "fields": [
              {
                "code": "PostingDate",
                "name": "Post Date",
                "value": "1445904000"
              },
              {
                "code": "Info",
                "name": "Type",
                "value": "Bonus"
              },
              {
                "code": "Miles",
                "name": "Points earned",
                "value": "+2,500"
              },
              {
                "code": "Description",
                "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/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.

warnings

array false

If we want to return any warnings along with the response we will return those warnings in this field. Please note that warnings can be returned alongside a completely valid response, so the fact that there is a warning doesn’t mean the rest of the response is invalid.

login

string false

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 false

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

double false

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.

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

date 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

code

string false

We have four predefined filed codes; they are:

PostingDate – date-time value of the transaction

Description – text value of the transaction description

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

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

name

string false

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

value

string false

The actual field value, such as "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

double 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/account/queue

Response

Parameter Type Required Description

queues

array false

Array of queue items grouped by provider.

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/confirmation/check

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.

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

An 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

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": [
    {
      "requestId": "580d54da9d44d8ee39e29584",
      "userData": "blah",
      "state": 1,
      "message": "",
      "checkDate": "2017-01-07T20:14:23+00:00",
      "requestDate": "2017-01-07T20:14:15+00:00",
      "itineraries": [
        {
          "providerDetails": {
            "confirmationNumber": "ABC321",
            "accountNumbers": "43214321, 56785678",
            "name": "Alaska Air",
            "code": "alaskaair"
          },
          "totalPrice": {
            "total": 316.25,
            "currencyCode": "USD",
            "tax": 27.17
          },
          "type": "flight",
          "segments": [
            {
              "departure": {
                "airportCode": "SEA",
                "name": "Seattle ",
                "localDateTime": "2017-01-21T06:15:00",
                "address": {
                  "text": "Seattle ",
                  "addressLine": "17801 International Boulevard",
                  "city": "Seattle",
                  "stateName": "Washington",
                  "countryName": "United States",
                  "postalCode": "98158",
                  "lat": "47.4502499",
                  "lng": "-122.3088165",
                  "timezone": "-28800"
                }
              },
              "arrival": {
                "airportCode": "LAX",
                "name": "Los Angeles, CA ",
                "localDateTime": "2017-01-21T08:49:00",
                "address": {
                  "text": "Los Angeles, CA ",
                  "addressLine": "1 World Way",
                  "city": "Los Angeles",
                  "stateName": "California",
                  "countryName": "United States",
                  "postalCode": "90045",
                  "lat": "33.9415889",
                  "lng": "-118.40853",
                  "timezone": "-28800"
                }
              },
              "seats": [
                "2A",
                "2B"
              ],
              "flightNumber": "446",
              "airlineName": "Alaska",
              "aircraft": "Boeing 737-900",
              "traveledMiles": "954",
              "cabin": "Main",
              "bookingClass": "R",
              "duration": "2h 34m",
              "meal": "Food for Purchase"
            }
          ],
          "travelers": [
            {
              "fullName": "John Smith"
            },
            {
              "fullName": "Jennifer Smith"
            }
          ]
        }
      ]
    }
  ]
}
                            
                        

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

warnings

array false

If we want to return any warnings along with the response we will return those warnings in this field. Please note that warnings can be returned alongside a completely valid response, so the fact that there is a warning doesn’t mean the rest of the response is invalid.

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

An array of itineraries that corresponds to this confirmation number.

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/confirmation/queue

Response

Parameter Type Required Description

queues

array false

Array of queue items grouped by provider.

Itineraries

Flight

Example

                            
{
  "providerDetails": {
    "confirmationNumber": "ABC321",
    "accountNumbers": "43214321, 56788765",
    "name": "Alaska Air",
    "code": "alaskaair"
  },
  "totalPrice": {
    "total": 322.25,
    "currencyCode": "USD",
    "tax": 37.38
  },
  "type": "flight",
  "segments": [
    {
      "departure": {
        "airportCode": "LAX",
        "name": "Los Angeles, CA ",
        "localDateTime": "2017-02-02T10:00:00",
        "address": {
          "text": "Los Angeles, CA ",
          "addressLine": "1 World Way",
          "city": "Los Angeles",
          "stateName": "California",
          "countryName": "United States",
          "postalCode": "90045",
          "lat": "33.9415889",
          "lng": "-118.40853",
          "timezone": "-28800"
        }
      },
      "arrival": {
        "airportCode": "SEA",
        "name": "Seattle ",
        "localDateTime": "2017-02-02T12:45:00",
        "address": {
          "text": "Seattle ",
          "addressLine": "17801 International Boulevard",
          "city": "Seattle",
          "stateName": "Washington",
          "countryName": "United States",
          "postalCode": "98158",
          "lat": "47.4502499",
          "lng": "-122.3088165",
          "timezone": "-28800"
        }
      },
      "seats": [
        "3C",
        "3D"
      ],
      "flightNumber": "475",
      "airlineName": "Alaska",
      "aircraft": "Boeing 737-900",
      "traveledMiles": "954",
      "cabin": "Main",
      "bookingClass": "R",
      "duration": "2h 45m",
      "meal": "Food for Purchase"
    }
  ],
  "travelers": [
    {
      "fullName": "John Smith"
    },
    {
      "fullName": "Jennifer Smith"
    }
  ]
}
                            
                        
Parameter Type Required Description

type

string true

Type of reservation. Possible options are:

- flight

- carRental

- hotelReservation

- transportation

- cruise

- event

- cancelled

providerDetails

object true

An object that contains common attributes that are related to the whole reservation.

totalPrice

object false

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

travelers

array false

Names of the people listed on the reservation

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.

segments

array true

An array describing individual flight segments of the itinerary.

FlightSegment

Parameter Type Required Description

flightNumber

string true

Flight number

departure

object true

An object describing all the aspects of the departure airport, such as code, name, address, geographical coordinates, etc.

arrival

object true

An object describing the arrival airport – same idea and structure as the object defining the departure airport.

seats

array false

Assigned passenger seats.

airlineName

string false

Airline Name. Typically, this would be the airline that sold the tickets.

operator

string false

If there is a separate operating airline it would be listed in this field.

aircraft

string false

Aircraft name such as “Boeing 777 jet”

traveledMiles

string false

Number of miles traveled on this flight segment.

cabin

string false

Cabin class, i.e. “Economy”

bookingClass

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.

meal

string false

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

smoking

string false

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

stops

integer false

Number of stops this flight has.

TripLocation

Itineraries where people travel from place to place have departure and arrival locations that have a lot in common. We define them as a separate object as described below.

Parameter Type Required Description

airportCode

string false

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

stationCode

string false

This attribute shows the bus station or train station or port code as it shows up on the provider’s website. This field is not validated.

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 false

Object defining the address of this location.

Address

Parameter Type Required Description

text

string false

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

string false

Latitude coordinate of the address

lng

string false

Longitude coordinate of the address

timezone

string false

Time zone in which this address is located.

Person

Parameter Type Required Description

fullName

string true

Full name of the person listed on the reservation.

TotalPrice

Parameter Type Required Description

total

double false

Total cost of the reservation including all taxes and fees.

cost

double false

Cost of the reservation before taxes.

tax

double false

Amount paid in taxes

discount

double false

Total amount of discounts, if any.

spentAwards

string false

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

currencyCode

string false

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

rate

string false

In case of a hotel reservation would be the room rate per night.

rateType

string false

In case of a hotel reservation this field would be describing the room, i.e. “2 QUEEN BEDS NONSMOKING”.

fees

array false

Various fees associated with the reservation.

Fee

Parameter Type Required Description

name

string false

Fee description.

charge

double false

Fee amount.

ProviderDetails

Parameter Type Required Description

confirmationNumber

string true

Reservation confirmation number.

confirmationNumbers

array false

In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked, there may be multiple reservation numbers, this array would list them all.

tripNumber

string false

When booking through an OTA there may be a separate confirmation number that is specific to that OTA.

accountNumbers

string false

Account numbers of the travelers listed on the reservation.

name

string false

Provider name, same as what you could get from the providers/{code} method.

code

string false

Provider code, same as what you could get from the providers/list method.

status

string false

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

reservationDate

string false

Date when the reservation was booked

earnedAwards

string false

Awards earned from this reservation.

CarRental

Example

                            
{
  "providerDetails": {
    "confirmationNumber": "1234567890",
    "accountNumbers": "9988776655",
    "name": "National",
    "code": "national"
  },
  "totalPrice": {
    "total": 158.67,
    "currencyCode": "$",
    "tax": 8.98,
    "discount": 0,
    "fees": [
      {
        "name": "Rental Car Facility Chrg 3.95/day",
        "charge": 11.85
      },
      {
        "name": "Concession Recoupment Fee 10 Pct (10.0%)",
        "charge": 11.99
      },
      {
        "name": "Florida Surcharge 2.00/day",
        "charge": 6
      },
      {
        "name": "Tire Battery Fee .02 Day",
        "charge": 0.06
      },
      {
        "name": "Vehicle License Fee .78/day",
        "charge": 2.34
      }
    ]
  },
  "type": "carRental",
  "pickup": {
    "address": {
      "text": "Ft. Lauderdale Intl Arpt  (FLL)",
      "addressLine": "100 Terminal Drive",
      "city": "Fort Lauderdale",
      "stateName": "Florida",
      "countryName": "United States",
      "postalCode": "33315",
      "lat": "26.0742344",
      "lng": "-80.1506022",
      "timezone": "-18000"
    },
    "localDateTime": "2017-01-08T12:00:00",
    "phone": "(954)359-2550"
  },
  "dropoff": {
    "address": {
      "text": "Ft. Lauderdale Intl Arpt  (FLL)",
      "addressLine": "100 Terminal Drive",
      "city": "Fort Lauderdale",
      "stateName": "Florida",
      "countryName": "United States",
      "postalCode": "33315",
      "lat": "26.0742344",
      "lng": "-80.1506022",
      "timezone": "-18000"
    },
    "localDateTime": "2017-01-10T15:00:00",
    "phone": "(954)359-2550"
  },
  "car": {
    "type": "Midsize",
    "model": "Hyundai Elantra",
    "imageUrl": "https://www.nationalcar.com/content/dam/global-vehicle-images/cars/HYUN_ELAN_SE_2017.png"
  },
  "driver": {
    "fullName": "John Smith"
  }
}
                            
                        

Rental car reservation

Parameter Type Required Description

type

string true

Type of reservation. Possible options are:

- flight

- carRental

- hotelReservation

- transportation

- cruise

- event

- cancelled

providerDetails

object true

An object that contains common attributes that are related to the whole reservation.

totalPrice

object false

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

pickup

object true

Object defining the pickup location of the car.

dropoff

object true

Object defining the dropoff location of the 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.

promoCode

string false

Promo code used during the reservation.

serviceLevel

string false

Level of service, such as gold, platinum, etc.

paymentMethod

string false

Method of payment such as Pay Now, Pay Later, etc.

CarRentalDiscount

Parameter Type Required Description

name

string false

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

code

string false

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.

CarRentalLocation

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.

HotelReservation

Example

                            
{
  "providerDetails": {
    "confirmationNumber": "1122334455",
    "name": "Marriott",
    "code": "marriott"
  },
  "totalPrice": {
    "total": 1659.39,
    "cost": 1622.51,
    "currencyCode": "USD",
    "tax": 36.88
  },
  "type": "hotelReservation",
  "hotelName": "Orlando World Center Marriott",
  "checkInDate": "2017-01-08T00:00:00",
  "checkOutDate": "2017-01-13T00:00:00",
  "address": {
    "text": "8701 World Center Drive, Orlando, Florida 32821 USA",
    "addressLine": "8701 World Center Drive",
    "city": "Orlando",
    "stateName": "Florida",
    "countryName": "United States",
    "postalCode": "32821",
    "lat": "28.3609503",
    "lng": "-81.5099458",
    "timezone": "-18000"
  },
  "phone": "+1-407-239-4200",
  "guests": [
    {
      "fullName": "Ms. Jenifer Smith"
    }
  ],
  "kidsCount": 0,
  "guestCount": 2,
  "roomsCount": 1,
  "rooms": [
    {
      "type": "5 nights at 270.00 USD 1,659.39 USD Total hotel currency (incl. est. taxes)",
      "description": ""
    }
  ],
  "cancellationPolicy": "If you cancel for any reason, attempt to modify this reservation, or do not arrive on your specified check-in date, your payment is non-refundable."
}
                            
                        

hotel reservation

Parameter Type Required Description

type

string true

Type of reservation. Possible options are:

- flight

- carRental

- hotelReservation

- transportation

- cruise

- event

- cancelled

providerDetails

object true

An object that contains common attributes that are related to the whole reservation.

totalPrice

object false

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

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.

cancellationPolicy

string false

Cancelation policy of this specific reservation.

rooms

array false

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

Room

Parameter Type Required Description

type

string true

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

description

string false

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

Transportation

Example

                            
{
  "providerDetails": {
    "confirmationNumber": "123ABC",
    "name": "Amtrak",
    "code": "amtrak"
  },
  "totalPrice": {
    "total": 40.25,
    "currencyCode": "$"
  },
  "type": "transportation",
  "segments": [
    {
      "departure": {
        "stationCode": "CHI",
        "name": "Chicago, IL ",
        "localDateTime": "2017-01-12T20:05:00",
        "address": {
          "text": "Chicago, IL ",
          "city": "Chicago",
          "stateName": "Illinois",
          "countryName": "United States",
          "lat": "41.8781136",
          "lng": "-87.6297982",
          "timezone": "-21600"
        }
      },
      "arrival": {
        "stationCode": "CHM",
        "name": "Champaign, IL ",
        "localDateTime": "2017-01-12T22:34:00",
        "address": {
          "text": "Champaign, IL ",
          "city": "Champaign",
          "stateName": "Illinois",
          "countryName": "United States",
          "lat": "40.1164204",
          "lng": "-88.2433829",
          "timezone": "-21600"
        }
      },
      "transport": {
        "type": "train"
      },
      "scheduleNumber": "59",
      "duration": "2 hr, 29 min"
    }
  ],
  "travelers": [
    {
      "fullName": "John Smith"
    },
    {
      "fullName": "Jennifer Smith"
    }
  ]
}
                            
                        

Public Transportation or Shuttle bus

Parameter Type Required Description

type

string true

Type of reservation. Possible options are:

- flight

- carRental

- hotelReservation

- transportation

- cruise

- event

- cancelled

providerDetails

object true

An object that contains common attributes that are related to the whole reservation.

totalPrice

object false

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

travelers

array false

Names of the people listed on the reservation

segments

array true

An array describing individual travel segments of the itinerary.

TransportationSegment

Parameter Type Required Description

scheduleNumber

string true

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

departure

object true

An object describing the departure location of this trip segment, such as train station or a bus stop location.

arrival

object true

An object describing the arrival location - similar to departure location.

transport

object false

Transportation type, i.e. train, bus, fairy, etc.

seats

array false

Assigned passenger seats.

traveledMiles

string false

Number of miles traveled on this segment.

cabin

string false

Cabin class, i.e. “Economy”

bookingClass

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.

Transport

This object defines the type of transportation this is.

Parameter Type Required Description

type

string false

We support four types of transportations, so this value could be one of the following: bus, train, ferry, ship

name

string false

User-friendly name of the transportation type.

vehicleClass

string false

Additional information about the transportation service (e.g. vehicle model, additional equipment, etc.).

Cruise

Example

                            
{
  "providerDetails": {
    "confirmationNumber": "3456789",
    "name": "Norwegian Cruise Line",
    "code": "norwegiancruise"
  },
  "totalPrice": [
    
  ],
  "type": "cruise",
  "segments": [
    {
      "departure": {
        "name": "New Orleans, Louisiana",
        "localDateTime": "2017-01-08T16:00:00",
        "address": {
          "text": "New Orleans, Louisiana",
          "city": "New Orleans",
          "stateName": "Louisiana",
          "countryName": "United States",
          "lat": "29.9510658",
          "lng": "-90.0715323",
          "timezone": "-21600"
        }
      },
      "arrival": {
        "name": "Cozumel, Mexico",
        "localDateTime": "2017-01-10T08:00:00",
        "address": {
          "text": "Cozumel, Mexico",
          "addressLine": "Cozumel",
          "city": "San Miguel de Cozumel",
          "stateName": "Quintana Roo",
          "countryName": "Mexico",
          "lat": "20.4229839",
          "lng": "-86.9223432",
          "timezone": "-18000"
        }
      }
    },
    {
      "departure": {
        "name": "Cozumel, Mexico",
        "localDateTime": "2017-01-10T17:00:00",
        "address": {
          "text": "Cozumel, Mexico",
          "addressLine": "Cozumel",
          "city": "San Miguel de Cozumel",
          "stateName": "Quintana Roo",
          "countryName": "Mexico",
          "lat": "20.4229839",
          "lng": "-86.9223432",
          "timezone": "-18000"
        }
      },
      "arrival": {
        "name": "Roatan, Bay Islands, Honduras",
        "localDateTime": "2017-01-11T10:00:00",
        "address": {
          "text": "Roatan, Bay Islands, Honduras",
          "addressLine": "Roat\u00e1n",
          "city": "Coxen Hole",
          "stateName": "Bay Islands Department",
          "countryName": "Honduras",
          "lat": "16.3297608",
          "lng": "-86.5299673",
          "timezone": "-21600"
        }
      }
    }
  ],
  "travelers": [
    {
      "fullName": "Mr John Smith"
    },
    {
      "fullName": "Mrs Jenifer Smith"
    },
    {
      "fullName": "Mr Ryan Smith"
    }
  ],
  "cruiseDetails": {
    "description": "7-Day Western Caribbean from New Orleans",
    "deck": "Inside Stateroom",
    "room": "1234",
    "ship": "Norwegian Dawn"
  }
}
                            
                        
Parameter Type Required Description

type

string true

Type of reservation. Possible options are:

- flight

- carRental

- hotelReservation

- transportation

- cruise

- event

- cancelled

providerDetails

object true

An object that contains common attributes that are related to the whole reservation.

totalPrice

object false

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

travelers

array false

Names of the people listed on the reservation

segments

array false

An array describing individual travel segments of the itinerary.

cruiseDetails

object false

Cruise Details

CruiseDetails

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.

CruiseSegment

Parameter Type Required Description

departure

object true

Object describing the departure port

arrival

object true

Object describing the arrival port

Event

Example

                            
{
  "providerDetails": {
    "confirmationNumber": "11223344",
    "name": "OpenTable.com",
    "code": "opentable",
    "earnedAwards": "100"
  },
  "totalPrice": [
    
  ],
  "type": "event",
  "eventName": "Palace Cafe",
  "address": {
    "text": "605 Canal Street New Orleans, LA 70130",
    "addressLine": "605 Canal Street",
    "city": "New Orleans",
    "stateName": "Louisiana",
    "countryName": "United States",
    "postalCode": "70130",
    "lat": "29.9528899",
    "lng": "-90.0681833",
    "timezone": "-21600"
  },
  "startDateTime": "2017-01-08T10:30:00",
  "phone": "+1 504-523-1661",
  "guestCount": 4
}
                            
                        
Parameter Type Required Description

type

string true

Type of reservation. Possible options are:

- flight

- carRental

- hotelReservation

- transportation

- cruise

- event

- cancelled

providerDetails

object true

An object that contains common attributes that are related to the whole reservation.

totalPrice

object false

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

address

object true

The address of the event.

eventName

string true

Event name such as the name of the restaurant.

eventType

integer false

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.

Cancelled

Example

                            
{
  "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

- transportation

- cruise

- event

- cancelled

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