AwardWallet Account Access API

Introduction

The AwardWallet Account Access API provides access to the loyalty account data that belongs to AwardWallet users. Once authorized by the end user, the API provides access to the loyalty accounts that the user shared with you.

To use this API you need to have a business account, which can be registered here, if you already have a personal AwardWallet account, or here if you don’t have a personal AwardWallet account.

Your API key and other API settings can be found under your business account.

This API will allow you to retrieve information about any of the users that linked their accounts to your business account. You don’t need to have a paid business account in order to use the API. However, if you need a nice UI interface to see all of the users who shared their loyalty accounts with your business, you can use our business interface to do that.

If you wish to be able to invite users to link their accounts to your business interface you need to request that form the AwardWallet team by sending a description of your business and intended use case.

Once approved by AwardWallet you could start inviting users by using create-auth-url method.

Finally, you can have two types of members under your business interface:

  • Connected Users – these are the users who have their own personal AwardWallet credentials who chose to connect their accounts to your business account. They can choose granularly what exactly they wish to share with you.
  • Members – basically these are just names you add under your business interface. They make your life easier when organizing stuff under your business interface. These members don’t have an AwardWallet account and therefore are not linked to you the same way as Connected Users are.

Since these two entities are quite different you need to use two different API calls to get info about them.

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 key. This key is passed in the "X-Authentication" field with the https request header. You can get your personal API key in the account settings of your business account.

X-Authentication: userapikey

Connect

Get Connection Link

POST Request Example

                            
{
  "platform": "mobile",
  "access": 1,
  "state": "Y2kRhAvHoJRqECgkZfFUUMgMZADboqbnQJzs",
  "granularSharing": false
}
                            
                        

Response Example

                            
{
  "url": "https://awardwallet.com/user/connections/approve?access=1&authKey=lkqjwebrlsfdkds&id=lkwqsdf"
}
                            
                        

Use this method to get a unique URL to securely connect an AwardWallet user to your business account.

HTTP Request

POST https://business.awardwallet.com/api/export/v1/create-auth-url

Query Parameters

Parameter Type Required Description

platform

string true

There are two possible values:

  • mobile - use this if you are planning to show the concent screen on the mobile device. Also, even if you are showing it on a desktop using the mobile interface may work better for you, so you should consider using this option regardless of where the consent screen is shown.
  • desktop - this option will show the consent screen in a context of our standard full-blown desktop interface.

access

integer true

This attribute accepts values 0 – 3. It identifies the level of account access the User will be prompted to grant to the business. The possible values are:

0 - Read account numbers / usernames and elite statuses only

1 - Read account balances and elite statuses only

2 - Read all information excluding passwords

3 - Full control (edit, delete, auto-login, view passwords)

granularSharing

boolean false

First of all this option (if set to true) only works with if you also set the platform to desktop. By default this attribute is set to false, if set to true users will be given a link that allows them to go into their AwardWallet profile and granularly select which accounts they wish to share via the full-blown AwardWallet desktop interface.

state

string false

Specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response. The server returns the exact value that you send as a state=xyz in the query string of the redirect_uri after the user consents to or denies your application's access request.

Response

Parameter Type Required Description

url

string true

This is the JSON-encoded URL string that you will need to redirect your user's browser to in order for the user to authorize your access.

You can redirect your users to the URL that gets returned to you in a number of ways. One way to do this is to open up a separate small window like this:

Get Connected User Info

Response Example

                            
{
  "userId": "123"
}
                            
                        

Use this method after a successful connection to receive a newly connected userId

HTTP Request

GET https://business.awardwallet.com/api/export/v1/get-connection-info/{code}

Query Parameters

Parameter Type Required Description
code string true

This code will be sent to your endpoint via a browser redirect after a successful authentication (initiated by the create-auth-url method ). You will receive it as a GET parameter as follows: ?code=xxx

Response

Parameter Type Required Description

userId

integer false

This is the ID of the newly connected user.

Accounts

Get Account Details

