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=WEBSample 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=corporateRequest 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=PromotionRequest 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=GroupNote: An invalid access code will result in a 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=BookerRequest 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=ChainAgentRequest 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=IATACalendar 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=3Response (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=14160760Currency 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¤cyCode=EURLoyalty 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=GOLDPrice 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=75Successful 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 |
"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=ADVRequest 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,BARRate 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=NegotiatedRate 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=HOTRF99Room 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