Skip to main content

Use Cases

The Hotel Lead Availability API returns Lead rates over a date range for one or more hotels. The output is a list of hotels and for each hotel, if it is available, failure reason(s) and pricing information including:

  • Average: The total price of all products divided by the number of products. The amount does not reflect the price of a specific product.
  • Maximum: The maximum total priced product.
  • Minimum: The minimum total priced product.
  • Maximum Average: The maximum daily average across all products. The amount does not reflect the price of a specific product.
  • Minimum Average: The minimum daily average across all products. The amount does not reflect the price of a specific product.
  • Maximum First Night: The maximum first-night price across all products.
  • Minimum First Night: The minimum first-night price across all products.
  • Maximum Highest Price with Inclusive Tax: The maximum highest room price inclusive of taxes across all products.
  • Minimum Highest Price with Inclusive Tax: The minimum highest room price inclusive of taxes across all products.


Usage Notes

  • Hotel Lead Availability uses a cache with a max life of 5 minutes. If you are testing with the exact same request, then it will pull the data from cache if it exists.
  • If there are no products available then the response will return pricing for the unavailable products. However, if there is at least 1 available product the response will only include the available product(s).
  • If the request includes a roomCode and either a rateCode or rateFilter then only combinations of those products are returned in the response. If there is no availability, then no other rooms or rates will be evaluated. The only way to search for “alternate” availability is if the request only includeds a roomCode or rateCode/rateFilter but not both.


REST Method/Endpoint

Method Endpoint
GET https://[environment]/v1/api/hotel/leadAvailability


Basic Search

Basic parameters are used in all searches and are the foundation with which additional use cases can be added.

  • Unqualified searches: Occur when only general availability products are part of the request.
  • To request generally available products: Only minimum required inputs are required.
Parameter Description
adults Number of adults staying in the room.
Type: Integer
Required
children Number of children staying in the room.
Type: Integer
childrenAge Ages of children
Type: Integer
chainId Unique ID that identifies hotel chain or management group in SynXis
Type: Integer
Required
hotelId ID that uniquely identifies a single hotel property in SynXis CR
Type: Integer
primaryChannel SynXis CR booking channel code (use for content customization)
Type: String
Required
secondaryChannel SynXis CR booking channel code (use for content customization)
Type: String
Required
numRooms Number of rooms requested
Type: Integer
Required
startDate Start date for requesting availability
Type: String
Format: yyyy-mm-dd
Required
endDate End date for requesting availability
Type: String
Format: yyyy-mm-dd
Required


Sample Request

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-20&endDate=2022-11-22&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB


Sample Response (Partial)

The response includes one leadAvailabilityList item per hotel for the specified @startDate and @endDate.

{
    "paging": {...},
    "leadAvailabilityList": [
        {
            "Hotel": {...},
            "AllocationBlockList": [],
            "LeastRestrictiveFailure": [...],
            "Failures": [...],
            "Price": [...],
            "PriceGroup": [...],
            "Available": true,
            "ArrivalDate": "2022-11-20",
            "DepartureDate": "2022-11-22"
        }
    ]
}


Qualified Search

A qualified search is a Hotel Availability request with additional search criteria to find protected or otherwise private rates, exclude rates/rooms or limit the products. A qualified search response contains a priceGroup node that provides pricing information only for the qualified searched products. The priceGroup node mirrors the price node but is specific to qualified searched products whereas the price node contains information across all products.

The price and priceGroup nodes provide a comparison between qualified searched products and all the products included in the general response.

For example, if a search request includes rate codes 'BAR' and 'ADV', then the response contains a priceGroup list item for both 'BAR' and 'ADV' along with a price list item across all products in the search results.

Use @onlyCheckRequested=true to limit the response to only include products that match the qualified search criteria.


Access Code

Access Code - Corporate, Group or Promotion

Include Corporate, Group, or Promotion Access codes to return associated rates Rates in the availability response. The response is almost identical in terms of structure to the unqualified search but it includes more products since the access code unlocks the usage of additional products.

