AwardWallet Hotel Reward Availability API

Introduction

The AwardWallet Hotel Award Search API enables developers to search for hotel reward availability and pricing in points across major loyalty programs. It is designed for applications that need reliable, up-to-date award inventory data to power hotel search, comparison, and booking experiences.

This RESTful API operates asynchronously. Developers submit a hotel search request, which is processed in the background, and retrieve results once available via callback or polling. The API returns detailed information about available hotels, including room types, redemption rates in points, cash co-pay amounts (if applicable), and property-level metadata.

The API supports flexible search parameters such as destination, travel dates, occupancy, and loyalty account credentials, allowing for both guest and account-based searches.

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 authentication token. This token is passed in the "X-Authentication" field in the HTTPS request header. The token is formed by concatenating the API username and API password with a ":" symbol. You need to contact us to get your API credentials.

X-Authentication: YourUserName:YourPassword

Providers

List supported providers

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

Request

GET https://ra-hotels.awardwallet.com/v1/providers/list

Response Example

                            
{
  "apiVersion": 1,
  "providers": [
    {
      "code": "goldpassport",
      "displayName": "Hyatt (World of Hyatt)",
      "shortName": "Hyatt",
      "loginRequired": false,
      "login": {
        "code": "Login",
        "title": "Membership Number or Username",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      },
      "login2": {
        "code": "Login2",
        "title": "Last Name",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      },
      "password": {
        "code": "Password",
        "title": "Password",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      }
    },
    {
      "code": "hhonors",
      "displayName": "Hilton (Honors)",
      "shortName": "Hilton",
      "loginRequired": false,
      "login": {
        "code": "Login",
        "title": "Username or Hilton Honors #",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      },
      "password": {
        "code": "Password",
        "title": "Password",
        "options": [
          
        ],
        "required": true,
        "defaultValue": ""
      }
    }
  ]
}

Response

Supported providers information

Parameter	Type	Required	Description
apiVersion	integer	true	Version of the API being used.
providers	array	true	An array of providers for which we support parsing reward availability data

ProviderItem

Parameter	Type	Required	Description
code	string	true	Alpha-numeric value with no spaces that uniquely identifies any given provider
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. British Airways (Executive Club)
shortName	string	true	Short name of the provider, typically without the name of the loyalty program, i.e. British Airways
loginRequired	boolean	true	Indicates whether a loyalty account is required to perform a search
login	object	true	Describes the `loyaltyAccount.login` input parameter.
login2	object	false	Describes the optional `loyaltyAccount.login2` input parameter.
password	object	true	Describes the `loyaltyAccount.password` input parameter.

InputParameter

Parameter	Type	Required	Description
code	string	true	Field code is used by developers to identify the type of this field, i.e. “Login”
title	string	true	User-friendly name of the field
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
required	boolean	true	Even if the options array gives you an empty string as an option, if this field is set to true the corresponding parameter is required
defaultValue	string	false	The default value that we expect for this field

Search

Submit a hotel search request

This method allows you to place a single hotel search request into a queue for data to be retrieved

Request Example

                            
{
  "provider": "marriott",
  "destination": "Atlanta, Georgia, United States",
  "checkInDate": "2027-04-16",
  "checkOutDate": "2027-04-18",
  "numberOfRooms": "1",
  "numberOfAdults": "2",
  "numberOfKids": "0",
  "callbackUrl": "https://your.callback.url/get/results",
  "priority": 9,
  "userData": "some_test_value",
  "downloadPreview": true,
  "loyaltyAccount": {
    "login": "JSmith",
    "login2": "US",
    "password": "Password1234",
    "answers": [
      {
        "question": "We\u2019ve sent a security code to your email",
        "answer": "1234"
      }
    ],
    "browserState": "x7hxa87s87as\u2026xm89s"
  }
}

Request

POST https://ra-hotels.awardwallet.com/v1/search

Request Parameters

