The Impala API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses.

To make the API as explorable as possible, accounts have a test and a live mode, differentiated by API key. There is a toggle at the bottom of the Impala Management Console sidebar on the Hotels, API and Webhooks pages. The toggle allows you to navigate between Live and Test mode. Requests made with test mode credentials never hit real hotel data and instead provide a response from your very own sandbox hotel, called "The Charleston". The Charleston is running on the Impala PMS, which supports all of the below mentioned resources. Note that once you are working in the live mode and with the real data, the hotel system will only support the resources, actions and fields that are supported, as highlighted in this documentation.

At the moment, we have paused accepting new customers to our Impala Stay. You can sign up here to join the list to be part of the next onboarding of new customers.

In the meantime, if you wish to have a look at our Impala Stay API documentation to see the integrations we support and the different data points. You can also find more additional resources about Impala and our technology in our Help Center.

Should you have any questions you can contact us at support@impala.travel.

If you already have an account, please follow the steps to get started: Sign in to the Impala Management Console to retrieve your test API key and the hotel ID of your sandbox hotel (called "The Charleston").

1. Sign in to the Impala Management Console.
2. Make sure you're in Test mode.
3. Pick up your test API key and the hotel ID for your very own sandbox hotel ("The Charleston"), complete with pre-loaded data similar to a real hotel.

Once you've tested your application with sandbox hotel data in Test mode, you're ready to get connected to a real hotel:

1. In the Impala Management Console, switch to Live mode.
2. Make sure your production app uses your live API key.
3. Go to the "Hotels" section of your application in the Management Console and request access to the hotel you want to connect to.
4. The Impala onboarding team will get in touch with the hotel contact you provided, and establish the connection.
5. Once data is flowing (typically within 72 hours after you first requested data), the hotel will be shown as "Live" in your Management Console.
6. You can now start accessing this hotel's data.

The Impala API requires you to use Bearer Token-based authentication to access the API for the hotels you connect to.

Every application in the Impala Management Console comes with two API keys (tokens):

• a Test mode API key to access your sandbox hotel.
• a Live mode API kley to access all the real hotels you connect to.

With every API request, you'll need to send the following request header:

Authorization: Bearer {Your API Key}

If your API key has been compromised at any point, please use the "Regenerate secret key" button in the Impala Management Console immediately.

All fields in the API can return null.

If a value is null, it is…

• …because the hotel system doesn't support the respective field.
• …because the value is in fact null in the hotel system.

Please familiarise yourself with the supported fields for each of our supported hotel systems using the support listed in this documentation. Let us know if your use case requires a particular field that's currently unsupported for a hotel property management system that you want to integrate with.

A value which can be an array will be null if the PMS doesn't support the value, and will be an empty array if it is supported by the hotel property management system but there are no values in it.

Similarly for objects, a value which can be an object will be null if not supported by the PMS. If supported by PMS it will be an object with its possible values all returning null.

Results returned as lists of resources, such as the /bookings or /rate-plans endpoints are paginated.

The response will contain a data property with the result of your query, and any pagination-related information will be returned in the _meta property.

Impala uses cursor-based pagination, which means that instead of passing in a limit and offset, every page returns a unique pointer to the next and previous page. This allows you to navigate through pages without data shifting around from changes ocurring between requests.

The Impala API uses standard HTTP error and status codes to communicate errors. To provide additional context, you'll se an additional JSON response body which includes message and type properties with further information.

{
	"type": "NOT_FOUND",
	"eventId": "678c54b5-eb23-4bc7-9410-4b720f22e3c0",
	"message": "Not found."
}

The message property contains an explanation specific to that error. This is the property that is most useful to a human.

The type property can be thought of as an error code. They provide Impala specific error types in addition to the HTTP status code.

The eventId property is a reference to this specific error instance. Please include this information when contacting our support team, as it helps to identify and diagnose the error.

Each application that you create has an API version stored against it. Unless overridden, this version will be used when making API requests and controls the status codes used and format of requests / responses. You can change the version of your application(s) in the Impala Management Console.

To override the version for a single request, use the X-API-Version header. Please note that you can't use a version lower than the one configured against your application.

You'll only be able to update to the latest version of the API once all hotel systems you currently connect to are available on this version.

Impala strives to map the data we receive from the various hotel property management systems into the fields documented for each resouce. This allows you to build your integration once, then sell to hotels on various systems without touching your code again.

If you need information that isn't mapped and documented, please send us an email to support@impala.travel and let us know.

Any infomation we receive from the hotel system, but don't currently map, is passed on in an object on each resource called _extras.

We can make no guarantees about what is contained within the _extras object or of what type they will be, we simply provide them as they arrive from the PMS.

As an example, take a look at this Area Type as it would be returned for a hotel running on Oracle Hospitality Opera. You'll find the properties that are mapped, like the id and name. You can rely on these being available and mapped for any hotel system. As a convenience, we're also providing all other data Opera specifically provides, but that wouldn't be available for any other hotel property management systems in the _extras field.

{
  "id":"SP",
  "name":"Superior Room",
  "code":"SP",
  "description":"Superior Room with Park View",
  "maxOccupancy":2,
  "parentAreaTypeId":null,
  "_extras":{
    "COMPONENTS":null,
    "FEATURE_LIST":"Parkview",
    "DEF_OCCUPANCY":"1",
    "HOUSEKEEPING":"Y",
    "YIELDABLE_YN":"N"
  },
  "_meta":{
    "lastRefreshedAt":1553770855
  }
}

Each response contains a _meta object with information on the freshness of the data and which hotel property management system it's sourced from.

Data freshness describes the length of time it takes to collect, process, and deliver data via our API. Thanks to our low latency processing pipeline we typically process data in less than a minute from the time we receive it. This means that, where the PMS allows it, we can provide near real-time updates on your data.

Reservation, Stay, Booking: hotel property management systems use different terminology for very similar concepts. At Impala, we flatten this down to two resources:

• Booking Sets contain one or more bookings.
• Bookings represent guests staying in one room or hostel bed (called an Area in Impala) over concurrent nights.

Imagine calling a hotel and asking to book a room for you and a room for a friend. You will have effectively created one Booking Set with two Bookings in the hotel property management system.

Much like bookings, every hotel property management system deals with room rates in a slightly different way. At Impala, we distil this into two rate resources:

• Rate Sets are groups of various Rate Plans.
• Rate Plans are the smallest units of a rate that share a name, description and common Rate Restrictions.
• Rate Restrictions are the rules that apply to bookings made with this rate plan.
• Rate Prices are the nightly rates that result when a rate plan is applied to a specific date and area type (Impala's terminology for rentable areas, such as rooms or hostel beds) combination.

As an example, a hotel might handle a rate set of "Deal Rates". It could contain two rate plans, "Advance Purchase 30 Days" and "Advance Purchase 90 Days". Both of them come with rate restrictions to ensure the rate is only bookable up until 30 or 90 days before the arrival date. When requesting a rate for a "Deluxe Room" area for a rate 60 days out, only "Advance Purchase 30 Days" would return a specific nightly rate of 120 USD.

For resources like Bookings, Charges and Extras we're handling a few financial properties:

• grossAmount
• netAmount
• taxAmount
• taxRate

Some hotel property management systems might only support a selection of these properties. In general netAmount added up with taxAmount would result in grossAmount.

Webhooks allow you to subscribe to changes in data and receive details of the change to a URL of your choice. Webhooks can be added on a per-application basis from within the Impala Management Console.

The User-Agent header for the requests will have a prefix of Impala-Hookshot/. If you reply on the contents of webhook notifications, make sure to verify their authenticity.

Webhook notifications are triggered based on the latency we support for each hotel system. In most cases, we fetch data between every minute to every 24 hours, at which point we detect difference and distribute webhook notifications.

For questions around update times for your specific use case contact us via email or live chat.

An allocation or group block is a set of area types that have been blocked for booking and allocated to a certain Contact.

The Area that the hotel or hostel is renting out. They're most commonly rooms, chalets, cabins or hostel beds in dormitories.

Why is it called an Area, not a Room?

Impala, like the PMS we support, handle different types of accommodation. In some instances, such as in a hostel, accommodation providers are not just selling "rooms" but additionally other inventory.

As such Impala uses the concept of an Area rather than a Room and an Area Type rather than a Room Type.

Typically there's no complexity in the implementation (hostels simply have more Areas). However, you should take note where the hotel/hostel composes rentable areas from other rentable areas. This can happen in the case of virtual suites (a suite made up of, for example, a Double Room and a Single Room with connecting doors). This can also happen if the hostel rents out whole dormitories as well as the beds inside.

Typically the category of the bookable area, room or hostel bed. Examples might include things like a "Deluxe Room" or "Bed in Female Dorm". These are typically the categories that are priced distinctly and booked by guests. Before or during the check-in of a guest, the hotel or hostel typically assigns the specific Area within the booked Area Type the guest will be staying in.

A Bill is a container of Charges and Payments.

A Booking Set represents the container for one or more Bookings. This container has metadata relevant to the set of bookings.

It's possible that the PMS itself doesn't offer something mappable to this resource, in which case we will create a virtual booking set.

A Booking represents a reservation for an area (type) on specific dates.

For any supported hotel systems, we strive to enable you to query Bookings up to one year in the past and future.

A Charge is an incurrence of debt at the property. Charges belong to a Bill.

Bookings might reference Companies. This typically happens when a guest was booked through a Travel Agency, or when they're a business traveler on a work-related trip for their employer.

Most hotel systems use this information to source the correct address for invoicing, and in many cases hotels use this data to aggregate the booking volume they receive from these Companies on an ongoing basis.

An Extra represents any good or service being sold by the hotel that isn't a room (although it could be a room upgrade).

For any supported hotel systems, we strive to enable you to query Guest information for Bookings up to one year in the past and future.

A Payment is a transfer of credit from someone to the property. Payments belong to a Bill.

A Rate Plan is a set of prices with a common name and set of restrictions.

Bookings that span multiple nights may have different prices each night. This value breaks down the price for each period defined by the duration.

The rate amounts returned are as listed on e.g. a booking confirmation and might include room, F&B (e.g. breakfast) and other extra services.

The Contact is an entity that is responsible for something (e.g. the primary booker for a booking).

Where the Contact already exists with the PMS then type and id should be used, where the Contact is to be created, type and data should be used.

A Contact By Info is a description of which methods of communication a guest has given permission for the hotel to use.

Any document represented by Impala. E.g. supplied by a Guest at check-in.

An Opt-In Info is a description of which topics of communication a guest has opted in to receive. This information should be used in conjunction with Contact By Info.

A Rate Price represents the price of a rate plan given a particular area type (or base price) on a particular date.

Please note that supplements and restrictions may appear on the RatePrice object rather than the parent RatePlan in PMS where there are restrictions and supplements per Area Type.

A Rate Restriction is a reason why a rate wouldn't be applicable. Each restriction will only contain a subset of these fields depending on the type value. See Rate Restriction Types for a list of types and fields. The type, daysCovered, createdAt and updatedAt fields apply to all types and could be present on any restriction regardless of type.

daysCovered can be one of the following:

• MONDAY
• TUESDAY
• WEDNESDAY
• THURSDAY
• FRIDAY
• SATURDAY
• SUNDAY

A Rate Supplement represents something additional to the standard rate price of an Area that may need to be paid.

An Allocation Status typically represents how concrete an allocation is:

An Amount Description is a description of a value which could either be fixed, derivative or supplementary to another Amount Description.

AmountDescriptionType - The type of the value field is dependent on the type field.

Either:

A Bill Status is a string with the following possible values:

BillingScheme is a string that has one of the following values (dependent on the PMS). If unlisted below, the PMS doesn't support differing BillingScheme and so in all likelihood ONCE can be inferred.

BillingFrequency is a string that indicates how often the billing is, i.e. when the billing happens.

A BookingStatus is a string representing the state of a booking. It has the following possible values:

A Booking Amount Breakdown Duration is a string representing the length of time a particular amount breakdown is for.

Company Type is a string with the following possible values:

An extra identifier by which to classify a guest.

This list represents the options that may be returned when reading from a PMS:

A Rate Restriction Type refers to the type that applies to a rate restriction.

A Rate Supplement Type describes how the Rate Supplement should be applied.

It is often used by PMS to describe tax.