Response Example

                            
{
  "account": [
    {
      "accountId": 7654321,
      "code": "british",
      "displayName": "British Airways (Executive Club)",
      "kind": "Airlines",
      "login": "johnsmith",
      "autologinUrl": "https://business.awardwallet.com/account/redirect?ID=7654321",
      "updateUrl": "https://business.awardwallet.com/account/edit/7654321?autosubmit=1",
      "editUrl": "https://business.awardwallet.com/account/edit/7654321",
      "balance": "146,780",
      "balanceRaw": 146780,
      "owner": "John Smith",
      "errorCode": 1,
      "lastDetectedChange": "+750",
      "expirationDate": "2018-12-10T00:00:00+00:00",
      "lastRetrieveDate": "2016-01-15T00:00:00+00:00",
      "lastChangeDate": "2016-01-15T00:49:33+00:00",
      "properties": [
        {
          "name": "Next Elite Level",
          "value": "Bronze",
          "kind": 9
        },
        {
          "name": "Date of joining the club",
          "value": "20 Jun 2013",
          "kind": 5
        },
        {
          "name": "Lifetime Tier Points",
          "value": "35,000"
        },
        {
          "name": "Executive Club Tier Points",
          "value": "35,000"
        },
        {
          "name": "Card expiry date",
          "value": "31 Mar 2017"
        },
        {
          "name": "Membership year ends",
          "value": "08 Feb 2016"
        },
        {
          "name": "Last Activity",
          "value": "10-Dec-15",
          "kind": 13
        },
        {
          "name": "Name",
          "value": "Mr Smith",
          "kind": 12
        },
        {
          "name": "Level",
          "value": "Blue",
          "rank": 0,
          "kind": 3
        },
        {
          "name": "Membership no",
          "value": "1122334455",
          "kind": 1
        }
      ],
      "history": [
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "3/31/14"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Expired Points"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Adjustments"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "-100"
            }
          ]
        },
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "12/11/13"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Google Wallet"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Other Earning"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "+100"
            }
          ]
        },
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "9/30/12"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Expired Points"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Adjustments"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "-1,042"
            }
          ]
        }
      ]
    }
  ],
  "connectedUser": {
    "userId": 12345,
    "fullName": "John Smith",
    "status": "Free",
    "userName": "JSmith",
    "email": "JSmith@email.com",
    "forwardingEmail": "JSmith@AwardWallet.com",
    "accessLevel": "Regular",
    "connectionType": "Connected",
    "accountsAccessLevel": "Full control",
    "accountsSharedByDefault": true,
    "editConnectionUrl": "https://business.awardwallet.com/members/connection/112233",
    "accountListUrl": "https://business.awardwallet.com/account/list#/?agentId=112233",
    "timelineUrl": "https://business.awardwallet.com/timeline/?agentId=166765#/112233",
    "bookingRequestsUrl": "https://business.awardwallet.com/awardBooking/queue?user_filter=332211"
  }
}
                            
                        

Using the accountId found in either the /member, /member/{id}, /connectedUser, or /connectedUser/{id} methods you can get a comprehensive list of all the account details including the entire transaction history list for that specific account.

HTTP Request

GET https://business.awardwallet.com/api/export/v1/account/{id}

Query Parameters

Parameter Type Required Description
id integer true

accountId

Response

Parameter Type Required Description

account

object true

An object that describes the Account

member

object false

An object that describes the Member to whom this account is linked.

connectedUser

object false

An object that describes the ConnectedUser to whom this account is linked.

Account data

ConnectedUser

Parameter Type Required Description

userId

integer true

Unique ID that identifies a given User

fullName

string true

Full name that User provided during registration

email

string true

Email address of a User

forwardingEmail

string true

AwardWallet email address of a User that can be used for forwarding User itineraries (as well as loyalty program statements) in order to update that User's travel plans on the timeline.

userName

string true

The logon name that User picked during registration

status

string true

User's status on AwardWallet. Possible values are:

  • Free
  • Plus

accessLevel

string false

Status of a User in the business account. Possible values are:

  • n/a
  • Regular
  • Booking Administrator
  • Administrator

connectionType

string true

User connection status. Possible values are:

  • Connected
  • Pending

Pending - is the status for those users who have not yet accepted an invitation to connect to the Business Account.

accountsAccessLevel

string true

Identifies the level of account access the User granted to the business. Possible values are:

0 - Read numbers

1 - Read balances

2 - Read all

3 - Full control

When inviting the users, you can pass one of these numbers as a value to the access GET parameter. This will determine the level of access you would be requesting by default. Keep in mind that users can change the level of access you have to their accounts at any time.

accountsSharedByDefault

boolean true

Identifies if the User is configured to share newly added accounts by default with the Business Account

editConnectionUrl

string true

URL address of the page where business administrator can manage the connection settings with this user.

accountListUrl

