Our Developer Documentation isn’t optimised for small screens yet. Please visit this site from a bigger device.

General

Introduction

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.

Get Started with Impala

It's free and simple to get started: Simply create an account, and 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. Simply create a free account.
  2. Sign in to the Impala Management Console.
  3. Make sure you're in Test mode.
  4. 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.

A great way to get a first idea of how the Impala API works, without writing code, is by using the following Postman Collection:

Run in Postman

You'll need to work in an Postman Environment and have the API_KEY and HOTEL_ID variables populated.

Creating an application

Once inside the developer web client, on the left hand side of the screen you'll have the option to create an application. The form prompts for two pieces of information; name, which is required and is used to help you identify your application, and description, which is optional but can be useful for storing extra information. Clicking 'Create' will save the application and take you to the application details screen where you'll see your application's ID, this will be used when calling the API along with your API key.

Connecting to Real Hotels

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.

Switching between Test and Live Mode

screenshot modes

There is a switch at the bottom of the sidebar that allows you to switch between Live and Test modes. There will be configuration that is specific for each of these, the screens you'll find this at are Hotels, API and Webhooks.

App Details

screenshot details

From this screen, you can see your application's ID, you can also use this page to update your application's name and description.

Connected Hotels

screenshot hotels

From this screen, you are able to see the list of hotels your application has access to. In the test mode, you are automatically given access to our sandbox hotel, The Charleston. Requesting access to a hotel in Live mode will start the process of connecting the hotel to Impala.

API

screenshot api

Here you can view your application's API key you'll need to use to connect to the Impala API. If you feel that your API key has been compromised, click the 'Regenerate Secret Key' to regenerate your key. Remember, that the keys are different for each mode.

Webhooks

screenshot webhooks

Here you can view your application's configured webhooks for each action. You can find out more about webhooks in the using webhooks section. Remember, that the configuration is different for each mode.

Organization Settings

screenshot org settings

On this screen, you'll be able to update your organization name and the users that have access to manage your organization's applications. You can add new team members by clicking the 'Add Team Member' button in the top right. You can also manage users' roles, they can either be:

Value Description
User Can read organisation data as well as read and write (but not delete) application data, including regenerating API keys.
Admin Full access to read, write and delete any data, including the ability to create new users.

Authentication

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.

Values returning
null

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.

Caveats

Dates

The dates returned by the API are all represented in Unix time in seconds.

Where possible dates will be returned in UTC. In the event a PMS doesn't specify a timezone dates will be returned as they are received which is normally the timezone of the hotel.

Where dates are passed in as query parameters they should be in the form YYYY-MM-DD.

Prices and Currencies

All prices returned by the API are represented as integer amounts in a currency’s smallest unit. For example, $5 USD would be returned as 500 (i.e, 500 cents).

For zero-decimal currencies, amounts will still be provided as an integer but without the need to divide by 100. For example, an amount of ¥5 (JPY) would be returned as 5.

The list of supported zero-decimal currencies is as follows:

Value Description
BIF Burundian franc
CLP Chilean peso
DJF Djiboutian franc
GNF Guinean franc
JPY Japanese yen
KMF Comoro franc
KRW South Korean won
MGA Malagasy ariary
PYG Paraguayan guaraní
RWF Rwandan franc
VND Vietnamese đồng
VUV Vanuatu vatu
XAF CFA franc BEAC
XOF CFA franc BCEAO
XPF CFP franc

All currency codes conform to ISO 4217.

paidAt
and
chargedAt

Please note that both are distinct from the concept of createdAt. Some hotel property management systems may treat chargedAt/paidAt as the same as when the record was created.

Resource IDs

All resources provide an ID through the id property. These are typically the unique identifier as they're handled in the hotel property management system, so these might look different depending on the hotel property management system.

In some cases we'll return a composite ID, consisting of several IDs needed to get to the hotel property management system's data, which won't directly map to an ID in the underlying PMS.

Country Codes

All country codes will be returned as ISO 3166-1 alpha-3. The same format should be used when providing values for writes.

When reading data from the PMS, Impala will attempt to parse the provided value and convert it to the appropriate ISO 3166-1 alpha-3 code. In the event that this is not possible, null will be returned.

Language Codes

All language codes will be returned as ISO 639-3. The same format should be used when providing values for writes.

When reading data from the PMS, Impala will attempt to parse the provided value and convert it to the appropriate ISO 639-3 code. In the event that this is not possible, null will be returned.

Errors

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.

Types of Errors

Here are listed the possible error types:

