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.

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:

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

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.

Please note that for security reasons, this URL is only valid for 10 minutes.

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

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

Please note that for security reasons, the {code} that you get via a browser redirect
to your endpoint is only valid for 1 minute.

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

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

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.

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.

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.

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:

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.

Using a nemberId, 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.

Please note that each Account history field is limited to only the last 10 history elements. In order to get the full account history, you need to call the /account/{id} method described below.

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.

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.

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.

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.

Please note that each Account history field is limited to only the last 10 history elements. In order to get the full account history, you need to call the /account/{id} method described below.

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.

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

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.

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: