Retrieving Hotel Details & Room Availability
Once you've identified hotels from a search, you can retrieve full property details and check real-time room availability with pricing. This article covers both endpoints.
Get Hotel Details
Retrieve comprehensive information about a specific hotel, including photos, amenities, policies, and guest reviews.
Endpoint
GET /hotels/api/v2/property/{property_id}
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
propertyid | string | Yes | The hotel's propertyid from search results. |
Example Request
GET /hotels/api/v2/property/XN00012345Authorization: {signature}x-correlation-id: {correlation_id}Content-Type: application/json
Example Response
JSON
{
"data": {
"property_id": "XN00012345",
"name": "Oceanview Resort & Spa",
"ratings": {
"star_rating": 4,
"user_rating": 8.5,
"review_count": 1240
},
"contact": {
"address": {
"line_1": "123 Ocean Drive",
"city": "Miami Beach",
"state": "FL",
"country": "US",
"postal_code": "33139"
},
"phone": "+1-305-555-0100",
"email": "info@oceanviewresort.com"
},
"location": {
"lat": 25.7825,
"long": -80.1305
},
"amenities": [
"Free WiFi",
"Outdoor Pool",
"Spa",
"Fitness Center",
"Restaurant",
"Bar/Lounge",
"Room Service",
"Concierge",
"Valet Parking",
"Business Center"
],
"images": {
"thumbnail": [
"https://images.xeni.com/hotels/12345/thumb_1.jpg"
],
"large": [
"https://images.xeni.com/hotels/12345/large_1.jpg",
"https://images.xeni.com/hotels/12345/large_2.jpg",
"https://images.xeni.com/hotels/12345/large_3.jpg"
],
"extra_large": [
"https://images.xeni.com/hotels/12345/xl_1.jpg"
]
},
"highlights": [
{
"type": "location",
"description": "Located on the beachfront in Miami Beach, this resort is steps from the ocean and minutes from South Beach attractions."
}
],
"policies": [
{
"type": "checkinbegin_time",
"description": "Check-in starts at 3:00 PM"
},
{
"type": "checkouttime",
"description": "Check-out by 11:00 AM"
},
{
"type": "knowbeforeyou_go",
"description": "Resort fee of $35 per night is charged at check-in. Rollaway beds are available for $25 per night."
}
],
"accessibilities": [
"Wheelchair accessible",
"Accessible parking",
"Roll-in shower"
]
}
}Response Fields
| Field | Type | Description |
|---|---|---|
propertyid | string | Unique hotel identifier. |
name | string | Hotel name. |
ratings.starrating | integer | Star rating (1–5). |
ratings.userrating | number | Guest review score (0–10). |
ratings.reviewcount | integer | Total number of guest reviews. |
contact | object | Address, phone, and email for the property. |
location | object | Geographic coordinates (lat, long). |
amenities | array | Full list of hotel amenities. |
images | object | Photo URLs organized by size: thumbnail, large, extra_large. |
highlights | array | Property highlights (location descriptions, notable features). |
policies | array | Check-in/out times, fees, and know-before-you-go information. |
accessibilities | array | Accessibility features available at the property. |
*
Check Room Availability
Check which room types are available for a specific hotel, including real-time pricing and availability tokens needed for the booking flow.
Endpoint
POST /hotels/api/v2/properties/availability
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
propertyid | string | Yes | The hotel's propertyid. |
checkindate | string | Yes | Check-in date in YYYY-MM-DD format. |
checkoutdate | string | Yes | Check-out date in YYYY-MM-DD format. |
occupancy | array | Yes | Same occupancy format as the hotel search endpoint. |
countryofresidence | string | Yes | ISO 2-letter country code (e.g., "US"). |
Example Request
POST /hotels/api/v2/properties/availabilityAuthorization: {signature}x-correlation-id: {correlation_id}Content-Type: application/json
{ "propertyid": "XN00012345", "checkindate": "2025-06-01", "checkoutdate": "2025-06-05", "occupancy": [ { "adults": 2, "childs": 0, "childages": [] } ], "countryof_residence": "US"}
Example Response
JSON
{
"data": [
{
"id": "room_101",
"name": "Deluxe Ocean View King",
"descriptions": "Spacious room with king bed and panoramic ocean views.",
"sleeps": 3,
"amenities": [
"Air Conditioning",
"Mini Bar",
"Safe",
"Coffee Maker"
],
"images": {
"large": [
"https://images.xeni.com/rooms/101/large_1.jpg"
],
"small": [
"https://images.xeni.com/rooms/101/small_1.jpg"
],
"thumbnail": [
"https://images.xeni.com/rooms/101/thumb_1.jpg"
]
},
"rates": [
{
"base_rate": 756,
"total_rate": 891.08,
"taxandfees": 135.08,
"currency": "USD",
"cancellation_policy": "Free cancellation until 48 hours before check-in.",
"refundable": true,
"beds": [
{
"name": "1 King Bed",
"availability_token": "eyJhbGciOiJIUzI1NiJ9.room101..."
}
]
}
]
},
{
"id": "room_102",
"name": "Standard Double Room",
"descriptions": "Comfortable room with two double beds.",
"sleeps": 4,
"amenities": [
"Air Conditioning",
"Safe",
"Coffee Maker"
],
"images": {
"large": [
"https://images.xeni.com/rooms/102/large_1.jpg"
]
},
"rates": [
{
"base_rate": 620,
"total_rate": 730.24,
"taxandfees": 110.24,
"currency": "USD",
"cancellation_policy": "Non-refundable.",
"refundable": false,
"beds": [
{
"name": "2 Double Beds",
"availability_token": "eyJhbGciOiJIUzI1NiJ9.room102..."
}
]
}
]
}
]
}Critical: The response structure for availability is an array of rooms at data — not an object with a rooms property. Ensure your code handles this correctly: response.data is the array.
Availability Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Room type identifier. Needed for SSO checkout. |
name | string | Room type name. |
descriptions | string | Room description. |
sleeps | integer | Maximum occupancy for the room. |
amenities | array | Room-specific amenities. |
images | object | Room photos in large, small, and thumbnail sizes. |
rates[].baserate | number | Room rate before taxes (full stay). |
rates[].totalrate | number | Total price including taxes and fees. |
rates[].taxandfees | number | Tax and fee amount. |
rates[].currency | string | Currency code (e.g., "USD"). |
rates[].cancellationpolicy | string | Cancellation terms for this rate. |
rates[].refundable | boolean | Whether the rate is refundable. |
rates[].beds[].name | string | Bed configuration description. |
rates[].beds[].availabilitytoken | string | The token needed for the next step. Pass this to the pricing confirmation endpoint. |
Key concept: The availabilitytoken found at rates[].beds[].availabilitytoken is what you'll pass to the Pricing Confirmation endpoint. This token identifies the specific room, rate, and bed configuration the guest has selected.
What to Store
After a successful availability check, save these values from the response — they're needed for subsequent steps:
- Room ID (
id) — Needed for SSO checkout URL. - Availability token (
rates[].beds[].availability_token) — Needed to confirm pricing. - Property ID — Already known from search; needed for checkout.
*
](#article-5)_