Value Description
AUTH_ERROR Usually accompanied by a 401 status code. Incorrect or invalid authentication details were provided.
UNKNOWN_ERROR Usually accompanied by a 500 status code. Something went wrong internally. This is usually a bug - contact us if the problem persists.
INVALID_PARAMETERS Usually accompanied by a 400 status code. Some given input was not in the correct format or was incorrect. Where possible the message will provide further information.
INVALID_CONTENT_TYPE Usually accompanied by a 415 status code. The request was rejected because it has the wrong Content-Type header.
NOT_FOUND Usually accompanied by a 404 status code. Not found, or somehow a necessary piece of data is missing.
PERMISSIONS_ERROR Usually accompanied by a 403 status code. The auth details are valid, but don't have the credentials to do the attempted action.
CREDENTIALS_ERROR Usually accompanied by a 403 status code. The request was rejected by the target hotel.
METHOD_NOT_IMPLEMENTED Usually accompanied by a 404 status code. See Unsupported API Endpoints.
METHOD_NOT_SUPPORTED Usually accompanied by a 404 status code. See Unsupported API Endpoints.
SECURITY_ERROR Usually accompanied by a 426 status code. The request was rejected based on security concerns like lack of HTTPS.
RATE_LIMIT_EXCEEDED Usually accompanied by a 429 status code. The request was rejected as you are making too many requests too quickly.
NO_DATA_FOR_HOTEL Usually accompanied by a 404 status code. No data has yet been fetched from the target hotel. This may be as it has just been created or you have only just been given access. If this error persists, please contact support@getimpala.com.

Unsupported API Endpoints

Value Description
METHOD_NOT_IMPLEMENTED Indicates that the attempted functionality is currently not supported by Impala for this PMS. The underlying PMS supports this functionality but we haven't implemented it in the Impala API yet. If you need a feature that we currently don't support, please let us know by contacting support@getimpala.com.
METHOD_NOT_SUPPORTED Indicates that the attempted functionality is not available for the PMS. The PMS simply doesn't provide the functionality necessary for this feature to be supported.

Warnings

In some situations the Impala API will return a success response but with the addition of a Warning header. This indicates that whilst the request was successful, some aspect of it wasn't processed as expected. The contents of the header will provide more information.

Currently we only return Warning headers in the event some update fields provided weren't saved as expected:

During development we recommend you pay particular attention to the contents of this header.

The contents of the header is PMS-specific and it's results can vary, even for the same request, on a per-hotel basis.

API Versioning

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.

2018-11-27

  • The NO_DATA_FOR_HOTEL error was added to differentiate no data being found for the given search parameters and no data being available for that hotel.

    Previously, a response would be returned with an empty data array.

  • When retrieving a single item (e.g. one booking) and the item not being found, the status code 404 is now sent and the response body is as on the right.

2019-04-23

  • The marketCode and sourceCode attributes will be removed and market and source attributes will be added. They will take the format {code: <string>, description: <string>}. The origin attribute will change from a string to this object format.

  • We've added companyIds to Bookings for companies associated with the booking, e.g. the travel agent, company of the guest source like a tourism board.

  • We've added region to Addresses: this field contains States in the US and regions in other parts of the world

  • Oracle Hospitality Opera: We've previously assumed the main guest staying on the booking is also the contact for the booking. Starting with this version, we'll stop that as Opera doesn't have a concept of booker that we can reliably map.

PMS-Specific Values in
_extras

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@getimpala.com 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
  }
}

Data Freshness and the
_meta
Element

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.

Guides

Working with Bookings

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.

Receiving Updates to Bookings

A common use case for Booking data is to react to booking changes, such as check-ins, check-outs or cancellations.

You might present the guest with a welcome message on the television screen, an in-room device or via email once they check in. Or you might want to follow up with them a few minutes after departure to ask for a positive review on Tripadvisor.

Impala supports these use cases and allows you to subscribe to booking-related webhooks.

That way, every time a guest checks in or out, you'll receive a webhook notification containing the previous and new state of the booking. You can react to changes to status as it moves from EXPECTED to CHECKED_IN to CHECKED_OUT and trigger the respective actions in your application accordingly.

Children and Infants

Most hotel property management systems provide only adultCount and childCount on a booking. Occasionally, however, a PMS will additionally provide an infantCount.

If the difference isn’t relevant to your use case, simple add up childCount and infantCount.

Impala only supports childCount when creating bookings.

Working with Guests

Creating a Guest as Part of a Booking