Parameter	Type	Required	Description
provider	string	true	Alpha-numeric value with no spaces that uniquely identifies any given provider. Can be retrieved from the `/providers/list` method
destination	string	true	At what destinations are you looking to find hotels
checkInDate	string	true	Desired hotel check-in date in the following format `2023-04-16`
checkOutDate	string	false	Desired hotel check-out date in the following format `2023-04-18`
numberOfRooms	integer	true	Number of rooms you want to search for. At the moment we only support searching maximum for 2 rooms
numberOfAdults	integer	true	Number of adults per room (maximum 4)
numberOfKids	integer	true	Number of kids per room (maximum 4)
downloadPreview	boolean	false	If set to true, the API will retrieve the hotel preview image and pass it as base64 encoded string
priority	integer	true	Request priority values range from 1 to 9, where 1 is the lowest priority and 9 is the highest priority. In some cases, we throttle requests with priorities lower than X (default is 9). Please use this attribute to separate background searches from foreground searches. In other words, background searches could have a priority of 1 (lowest), and hotel searches when an actual user is waiting for search results should be run with the priority of 9 (highest). This way, your background searches will never negatively impact your live users.
callbackUrl	uri	false	All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. Here is how it works. You send us a request for a hotel search, and we send you the response as soon as we finished parsing the website to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. To register your callbacks, we do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks: Content-type: 'application/json' Authorization: 'Basic YXdhcmR3YWxsZXQ6cGFzc3dvcmQ=' where `YXdhcmR3YWxsZXQ6cGFzc3dvcmQ=` is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password When we send our callbacks, we expect to receive code 200. If we get anything other than code 200, we will keep re-trying to send you the response. The page itself can be empty as long as we get code 200
userData	string	false	Any data you wish to send. It will be returned untouched in the response. Could be used for matching requests to responses
loyaltyAccount	object	false	Loyalty program account credentials to use in the search

Response Example

                            
{
  "requestId": "660d54da7s34d8ee39e29584"
}

Response

Search response

Parameter	Type	Required	Description
requestId	string	true	An ID that uniquely identifies this request. You can use this value to get the results of this update request using the `/getResults/{id}` method

LoyaltyAccount

Parameter	Type	Required	Description
login	string	true	User's login value to be used to login to the provider's website
login2	string	false	Second login value. I.e. “Last name”
password	string	true	User's password value to be used to login to the provider's website
answers	array	false	List of `answer` objects, containing information about security questions or one-time codes
browserState	string	false	When you update accounts that have security questions for the first time, you will get a browserState attribute back from us. Please store it on your end and send it with your next account update so the user isn’t prompted for security questions again

Retrieve hotel search results

This method allows you to query our API using the requestId attribute you received from the /search method, it should only be used during testing or debugging. For production use, a callback URL should be used instead to receive the results as soon as we have them

Request

GET https://ra-hotels.awardwallet.com/v1/getResults/{requestId}

Request Parameters

Parameter	Type	Required	Description
requestId	string	true	The unique request ID returned by the `/search` endpoint.

Response Example

                            
{
  "requestId": "12345678900987654321",
  "userData": "some text",
  "state": "success",
  "requestDate": "2022-03-22T18:08:18+00:00",
  "hotels": [
    {
      "name": "Fairfield Inn & Suites Atlanta Downtown",
      "checkInDate": "2023-04-16",
      "checkOutDate": "2023-04-18",
      "roomType": "Standard Room Reward",
      "rooms": [
        {
          "type": "Suite",
          "name": "One Bedroom King Suite (Plus Sofa Bed)",
          "description": "Our one-bedroom suite features a plush king bed, separate living room with sectional sleeper sofa, and a kitchen amid 396\u2013600 square feet.",
          "rates": [
            {
              "name": "Standard Suite Points Plus Cash",
              "description": "STANDARD SUITE POINTS PLUS CASH - Valid on 1-Bedroom Suite only. - Standard guarantee/cxl policy changed to Standard Rate.",
              "pointsPerNight": 13500,
              "cashPerNight": 230
            },
            {
              "name": "Lp Suite Pts Upgr",
              "description": "WORLD OF HYATT SUITE POINT UPGRADE - Valid on 1-Bedroom Suite only. - Standard guarantee/cxl policy",
              "pointsPerNight": 6000,
              "cashPerNight": 113
            }
          ]
        }
      ],
      "hotelDescription": "Newly renovated historic downtown property with spacious suites & fully equipped kitchens.",
      "numberOfNights": 4,
      "distance": 0.3,
      "rating": 3.6,
      "awardCategory": 4,
      "numberOfReviews": 1454,
      "phone": "+1 404-698-3514",
      "hotelURL": "https://www.marriott.com/hotels/alfo-four-points-atlanta-downtown/",
      "preview": "/9j/4AAQSkZJRgABAQI\u2026",
      "address": {
        "text": "136 West 42nd Street, New York, New York, 10036, USA",
        "addressLine": "136 West 42nd Street",
        "city": "New York",
        "stateName": "NY",
        "countryName": "US",
        "postalCode": "10036",
        "lat": 40.7551598381,
        "lng": -73.985726818
      }
    }
  ],
  "question": "Please enter the verification code that was sent to you",
  "browserState": "jxaAS78cs0DAS\u20268cjSDH7sd2DHS"
}

