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

                    
                        # TODO: With php. Build php example

                    
# 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

You need to replace userapikey with your personal API key.

Connect

Get Connection Link

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

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

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

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

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

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

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

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

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

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

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

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

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

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