Most hotel property management systems are adapted to handling guest profiles as part fo bookings. While creating a booking, you'll need to add a guests property containing the guest data.

If you create a booking for a guest who stayed at the hotel before, make sure to provide their guest ID instead of full details to avoid duplication in the hotel property management system.

Creating a Guest outside of a Booking

If you require more CRM-like functionality, then you may need to deal with guests outside of the context of a booking.

  • You can manage guests (Read, Update and Delete) via the /guest/:id endpoint (with the relevant HTTP method).
  • To retrieve an initial set of guests listed at the PMS you can use the Get all Guests endpoint where supported. Otherwise you should cycle through bookings and retrieve guests.

Hotels fight duplication of Guest profiles in their hotel systems every day. It is therefore recommended that you make sure to avoid creating duplicate profiles.

Working with Rates

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.

Working with Taxes

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.

Using Webhooks

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.

Webhook
type
and
events
format

Here we'll list each possible type in a webhook object and the format in the events which goes along with that type.

BOOKING_SET_CREATED

{
  "type": "BOOKING_SET_CREATED",
  "hotelId": "...",
  "events": [
    {
      "newBookingSet": {...}
    }
  ]
}

This is triggered whenever we detect that the more recent data has one or more booking sets that weren't found in older versions of the data.

Property Type Description
newBookingSet Booking Set The booking set that has been created.

BOOKING_SET_CHANGED

{
  "type": "BOOKING_SET_CHANGED",
  "hotelId": "...",
  "events": [
    {
      "newBookingSet": {...}
    }
  ]
}

This is triggered when we detect that the more recent data has one or more booking sets that have seen a change in the value of one of their properties.

Property Type Description
newBookingSet Booking Set The new version of the booking set.

BOOKING_CREATED

{
  "type": "BOOKING_CREATED",
  "hotelId": "...",
  "events": [
    {
      "newBooking": {...}
    }
  ]
}

This is triggered whenever we detect that the more recent data has one or more bookings that weren't found in older versions of the data.

Property Type Description
newBooking Booking The booking that has been created.

BOOKING_CHANGED

{
  "type": "BOOKING_CHANGED",
  "hotelId": "...",
  "events": [
    {
      "newBooking": {...}
    }
  ]
}

This is triggered whenever we detect that the more recent data has one or more bookings that have seen a change in the value of one of their properties.

Note that for this webhook we ignore all changes to the following properties in order to not conflict with other webhooks:

  • status (if the value is CANCELLED)
  • areaId
  • start
  • end
  • allocationId
Property Type Description
newBooking Booking The new version of the booking.

BOOKING_CANCELLED

{
  "type": "BOOKING_CANCELLED",
  "hotelId": "...",
  "events": [
    {
      "cancelledBooking": {...}
    }
  ]
}

This is triggered whenever we detect that the more recent data has one or more bookings that have had their status property updated to CANCELLED.

Property Type Description
cancelledBooking Booking The booking that has been cancelled.

BOOKING_AREA_CHANGED

{
  "type": "BOOKING_AREA_CHANGED",
  "hotelId": "...",
  "events": [
    {
      "booking": {...},
      "newAreaId": "bar"
    }
  ]
}

This is triggered whenever we detect that the more recent data has one or more bookings that have had their areaId property updated.

Property Type Description
booking Booking The booking in question.
newAreaId string The ID of the new Area.

BOOKING_DATE_CHANGED

{
  "type": "BOOKING_DATE_CHANGED",
  "hotelId": "...",
  "events": [
    {
      "booking": {...},
      "newStart": 1514937600,
      "newEnd": 1515283200
    }
  ]
}

This is triggered whenever we detect that the more recent data has one or more bookings that have had some date changed in relation to the booking period.

All properties will be present, regardless of which were changed.

Property Type Description
booking Booking The booking in question.
newStart timestamp The new start value of the booking. See Dates.
newEnd timestamp The new end value of the booking. See Dates.

Anatomy of Webhook Notifications

All webhooks follow the same basic structure:

Property Type Description
type string The constant name of the webhook.
hotelId string The hotel that this event occurred in.
events array An array containing all the instances found for this webhook for this hotel.

Webhook type and corresponding events formats are described here.

Verifying Webhook Authenticity

Each application has a unique webhook secret that is used to sign the JSON body of webhook requests. It can be viewed and regenerated in the Impala Management Console. As the secret value is per-application, you can use it to verify that a webhook request came from Impala and that it relates to your application.