Response

Search result response

Parameter	Type	Required	Description
requestId	string	true	An ID that uniquely identifies this request
userData	string	true	This field returns whatever data you put in it when you made your request as is. Can be used for some sort of tracking
state	string	true	queued_up – The hotel search data has not yet been retrieved from the provider’s website. Please repeat your request again later to get the results. success - Hotel search data has been successfully retrieved. invalid_credentials - The provider did not accept user credentials that are being used to perform the searches. security_question - The provider requires an answer to a security question or a 2-factor authorization provider_error - Error. The provider has returned some error or requires some additional user action, such as updating personal information. unknown_error - An Unknown Error occurred, something unexpected happened, and AwardWallet failed to retrieve the data. warning - Hotel search data was successfully retrieved; however, there was some type of warning. The warning message is returned in the message field. timeout - Retrieving hotel search results took too much time. The request timed out.
message	string	true	Human-readable error message
requestDate	string	true	Date and time of when the request was sent to us, i.e., when the reward availability search was put into our queue
hotels	array	true	An array of available hotels that we found for this search
question	string	false	Security question
browserState	string	false	Browser state, such as cookies and other info. Please store this data on your end with the account and always send it back to us for any subsequent requests

Hotel

Parameter	Type	Required	Description
name	string	true	The name of the hotel
checkInDate	string	true	Hotel check-in date
checkOutDate	string	false	Hotel check-out date
rooms	array	true	An array of available rooms that we found for this hotel
hotelDescription	string	false	Hotel description, if available, such as “Newly renovated historic downtown property with spacious suites & fully equipped kitchens.”
numberOfNights	integer	true	The number of nights being booked
pointsPerNight	integer	true	Average cost in points per night for this room. If you need to know the total cost in points for this stay you need to multiply this number by the number of nights being booked
fullCashPricePerNight	number	true	Alternative cost of this room in cash (USD)
originalCurrency	string	false	Currency in which a request is made. If a request is made in USD, this field will be empty
conversionRate	number	false	If we converted the prices from one currency to USD, we will specify the conversion rate in this attribute
distance	number	false	Distance from the address in miles
rating	number	false	Hotel star rating where 5 starts is the highest rating
awardCategory	integer	false	Hotel award category
numberOfReviews	integer	false	This number indicates the number of people who rated this hotel
phone	string	false	Hotel phone number
hotelURL	string	false	URL address of the hotel
preview	string	false	Base64 encoded image of the hotel as shown on the hotel website
address	object	true	Detailed address object

DetailedAddress

Parameter	Type	Required	Description
text	string	true	The address of the hotel as it appears on the hotel’s website
addressLine	string	false	Just the street address part of the hotel
city	string	false	City part of the address
stateName	string	false	State part of the address
countryName	string	false	Country part of the address
postalCode	string	false	Postal code part of the address
lat	number	false	Latitude coordinate of the hotel
lng	number	false	Longitude coordinate of the hotel

Room

Parameter	Type	Required	Description
type	string	false	The type of the room
name	string	true	The name of the room
description	string	false	Room description, if available, such as “With one king bed”
rates	array	true	An array of available rates that we found for this room

Rate

Parameter	Type	Required	Description
name	string	false	The name of the rate
description	string	false	Rate description
pointsPerNight	integer	true	Cost in points per night for this room. If you need to know the total cost in points for this stay, you need to multiply this number by the number of nights being booked
cashPerNight	number	false	Additional cost of this room in cash (USD)
originalCurrency	string	false	Currency in which a request is made. If a request is made in USD, this field will be empty
conversionRate	number	false	If we converted the prices from one currency to USD, we will specify the conversion rate in this attribute

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

查找 AwardWallet 的商標、橫幅或螢幕截圖？

我們將其井然有序地整理在此頁面：

AwardWallet Hotel Reward Availability API

Introduction

Authentication

Providers

List supported providers

Request

Response

ProviderItem

InputParameter

Search

Submit a hotel search request

Request

Request Parameters

Response

LoyaltyAccount

Retrieve hotel search results

Request

Request Parameters

Response

Hotel

DetailedAddress

Room

Rate

Errors