string true

URL address of the page where business administrator can see all of the loyalty accounts shared by the user with the business account.

timelineUrl

string true

URL address of the page where business administrator can see the travel timeline (i.e. all of their travel reservations) of this connected user.

bookingRequestsUrl

string false

URL address of the page where business administrator can see all the reward booking requests made by the user with the business.

Member

Parameter Type Required Description

memberId

integer true

Unique ID that identifies a given Member

fullName

string true

Full name of a Member

email

string false

Email address of a Member

forwardingEmail

string false

AwardWallet email address of a Member that can be used for forwarding Member itineraries (as well as loyalty program statements) in order to update that Member’s travel plans on the timeline.

editMemberUrl

string true

URL address of the page where business administrator can edit this member’s settings such as name or email address.

accountListUrl

string true

URL address of the page where business administrator can see all of the loyalty accounts that belong to this member.

timelineUrl

string true

URL address of the page where business administrator can see the travel timeline (i.e. all of their travel reservations) of this member.

Account

Parameter Type Required Description

accountId

integer true

Unique identifier of an Account

code

string true

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

displayName

string true

Name of the provider to which the Account belongs to. This is a user-friendly name that shows both the name the company as well as the actual name of the loyalty program. I.e. British Airways (Executive Club)

kind

string true

Type of account provider. Possible values are:

  • Airlines
  • Hotels
  • Credit Cards
  • Shopping
  • Rentals
  • Dining
  • Trains
  • Cruises
  • Surveys
  • Other

login

string true

Account login value. Could be "n/a" if the value is empty.

autologinUrl

string true

The auto-login URL that will automatically log you into that account on the provider’s website. Auto-login is only available on the accounts that provided the Business Account with Full Control. If the Business Account doesn’t have Full Control this value will be set to "n/a".

updateUrl

string true

The URL where you can retrieve all account details from the prover’s website. Account updating is only available on the accounts that provided the Business Account with Full Control. If the Business Account doesn’t have Full Control this value will be set to "n/a".

editUrl

string true

The URL where you can change account details, such as username and password values. Changing accounts is only available on the accounts that provided the Business Account with Full Control. If the Business Account doesn’t have Full Control this value will be set to "n/a".

balance

string true

Current account balance presented as a formatted number

balanceRaw

number true

Current account balance

lastDetectedChange

string false

Last change in the account balance as detected by AwardWallet. This change may or may not correlate with the actual change in the history of the account on the provider’s website.

expirationDate

date-time false

The date when all or part of the account balance will expire. In most cases this date was calculated by AwardWallet.

barcode

string false

Zeros and ones representing the bar code of the account. If available, and drawn properly, can be used with the provider’s bar code readers.

owner

string true

Full name of the account owner. Keep in mind that a Connected User could share accounts of his or her family members. In that case that person would show up as the account owner.

errorCode

integer true

The result of the last account update. Possible values are:

0 - Account has never been updated

1 – Account was successfully updated

2 – Account has Invalid credentials

3 – Account is locked out

4 – The provider returned some error, or requires some user action

5 – The provider is disabled by AwardWallet

6 - AwardWallet failed to parse the provider’s web site for unknown reason

7 – Account password is missing

8 – Account is disabled to prevent lockouts on the prover’s website

9 – Account was successfully updated, but there is a warning message returned

10 – The user needs to answer a security question, to update this account

11 - Account updating timed out.

errorMessage

string false

Account error message as shown on the provider’s website.

lastChangeDate

date-time false

Last time AwardWallet detected a change in the account balance. This date will probably not correlate with the date last time account actually changed on the provider’s website.

lastRetrieveDate

date-time false

Last time AwardWallet successfully logged into the account and successfully retrieved the account information

history

array false

Whenever Account History is available it will be presented as a History array. Please note that all providers choose to show account history in different formats, so unfortunately there is no standard column definitions across all providers. If you need to work with Account History you would need to evaluate the History array on per provider basis.

properties

array false

Account properties are so called "secondary attributes" that we gather from providers' websites whenever possible. Each provider has a different set of these secondary properties. To standardize some of them, properties may have a kind value as described below.

subAccounts

array false

Some accounts have subaccounts. For example, a single Capital One account can have multiple credit cards with individual balances under each card. Those separate balances would be tracked as subaccounts under that Capital One account.

SubAccount

Parameter Type Required Description

subAccountId

integer true

Unique identifier of a sub-account

displayName