Note: For a Corporate code search, the system will look for a Hotel-level company profile first and if not found then a Chain-level profile.

Parameter Description Type
accessCode Access code String
accessType Access code type.
Values: corporate, group, promotion
String
onlyCheckRequested If true, the system will only check for product availability based upon the requested parameters. Boolean

Sample Request

Request for Corporate access code

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&accessCode=DELL&accessType=corporate


Request for Promotion access code

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&accessCode=50PCTDISC&accessType=Promotion


Request for Group access code

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&accessCode=ABA&accessType=Group


Note: An invalid access code will result in a warning.

    "Warning": [
        {
            "Code": "InvalidPromoOrCorporateCode",
            "Value": "DELL2"
        }
    ]


Agent - Booker, Chain Agent, or Travel Agent specific rates

Unlock rates assigned to a Booker, IATA Agency, or Chain Agent.

Parameter Description Type
agentId ID associated to an agent String
agentType Agent Type
Values: Booker, ChainAgent, or IATA
String

Samples Request

Request for rates assigned to a Booker profile

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&agentId=12075c7a-6a21-4402-94b6-600a19f2983d&agentType=Booker


Request for rates assigned to a Chain Agent

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&agentId=VA263474&agentType=ChainAgent


Request for rates assigned to a Travel Agent

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&agentId=05620860&agentType=IATA


Calendar Availability

Request pricing elements per night by length of stay, per hotel, across a stay interval by populating the @lengthOfStay parameter

Parameter Description Type
lengthOfStay Length of stay used when requesting nightly (i.e. Calendar) availability.
If populated, the system returns Nightly Availability for the length of stay.
If not, populated the system returns Lead Availability.
Number


Request

Sample request with startDate=2022-11-20, endDate=2022-11-22 and lengthOfStay=3.

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&startDate=2022-11-20&endDate=2022-11-22&lengthOfStay=3


Response (Partial)

The response includes leadAvailabilityList items for each night and lengthOfStay.

{
    "paging": {...},
    "leadAvailabilityList": [
        {
            "Hotel": {...},
            "AllocationBlockList": [],
            "LeastRestrictiveFailure": [...],
            "Failures": [...],
            "Price": [...],
            "PriceGroup": [...],
            "Available": true,
            "ArrivalDate": "2022-11-20",
            "DepartureDate": "2022-11-23"
        },
        {
            "Hotel": {...},
            "AllocationBlockList": [],
            "LeastRestrictiveFailure": [...],
            "Failures": [...],
            "Price": [...],
            "PriceGroup": [...],
            "Available": true,
            "ArrivalDate": "2022-11-21",
            "DepartureDate": "2022-11-24"
        },
        {
            "Hotel": {...},
            "AllocationBlockList": [],
            "LeastRestrictiveFailure": [...],
            "Failures": [...],
            "Price": [...],
            "PriceGroup": [...],
            "Available": true,
            "ArrivalDate": "2022-11-22",
            "DepartureDate": "2022-11-25"
        }
    ]
}


Central Reservations Office (CRO) Rates

Search for rates assigned to CRO by including @croId in the request. Additionally, a CRO search can request availability for the previous day when the date is already past midnight. This functionality allows a late arriving guest to still get a room for the night, even if the night is past midnight. (This functionality is configurable in the SynXis CR.) Example: If today is January 3 at 3:00 AM, a CRO request can shop for dates of Jan 2 – Jan 3.

Parameter Description Type
croId SynXis CR ID for a Central Reservation Office (CRO). String


Request for CRO rates

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&croId=14160760


Currency Code

Rates can be set up in the Hotel’s default currency or in alternate currencies. By default, the response only contains rates set up in the default currency.

Including @currencyCode in the request, the system will evaluate rates configured in the requested currency and perform currency conversion on rates not loaded in the specified currency.

