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.

Our API is hosted on a single domain: https://api.getimpala.com/. This is used for both Test and Live modes. For example, to retrieve all bookings for a hotel, use https://api.getimpala.com/v2/hotels/{{hotelId}}/bookings.”

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
Owner Your organization's main point of contact for technical issues and billing queries. Manage user and admin accounts, delete existing hotels, request new hotels, view and regenerate the API key.
Please contact our support team if you would like to transfer ownership of your organisation to another user.
Admin Manage user and other admin accounts, delete existing hotels, request new hotels, view and regenerate the API key.
User See details of existing hotels, request new hotels, view and regenerate the API key.

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)

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
start
String
end
String
contact
Contact
cutoffDate
String

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

cutoffType
Allocation Cutoff Types
allocationRestrictions
Array of Allocation Restrictions
status
Allocation Status
createdAt
String
updatedAt
String
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

GET /v2/hotel/{{hotelId}}/allocations/{{allocationId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

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"
}

Retrieve all Allocations

GET /v2/hotel/{{hotelId}}/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)

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
name
String
areaTypeId
String
status
Area Status
description
String
parentAreaId
String
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"
}

Retrieve an Area

GET /v2/hotel/{{hotelId}}/areas/{{areaId}}
Path Parameter
Type
Support
Comments
id
String
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"
}

Change the Status of an Area

PUT /v2/hotel/{{hotelId}}/areas/{{areaId}}/status
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments
status
Area Status
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

GET /v2/hotel/{{hotelId}}/areas
Query Parameter
Type
Support
Comments
name
String
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)

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

The unique identifier for the area types resource.

code
String

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

name
String

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

maxOccupancy
Integer
parentAreaTypeId
String

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
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

GET /v2/hotel/{{hotelId}}/area-types/{{areaTypeId}}
Path Parameter
Type
Support
Comments
id
String
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

GET /v2/hotel/{{hotelId}}/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

A Bill is a container of Charges and Payments.

Field
Type
Support
Comments
id
String

The unique identifier of the bill.

reference
String
dueDate
Unix timestamp
issuedDate
Unix timestamp
charges
array of Charges

See Charges.

payments
array of Payments
status
Bill Status

Indicated whether the bill has been settled.

isPaid
Boolean

Indicates whether or not the bill has been paid.

bookingId
String

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

guestId
String

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 a Bill

GET /v2/hotel/{{hotelId}}//bills/{{billId}}
Path Parameter
Type
Support
Comments
id
String
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 Bills for a Booking

GET /v2/hotel/{{hotelId}}/bookings/{{bookingId}}/bills
Path Parameter
Type
Support
Comments
id
String
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

POST /v2/hotel/{{hotelId}}/bills/{{billId}}/payment/{{paymentId}}/refund
Path Parameter
Type
Support
Comments
id
String
paymentId
String
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

POST /v2/hotel/{{hotelId}}/bills/{{billId}}/payment
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments
description
String
grossAmount
String
currencyCode
String
notes
String
isVoid
Boolean
paymentType
Payment Type
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

POST /v2/hotel/{{hotelId}}/bills/{{biilId}}/charge/{{chargeId}}/refund
Path Parameter
Type
Support
Comments
id
String
chargeId
String
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

POST /v2/hotel/{{hotelId}}/bills/{{billId}}/charge
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments
grossAmount
String
taxRate
String
currencyCode
String
description
String
notes
String
chargedAt
Unix timestamp
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"
}

Booking Sets

A Booking Set represents the container for one or more Bookings. This container has certain 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.

Field
Type
Support
Comments
id
String
parentId
String

Some PMS support nested Booking Sets. This field enables that use-case.

reference
String

The confirmation number the hotel handles with the Guest.

start
String

A Unix timestamp indicating the earliest start available in the Bookings in the Booking Set.

end
String

A Unix timestamp indicating the latest end available in the Bookings in the Booking Set.

contact
Contact
bookingIds
Array of Strings

The IDs of the Bookings contained in the Booking Set. Contains at least one string, may contain many.

createdAt
String

A Unix timestamp indicating the time at which the Booking Set was created.

updatedAt
String

A Unix timestamp indicating the time at which the booking set was last updated.

Required Parameter MarkRequired
{
  "id": "b7419c93-e4e7-43c0-abe0-1ab8c7d356d8",
  "parentId": "00f38936-41a9-4987-9a53-c4c201084639",
  "reference": "XJKRSJG",
  "start": "1564059600",
  "end": "1564394400",
  "contact": {
    "type": "guest",
    "id": "a33aaf4b-705f-4a10-af96-96e47164b0df"
  },
  "bookingIds": [
    "f50584ad-7b19-4d14-bba6-20c59a50b638"
  ],
  "createdAt": "1551119832",
  "updatedAt": "1551119832"
}

Change a Booking Set

PATCH /v2/hotel/{{hotelId}}/booking-sets/{{bookingSetId}}
Body Parameter
Type
Support
Comments
parentId
String
reference
String
contact
Contact
bookings
array of ids or Bookings

You can provide IDs to already-existing Bookings, or you can provide the full body of the new Bookings as objects, and they will be created along with the Booking Set.

Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "b7419c93-e4e7-43c0-abe0-1ab8c7d356d8",
  "parentId": "00f38936-41a9-4987-9a53-c4c201084639",
  "reference": "XJKRSJG",
  "start": "1564059600",
  "end": "1564394400",
  "contact": {
    "type": "guest",
    "id": "a33aaf4b-705f-4a10-af96-96e47164b0df"
  },
  "bookingIds": [
    "f50584ad-7b19-4d14-bba6-20c59a50b638"
  ],
  "createdAt": "1551119832",
  "updatedAt": "1551119832"
}

Create a Booking Set

POST /v2/hotel/{{hotelId}}/booking-sets
Body Parameter
Type
Support
Comments
parentId
String
reference
String
contact
Contact
bookings
array of ids or Bookings

You can provide IDs to already-existing Bookings, or you can provide the full body of the new Bookings as objects, and they will be created along with the Booking Set.

Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "b7419c93-e4e7-43c0-abe0-1ab8c7d356d8",
  "parentId": "00f38936-41a9-4987-9a53-c4c201084639",
  "reference": "XJKRSJG",
  "start": "1564059600",
  "end": "1564394400",
  "contact": {
    "type": "guest",
    "id": "a33aaf4b-705f-4a10-af96-96e47164b0df"
  },
  "bookingIds": [
    "f50584ad-7b19-4d14-bba6-20c59a50b638"
  ],
  "createdAt": "1551119832",
  "updatedAt": "1551119832"
}

Retrieve a Booking Set