string true

User friendly name of a sub-account

balance

string true

Current sub-account balance presented as a formatted number

balanceRaw

number false

Current sub-account balance

lastDetectedChange

string false

Last change in the sub-account balance as detected by AwardWallet. This change may or may not correlate with the actual change in the history of that sub-account on the provider’s website.

properties

array false

Sub-account properties are so called "secondary attributes" that we gather from providers' websites whenever possible. Each provider has a different set of these secondary properties.

history

array false

Whenever SubAccount History is available it will be presented as a History array. Please note that all providers choose to show account history in different formats, so unfortunately there is no standard column definitions across all providers. If you need to work with Account History you would need to evaluate the History array on per provider basis.

AccountProperty

Parameter Type Required Description

name

string true

Attribute name

value

string true

Attribute value

rank

integer false

Only used to provide a numeric representation of the elite status of an Account so that elite statuses could be standardized across all providers. It is only used for the Status property (Kind = 3)

kind

integer false

Used to standardize properties across different providers as they all may call conceptually the same attributes slightly differently. Possible values are:

  • 1 - Account number
  • 2 - Expiration
  • 3 - Status
  • 4 - Lifetime points
  • 5 - Member since
  • 6 - Expiring balance
  • 7 - YTD Miles/Points
  • 8 - YTD Segments
  • 9 - Next elite level
  • 10 - Miles/Points needed to next level
  • 11 - Segments needed to next level
  • 12 - Name
  • 13 - Last activity
  • 14 - Miles/Points needed for next reward
  • 15 - Status expiration
  • 16 - Miles/Points to retain status
  • 17 - Segments to retain status
  • 18 - Alliance elite level
  • 19 - Status miles/points

History

Account history row

Parameter Type Required Description

fields

array false

History fields

HistoryField

Account history field

Parameter Type Required Description

code

string true

There are 4 predefined field codes:

PostingDate - The date when miles or points were posted to the account

Description - Description of the transaction

Miles - Shows the numerical change in the miles or points

Bonus - Shows the bonus miles or points

For everything else this code value will be set to Info

name

string true

Human readable name of the attribute, such as "Transaction Date"

value

string true

Attribute value, such as "Finance Card - BA VISA NON BA SPEND"

Members

List Members

Response Example

                            
{
  "members": [
    {
      "memberId": 1234,
      "fullName": "John Smith",
      "email": "JSmith@email.com",
      "forwardingEmail": "BusinessABC.JSmith@AwardWallet.com",
      "editMemberUrl": "https://business.awardwallet.com/agent/editFamilyMember.php?ID=998877&Source=M",
      "accountListUrl": "https://business.awardwallet.com/account/list#/?agentId=998877",
      "timelineUrl": "https://business.awardwallet.com/timeline/?agentId=998877#/998877",
      "accountsIndex": [
        {
          "accountId": 12345,
          "lastChangeDate": "2016-07-20T17:17:17+00:00",
          "lastRetrieveDate": "2016-07-20T17:17:17+00:00"
        },
        {
          "accountId": 12346,
          "lastChangeDate": "2016-07-10T17:17:37+00:00",
          "lastRetrieveDate": "2016-07-22T17:17:37+00:00"
        }
      ]
    }
  ]
}
                            
                        

Members are just names you add under your business interface. They make your life easier when organizing stuff under your business interface. These members don’t have an AwardWallet account and therefore are not linked to your business account the same way as Connected Users are. You can use this method to retrieve all the members under your business account.

HTTP Request

GET https://business.awardwallet.com/api/export/v1/member

Response

Parameter Type Required Description

members

array true

array of MembersListItem

An array of Members

MembersListItem

Parameter Type Required Description

memberId

integer true

Unique ID that identifies a given Member

fullName

string true

Full name of a Member

email

string false

Email address of a Member

forwardingEmail

string false

AwardWallet email address of a Member that can be used for forwarding Member itineraries (as well as loyalty program statements) in order to update that Member’s travel plans on the timeline.

editMemberUrl

string true

URL address of the page where business administrator can edit this member’s settings such as name or email address.

accountListUrl

string true

URL address of the page where business administrator can see all of the loyalty accounts that belong to this member.

timelineUrl

string true

URL address of the page where business administrator can see the travel timeline (i.e. all of their travel reservations) of this member.

accountsIndex

array true

An index of all Member accounts that can be used to determine if calling the account/{id} is necessary for each account.