The signature is sent in the X-Impala-Signature header and is a SHA256 HMAC that's hex encoded. To verify it, hash the request body with your application's webhook secret and then compare the generated hash with the signature header value. If the two values match, the request is from Impala and for your application.

Please check out our Node.js example of how to check the authenticity of a received Webhook notification.

Date range covered by Notifications

Where data may have a time associated with it (Bookings, Booking Sets, etc.), webhooks will only report on changes +/- 365 days from the time at which the data is updated.

If you have a requirement for detecting differences outside that range, you should poll the relevant API directly.

Main Resources

Allocations (Group Blocks)

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

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

Field
Type
Support
Comments

id

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

start

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

end

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

contact

SOME INTEGRATIONS

cutoffDate

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

The date on which the blocked areas of this allocation will be released to generally available inventory.

cutoffType

  • Clock PMS

  • Impala Sandbox PMS

  • Protel

    Protel only supports ABSOLUTE cutoff
  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • Opera (On-Premise) (Request)

  • Opera (hosted by Oracle) (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

allocationRestrictions

SOME INTEGRATIONS

status

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

createdAt

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

updatedAt

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS
Required Parameter MarkRequired
{
  "id": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "start": "1541980801",
  "end": "1545393600",
  "contact": {
    "type": "guest",
    "data": {
      "title": "Mr.",
      "firstName": "Joe",
      "lastName": "Jones"
    }
  },
  "cutoffDate": "1541894400",
  "cutoffType": "ABSOLUTE",
  "allocationRestrictions": [],
  "status": "PROSPECT",
  "createdAt": "1541165040",
  "updatedAt": "1541165040"
}

Retrieve an Allocation

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS
GET /allocations/{id}
Path Parameter
Type
Support
Comments

id

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type

data

Allocation (Group Block)
{
  "id": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "start": "1541980801",
  "end": "1545393600",
  "contact": {
    "type": "guest",
    "data": {
      "title": "Mr.",
      "firstName": "Joe",
      "lastName": "Jones"
    }
  },
  "cutoffDate": "1541894400",
  "cutoffType": "ABSOLUTE",
  "allocationRestrictions": [],
  "status": "PROSPECT",
  "createdAt": "1541165040",
  "updatedAt": "1541165040"
}

Retrieve all Allocations

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS
GET /allocations

Returns

[
  {
    "id": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
    "start": "1541980801",
    "end": "1545393600",
    "contact": {
      "type": "guest",
      "data": {
        "title": "Mr.",
        "firstName": "Joe",
        "lastName": "Jones"
      }
    },
    "cutoffDate": "1541894400",
    "cutoffType": "ABSOLUTE",
    "allocationRestrictions": [],
    "status": "PROSPECT",
    "createdAt": "1541165040",
    "updatedAt": "1541165040"
  }
]

Areas (Rooms & Beds)

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS

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.

Field
Type
Support
Comments

id

String

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS

name

String

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS

areaTypeId

String

  • Clock PMS

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

  • Guestline (Request)

SOME INTEGRATIONS

status

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

    Upon request. Please contact us for installation of an additional report.
  • Opera (hosted by Oracle)

    Upon request. Please contact us for installation of an additional report.
  • Protel

  • Suite8

  • Clock PMS (Request)

  • Guestline (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

description

String

  • Clock PMS

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

parentAreaId

String

SOME INTEGRATIONS
Required Parameter MarkRequired
{
  "id": "95151a02-8264-4ed0-927f-184de0d07c64",
  "name": "1410",
  "areaTypeId": "3be3e840-6b20-4f57-8bbd-8ca418dfaa32",
  "status": "CLEAN",
  "description": "Presidential Suite with Park View",
  "parentAreaId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9"
}

Change the Status of an Area

FUTURE INTEGRATIONS
PUT /areas/{id}/status
Path Parameter
Type
Support
Comments

id

String

FUTURE INTEGRATIONS
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments

status

Area Status

FUTURE INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type

data

{
  "id": "95151a02-8264-4ed0-927f-184de0d07c64",
  "name": "1410",
  "areaTypeId": "3be3e840-6b20-4f57-8bbd-8ca418dfaa32",
  "status": "CLEAN",
  "description": "Presidential Suite with Park View",
  "parentAreaId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9"
}

Retrieve an Area

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS
GET /areas/{id}
Path Parameter
Type
Support
Comments

id

String

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type

data

{
  "id": "95151a02-8264-4ed0-927f-184de0d07c64",
  "name": "1410",
  "areaTypeId": "3be3e840-6b20-4f57-8bbd-8ca418dfaa32",
  "status": "CLEAN",
  "description": "Presidential Suite with Park View",
  "parentAreaId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9"
}

Retrieve all Areas

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS
GET /areas
Query Parameter
Type
Support
Comments

name

String

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

  • Clock PMS (Request)

SOME INTEGRATIONS
Required Parameter MarkRequired

Returns

[
  {
    "id": "95151a02-8264-4ed0-927f-184de0d07c64",
    "name": "1410",
    "areaTypeId": "3be3e840-6b20-4f57-8bbd-8ca418dfaa32",
    "status": "CLEAN",
    "description": "Presidential Suite with Park View",
    "parentAreaId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9"
  }
]

Area Types (Room Types)

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS

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.

Field
Type
Support
Comments

id

String

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS

The unique identifier for the area types resource.

code

String

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • SIHOT (Request)

SOME INTEGRATIONS

Short identifier for this Area Type (often used in reporting and house keeping).

name

String

  • Clock PMS

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

  • Guestline (Request)

SOME INTEGRATIONS

Full name of the category (often used in guest-facing material like booking confirmations).

maxOccupancy

Integer

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • Suite8

  • Infor HMS (Request)

  • Mews Systems (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

parentAreaTypeId

String

SOME INTEGRATIONS

An Area Type might have a parent, e.g. "Superior Rooms" might be the parent Area Type of "Superior Rooms with Park View" and "Superior Rooms with City View".

description

String

SOME INTEGRATIONS
Required Parameter MarkRequired
{
  "id": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "code": "PSUI",
  "name": "Presidential Suites",
  "maxOccupancy": 3,
  "parentAreaTypeId": "91343d8c-70f7-46b1-824c-cee0f0b5c719",
  "description": "Luxurious presidential suites equipped with modern amenities, a whirlpool and walk-in closet."
}

Retrieve an Area Type

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS
GET /area-types/{id}
Path Parameter
Type
Support
Comments

id

String

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS
Required Parameter MarkRequired

Returns

{
  "id": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "code": "PSUI",
  "name": "Presidential Suites",
  "maxOccupancy": 3,
  "parentAreaTypeId": "91343d8c-70f7-46b1-824c-cee0f0b5c719",
  "description": "Luxurious presidential suites equipped with modern amenities, a whirlpool and walk-in closet."
}

Retrieve all Area Types

  • Clock PMS

  • Guestline

  • Impala Sandbox PMS

  • Infor HMS

  • Mews Systems

  • Opera (On-Premise)

  • Opera (hosted by Oracle)

  • Protel

  • SIHOT

  • Suite8

ALL INTEGRATIONS
GET /area-types

Returns

[
  {
    "id": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
    "code": "PSUI",
    "name": "Presidential Suites",
    "maxOccupancy": 3,
    "parentAreaTypeId": "91343d8c-70f7-46b1-824c-cee0f0b5c719",
    "description": "Luxurious presidential suites equipped with modern amenities, a whirlpool and walk-in closet."
  }
]

Bills

  • Clock PMS

  • Impala Sandbox PMS

  • Mews Systems

  • Opera (On-Premise)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Opera (hosted by Oracle) (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

A Bill is a container of Charges and Payments.

Field
Type
Support
Comments

id

String

  • Clock PMS

  • Impala Sandbox PMS

  • Mews Systems

  • Opera (On-Premise)

  • Protel

  • Suite8

  • Guestline (Request)

  • Infor HMS (Request)

  • Opera (hosted by Oracle) (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

The unique identifier of the bill.

reference

String

SOME INTEGRATIONS

dueDate

Unix timestamp

SOME INTEGRATIONS

issuedDate

Unix timestamp

SOME INTEGRATIONS

charges

array of Charges

  • Impala Sandbox PMS

  • Mews Systems

  • Opera (On-Premise)

    Upon request. Please contact us for installation of an additional report.
  • Protel

  • Suite8

  • Clock PMS (Request)

  • Guestline (Request)

  • Infor HMS (Request)

  • Opera (hosted by Oracle) (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

See Charges.

payments

array of Payments

  • Impala Sandbox PMS

  • Mews Systems

  • Opera (On-Premise)

    Upon request. Please contact us for installation of an additional report.
  • Protel

  • Suite8

  • Clock PMS (Request)

  • Guestline (Request)

  • Infor HMS (Request)

  • Opera (hosted by Oracle) (Request)

  • SIHOT (Request)

SOME INTEGRATIONS

status

SOME INTEGRATIONS

Indicated whether the bill has been settled.

isPaid

Boolean

SOME INTEGRATIONS

Indicates whether or not the bill has been paid.

bookingId

String

SOME INTEGRATIONS

The unique identifier of the booking associated with the bill. See Booking.

guestId

String

SOME INTEGRATIONS

The unique identifier of the guest associated with the bill. See Guest.

Required Parameter MarkRequired
{
  "id": "4666677939",
  "reference": "ANQ1999995",
  "dueDate": 1552402011,
  "issuedDate": 1552488411,
  "charges": [],
  "payments": [],
  "status": "OPEN",
  "isPaid": false,
  "bookingId": "f689880de3cb4d31bc73",
  "guestId": "7f6afc82-927a-4fe8"
}

Retrieve Bills for a Booking

SOME INTEGRATIONS
GET /bookings/{id}/bills
Path Parameter
Type
Support
Comments

id

String

SOME INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type
[
  {
    "id": "4666677939",
    "reference": "ANQ1999995",
    "dueDate": 1552402011,
    "issuedDate": 1552488411,
    "charges": [],
    "payments": [],
    "status": "OPEN",
    "isPaid": false,
    "bookingId": "f689880de3cb4d31bc73",
    "guestId": "7f6afc82-927a-4fe8"
  }
]

Refund a Payment on a Bill

FUTURE INTEGRATIONS
POST /bills/{id}/payment/{paymentId}/refund
Path Parameter
Type
Support
Comments

id

String

FUTURE INTEGRATIONS

paymentId

String

FUTURE INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type

data

{
  "id": "4666677939",
  "reference": "ANQ1999995",
  "dueDate": 1552402011,
  "issuedDate": 1552488411,
  "charges": [],
  "payments": [],
  "status": "OPEN",
  "isPaid": false,
  "bookingId": "f689880de3cb4d31bc73",
  "guestId": "7f6afc82-927a-4fe8"
}

Refund a Charge on a Bill

FUTURE INTEGRATIONS
POST /bills/{id}/charge/{chargeId}/refund
Path Parameter
Type
Support
Comments

id

String

FUTURE INTEGRATIONS

chargeId

String

FUTURE INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type

data

{
  "id": "4666677939",
  "reference": "ANQ1999995",
  "dueDate": 1552402011,
  "issuedDate": 1552488411,
  "charges": [],
  "payments": [],
  "status": "OPEN",
  "isPaid": false,
  "bookingId": "f689880de3cb4d31bc73",
  "guestId": "7f6afc82-927a-4fe8"
}

Add a Payment to a Bill

FUTURE INTEGRATIONS
POST /bills/{id}/payment
Path Parameter
Type
Support
Comments

id

String

FUTURE INTEGRATIONS
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments

description

String

FUTURE INTEGRATIONS

grossAmount

String

FUTURE INTEGRATIONS

currencyCode

String

FUTURE INTEGRATIONS

notes

String

FUTURE INTEGRATIONS

isVoid

Boolean

FUTURE INTEGRATIONS

paymentType

Payment Type

FUTURE INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type

data

{
  "id": "4666677939",
  "reference": "ANQ1999995",
  "dueDate": 1552402011,
  "issuedDate": 1552488411,
  "charges": [],
  "payments": [],
  "status": "OPEN",
  "isPaid": false,
  "bookingId": "f689880de3cb4d31bc73",
  "guestId": "7f6afc82-927a-4fe8"
}

Add a Charge to a Bill

FUTURE INTEGRATIONS
POST /bills/{id}/charge
Path Parameter
Type
Support
Comments

id

String

FUTURE INTEGRATIONS
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments

grossAmount

String

FUTURE INTEGRATIONS

taxRate

String

FUTURE INTEGRATIONS

currencyCode

String

FUTURE INTEGRATIONS

description

String

FUTURE INTEGRATIONS

notes

String

FUTURE INTEGRATIONS

chargedAt

Unix timestamp

FUTURE INTEGRATIONS
Required Parameter MarkRequired

Returns

Field
Type

data

{
  "id": "4666677939",
  "reference": "ANQ1999995",
  "dueDate": 1552402011,
  "issuedDate": 1552488411,
  "charges": [],
  "payments": [],
  "status": "OPEN",
  "isPaid": false,
  "bookingId": "f689880de3cb4d31bc73",
  "guestId": "7f6afc82-927a-4fe8"
}

Retrieve a Bill

SOME INTEGRATIONS
GET /bills/{id}
Path Parameter
Type
Support
Comments

id

String