GET /v2/hotel/{{hotelId}}/booking-sets/{{bookingSetId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "b7419c93-e4e7-43c0-abe0-1ab8c7d356d8",
  "parentId": "00f38936-41a9-4987-9a53-c4c201084639",
  "reference": "XJKRSJG",
  "start": "1564059600",
  "end": "1564394400",
  "contact": {
    "type": "guest",
    "id": "a33aaf4b-705f-4a10-af96-96e47164b0df"
  },
  "bookingIds": [
    "f50584ad-7b19-4d14-bba6-20c59a50b638"
  ],
  "createdAt": "1551119832",
  "updatedAt": "1551119832"
}

Retrieve all Booking Sets

GET /v2/hotel/{{hotelId}}/booking-sets
Query Parameter
Type
Support
Comments
startDate
date

Format YYYY-MM-DD. Default value is seven days in the past (today minus 7 days). Booking sets will only be returned if their start value is higher than or equal to the provided value.

endDate
date

Format YYYY-MM-DD. Default value is seven days in the future (today plus 7 days). Booking sets will only be returned if their end value is lower than or equal to the provided value.

Required Parameter MarkRequired

Returns

{
  "id": "b7419c93-e4e7-43c0-abe0-1ab8c7d356d8",
  "parentId": "00f38936-41a9-4987-9a53-c4c201084639",
  "reference": "XJKRSJG",
  "start": "1564059600",
  "end": "1564394400",
  "contact": {
    "type": "guest",
    "id": "a33aaf4b-705f-4a10-af96-96e47164b0df"
  },
  "bookingIds": [
    "f50584ad-7b19-4d14-bba6-20c59a50b638"
  ],
  "createdAt": "1551119832",
  "updatedAt": "1551119832"
}

Bookings

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.

Field
Type
Support
Comments
id
String

This is the unique identifier for this booking. In most cases, hotel staff or guests won't know about or use this number.

reference
String

The identifier hotel staff uses to look up the booking in their system. For guests who called in to make a booking (as opposed to booked through external channels like online travel agencies), this is the confirmation identifier they receive.

status
Booking Status
bookingSetId
String
ratePlanId
String
market
Object with code and/or description

Used to identify the market segment this booking belongs to. Hotels often use this information to track performance in certain segments, e.g. business travel, individual guests or guests who stay through wholesale contracts. These values vary by hotel and aren't globally mapped.

source
Object with code and/or description

Used by hotels to identify the source of business (e.g. mail, telephone, fax, central reservations, specific travel agencies like Booking.com or Expedia). These values vary by hotel and aren't globally mapped.

origin
Object with code and/or description

Typically used by hotels to identify the technical source of a Booking. These are often values like mail, telephone, fax, central reservations, travel agency or global distribution systems. These values vary by hotel and aren't globally mapped.

channelManager
String

This field will be populated with the name of the channel manager that this booking was generated through. Channel manager software is used to distribute rates across channels (e.g. tens of online travel agencies) and limit availability to avoid overbooking.

start
String
end
String
areaId
String

The assigned Area (room or hostel bed) for this booking.

requestedAreaTypeId
String

The requested Area Type for this booking.

adultCount
Integer
childCount
Integer
infantCount
Integer
netAmount
Integer

Realised and posted revenue excluding tax. Most hotels post revenue each night for the rate amount, and near real time when e.g. food & beverage purchases occur. This means that you'll typically see the realised revenue go up from zero to the total amount during a guest's stay, with no additional revenue being added after check-out. See Prices.

grossAmount
Integer

Realised and posted total revenue including tax. Most hotels post revenue each night for the rate amount, and near real time when e.g. food & beverage purchases occur. This means that you'll typically see the realised revenue go up from zero to the total amount during a guest's stay, with no additional revenue being added after check-out. See Prices.

taxAmount
Integer

Tax expressed as an amount. See Prices.

taxRate
Fractional Decimal

Tax expressed as a fractional decimal.

amountBreakdown
Amount Breakdown

Pricing breakdown per time unit. Typically per-night room or hostel bed rates which might differ for each night of the stay.

currencyCode
String
contact
Contact
guestIds
Array of Strings
allocationId
String
createdAt
String
cancelledAt
String
updatedAt
String
companyIds
Array of Strings

Companies associated with this booking, e.g. the employer or travel agent of the guest or booker.

externalReferences
Array of Strings

References generated by external systems that the guest or booker might use for to identify the booking. This could be the confirmation number a online travel agency like Booking.com uses in their system, as opposed to the reference that is generated in the hotel system. As bookings are created through multiple systems, they might have multiple external references. As an example, a booking created by HRS through a Global Distribution System (GDS) might have a confirmation number generated by HRS as well as a GDS Personal Record Number.

Required Parameter MarkRequired
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Check out a Booking

POST /v2/hotel/{{hotelId}}/bookings/{{bookingId}}/check-out
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Check in a Booking

POST /v2/hotel/{{hotelId}}/bookings/{{bookingId}}/check-in
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Cancel a Booking

POST /v2/hotel/{{hotelId}}/bookings/{{bookingId}}/cancel
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Update a Booking

PATCH /v2/hotel/{{hotelId}}/bookings/{{bookingId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments
startDate
String

Date in YYYY-MM-DD format. Default is 7 days in the past.

endDate
String

Date in YYYY-MM-DD format. Default is 7 days in the future.

requestedAreaTypeId
String
ratePlanId
String
guests
Array of Guests or Guest IDs
adultCount
Integer
childCount
String
contact
Contact
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Create a Booking

POST /v2/hotel/{{hotelId}}/bookings
Body Parameter
Type
Support
Comments
start
String

Epoch time in seconds.

end
String

Epoch time in seconds.

requestedAreaTypeId
String
ratePlanId
String
guests
Array of Guests or Guest IDs
adultCount
Integer
childCount
String
contact
Contact
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Retrieve all Bookings

GET /v2/hotel/{{hotelId}}/bookings
Query Parameter
Type
Support
Comments
startDate
String

When set, this will filter to bookings arriving on or after the date set. Date in YYYY-MM-DD format. Default is 7 days in the past.

endDate
String

When set, this will filter to bookings departing before or on the date. Date in YYYY-MM-DD format. Default is 7 days in the future.

areaId
String
guestId
String

Find bookings with which the specified guest is associated.

Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Retrieve a Booking

GET /v2/hotel/{{hotelId}}/bookings/{{bookingId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "485159",
  "reference": "3701937",
  "status": "CHECKED_IN",
  "bookingSetId": "457295772",
  "ratePlanId": "BAR4",
  "market": {
    "code": "IDL",
    "description": "Individual Leisure"
  },
  "source": {
    "code": "EXP",
    "description": "Expedia.com"
  },
  "origin": {
    "code": "ON",
    "description": "Online"
  },
  "channelManager": "SynXis Channel Connect",
  "start": "1551830400",
  "end": "1552003200",
  "areaId": "95151a02-8264-4ed0-927f-184de0d07c64",
  "requestedAreaTypeId": "6ab22725-961d-4e96-a6bf-17ca7c1742a9",
  "adultCount": 1,
  "childCount": 0,
  "infantCount": 0,
  "netAmount": 18132,
  "grossAmount": 20000,
  "taxAmount": 1868,
  "taxRate": "0.103",
  "amountBreakdown": [],
  "currencyCode": "USD",
  "contact": {
    "id": "5c41b84f9de35076b9b0f060",
    "type": "guest"
  },
  "guestIds": [
    "123456"
  ],
  "allocationId": "cb9aa447-8d12-4864-9d5b-388c720e69ce",
  "createdAt": "1531207775",
  "cancelledAt": "null",
  "updatedAt": "1531207775",
  "companyIds": [
    "123456"
  ],
  "externalReferences": [
    "PN39DR",
    "472857122"
  ]
}

Charges

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

Field
Type
Support
Comments
id
String
billId
String

The ID of the Bill that the charge belongs to.

netAmount
Integer

The amount without including tax. See the section "Prices" in the Caveats.

grossAmount
Integer

The amount including tax (netAmount + taxAmount). See the section "Prices" in the Caveats.

taxAmount
Integer

Tax expressed as an amount. See the section "Prices" in the Caveats.

taxRate
String

Tax expressed as a fractional decimal (0 <= taxRate <= 1).

currencyCode
String

See the section "Currency codes" in the Caveats.

description
String
notes
String
isVoid
Boolean
chargedAt
String

A Unix timestamp representing the moment the Charge was created.

Required Parameter MarkRequired
{
  "id": "65faae2d-5e92-4ddb-9544-bba7acd23251",
  "billId": "145a1b7b-a9b5-45a2-9c77-b2f97e5242ed",
  "netAmount": 8000,
  "grossAmount": 9600,
  "taxAmount": 1600,
  "taxRate": "0.2",
  "currencyCode": "EUR",
  "description": "Breakfast",
  "notes": "Eggs & toast",
  "isVoid": false,
  "chargedAt": "1552488411"
}

Retrieve a Charge

GET /v2/hotel/{{hotelId}}/bill/{{billId}}/charge/{{chargeId}}
Path Parameter
Type
Support
Comments
id
String
chargeId
String
Required Parameter MarkRequired

Returns

Field
Type
data
{
  "id": "65faae2d-5e92-4ddb-9544-bba7acd23251",
  "billId": "145a1b7b-a9b5-45a2-9c77-b2f97e5242ed",
  "netAmount": 8000,
  "grossAmount": 9600,
  "taxAmount": 1600,
  "taxRate": "0.2",
  "currencyCode": "EUR",
  "description": "Breakfast",
  "notes": "Eggs & toast",
  "isVoid": false,
  "chargedAt": "1552488411"
}

Retrieve all Charges on a Bill

GET /v2/hotel/{{hotelId}}/bills/{{billId}}}/charges

Returns

Field
Type
{
  "id": "65faae2d-5e92-4ddb-9544-bba7acd23251",
  "billId": "145a1b7b-a9b5-45a2-9c77-b2f97e5242ed",
  "netAmount": 8000,
  "grossAmount": 9600,
  "taxAmount": 1600,
  "taxRate": "0.2",
  "currencyCode": "EUR",
  "description": "Breakfast",
  "notes": "Eggs & toast",
  "isVoid": false,
  "chargedAt": "1552488411"
}

Companies

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.

Field
Type
Support
Comments
id
String
companyType
Company Types
reference
String

This field might contain company identifiers like IATA numbers for travel agents or business registry / VAT numbers for companies.

name
String
addresses
Array of Addresses
emails
Array of Strings
phoneNumbers
Array of Strings
taxId
String

The tax identification or VAT number of the business.

Required Parameter MarkRequired
{
  "id": "bdf856ac-d35a-4b8f-b92f-50b4bfbfe240",
  "companyType": "\"COMPANY\"",
  "reference": "\"123123\"",
  "name": "\"John's Trips\"",
  "addresses": [
    {
      "line1": "1 Main St",
      "line2": "Apt. 58",
      "city": "Paris",
      "postalCode": "07500",
      "countryCode": "FRA"
    }
  ],
  "emails": [
    "john@johns-trips.com"
  ],
  "phoneNumbers": [
    "555-5555",
    "555-123-848"
  ],
  "taxId": "48458482873489-XXX"
}

Update a Company

PATCH /v2/hotel/{{hotelId}}/companies/{{companyId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired
Body Parameter
Type
Support
Comments
companyType
Company Types
reference
String

This field might contain company identifiers like IATA numbers for travel agents or business registry / VAT numbers for companies.

name
String
addresses
Array of Addresses
emails
Array of Strings
phoneNumbers
Array of Strings
taxId
String

The tax identification or VAT number of the business.

Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "bdf856ac-d35a-4b8f-b92f-50b4bfbfe240",
  "companyType": "\"COMPANY\"",
  "reference": "\"123123\"",
  "name": "\"John's Trips\"",
  "addresses": [
    {
      "line1": "1 Main St",
      "line2": "Apt. 58",
      "city": "Paris",
      "postalCode": "07500",
      "countryCode": "FRA"
    }
  ],
  "emails": [
    "john@johns-trips.com"
  ],
  "phoneNumbers": [
    "555-5555",
    "555-123-848"
  ],
  "taxId": "48458482873489-XXX"
}

Create a Company

POST /v2/hotel/{{hotelId}}/companies
Body Parameter
Type
Support
Comments
companyType
Company Types
reference
String

This field might contain company identifiers like IATA numbers for travel agents or business registry / VAT numbers for companies.

name
String
addresses
Array of Addresses
emails
Array of Strings
phoneNumbers
Array of Strings
taxId
String

The tax identification or VAT number of the business.

Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "bdf856ac-d35a-4b8f-b92f-50b4bfbfe240",
  "companyType": "\"COMPANY\"",
  "reference": "\"123123\"",
  "name": "\"John's Trips\"",
  "addresses": [
    {
      "line1": "1 Main St",
      "line2": "Apt. 58",
      "city": "Paris",
      "postalCode": "07500",
      "countryCode": "FRA"
    }
  ],
  "emails": [
    "john@johns-trips.com"
  ],
  "phoneNumbers": [
    "555-5555",
    "555-123-848"
  ],
  "taxId": "48458482873489-XXX"
}

Retrieve a Company

GET /v2/hotel/{{hotelId}}/companies/{{companyId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "bdf856ac-d35a-4b8f-b92f-50b4bfbfe240",
  "companyType": "\"COMPANY\"",
  "reference": "\"123123\"",
  "name": "\"John's Trips\"",
  "addresses": [
    {
      "line1": "1 Main St",
      "line2": "Apt. 58",
      "city": "Paris",
      "postalCode": "07500",
      "countryCode": "FRA"
    }
  ],
  "emails": [
    "john@johns-trips.com"
  ],
  "phoneNumbers": [
    "555-5555",
    "555-123-848"
  ],
  "taxId": "48458482873489-XXX"
}

Extras

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

Field
Type
Support
Comments
id
String
isActive
Boolean

Is the extra historic or can it be purchased.

name
String
code
String
description
String
billingScheme
BillingScheme

How the PMS should calculate charges.

billingFrequency
BillingFrequency

When the PMS will post charges.

netAmount
Integer

Amount before tax.

grossAmount
Integer

Amount after tax.

taxAmount
Integer

Tax expressed as an amount.

taxRate
String

Tax expressed as a fractional decimal (0 <= x <= 1).

currencyCode
String
createdAt
String

The date that the extra was created. See Dates.

updatedAt
String

The time the extra was last updated. See Dates.

Required Parameter MarkRequired
{
  "id": "5c90e298d2477b343d053239",
  "isActive": true,
  "name": "Wi-Fi",
  "code": "",
  "description": "WiFi at the hotel, available in all areas",
  "billingScheme": "PER_NIGHT",
  "billingFrequency": "",
  "netAmount": 0,
  "grossAmount": 0,
  "taxAmount": 0,
  "taxRate": "0.103",
  "currencyCode": "GBP",
  "createdAt": "1552999067",
  "updatedAt": "1552999067"
}

Retrieve a Extra

GET /v2/hotel/{{hotelId}}/extras/{{extraId}}

Returns

Field
Type
data
{
  "id": "5c90e298d2477b343d053239",
  "isActive": true,
  "name": "Wi-Fi",
  "code": "",
  "description": "WiFi at the hotel, available in all areas",
  "billingScheme": "PER_NIGHT",
  "billingFrequency": "",
  "netAmount": 0,
  "grossAmount": 0,
  "taxAmount": 0,
  "taxRate": "0.103",
  "currencyCode": "GBP",
  "createdAt": "1552999067",
  "updatedAt": "1552999067"
}

Retrieve all Extras

GET /v2/hotel/{{hotelId}}/extras

Returns

Field
Type
{
  "id": "5c90e298d2477b343d053239",
  "isActive": true,
  "name": "Wi-Fi",
  "code": "",
  "description": "WiFi at the hotel, available in all areas",
  "billingScheme": "PER_NIGHT",
  "billingFrequency": "",
  "netAmount": 0,
  "grossAmount": 0,
  "taxAmount": 0,
  "taxRate": "0.103",
  "currencyCode": "GBP",
  "createdAt": "1552999067",
  "updatedAt": "1552999067"
}

Guests

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.

Field
Type
Support
Comments
id
String

The unique identifier for the Guests resource

title
String

One or more words used before the person's name. In some contexts it may signify veneration, an official position, or a professional or academic qualification.

firstName
String

The first name of the guest the resource is for.

middleName
String

The middle name of the guest the resource is for.

lastName
String

The last name of the guest the resource is for.

sexCode
Integer

There is special case for sexCode, as per the ISO/IEC 5218 standard, if the PMS doesn't provide the information the value returned will not be null, and instead will be 0. This special case does not exempt sexCode from the caveat linked above

emails
Array of Strings

Email addresses, the PMS has record of, for the guest in question.

phoneNumbers
Array of Strings

Telephone numbers, the PMS has record of, for the guest in question.

languageCode
String

Language of the guest in ISO 639-3.

nationalityCode
String

Nationality, the PMS has record of, for the guest in question in ISO 3166-1 alpha-3 format.

dateOfBirth
ISO 8601 Timestamp

Date of birth, the PMS has record of, for the guest in question in ISO-8601 format.

placeOfBirth
String

Place of birth, the PMS has record of, for the guest in question.

loyaltyPrograms
Array of Loyalty Programs

A list of loyalty programs, the PMS has record of, the guest in question is signed up to.

notes
String

A free text field for notes that the PMS holds on the guest in question.

classifications
Array of Guest Classifications

A list of classifications, the PMS has record of, attributed to the guest in question.

documents
Array of Documents

Documents, the PMS has record of, for the guest in question, for example, Passports, Driving Licences.

addresses
array of Addresses

Addresses, the PMS has record of, for the guest in question.

optIns
Opt In Info

Topics of communication, the PMS has record of, the guest in question has opted in to.

contactBy
Contact By Info

Communication methods, the PMS has record of, the guest in question has opted in to.

createdAt
String

The time at which the guest resource was created.

updatedAt
String

The time at which the guest resource was updated.

Required Parameter MarkRequired
{
  "id": "5bf2856765265100df4d0337",
  "title": "Miss",
  "firstName": "Terrance",
  "middleName": "Jaime",
  "lastName": "Huel",
  "sexCode": 2,
  "emails": [
    "Alaina.Hahn@example.com"
  ],
  "phoneNumbers": [
    "700 864 248 1150"
  ],
  "languageCode": "eng",
  "nationalityCode": "PHL",
  "dateOfBirth": "1988-11-10",
  "placeOfBirth": "London",
  "loyaltyPrograms": [
    {
      "code": "BWR",
      "membershipNumber": "6006637602349631",
      "memberSince": "2005-11-10"
    }
  ],
  "notes": "The guest prefers to have a south-facing room. They enjoy the Opera when they stay.",
  "classifications": [
    "RETURNING",
    "VIP"
  ],
  "documents": [
    {
      "type": "PASSPORT",
      "number": "789567123"
    }
  ],
  "addresses": [
    {
      "line1": "25116 Moen Crescent",
      "line2": "Tx",
      "city": "Lake Elfrieda",
      "postalCode": "96762-1414",
      "countryCode": "AGO"
    }
  ],
  "optIns": {
    "marketResearch": false,
    "thirdParty": false,
    "marketing": true,
    "misc": false
  },
  "contactBy": {
    "email": true,
    "sms": false,
    "phone": false
  },
  "createdAt": "1551448516",
  "updatedAt": "1551448516"
}

Creating a new Guest

POST /v2/hotel/{{hotelId}}/guests
Body Parameter
Type
Support
Comments
title
String
firstName
String
middleName
String
lastName
String
sexCode
String
emails
Array of Strings
phoneNumbers
Array of Strings
languageCode
String
nationalityCode
String
dateOfBirth
String
placeOfBirth
String
loyaltyPrograms
Array of Loyalty Programs
notes
String
classifications
Array of Guest Classifications
documents
Array of Documents
addresses
array of Addresses
Required Parameter MarkRequired

Returns

Field
Type
data
{
  "id": "5bf2856765265100df4d0337",
  "title": "Miss",
  "firstName": "Terrance",
  "middleName": "Jaime",
  "lastName": "Huel",
  "sexCode": 2,
  "emails": [
    "Alaina.Hahn@example.com"
  ],
  "phoneNumbers": [
    "700 864 248 1150"
  ],
  "languageCode": "eng",
  "nationalityCode": "PHL",
  "dateOfBirth": "1988-11-10",
  "placeOfBirth": "London",
  "loyaltyPrograms": [
    {
      "code": "BWR",
      "membershipNumber": "6006637602349631",
      "memberSince": "2005-11-10"
    }
  ],
  "notes": "The guest prefers to have a south-facing room. They enjoy the Opera when they stay.",
  "classifications": [
    "RETURNING",
    "VIP"
  ],
  "documents": [
    {
      "type": "PASSPORT",
      "number": "789567123"
    }
  ],
  "addresses": [
    {
      "line1": "25116 Moen Crescent",
      "line2": "Tx",
      "city": "Lake Elfrieda",
      "postalCode": "96762-1414",
      "countryCode": "AGO"
    }
  ],
  "optIns": {
    "marketResearch": false,
    "thirdParty": false,
    "marketing": true,
    "misc": false
  },
  "contactBy": {
    "email": true,
    "sms": false,
    "phone": false
  },
  "createdAt": "1551448516",
  "updatedAt": "1551448516"
}

Updating an existing Guest

PATCH /v2/hotel/{{hotelId}}/guests/{{guestId}}
Body Parameter
Type
Support
Comments
title
String
firstName
String
middleName
String
lastName
String
sexCode
String
emails
Array of Strings
phoneNumbers
Array of Strings
languageCode
String
nationalityCode
String
dateOfBirth
String
placeOfBirth
String
loyaltyPrograms
Array of Loyalty Programs
notes
String
classifications
Array of Guest Classifications
documents
Array of Documents
addresses
array of Addresses
Required Parameter MarkRequired

Returns

Field
Type
data
{
  "id": "5bf2856765265100df4d0337",
  "title": "Miss",
  "firstName": "Terrance",
  "middleName": "Jaime",
  "lastName": "Huel",
  "sexCode": 2,
  "emails": [
    "Alaina.Hahn@example.com"
  ],
  "phoneNumbers": [
    "700 864 248 1150"
  ],
  "languageCode": "eng",
  "nationalityCode": "PHL",
  "dateOfBirth": "1988-11-10",
  "placeOfBirth": "London",
  "loyaltyPrograms": [
    {
      "code": "BWR",
      "membershipNumber": "6006637602349631",
      "memberSince": "2005-11-10"
    }
  ],
  "notes": "The guest prefers to have a south-facing room. They enjoy the Opera when they stay.",
  "classifications": [
    "RETURNING",
    "VIP"
  ],
  "documents": [
    {
      "type": "PASSPORT",
      "number": "789567123"
    }
  ],
  "addresses": [
    {
      "line1": "25116 Moen Crescent",
      "line2": "Tx",
      "city": "Lake Elfrieda",
      "postalCode": "96762-1414",
      "countryCode": "AGO"
    }
  ],
  "optIns": {
    "marketResearch": false,
    "thirdParty": false,
    "marketing": true,
    "misc": false
  },
  "contactBy": {
    "email": true,
    "sms": false,
    "phone": false
  },
  "createdAt": "1551448516",
  "updatedAt": "1551448516"
}

Retrieve a Guest

GET /v2/hotel/{{hotelId}}/guests/{{guestId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
data
{
  "id": "5bf2856765265100df4d0337",
  "title": "Miss",
  "firstName": "Terrance",
  "middleName": "Jaime",
  "lastName": "Huel",
  "sexCode": 2,
  "emails": [
    "Alaina.Hahn@example.com"
  ],
  "phoneNumbers": [
    "700 864 248 1150"
  ],
  "languageCode": "eng",
  "nationalityCode": "PHL",
  "dateOfBirth": "1988-11-10",
  "placeOfBirth": "London",
  "loyaltyPrograms": [
    {
      "code": "BWR",
      "membershipNumber": "6006637602349631",
      "memberSince": "2005-11-10"
    }
  ],
  "notes": "The guest prefers to have a south-facing room. They enjoy the Opera when they stay.",
  "classifications": [
    "RETURNING",
    "VIP"
  ],
  "documents": [
    {
      "type": "PASSPORT",
      "number": "789567123"
    }
  ],
  "addresses": [
    {
      "line1": "25116 Moen Crescent",
      "line2": "Tx",
      "city": "Lake Elfrieda",
      "postalCode": "96762-1414",
      "countryCode": "AGO"
    }
  ],
  "optIns": {
    "marketResearch": false,
    "thirdParty": false,
    "marketing": true,
    "misc": false
  },
  "contactBy": {
    "email": true,
    "sms": false,
    "phone": false
  },
  "createdAt": "1551448516",
  "updatedAt": "1551448516"
}

Retrieve all Guests

GET /v2/hotel/{{hotelId}}/guests
Query Parameter
Type
Support
Comments
startDate
date

Will return guests that were created or updated after this time.

endDate
date

Will return guests that were created or updated before this time.

Required Parameter MarkRequired

Returns

Field
Type
data
{
  "id": "5bf2856765265100df4d0337",
  "title": "Miss",
  "firstName": "Terrance",
  "middleName": "Jaime",
  "lastName": "Huel",
  "sexCode": 2,
  "emails": [
    "Alaina.Hahn@example.com"
  ],
  "phoneNumbers": [
    "700 864 248 1150"
  ],
  "languageCode": "eng",
  "nationalityCode": "PHL",
  "dateOfBirth": "1988-11-10",
  "placeOfBirth": "London",
  "loyaltyPrograms": [
    {
      "code": "BWR",
      "membershipNumber": "6006637602349631",
      "memberSince": "2005-11-10"
    }
  ],
  "notes": "The guest prefers to have a south-facing room. They enjoy the Opera when they stay.",
  "classifications": [
    "RETURNING",
    "VIP"
  ],
  "documents": [
    {
      "type": "PASSPORT",
      "number": "789567123"
    }
  ],
  "addresses": [
    {
      "line1": "25116 Moen Crescent",
      "line2": "Tx",
      "city": "Lake Elfrieda",
      "postalCode": "96762-1414",
      "countryCode": "AGO"
    }
  ],
  "optIns": {
    "marketResearch": false,
    "thirdParty": false,
    "marketing": true,
    "misc": false
  },
  "contactBy": {
    "email": true,
    "sms": false,
    "phone": false
  },
  "createdAt": "1551448516",
  "updatedAt": "1551448516"
}

Payments

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

Field
Type
Support
Comments
id
String
billId
String
amount
String

The amount paid. See prices

currencyCode
String

See currencies

notes
String
isVoid
Boolean

Extremely limited PMS support, means void payment rather than a "refund"

paymentType
Payment Type
paidAt
String
Required Parameter MarkRequired
{
  "id": "",
  "billId": "",
  "amount": "",
  "currencyCode": "",
  "notes": "",
  "isVoid": false,
  "paymentType": "",
  "paidAt": ""
}

Retrieve a Payment

GET /v2/hotel/{{hotelId}}/bills/{{billId}}/payment/{{paymentId}}
Path Parameter
Type
Support
Comments
id
String
paymentId
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "",
  "billId": "",
  "amount": "",
  "currencyCode": "",
  "notes": "",
  "isVoid": false,
  "paymentType": "",
  "paidAt": ""
}

Retrieve all Payments on a Bill

GET /v2/hotel/{{hotelId}}/bills/{{billId}}/payments
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "",
  "billId": "",
  "amount": "",
  "currencyCode": "",
  "notes": "",
  "isVoid": false,
  "paymentType": "",
  "paidAt": ""
}

Rate Plans

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

Field
Type
Support
Comments
id
String

The ID of the Rate Plan.

isActive
Boolean

Is the Rate Plan currently bookable.

isPublic
Boolean

Is the Rate Plan available publicly or qualified somehow?

rateSetId
String

Will be null in PMS that do not support Rate Sets.

name
String
restrictions
array of RateRestrictions
supplements
array of RateSupplements
parentRatePlanId
String

The ID of the Rate Plan to which this Rate Plan belongs.

createdAt
String

See Dates.

updatedAt
String

See Dates.

Required Parameter MarkRequired
{
  "id": "5b44605c6a485739bc5833be",
  "isActive": true,
  "isPublic": true,
  "rateSetId": "5b44605cb5dd67860e81dc5f",
  "name": "BAR/Weekend",
  "restrictions": [
    {
      "startDate": null,
      "endDate": null,
      "daysCovered": [
        "FRI"
      ],
      "minAdvanceDays": null,
      "maxAdvanceDays": null,
      "minLengthOfStay": null,
      "maxLengthOfStay": null,
      "type": "WEEKENDS",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "id": "5b44605c8bd994b0a5f46dbb",
      "_extras": {}
    }
  ],
  "supplements": [
    {
      "id": "5b44605c1dc9ec9d1f3b6b7b",
      "quantity": 1,
      "description": "WiFi",
      "amount": {
        "value": 500,
        "type": "ADDITIONAL"
      },
      "billingScheme": "PER_NIGHT",
      "type": "SERVICES",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "_extras": {}
    }
  ],
  "parentRatePlanId": "5b44605cc741b929439fcf12",
  "createdAt": "1531207775",
  "updatedAt": "1531207775"
}

Make a pricing decision for a Rate Plan

PUT /v2/hotel/{{hotelId}}/rate-plans/{{ratePlanId}}/price
Body Parameter
Type
Support
Comments
date
date
amountDescription
AmountDescription
areaTypeId
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "5b44605c6a485739bc5833be",
  "isActive": true,
  "isPublic": true,
  "rateSetId": "5b44605cb5dd67860e81dc5f",
  "name": "BAR/Weekend",
  "restrictions": [
    {
      "startDate": null,
      "endDate": null,
      "daysCovered": [
        "FRI"
      ],
      "minAdvanceDays": null,
      "maxAdvanceDays": null,
      "minLengthOfStay": null,
      "maxLengthOfStay": null,
      "type": "WEEKENDS",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "id": "5b44605c8bd994b0a5f46dbb",
      "_extras": {}
    }
  ],
  "supplements": [
    {
      "id": "5b44605c1dc9ec9d1f3b6b7b",
      "quantity": 1,
      "description": "WiFi",
      "amount": {
        "value": 500,
        "type": "ADDITIONAL"
      },
      "billingScheme": "PER_NIGHT",
      "type": "SERVICES",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "_extras": {}
    }
  ],
  "parentRatePlanId": "5b44605cc741b929439fcf12",
  "createdAt": "1531207775",
  "updatedAt": "1531207775"
}

Retrieve Price of a Rate Plan

GET /v2/hotel/{{hotelId}}/rate-plans/{{ratePlanId}}/price
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired
Query Parameter
Type
Support
Comments
startDate
date
endDate
date
areaTypeId
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "5b44605c6a485739bc5833be",
  "isActive": true,
  "isPublic": true,
  "rateSetId": "5b44605cb5dd67860e81dc5f",
  "name": "BAR/Weekend",
  "restrictions": [
    {
      "startDate": null,
      "endDate": null,
      "daysCovered": [
        "FRI"
      ],
      "minAdvanceDays": null,
      "maxAdvanceDays": null,
      "minLengthOfStay": null,
      "maxLengthOfStay": null,
      "type": "WEEKENDS",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "id": "5b44605c8bd994b0a5f46dbb",
      "_extras": {}
    }
  ],
  "supplements": [
    {
      "id": "5b44605c1dc9ec9d1f3b6b7b",
      "quantity": 1,
      "description": "WiFi",
      "amount": {
        "value": 500,
        "type": "ADDITIONAL"
      },
      "billingScheme": "PER_NIGHT",
      "type": "SERVICES",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "_extras": {}
    }
  ],
  "parentRatePlanId": "5b44605cc741b929439fcf12",
  "createdAt": "1531207775",
  "updatedAt": "1531207775"
}

Retrieve a Rate Plan

GET /v2/hotel/{{hotelId}}/rate-plans/{{ratePlanId}}
Path Parameter
Type
Support
Comments
id
String
Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "5b44605c6a485739bc5833be",
  "isActive": true,
  "isPublic": true,
  "rateSetId": "5b44605cb5dd67860e81dc5f",
  "name": "BAR/Weekend",
  "restrictions": [
    {
      "startDate": null,
      "endDate": null,
      "daysCovered": [
        "FRI"
      ],
      "minAdvanceDays": null,
      "maxAdvanceDays": null,
      "minLengthOfStay": null,
      "maxLengthOfStay": null,
      "type": "WEEKENDS",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "id": "5b44605c8bd994b0a5f46dbb",
      "_extras": {}
    }
  ],
  "supplements": [
    {
      "id": "5b44605c1dc9ec9d1f3b6b7b",
      "quantity": 1,
      "description": "WiFi",
      "amount": {
        "value": 500,
        "type": "ADDITIONAL"
      },
      "billingScheme": "PER_NIGHT",
      "type": "SERVICES",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "_extras": {}
    }
  ],
  "parentRatePlanId": "5b44605cc741b929439fcf12",
  "createdAt": "1531207775",
  "updatedAt": "1531207775"
}

Retrieve all Rate Plans

GET /v2/hotel/{{hotelId}}/rate-plans
Query Parameter
Type
Support
Comments
accessCode
String

A code used to gain access to 'extra' rate plans not available to the public

Required Parameter MarkRequired

Returns

Field
Type
{
  "id": "5b44605c6a485739bc5833be",
  "isActive": true,
  "isPublic": true,
  "rateSetId": "5b44605cb5dd67860e81dc5f",
  "name": "BAR/Weekend",
  "restrictions": [
    {
      "startDate": null,
      "endDate": null,
      "daysCovered": [
        "FRI"
      ],
      "minAdvanceDays": null,
      "maxAdvanceDays": null,
      "minLengthOfStay": null,
      "maxLengthOfStay": null,
      "type": "WEEKENDS",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "id": "5b44605c8bd994b0a5f46dbb",
      "_extras": {}
    }
  ],
  "supplements": [
    {
      "id": "5b44605c1dc9ec9d1f3b6b7b",
      "quantity": 1,
      "description": "WiFi",
      "amount": {
        "value": 500,
        "type": "ADDITIONAL"
      },
      "billingScheme": "PER_NIGHT",
      "type": "SERVICES",
      "createdAt": 1531207775,
      "updatedAt": 1531207775,
      "_extras": {}
    }
  ],
  "parentRatePlanId": "5b44605cc741b929439fcf12",
  "createdAt": "1531207775",
  "updatedAt": "1531207775"
}

Rate Prices

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.

For how to request a Rate Plan's price see Retrive the price of a Rate Plan.

Field
Type
Support
Comments
currency
String
date
String

See Dates.

price
AmountDescription
areaTypeId
String

Will be omitted if the Rate Price represents a base price.

ratePlanId
String

The ID of the Rate Plan the price is for.

supplements
RateSupplements
restrictions
RateRestrictions
Required Parameter MarkRequired
{
  "currency": "GBP",
  "date": "1536710400",
  "price": {
    "type": "ABSOLUTE",
    "value": 10000
  },
  "areaTypeId": "5b44605c0d44ea902055d73c",
  "ratePlanId": "5b3f380aacbb28c94565bd4d",
  "supplements": {},
  "restrictions": {}
}

Rate Sets

A Rate Set is a container for one or more Rate Plans.

Rate Sets should only be used in the case where you have specific support requirements at a specific PMS.

For more information, see Working with Rates.

Field
Type
Support
Comments
id
String
isActive
Boolean

Is the rate set currently bookable?

name
String
ratePlanIds
Array of Strings
createdAt
String

See Dates.

updatedAt
String

See Dates.

Required Parameter MarkRequired
{
  "id": "5b3f380ac45bcef10121990c",
  "isActive": true,
  "name": "BAR Rates",
  "ratePlanIds": [
    "5b3f380acf6ce42cc091429a",
    "5b3f380aacbb28c94565bd4d"
  ],
  "createdAt": "1530869773",
  "updatedAt": "1530869773"
}

Retrieve all Rate Sets

GET /v2/hotel/{{hotelId}}/rate-sets

Returns

Field
Type
{
  "id": "5b3f380ac45bcef10121990c",
  "isActive": true,
  "name": "BAR Rates",
  "ratePlanIds": [
    "5b3f380acf6ce42cc091429a",
    "5b3f380aacbb28c94565bd4d"
  ],
  "createdAt": "1530869773",
  "updatedAt": "1530869773"
}
Secondary Resources

Addresses

Field
Type
Support
Comments
line1
String
line2
String
city
String
postalCode
String
region
String

State or Province information based on ISO 3166-2.

countryCode
String

Country code based on ISO 3166-1.

Required Parameter MarkRequired
{
  "line1": "22 Charles Court",
  "line2": "Apt. 58",
  "city": "Carrollton",
  "postalCode": "75006",
  "region": "TX",
  "countryCode": "USA"
}

Allocation Restrictions

Field
Type
Support
Comments
areaTypeId
String
ratePlanId
String
date
String

The date on which the restriction applies (null indicates the entire allocation)

numberOfAreas
String

numberOfAreas refers to the total number of areas that were allocated for the allocation when the allocation was created.

numberOfAreasFree
String

numberOfAreasFree refers to the total number of areas still available on the allocation.

numberOfAreasPickedUp
String

Refers to the total number of areas that are no longer available (because they're filled with bookings connected to the allocation).

Required Parameter MarkRequired
{
  "areaTypeId": "DBL-S",
  "ratePlanId": "BAR",
  "date": "1553006811",
  "numberOfAreas": "5",
  "numberOfAreasFree": "3",
  "numberOfAreasPickedUp": "2"
}

Allocation Cutoff Types

Value Description
ABSOLUTE When cutoffType is ABSOLUTE, the number of areas listed in the restriction is total.
DAY_BY_DAY When it is DAYBYDAY that means that the number of areas referred to in the restriction should be reduced every day (evenly).

Booking Amount Breakdowns

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.

Field
Type
Support
Comments
duration
String
start
String

A Unix timestamp representing the start of the period delimited by duration.

netAmount
Integer

The amount without including tax. See the section "Prices" in the Caveats.

grossAmount
Integer

The amount including tax (netAmount + taxAmount). See the section "Prices" in the Caveats.

taxAmount
Integer

Tax expressed as an amount. See the section "Prices" in the Caveats.

taxRate
String

Tax expressed as a fractional decimal (0 <= taxRate <= 1).

Required Parameter MarkRequired
{
  "duration": "NIGHT",
  "start": "1564059600",
  "netAmount": 8000,
  "grossAmount": 9600,
  "taxAmount": 1600,
  "taxRate": "0.2"
}

Contacts

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.

Field
Type
Support
Comments
type
String

guest or company

data
Object

Optional, if type is guest then an object that matches the Guest schema

id
String

Optional

Required Parameter MarkRequired
{
  "type": "",
  "data": "",
  "id": ""
}

Contact by Info

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

Field
Type
Support
Comments
email
Boolean
sms
Boolean
phone
Boolean
Required Parameter MarkRequired
{
  "email": false,
  "sms": false,
  "phone": false
}

Documents

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

Field
Type
Support
Comments
type
String

The type of document i.e. "Passport", "Drivers Licence".

number
String

The relevant identification/issue number for the document.

Required Parameter MarkRequired
{
  "type": "",
  "number": ""
}

Loyalty Programs

Field
Type
Support
Comments
code
String

The code representing the scheme.

membershipNumber
String
memberSince
ISO 8601 Timestamp
Required Parameter MarkRequired
{
  "code": "",
  "membershipNumber": "",
  "memberSince": ""
}

Opt-In Info

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.

Field
Type
Support
Comments
marketResearch
Boolean
thirdParty
Boolean
marketing
Boolean
misc
Boolean

Used when the PMS has a single opt-in option that doesn't differentiate between communication topics.

Required Parameter MarkRequired
{
  "marketResearch": false,
  "thirdParty": false,
  "marketing": false,
  "misc": false
}

Rate Restrictions

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
Field
Type
Support
Comments
startDate
String

The date that the restriction application begins (may be null for timeless restriction). See Dates.

endDate
String

The date that the restriction application begins (may be null for timeless restriction). See Dates.

minAdvanceDays
number

Minimum days in advance of the stay the booking must be made.

maxAdvanceDays
number

Maximum days in advance of the stay the booking can be made.

minLengthOfStay
number

The minimum number of nights the guest must stay to qualify for the rate.

maxLengthOfStay
number

The maximum number of nights the guest can stay to qualify for the rate.

accessCode
String

The code required to access the rate plan. See Rate Plans.

type
RateRestrictionType

The type of restriction. This will determine which fields are populated.

daysCovered
Array of Strings

Days the restriction applies on (may be null). See above.

createdAt
String

See Dates.

updatedAt
String

See Dates.

Required Parameter MarkRequired
{
  "startDate": "1553008155",
  "endDate": "1553299200",
  "minAdvanceDays": "3",
  "maxAdvanceDays": "6",
  "minLengthOfStay": "7",
  "maxLengthOfStay": "14",
  "accessCode": "605cb5dd67",
  "type": "",
  "daysCovered": [
    "MONDAY",
    "TUESDAY"
  ],
  "createdAt": "1548979200",
  "updatedAt": "1548979200"
}

Rate Supplements

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

Field
Type
Support
Comments
quantity
String

e.g. The number of additional guests.

type
RateSupplementType
amount
AmountDescription
billingScheme
BillingScheme
createdAt
String

See Dates.

updatedAt
String

See Dates.

Required Parameter MarkRequired
{
  "quantity": "1",
  "type": "SURCHARGE",
  "amount": {
    "type": "ABSOLUTE",
    "value": 10000
  },
  "billingScheme": "ONCE",
  "createdAt": "1553008410",
  "updatedAt": "1553008410"
}
Enumerations

Area Statuses

Value Description
CLEAN
DIRTY
INSPECTED The area is clean and inspected.
OUT_OF_SERVICE
OUT_OF_ORDER
OUT_OF_INVENTORY
INDETERMINATE The state of the room can't be determined.
OTHER The PMS has supplied an unmapped value.

Allocation Statuses

An Allocation Status typically represents how concrete an allocation is:

Value Description
CANCELLED The allocation has been cancelled.
DEFINITE The allocation is confirmed.
LOST_OR_DECLINED The allocation was turned down or was not possible.
PROSPECT The allocation has been inquired about.
TENTATIVE The allocation has been noted but not confirmed.

Amount Descriptions

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:

Value Description
ABSOLUTE For a fixed cost. value should be an integer. See Prices.
ADDITIONAL For a cost that is in addition to it's parent. value should be an integer. See Prices.
PERCENTAGE For a cost that is a percentage of its parent. value should be a fractional decimal expressed as a string (0 <= x <= 1), e.g. "0.15".
Field
Type
Support
Comments
type
AmountDescriptionType
value
String
Required Parameter MarkRequired
{
  "type": "ABSOLUTE",
  "value": "5000"
}

Bill Statuses

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

Value Description
OPEN The bill is open.
CLOSED The bill is closed.

Billing Schemes

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.

PMS Value Description
Guestline PER_AREA Billing is applied per area.
  PER_PERSON Billing is applied per person regardless of age.
  PER_ADULT Billing is applied per adult.
  PER_CHILD Billing is applied per child.
  PER_INFANT Billing is applied per infant.
  ONCE Billing is applied only once.
  PER_DAY_PER_AREA Billing is applied each day for each area.
  PER_DAY_PER_PERSON Billing is applied each day for each person.
  PER_HOUR_PER_AREA Billing is applied each hour for each area.
  PER_HOUR_PER_PERSON Billing is applied each hour for each person.
  FUNCTION_SINGLE_CHARGE Billing is applied once for a function/event.
  UNKNOWN  
     
MEWS ONCE Billing is applied only once.
  PER_TIME Billing is applied each specified window of time.
  PER_TIME_PER_PERSON Billing is applied every window for each person.
  PER_PERSON Billing is applied per person regardless of age.
     
HTNG/Infor PER_AREA Billing is applied per area.
  PER_DAY_PER_AREA Billing is applied each day for each area.
  PER_PERSON Billing is applied per person regardless of age.
  PER_DAY_PER_PERSON Billing is applied each day for each person.

Billing Frequencies

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

Value Description
EVERY_BLOCK
ON_ARRIVAL
ON_DEPARTURE
ON_ARRIVAL_AND_DEPARTURE
EVERY_BLOCK_EXCL_ARRIVAL
EVERY_BLOCK_EXCL_DEPARTURE
EVERY_BLOCK_EXCL_ARRIVAL_AND_DEPARTURE
UNKNOWN

Booking Statuses

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

Value Description
EXPECTED The guest for the booking is expected to come in.
NO_SHOW The guest for the booking didn't show up.
CANCELLED The booking is cancelled.
CHECKED_IN The booking has been checked in.
CHECKED_OUT The booking has been checked out.
TRANSFERRED The guest couldn't be checked in upon arrival (e.g. the hotel was overbooked) and so they were transferred to another hotel.
OTHER The status of the booking does not correspond with any of the above values.

Booking Amount Breakdown Durations

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

Value Description
NIGHT The length of time is equivalent to one hotel night.
HOUR The length of time is equivalent to one hour.

Company Types

Company Type is a string with the following possible values:

Value Description
TRAVEL_AGENT A company typically booking on behalf of guests and other companies, not for their own employees.
COMPANY A company booking for their own employees and customers.

Payment Types

Value Description
CASH
CARD Covers all card types.
BANK_TRANSFER
CHARGE_TO_COMPANY
CHECK
VOUCHER
OTHER PMS provided a response which mapped to "other" or a fringe payment method.

Guest Classifications

An extra identifier by which to classify a guest.

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

Value Description
PAYMASTER_ACCOUNT
BLACKLIST
MEDIA
LOYALTY_PROGRAM
COMPLAINED
RETURNING
STAFF
MANAGEMENT
IP
VIP
PROBLEMATIC
CASHLIST
DISABLED
MILITARY
MARKETING_SUBSCRIBED
SMOKER
OTHER

Rate Restriction Types

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

Value Description Fields Available
DATE_RESTRICTION Restricts the dates the rate plan/price is available. startDate, endDate
LENGTH_RESTRICTION Restricts the duration of stay for the rate plan/price. minLengthOfStay, maxLengthOfStay
EARLINESS_RESTRICTION Restricts the number of days in advance a rate plan/price is available. minAdvanceDays, maxAdvanceDays
ACCESS_RESTRICTION Restricts the visibility of the rate plan/price. accessCode

Rate Supplement Types

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

It is often used by PMS to describe tax.

Value Description
TOTAL_TAX
SURCHARGE
SERVICE_CHARGE
MISC
VATGST_TAX
LODGING_TAX
STATE_TAX
CITY_TAX
OCCUPANCY_TAX
LOCAL_FEE