AccountsIndexItem

Parameter Type Required Description

accountId

integer true

Unique identifier of an Account

lastChangeDate

date-time true

Last time AwardWallet detected a change in the account balance. This date will probably not correlate with the date last time account actually changed on the provider’s website.

lastRetrieveDate

date-time false

Last time AwardWallet successfully logged into the account and successfully retrieved the account information

Get Member Details

Response Example

                            
{
  "memberId": 1234,
  "fullName": "John Smith",
  "email": "JSmith@email.com",
  "forwardingEmail": "BusinessABC.JSmith@AwardWallet.com",
  "editMemberUrl": "https://business.awardwallet.com/agent/editFamilyMember.php?ID=998877&Source=M",
  "accountListUrl": "https://business.awardwallet.com/account/list#/?agentId=998877",
  "timelineUrl": "https://business.awardwallet.com/timeline/?agentId=998877#/998877",
  "accounts": [
    {
      "accountId": 7654321,
      "code": "british",
      "displayName": "British Airways (Executive Club)",
      "kind": "Airlines",
      "login": "johnsmith",
      "autologinUrl": "https://business.awardwallet.com/account/redirect?ID=7654321",
      "updateUrl": "https://business.awardwallet.com/account/edit/7654321?autosubmit=1",
      "editUrl": "https://business.awardwallet.com/account/edit/7654321",
      "balance": "146,780",
      "balanceRaw": 146780,
      "owner": "John Smith",
      "errorCode": 1,
      "lastDetectedChange": "+750",
      "expirationDate": "2018-12-10T00:00:00+00:00",
      "lastRetrieveDate": "2016-01-15T00:00:00+00:00",
      "lastChangeDate": "2016-01-15T00:49:33+00:00",
      "properties": [
        {
          "name": "Next Elite Level",
          "value": "Bronze",
          "kind": 9
        },
        {
          "name": "Date of joining the club",
          "value": "20 Jun 2013",
          "kind": 5
        },
        {
          "name": "Lifetime Tier Points",
          "value": "35,000"
        },
        {
          "name": "Executive Club Tier Points",
          "value": "35,000"
        },
        {
          "name": "Card expiry date",
          "value": "31 Mar 2017"
        },
        {
          "name": "Membership year ends",
          "value": "08 Feb 2016"
        },
        {
          "name": "Last Activity",
          "value": "10-Dec-15",
          "kind": 13
        },
        {
          "name": "Name",
          "value": "Mr Smith",
          "kind": 12
        },
        {
          "name": "Level",
          "value": "Blue",
          "rank": 0,
          "kind": 3
        },
        {
          "name": "Membership no",
          "value": "1122334455",
          "kind": 1
        }
      ],
      "history": [
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "3/31/14"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Expired Points"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Adjustments"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "-100"
            }
          ]
        },
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "12/11/13"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Google Wallet"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Other Earning"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "+100"
            }
          ]
        },
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "9/30/12"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Expired Points"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Adjustments"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "-1,042"
            }
          ]
        }
      ]
    }
  ]
}
                            
                        

Using a memberId, received from the /member method you are able to retrieve all of the loyalty accounts that this member has, as well as other member-specific attributes, such as name and email of the member.

HTTP Request

GET https://business.awardwallet.com/api/export/v1/member/{id}

Query Parameters

Parameter Type Required Description
id integer true

memberId

Response

Parameter Type Required Description

memberId

integer true

Unique ID that identifies a given Member

fullName

string true

Full name of a Member

email

string false

Email address of a Member

forwardingEmail

string false

AwardWallet email address of a Member that can be used for forwarding Member itineraries (as well as loyalty program statements) in order to update that Member’s travel plans on the timeline.

editMemberUrl

string true

URL address of the page where business administrator can edit this member’s settings such as name or email address.

accountListUrl

string true

URL address of the page where business administrator can see all of the loyalty accounts that belong to this member.

timelineUrl

string true

URL address of the page where business administrator can see the travel timeline (i.e. all of their travel reservations) of this member.

accounts

array true

Array of Member accounts

Member data and array of accounts

Connected Users

List Connected Users

