canonical: https://jentic.com/apis/impala.travel/impala-hotel-bookings

# Impala Travel Impala Hotel Bookings API

The Impala Hotel Bookings API v2 is a streamlined hotel content, rates, and bookings interface from Impala. Across 8 endpoints it covers hotel search, hotel detail, room types, rates and availability, plus booking creation, retrieval, and cancellation. Authentication uses an x-api-key header. The v2 surface is smaller and more uniform than v1, making it the preferred starting point for new travel marketplace and concierge integrations.

## For AI agents

Search hotels, fetch room types and rates, and manage hotel bookings. Useful for travel marketplaces and AI travel agents.

## Scope

Does not handle flights, payments outside the booking flow, or activities - use for hotel search, rates, and booking lifecycle only.

## Capabilities

- Search hotels by destination and date range
- Retrieve detailed hotel content including amenities and imagery
- Pull available room types for a specific hotel
- Fetch rates and availability for date ranges
- Create a hotel booking with guest details
- Retrieve and cancel bookings via dedicated endpoints

## Use cases

### Travel Marketplace Hotel Search

Add hotel search and booking to a travel marketplace using the Impala Hotel Bookings v2 surface. The hotels and rates endpoints expose a uniform schema across thousands of properties so the marketplace does not need to integrate with individual channel managers.

Example prompt: Search hotels for 'Madrid' between 2026-08-10 and 2026-08-12, fetch the lowest-rate room type for the top result, and create a booking for one guest.

### AI Concierge with Hotel Booking

Power AI concierge experiences that recommend and book hotels via natural language. The agent calls the search and rates endpoints to compare options and books the chosen hotel through POST /bookings, returning a confirmation reference to the user.

Example prompt: Given a user request 'book a hotel in Lisbon under 150 EUR for two nights starting 2026-09-01', search hotels, pick the cheapest available room type, and confirm the booking on user approval.

### Cancellation Self-Service

Customer self-service flows can use POST `/bookings/{bookingId}/cancel` to cancel an existing reservation without operator intervention. The agent looks up the booking, confirms the cancellation policy attached to the rate, and triggers cancellation in one call.

Example prompt: Cancel booking BKG-44521 and return the cancellation confirmation id to the support ticket.

### Jentic-Driven Trip Planner

Expose Impala v2 to Jentic so a trip-planning agent can search hotels, fetch room types, and create bookings without learning the OpenAPI spec. The agent uses Jentic intent search to locate each operation and Jentic injects the x-api-key at runtime.

Example prompt: Plan a 3-night Lisbon trip: search hotels, list available room types for the top match, and create a booking for two guests with check-in 2026-10-04.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/hotels` | Search hotels |
| GET | `/hotels/{hotelId}` | Get hotel details |
| GET | `/hotels/{hotelId}/room-types` | Get room types for a hotel |
| GET | `/hotels/{hotelId}/rates` | Get rates and availability |
| POST | `/bookings` | Create a booking |
| GET | `/bookings/{bookingId}` | Get a booking |
| POST | `/bookings/{bookingId}/cancel` | Cancel a booking |

## Key resources

- **Hotels** — Search hotels and retrieve detailed hotel content
- **Room Types** — List available room types for a specific hotel
- **Rates** — Pull rates and availability across a date range
- **Bookings** — Create, list, retrieve, and cancel hotel bookings

## Why Jentic

- **Setup:** Wiring the Impala Hotel Bookings API by hand means setting up its x-api-key header against the api.impala.travel v2 host and handling hotel search, rates, and the booking lifecycle yourself. Through Jentic you install once, import the Impala Hotel Bookings API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Impala v2 puts the hotel id and booking id in the URL path (`/hotels/{hotelId}/rates`, `/bookings/{bookingId}`), so a rule can pin your agent to one booking. You choose the operations it may call, so the cancel-booking operation is not included unless you add it.
- **Credential handling:** Your Impala x-api-key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search hotels' or 'create a booking', and Jentic returns the matching Impala v2 operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Impala Hotel Booking API v1** — Earlier v1 surface from Impala with rate calendar and payment JWT flow
- **Booking.com** — Large OTA with broad hotel inventory and affiliate booking flow
- **Cloudbeds** — Property management system useful for hoteliers receiving reservations

## FAQ

### What authentication does the Impala Hotel Bookings API use?

The API uses an x-api-key header issued from your Impala account. Through Jentic, the key is stored in the encrypted vault and the agent receives a scoped Jentic token, so the raw key never enters the agent context.

### Can I search hotels by destination with this API?

Yes. GET /hotels accepts search parameters and returns a list of hotels. You can then call GET `/hotels/{hotelId}` to pull content, GET `/hotels/{hotelId}/room-types` for inventory, and GET `/hotels/{hotelId}/rates` for pricing.

### What are the rate limits for the Impala Hotel Bookings API?

The published spec does not state explicit rate limit numbers. Impala throttles per-account, so agents should monitor for 429 responses and back off, especially when running large search sweeps across multiple destinations.

### How do I create a hotel booking through Jentic?

Search Jentic for 'create a hotel booking' to surface the operation backed by POST /bookings on this v2 API. Load the schema, pass hotelId, room type, guest details, and dates, then execute. Jentic injects the x-api-key at runtime.

### How do I cancel a booking through this API?

Call POST `/bookings/{bookingId}/cancel` with the booking id. The response confirms cancellation; refund treatment is determined by the rate's cancellation policy at the time of booking.

### Should I use v1 or v2 of the Impala booking surface?

Prefer v2 for new builds. It has a smaller, more uniform set of endpoints and uses a simple x-api-key flow. Use v1 only when maintaining an existing integration that depends on the v1 rate plan model.

### Can I limit what my agent is allowed to do with the Impala Hotel Bookings API?

Yes. Because you run Jentic One yourself, your own rules decide which of the eight operations the agent can call, so you can allow hotel search, GET `/hotels/{hotelId}/rates`, and GET `/bookings/{bookingId}` while withholding POST `/bookings/{bookingId}/cancel` and POST /bookings until you explicitly add them. Since the hotel id and booking id sit in the URL path, a rule can pin the agent to a single hotel or a single booking rather than the whole account. Your Impala x-api-key stays stored by your own instance and is injected only at execution time, so the agent operates strictly within the scope you set.