Note: Converting rates to the requested currency is only done as a courtesy for the client. Rates must be booked and paid for in the currency they are configured, not based on currency conversion.

Parameter Description Type
currencyCode ISO 4217 three alpha currency code. String


Request for a specific currency code

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&currencyCode=EUR


Loyalty Program

Use a qualified search to check availability based on loyalty program code and level.

Note: Point Redemption Rates are not supported in the Lead Availability API. Only cash rates or the cash amount for Points or Cash rates are supported.

Parameter Description Type
loyaltyProgram Loyalty program code String
loyaltyLevel Code associated with a loyalty program level (i.e. SILVER, GOLD, PLATINUM) [String]
onlyCheckRequested If true, the system will only check for product availability based upon the requested parameters. Boolean


Request for rates assigned to a loyalty program and level

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&children=1&childrenAge=10&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&loyaltyProgram=MyLoyalty&loyaltyLevel=GOLD


Price Range

The search results can be filtered by specifying a minimum and/or maximum price, a price type and a currency type.

Parameter Description Type
priceRangeMin Low-end price range to include in the results Number
priceRangeMax High-end price range to include in the results Number
priceRangeType Indicates which value the min / max price range should apply. Required for a price range search.
Values: Average, FirstNight, Highest, HighestInclusiveTax, Lowest, Total
String
priceRangeCurrency Indicates which currency the min / max price range should apply
Values: HotelDefaultCurrency, RequestedCurrency
String


Pagination

Use pagination to access the response data in smaller sets.

Parameter Description Type
pageStart Indicates the starting record to be returned in the response. Integer
pageSize Indicates the number of records to return in the response (0 = return the maximum size of 100). Integer


Request using pagination

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&pageStart=2&pageSize=75


Successful Response (partial)

A successful response will return a Paging node. The values from the paging node can be used to access the data in smaller sets.

Parameter Description Type
paging/@Size Number of records returned in the response Integer
paging/@Start Starting record returned in the response Integer
paging/@Total Total number of records Integer


    "paging": {
        "Size": 51,
        "Start": 0,
        "Total": 51
    }


Rate

Search for specific rate codes in the availability results.

Parameter Description Type
rateCode Rate Code [String]
onlyCheckRequested If true, the system will only check for product availability based upon the requested parameters. Boolean


Request for one rate code

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&onlyCheckRequested=true&rateCode=ADV


Request for multiple rate codes

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&onlyCheckRequested=true&rateCode=ADV,BAR


Rate Class

Include or exclude rates assigned to a rate class from the search by passing in one or more rateClass or rateClassExclude values.

Note: A request can contain both rateClass and rateClassExclude parameters.

Parameter Description Type
rateClass Rate class types to include
Values: Association, Convention, Corporate, Government, Military, Negotiated, Package, Promotional, Rack
[String]
rateClassExclude Rate class types to exclude
Values: Association, Convention, Corporate, Government, Military, Negotiated, Package, Promotional, Rack
[String]
onlyCheckRequested If true, the system will only check for product availability based upon the requested parameters. Boolean


Request to include a rate class

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&onlyCheckRequested=true&rateClass=Negotiated


Rate Filter

Search for rates associated with a Rate Filter code.

Parameter Description Type
rateFilter Code associated with a rate filter [String]
onlyCheckRequested If true, the system will only check for product availability based upon the requested parameters. Boolean


Request for a specific rate filter

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&onlyCheckRequested=true&rateFilter=HOTRF99


Room Code

Search by specific room codes.

Parameter Description Type
roomCode Room Code [String]
onlyCheckRequested If true, the system will only check for product availability based upon the requested parameters. Boolean

Request for a specific room code

/v1/hotel/leadAvailability?chainId=12723&hotelId=13098&adults=2&startDate=2022-11-10&endDate=2022-11-12&numRooms=1&primaryChannel=WEB&secondaryChannel=WEB&onlyCheckRequested=true&roomCode=A1K