Response Example

                            
{
  "connectedUsers": [
    {
      "userId": 12345,
      "fullName": "John Smith",
      "status": "Free",
      "userName": "JSmith",
      "email": "JSmith@email.com",
      "forwardingEmail": "JSmith@AwardWallet.com",
      "accessLevel": "Regular",
      "connectionType": "Connected",
      "accountsAccessLevel": "Full control",
      "accountsSharedByDefault": true,
      "editConnectionUrl": "https://business.awardwallet.com/members/connection/112233",
      "accountListUrl": "https://business.awardwallet.com/account/list#/?agentId=112233",
      "timelineUrl": "https://business.awardwallet.com/timeline/?agentId=166765#/112233",
      "bookingRequestsUrl": "https://business.awardwallet.com/awardBooking/queue?user_filter=332211",
      "accountsIndex": [
        {
          "accountId": 12345,
          "lastChangeDate": "2016-07-20T17:17:17+00:00",
          "lastRetrieveDate": "2016-07-20T17:17:17+00:00"
        },
        {
          "accountId": 12346,
          "lastChangeDate": "2016-07-10T17:17:37+00:00",
          "lastRetrieveDate": "2016-07-22T17:17:37+00:00"
        }
      ]
    }
  ]
}
                            
                        

Connected Users are the users who have their own personal AwardWallet credentials who chose to connect their accounts to your business account. They can granularly choose what exactly they wish to share with you.

This method will list all such users as well as an index of the loyalty accounts that they own.

HTTP Request

GET https://business.awardwallet.com/api/export/v1/connectedUser

Response

Parameter Type Required Description

connectedUsers

array true

array of users

An array of users

ConnectedUsersListItem

Parameter Type Required Description

userId

integer true

Unique ID that identifies a given User

fullName

string true

Full name that User provided during registration

email

string true

Email address of a User

forwardingEmail

string true

AwardWallet email address of a User that can be used for forwarding User itineraries (as well as loyalty program statements) in order to update that User's travel plans on the timeline.

userName

string true

The logon name that User picked during registration

status

string true

User's status on AwardWallet. Possible values are:

  • Free
  • Plus

accessLevel

string false

Status of a User in the business account. Possible values are:

  • n/a
  • Regular
  • Booking Administrator
  • Administrator

connectionType

string true

User connection status. Possible values are:

  • Connected
  • Pending

Pending - is the status for those users who have not yet accepted an invitation to connect to the Business Account.

accountsAccessLevel

string true

Identifies the level of account access the User granted to the business. Possible values are:

0 - Read numbers

1 - Read balances

2 - Read all

3 - Full control

When inviting the users, you can pass one of these numbers as a value to the access GET parameter. This will determine the level of access you would be requesting by default. Keep in mind that users can change the level of access you have to their accounts at any time.

accountsSharedByDefault

boolean true

Identifies if the User is configured to share newly added accounts by default with the Business Account

editConnectionUrl

string true

URL address of the page where business administrator can manage the connection settings with this user.

accountListUrl

string true

URL address of the page where business administrator can see all of the loyalty accounts shared by the user with the business account.

timelineUrl

string true

URL address of the page where business administrator can see the travel timeline (i.e. all of their travel reservations) of this connected user.

bookingRequestsUrl

string false

URL address of the page where business administrator can see all the reward booking requests made by the user with the business.

accountsIndex

array true

An index of all Member accounts that can be used to determine if calling the account/{id} is necessary for each account.

Get Connected User Details

Response Example

                            
{
  "userId": 12345,
  "fullName": "John Smith",
  "status": "Free",
  "userName": "JSmith",
  "email": "JSmith@email.com",
  "forwardingEmail": "JSmith@AwardWallet.com",
  "accessLevel": "Regular",
  "connectionType": "Connected",
  "accountsAccessLevel": "Full control",
  "accountsSharedByDefault": true,
  "editConnectionUrl": "https://business.awardwallet.com/members/connection/112233",
  "accountListUrl": "https://business.awardwallet.com/account/list#/?agentId=112233",
  "timelineUrl": "https://business.awardwallet.com/timeline/?agentId=166765#/112233",
  "bookingRequestsUrl": "https://business.awardwallet.com/awardBooking/queue?user_filter=332211",
  "accounts": [
    {
      "accountId": 7654321,
      "code": "british",
      "displayName": "British Airways (Executive Club)",
      "kind": "Airlines",
      "login": "johnsmith",
      "autologinUrl": "https://business.awardwallet.com/account/redirect?ID=7654321",
      "updateUrl": "https://business.awardwallet.com/account/edit/7654321?autosubmit=1",
      "editUrl": "https://business.awardwallet.com/account/edit/7654321",
      "balance": "146,780",
      "balanceRaw": 146780,
      "owner": "John Smith",
      "errorCode": 1,
      "lastDetectedChange": "+750",
      "expirationDate": "2018-12-10T00:00:00+00:00",
      "lastRetrieveDate": "2016-01-15T00:00:00+00:00",
      "lastChangeDate": "2016-01-15T00:49:33+00:00",
      "properties": [
        {
          "name": "Next Elite Level",
          "value": "Bronze",
          "kind": 9
        },
        {
          "name": "Date of joining the club",
          "value": "20 Jun 2013",
          "kind": 5
        },
        {
          "name": "Lifetime Tier Points",
          "value": "35,000"
        },
        {
          "name": "Executive Club Tier Points",
          "value": "35,000"
        },
        {
          "name": "Card expiry date",
          "value": "31 Mar 2017"
        },
        {
          "name": "Membership year ends",
          "value": "08 Feb 2016"
        },
        {
          "name": "Last Activity",
          "value": "10-Dec-15",
          "kind": 13
        },
        {
          "name": "Name",
          "value": "Mr Smith",
          "kind": 12
        },
        {
          "name": "Level",
          "value": "Blue",
          "rank": 0,
          "kind": 3
        },
        {
          "name": "Membership no",
          "value": "1122334455",
          "kind": 1
        }
      ],
      "history": [
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "3/31/14"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Expired Points"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Adjustments"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "-100"
            }
          ]
        },
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "12/11/13"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Google Wallet"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Other Earning"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "+100"
            }
          ]
        },
        {
          "fields": [
            {
              "name": "Transaction Date",
              "code": "PostingDate",
              "value": "9/30/12"
            },
            {
              "name": "Description",
              "code": "Description",
              "value": "Expired Points"
            },
            {
              "name": "Type",
              "code": "Info",
              "value": "Adjustments"
            },
            {
              "name": "Points",
              "code": "Miles",
              "value": "-1,042"
            }
          ]
        }
      ]
    }
  ]
}
                            
                        

Using a userId, received from the /connectedUser method you are able to retrieve all of the loyalty accounts that this user has shared with your business account, as well as other user-specific attributes, such as their name, email, level of access they provided you with, etc.

HTTP Request

GET https://business.awardwallet.com/api/export/v1/connectedUser/{id}

Query Parameters

Parameter Type Required Description
id integer true

userId

Response

Parameter Type Required Description

userId

integer true

Unique ID that identifies a given User

fullName

string true

Full name that User provided during registration

email

string true

Email address of a User

forwardingEmail

string true

AwardWallet email address of a User that can be used for forwarding User itineraries (as well as loyalty program statements) in order to update that User's travel plans on the timeline.

userName

string true

The logon name that User picked during registration

status

string true

User's status on AwardWallet. Possible values are:

  • Free
  • Plus

accessLevel

string false

Status of a User in the business account. Possible values are:

  • n/a
  • Regular
  • Booking Administrator
  • Administrator

connectionType

string true

User connection status. Possible values are:

  • Connected
  • Pending

Pending - is the status for those users who have not yet accepted an invitation to connect to the Business Account.

accountsAccessLevel

string true

Identifies the level of account access the User granted to the business. Possible values are:

0 - Read numbers

1 - Read balances

2 - Read all

3 - Full control

When inviting the users, you can pass one of these numbers as a value to the access GET parameter. This will determine the level of access you would be requesting by default. Keep in mind that users can change the level of access you have to their accounts at any time.

accountsSharedByDefault

boolean true

Identifies if the User is configured to share newly added accounts by default with the Business Account

editConnectionUrl

string true

URL address of the page where business administrator can manage the connection settings with this user.

accountListUrl

string true

URL address of the page where business administrator can see all of the loyalty accounts shared by the user with the business account.

timelineUrl

string true

URL address of the page where business administrator can see the travel timeline (i.e. all of their travel reservations) of this connected user.

bookingRequestsUrl

string false

URL address of the page where business administrator can see all the reward booking requests made by the user with the business.

accounts

array true

Array of accounts the User has shared with the Business Account. It includes all account details as described below, except the array of History items is limited to the first 10 records.

User data and array of accounts

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. This list will change over time, so you need to periodically call this method to get any changes.

HTTP Request

GET https://business.awardwallet.com/api/export/v1/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 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

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,
  "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://business.awardwallet.com/api/export/v1/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.

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

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

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