NAV Navbar
cURL Node PHP
  • General
  • Introduction
  • Getting Started
  • Developer Web Client
  • Authentication
  • API Libraries
  • Which Endpoints To Integrate
  • Writing Data
  • Null values
  • Pagination
  • Caveats
  • PMS Guidance
  • Errors
  • Warnings
  • Versioning
  • Guides
  • Handling Bookings
  • Handling Bills
  • Handling Guests
  • Handling Rates
  • Handling Taxes
  • Webhooks
  • Reference
  • Resources
  • Address
  • Allocation (Group Block)
  • Allocation Restriction
  • Allocation Status
  • Amount Description
  • Area
  • Area Status
  • Area Types
  • Bill
  • Bill Status
  • Billing Scheme
  • Billing Frequency
  • Booking
  • Booking Set
  • Booking Status
  • Booking Amount Breakdown
  • Booking Amount Breakdown Duration
  • Charge
  • Company
  • Company Type
  • Contact
  • Contact By Info
  • Document
  • Extra
  • Guest
  • Guest Classification
  • Loyalty Program
  • Opt In Info
  • Payment
  • Payment Type
  • Rate Plan
  • Rate Price
  • Rate Restriction
  • Rate Restriction Type
  • Rate Set
  • Rate Supplement
  • Rate Supplement Type
  • General

    Introduction

    Official libraries for the Impala API are available in our API Libraries section. Else you can directly connect to the API using the endpoints we provide.

    https://api.getimpala.com
    

    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, including errors, although our API libraries convert responses to appropriate language-specific objects.

    To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit real hotel data and instead provide a response from our own sandbox hotel, The Charleston. The Charleston is running on the Impala Test 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 PMS that the hotel is using may not offer a full support of the same resources. To see which resources are not supported by the PMS, see PMS Caveats.

    Getting Started

    To get started, you must first have a developer account. In order to set one up, please visit https://getimpala.com and click "Sign Up". Once you have your credentials setup, visit https://developer.getimpala.com and sign in.

    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.

    Developer Web Client

    Modes

    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.

    Details

    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.

    Hotels

    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. Currently, in beta, to request access to a hotel you'll have to submit a form. As we move live, you'll be able to provide credentials directly and get instant access.

    API

    API

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

    Webhooks

    Webhooks

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

    Organization Settings

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

    Authentication

    To provide the correct authentication details you will need to pass you application's API key as part of the Authorization header. For example: Authorization: Bearer XXX where XXX is your API key.

    You can find your app's API Key in the developer web client in the application's relevant "API" section. This is your way of interacting with Impala's API.

    API Libraries

    We are currently developing libraries for all major web languages. If you have a request for a specific language library, please email info@getimpala.com.

    Which Endpoints To Integrate

    The goal of Impala is to make it exceptionally easy to exchange data bi-directionally with Property Management Systems (PMS). Impala aims to be the last integration you will ever need and to minimize to the absolute extreme the amount of code changes you need to make to connect to different PMS.

    With that in mind these docs contain two distinct sections:

    Standard-Flow vs Edge-Case

    Not all PMS are built the same. They often take a very different view on how best to implement common hospitality concepts like "Reservations" and "Rates". In order to make your life easier, Impala abstracts away as many of these problems as possible beneath the API.

    Where you see a Standard-Flow endpoint or the use cases describe something as Standard-Flow, we mean that this is the way you should do something as standard. Where we've labelled something as Edge-Case, we mean that this endpoint should only be used as a special case where we couldn't abstract behaviour from a particularly deviant PMS.

    If you're integrating Impala from scratch, you should build your app using Standard-Flow endpoints and then only look at Edge-Case endpoints where the Standard-Flow endpoint lists a problem with a PMS that you also need to support.

    Writing Data

    One of the great things about Impala is the ability to not just read data from the PMS but additionally to write data back to it. There are a few things you should be aware of however before starting to write data.

    The Write-Back Loop

    Because every PMS is different, Impala provides a caching layer between you and the PMS in order to serve the data that you need. When you're requesting data from the API the following scenarios are possible:

    We use the former wherever possible but it isn't always for a variety of reasons. For most use cases this is no problem and indeed you can see how recently data was refreshed via the _meta property.

    If you're writing data however, you should be aware that you may write a change that succeeds but that when you read back it doesn't seem like it has been successful. This is because we're serving cached data until we refresh.

    The best practice here is to check if you receive a 200 or 204 status code from any write. For a 200, you'll receive a copy of the altered object which you can store and serve locally. For 204 we are unable to return the altered object and so you should alter your object locally.

    If you absolutely need the altered copy and receive a 204 from the write, you should incorporate the relevant webhook to be updated as soon as we have the refreshed copy.

    Write Returns

    Whenever you write data, we'll either return a copy of the new data with a 200 status code or a 204 status code without the new copy.

    Null values

    All values returned by our API can be null.

    If a value is null, it is either because the PMS does not support it or it is in fact null.

    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 PMS but there are no values in it.

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

    Pagination

    {
      "data": [...],
      "_meta": {
        "previous": "eyIkb2lkIjoiNWIzZjc1ZjE3NjVhOTMwMDdkYmQwNjhmIn0",
        "hasPrevious": false,
        "next": "eyIkb2lkIjoiNWIzZjc1ZjE3NjVhOTMwMDdkYmQwNjhmIn0",
        "hasNext": true,
        "pms": "IMPALA_PMS"
      }
    }
    

    Example response which has pagination

    The index routes of all resources such as /booking or /rate-plan are paginated.

    You will receive an object with a data property, which contains the result of the query, and any pagination-related data will be included in the _meta property.

    We use cursor-based pagination, which means that instead of passing in a limit and offset, you pass along a pointer to the first record of the next/previous page and a limit. Cursor-based pagination has performance benefits and if the data changes the content of the pages doesn't shift around.

    Pagination properties in _meta

    These can be found inside of the _meta property.

    Parameter Type Description
    hasNext boolean Is there a next page
    next string The cursor position for the next page
    hasPrevious boolean Is there a previous page
    previous string The cursor position for the previous page

    In case that there are no results, hasNext and hasPrevious will be false and next and previous will not be present.

    Query parameters

    The following properties can be passed along as query parameters in order to influence the pagination behaviour:

    Parameter Type Description
    limit integer Number of results per page, default 50
    next string The next page to load, can be obtained from _meta.next
    previous string The previous page to load, can be obtained from _meta.previous

    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 params they should be in the form YYYY-MM-DD.

    paidAt and chargedAt

    Please note that both are distinct from the concept of createdAt. Some PMS may treat chargedAt/paidAt as the same as when the record was created but not guaranteed (and we would argue shouldn't be).

    Prices

    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: BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, VND, VUV, XAF, XOF, XPF.

    Currency Codes

    All currency codes conform to ISO 4217.

    Resource IDs

    All resources provide an ID through the id property, when available. The id property represents the unique identifier as provided by the PMS.

    Composite IDs

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

    In the case that any of these required parts of a composite ID aren't available, the returned ID will be null.

    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.

    PMS Guidance

    Whilst Impala makes every effort to abstract away differences between PMS, this isn't always possible to do accurately, as there are instances where the given PMS does not support a certain endpoint. This section details where it's necessary to deviate from the Standard-Flow for each PMS.

    Clock

    Clock doesn’t support the following resource endpoints. To find out the way to work around these endpoints, please contact our support.

    Allocations

    GET /allocation

    GET /allocation/:id

    Bills / Charges / Payments

    GET /bill/:id

    POST /bill/:id/charge

    GET /bill/:id/charge

    POST /bill/:id/charge/:id/refund

    GET /bill/:id/charge/:id

    POST /bill/:id/payment

    GET /bill/:id/payment

    POST /bill/:id/payment/:id/refund

    GET /bill/:id/payment/:id

    Bookings / Booking Sets

    GET /booking/:id/bill

    POST /booking-set

    PATCH /booking-set/:id

    Extras

    GET /extra

    GET /extra/:id

    Guests

    POST /guest

    GET /guest

    PATCH /guest/:id

    GET /guest/:id/bill

    Guestline

    Guestline will return a maximum of 200 results from BookingSearch (even where we paginate more than that). Please ensure that you're searching week-by-week for open queries in order to avoid hitting this limit.

    Guestline doesn’t support the following resource endpoints. To find out the way to work around these endpoints, please contact our support.

    Allocations

    GET /allocation

    GET /allocation/:id

    Area Types

    GET /area-type/:id

    Bookings/ Booking Sets

    PATCH /booking/:id

    GET /booking-set/:id

    POST /booking-set

    PATCH /booking-set/:id

    Guests / Bills

    GET /guest/:id/bill

    Rate Sets

    GET /rate-set

    GET /rate-set/:id

    Mews

    Mews doesn’t support the following resource endpoints. To find out the way to work around these endpoints, please contact our support.

    Allocations

    GET /allocation

    GET /allocation/:id

    Areas / Area Types

    GET /area/:id

    GET /area-type/:id

    Bookings / Booking Sets

    PATCH /booking/:id

    POST /booking-set

    GET /booking-set/:id

    PATCH /booking-set/:id

    Extras

    GET /extra/:id

    Rate Sets

    GET /rate-set

    GET /rate-set/:id

    Errors

    Status code: 404
    Content-Type: "application/json"
    Body:
    {
      "type": "NOT_FOUND",
      "message": "Not found.",
      "eventId": "123456abcdef"
    }
    

    An example of an error response.

    The Impala API uses standard HTTP codes to communicate errors, however to provide more useful context as to what the problem is, we send a JSON response to the client which includes message and type properties with further information.

    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. Including this information when reporting errors to support will help us better diagnose the problem.

    Error types

    Here are listed the possible error types:

    Errors of note

    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 is returning this error, 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:

    Warning: 299 - The following values weren't updated by the PMS: foo, bar
    

    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.

    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 developer web client.

    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.

    Version 2018-07-05 changelog

    This is the earliest available version tag.

    Version 2018-11-27 changelog

    No data found example response

    {
      "data": [],
      "_meta": {
        "pms": "EXAMPLE_PMS"
      }
    }
    

    GET single resource not found - new format

    {
      "type": "NOT_FOUND",
      "message": "Not found."
    }
    

    Guides

    Handling Bookings

    Reservation, stay, booking. The world of hospitality has a number of different words for very similar concepts. At Impala, we flatten this down to two objects:

    Imagine calling a hotel and asking to book a room for you and a room for your brother. You will have effectively created one BookingSet and two Bookings at the PMS.

    Creating Bookings

    The right approach with Impala is always to create a BookingSet directly, even where there is only one room stay being created. The POST /booking-set endpoint is considered Standard-Flow.

    You can also create bookings via the POST /booking endpoint where the PMS supports it but this is considered Edge-Case and should only be used where the PMS does not support creating by BookingSet

    Being Updated about New Bookings

    The best approach to being updated about new bookings is to use the relevant Bookings endpoints and webhooks. The reason for this is that new bookings can be added to a BookingSet and so you won't receive them if you're listening to the senior endpoint/webhook.

    childCount vs infantCount

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

    If you don't care about this distinction then simply add childCount and infantCount together.

    When writing, Impala only supports childCount.

    Handling Bills

    Where the bill lives and to whom it belongs is one of the most divergent features of a PMS. Some believe that the bill belongs to the Guest, some believe it's the Booking and some think it lives with the Room.

    At Impala you should access the bill via the Booking. Behind the scenes we will, wherever possible, retrieve the relevant bill no matter where it lives in the PMS.

    Handling payments & charges happen directly on the bill record itself (e.g. POST /bill/:id/charge) and so there's no need to worry about if the PMS is an Edge-Case in this instance.

    Handling Guests

    Normally, vendors will only need to handle guests as part of a booking. If this is the case then doing so with Impala is very easy.

    Creating Guests at Booking Creation

    Creating a BookingSet, you will see there is a parameter contact and a parameter guests. This represents the distinction between the customer that booked the room and the guests that are staying in it (although this could be the same person).

    Where the Contact is of the type guest, you do not have to include the guest again in the guests array, it will be created automatically.

    For all other guests, you can include them within the guests array (or ids of existing guests that are listed at the PMS).

    Outside of Bookings

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

    Handling Rates

    Much like bookings, every PMS deals with and thinks about rates in a slightly different way (rate groups, rate sets, rates, rate plans, rate prices etc). At Impala we have two main rate objects:

    There is also another object RateSet which is a container of one or more RatePlans that share some commonality. This is considered Edge-Case and only exists to support certain PMS.

    Retrieving all Rates

    As an RMS, often you want to retrieve the different rates that are used at a property. We suggest doing this by using GET /rate-plan. This will return all rate plans at the property. You should only use GET /rate-set when you are using a PMS that has a higher level container (listed in the RatePlan resource).

    Providing a Rate Decision

    As standard (unless we've built an adapter), you will provide rate decisions using the PUT /rate-plan/:id/price endpoint. This will have one of two effects at the PMS:

    What is a base price?

    Some PMS have Rate Plans that provide a price as standard and then derive Rate Prices as either a percentage of or addition to that base price.

    Handling Taxes

    For resources like Charges, Bookings and Extras you will see the schema describes a number of financial properties:

    On reading, we only guarantee grossAmount will be present. On writing, we only guarantee that the grossAmount can be written.

    Literally every PMS deals with fiscalization differently and so if you're building something that requires reading a very deep connection to the tax details of a charge, you can inspect the _extras field that comes with a charge. This is all the un-normalizable data we receive from the PMS and should contain further details.

    Webhooks

    Webhooks allow you to subscribe to changes in hotel resources 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 developer web client.

    The User-Agent header for the requests will have a prefix of Impala-Hookshot/.

    Not realtime

    Webhooks are not realtime. We fetch data from the PMS approximately every 15 minutes (depending on the integration), at which point we detect any differences. If we can detect a particular webhook, that webhook will be sent.

    Do not depend on a webhook being fired instantly when something happens in the PMS, our webhooks are not realtime.

    Fetch range

    Where data may have a time associated with it (Booking, BookingSet, 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.

    Authenticating webhook requests

    Example verification (select "Node" above)

    const crypto = require('crypto');
    
    const hmac = crypto.createHmac('SHA256', 'my-webhook-secret');
    hmac.update('{ ... }'); // request body
    const correctHash = hmac.digest().toString('hex');
    
    const receivedHash = '...'; // e.g. req.get('x-impala-signature');
    
    /*
     * It's important to perform a constant time equality comparison of the
     * two HMACs to avoid timing attacks.
     *
     * See: https://en.wikipedia.org/wiki/Timing_attack
     */
    if (
      receivedHash.length === correctHash.length &&
      crypto.timingSafeEqual(
        Buffer.from(correctHash),
        Buffer.from(receivedHash)
      )
    ) {
      // Request is valid
    } else {
      throw new Error('Authentication failed.');
    }
    

    Each application has a unique webhook secret that is used to sign the JSON body of webhook requests and it can be viewed and regenerated in the developer web client. 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.

    An example of performing this check in Node.JS is shown to the right. If it's not visible, select the "Node" language at the top right of the page.

    Webhook anatomy

    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

    All the possible types and corresponding events formats are described below.

    Webhook types and events formats

    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 BookingSet 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 BookingSet 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": [
        {
          "oldBooking": {...},
          "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:

    Property Type Description
    oldBooking Booking The old version of the booking
    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

    Reference

    Resources

    A 'resource' is a particular set of data available through the API. Each resource has a set of methods, specific to the resource type, for interacting with the data.

    Non-Mapped Parameters

    Imagine a record that we normalized that had a name parameter only but an underlying PMS also provided a "foo" parameter as well. It's the only PMS that does so so we haven't mapped it to our domain. Instead we provide it in extras.

    {
      "id": 1,
      "name": "x",
      "_extras": {
        "foo": "bar",
      },
    }
    

    Impala normalizes the data that we receive from the PMS into the fields described in each resource. Different PMS however sometimes support further additional fields (for instance, one PMS might return a "first initial" field on the guest resource).

    Where this is true and we haven't explicitly normalized the data, we provide it 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.

    Meta Element

    The _meta element returned includes information about the object you're fetching such as the last time that the object was refreshed and the PMS that it comes from. It also includes any data relevant to pagination, as described below.

    Address

    Any physical address reported by Impala.

    Schema

    Parameter Type Description
    line1 string
    line2 string
    city string
    postalCode string
    countryCode string See country codes

    Allocation (Group Block)

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

    Allocations are typically only supported by larger PMS.

    Schema

    Parameter Type Description
    id string
    start timestamp See dates
    end timestamp See dates
    contact Contact
    cutoffDate timestamp The date on which the Allocation will be released
    cutoffType ABSOLUTE or DAY_BY_DAY See below
    allocationRestrictions array of AllocationRestrictions
    createdAt timestamp See dates
    updatedAt timestamp See dates
    status AllocationStatus Where supported

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

    Getting all Allocations

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/allocation \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "start": "string",
          "end": "string",
          "cutoffDate": 0,
          "cutoffType": "ABSOLUTE",
          "status": "CANCELLED",
          "contact": { ... },
          "allocationRestrictions": [ ... ],
          "createdAt": 0,
          "updatedAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to get all Allocations at the property.

    HTTP Request

    GET /allocation

    Return Value

    Parameter Type Description
    data array of Allocations
    _meta Object

    Getting a specific Allocation

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/allocation/:allocationId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "start": "string",
        "end": "string",
        "cutoffDate": 0,
        "cutoffType": "ABSOLUTE",
        "status": "CANCELLED",
        "contact": { ... },
        "allocationRestrictions": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve a specific Allocation.

    HTTP Request

    GET /allocation/:id

    Path Parameters

    Parameter Type Description
    id string The ID of the allocation to retrieve

    Return Value

    Parameter Type Description
    data Allocation
    _meta Object

    Allocation Restriction

    An Allocation Restriction lists the areas and rates to which an Allocation applies.

    Schema

    Parameter Type Description
    areaTypeId string
    ratePlanId string
    date timestamp The date on which the restriction applies (null indicates the entire allocation)
    numberOfAreas integer See below
    numberOfAreasFree integer See below
    numberOfAreasPickedUp integer See below

    numberOfAreas refers to the total number of areas that were allocated for the allocation when the allocation was created. numberOfAreasFree refers to the total number of areas still available on the allocation. numberOfAreasPickedUp refers to the total number of areas from the allocation that are no longer available.

    Impala does not reduce the number of areas available for you when the cutoffType of the parent Allocation is DAY_BY_DAY (or ABSOLUTE but you wouldn't need to reduce the number of areas anyway).

    Allocation Status

    An Allocation Status typically represents how concrete an allocation is.

    Options

    Amount Description

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

    Schema

    Parameter Type Description
    type AmountDescriptionType See below.
    value integer / string See below.

    AmountDescriptionType

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

    Either:

    Area

    An Area is an object in the hotel that can be rented out (usually a room or bed).

    Areas vs Rooms

    Impala, like the PMS it abstracts, supports multiple 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 AreaType rather than an Room Type.

    Typically there's no complexity in the implementation (hostels simply have more AreaTypes). 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). It can also happen if the hostel rents out whole dormitories as well as the beds inside.

    Schema

    Parameter Type Description
    id string
    name string
    areaTypeId string
    status AreaStatus
    description string
    parentAreaId string

    Getting a list of Areas

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/area \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "name": "string",
          "areaTypeId": "string",
          "status": "CLEAN",
          "description": "string",
          "parentAreaId": "string",
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to retrieve a list of areas at the property.

    HTTP Request

    GET /area

    Query Parameters

    Parameter Type Description
    name string The name of the area, please note that this is not guaranteed to be unique.

    Return Value

    Parameter Type Description
    data array of Areas
    _meta object

    Getting a specific Area

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/area/:areaId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "name": "string",
        "areaTypeId": "string",
        "status": "CLEAN",
        "description": "string",
        "parentAreaId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to retrieve a specific area at the property.

    HTTP Request

    GET /area/:id

    Path Parameters

    Parameter Type Description
    id string The ID of the Area

    Return Value

    Parameter Type Description
    data Area
    _meta object

    Changing the Area Status of an Area

    Example Request

    curl -X PUT \
      https://api.getimpala.com/v2/hotel/:hotelId/area/:areaId/status \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "status": "CLEAN" }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "name": "string",
        "areaTypeId": "string",
        "status": "CLEAN",
        "description": "string",
        "parentAreaId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to update the Area Status of an Area.

    HTTP Request

    PUT /area/:id/status

    Path Parameters

    Parameter Type Description
    id string The ID of the Area

    Body Parameters

    Parameter Type Description
    status Area Status

    Return Value

    An object of type Area

    Area Status

    An Area Status is a string with the following possible values:

    Value Meaning Write Support
    CLEAN All PMS
    DIRTY All PMS
    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 a fringe value

    Area Types

    Schema

    Parameter Type Description
    id string
    code string
    name string
    description string
    maxOccupancy integer
    parentAreaTypeId string

    Get all Area Types

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/area-type \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "name": "string",
          "code": "string",
          "description": "string",
          "maxOccupancy": 0,
          "parentAreaTypeId": "string",
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to retrieve a list of all area types at the property.

    HTTP Request

    GET /area-type

    Return Value

    Parameter Type Description
    data array of Area Types
    _meta object

    Get a specific Area Type

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/area-type/:areaTypeId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "name": "string",
        "code": "string",
        "description": "string",
        "maxOccupancy": 0,
        "parentAreaTypeId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to retrieve a single area type.

    HTTP Request

    GET /area-type/:id

    Path Parameters

    Parameter Type Description
    id string

    Return Value

    Parameter Type Description
    data AreaType
    _meta object

    Bill

    A Bill is a container of Charges and Payments.

    Schema

    Parameter Type Description
    id string
    reference string
    dueDate Unix timestamp See dates
    issuedDate Unix timestamp See dates
    charges array of Charges
    payments array of Payments
    status BillStatus
    isPaid Boolean
    bookingId integer
    guestId integer

    Get a single Bill

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "dueDate": 0,
        "issuedDate": 0,
        "charges": [ ... ],
        "payments": [ ... ],
        "status": "OPEN",
        "isPaid": true,
        "bookingId": "string",
        "guestId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve a specific bill.

    HTTP Request

    GET /bill/:id

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill

    Return Value

    Parameter Type Description
    data Bill
    _meta object

    Get a list of Charges for the Bill

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/charge \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "billId": "string",
          "netAmount": 0,
          "grossAmount": 0,
          "taxAmount": 0,
          "taxRate": "string",
          "currencyCode": "string",
          "description": "string",
          "notes": "string",
          "isVoid": true,
          "chargedAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve all the Charges on the Bill.

    HTTP Request

    GET /bill/:id/charge

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill

    Return Value

    Parameter Type Description
    data array of Charges
    _meta object

    Get a single Charge

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/charge/:chargeId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "billId": "string",
        "netAmount": 0,
        "grossAmount": 0,
        "taxAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "description": "string",
        "notes": "string",
        "isVoid": true,
        "chargedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve a specific Charge on a Bill.

    HTTP Request

    GET /bill/:id/charge/:chargeId

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill
    chargeId string The ID of the Charge

    Return Value

    Parameter Type Description
    data Charge
    _meta object

    Add a new Charge to a Bill

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/charge \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "grossAmount": 0, "taxRate": "", "currencyCode": "", "description": "", "notes": "", "chargedAt": 1531083565 }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "dueDate": 0,
        "issuedDate": 0,
        "charges": [ ... ],
        "payments": [ ... ],
        "status": "OPEN",
        "isPaid": true,
        "bookingId": "string",
        "guestId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to add a new Charge to a Bill.

    HTTP Request

    POST /bill/:id/charge

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill

    Body Parameters

    Parameter Type Description
    grossAmount integer See handling taxes
    taxRate string Tax expressed as a fractional decimal (0 <= x <= 1)
    currencyCode string See currencies
    description string
    notes string
    chargedAt Unix timestamp See dates

    Return Value

    Parameter Type Description
    data Bill
    _meta Object

    For certain PMS (see caveats) the data property returned will be null.

    Refund a Charge on Bill

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/charge/:chargeId/refund \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "dueDate": 0,
        "issuedDate": 0,
        "charges": [ ... ],
        "payments": [ ... ],
        "status": "OPEN",
        "isPaid": true,
        "bookingId": "string",
        "guestId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to refund or void a Charge.

    HTTP Request

    POST /bill/:id/charge/:chargeId/refund

    Path Parameters

    Parameter Type Description
    id string The id of the Bill
    chargeId string The id of the Charge

    Return Value

    Parameter Type Description
    data Bill
    _meta Object

    For certain PMS (see caveats) the data property returned will be null.

    Get a list of Payments on Bill

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/payment \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "billId": "string",
          "amount"
          "currencyCode": "string",
          "description": "string",
          "notes": "string",
          "isVoid": true,
          "paymentType": "CASH",
          "paidAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to get a list of payments related to a bill.

    HTTP Request

    GET /bill/:id/payment

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill

    Return Value

    Parameter Type Description
    data array of Payments
    _meta Object

    Get a single Payment

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/payment/:paymentId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "billId": "string",
        "amount": "string",
        "currencyCode": "string",
        "notes": "string",
        "isVoid": true,
        "paymentType": "CASH",
        "paidAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve a single payment.

    HTTP Request

    GET /bill/:id/payment/:paymentId

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill
    paymentId string The ID of the Payment

    Return Value

    Parameter Type Description
    data Payment
    _meta Object

    Add a new Payment to a Bill

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/payment \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "amount": 0, "currencyCode": "", "description": "", "notes": "", "isVoid": false, "paymentType": "" }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "dueDate": 0,
        "issuedDate": 0,
        "charges": [ ... ],
        "payments": [ ... ],
        "status": "OPEN",
        "isPaid": true,
        "bookingId": "string",
        "guestId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to add a new payment to a bill.

    HTTP Request

    POST /bill/:id/payment

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill

    Body Parameters

    Parameter Type Description
    description string Information about the payment type or other aspect of payment
    grossAmount integer The amount paid
    currencyCode string See prices
    notes string
    isVoid boolean Extremely limited PMS support, means void payment rather than a "refund"
    paymentType PaymentType

    Return Value

    Parameter Type Description
    data Bill
    _meta Object

    For certain PMS (see caveats) the data property returned will be null.

    Refund a Payment

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/bill/:billId/payment/:paymentId/refund \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "dueDate": 0,
        "issuedDate": 0,
        "charges": [ ... ],
        "payments": [ ... ],
        "status": "OPEN",
        "isPaid": true,
        "bookingId": "string",
        "guestId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    
    

    Standard-Flow

    Use this to refund a payment.

    HTTP Request

    POST /bill/:id/payment/:paymentId/refund

    Path Parameters

    Parameter Type Description
    id string The ID of the Bill
    paymentId string The id of the Payment

    Return Value

    Return Value

    Parameter Type Description
    data Bill
    _meta Object

    For certain PMS (see caveats) the data property returned will be null.

    Bill Status

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

    Value Meaning Write Support
    OPEN The bill is open All PMS
    CLOSED The bill is closed All PMS

    Billing Scheme

    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.

    Guestline

    MEWS

    HTNG/Infor

    Billing Frequency

    BillingFrequency is a string that has one of the following values (dependent on the PMS). If unlisted below, the PMS doesn't support differing BillingFrequency.

    Guestline

    Booking

    A Booking represents a booking or reservation at a hotel.

    Schema

    {
      "id": 1,
      "reference": "XJKRSJG",
      "externalReferences": ["...", ...],
      "bookingSetId": 1,
      "ratePlanId": "string",
      "channelManager": "MyAllocator",
      "marketCode": "string",
      "statusCode": "string",
      "status": null,
      "origin": null,
      "start": 1530025705,
      "end": 1530284905,
      "areaId": 1,
      "requestedAreaTypeId": null,
      "allocationId": null,
      "adultCount": 1,
      "childCount": 0,
      "infantCount":  0,
      "netAmount": 0,
      "taxAmount": 0,
      "grossAmount": 0,
      "taxRate": "string",
      "currencyCode": "string",
      "amountBreakdown": [...],
      "contact": { ... },
      "guestIds": [2, 3],
      "createdAt": 1520025705,
      "cancelledAt": null,
      "updatedAt": 1520025707,
      "_extras": { ... },
      "_meta": { ... },
    }
    
    Parameter Type Notes
    id string
    reference string The confirmation number the hotel handles with the guest.
    externalReferences array of strings Confirmation numbers that the guest has from the parties they booked with (Booking.com, Expedia, etc.).
    bookingSetId string The ID of the BookingSet
    ratePlanId string The ID of the RatePlan the booking was booked under
    channelManager string The name of the channel manager that provided the booking
    marketCode string Free form text, often used to indicate market segment e.g. business/leisure
    sourceCode string Free form text, used to indicate the source of the booking
    status BookingStatus
    origin string
    start timestamp The start of the booking. See dates.
    end timestamp The end of the booking. See dates.
    areaId string The ID of the Area
    requestedAreaTypeId string The initial requested type
    adultCount integer
    childCount integer
    infantCount integer
    netAmount integer Amount before tax. See prices
    grossAmount integer Amount after tax. See prices
    taxAmount integer Tax expressed as an amount. See prices
    taxRate string Tax expressed as a fractional decimal (0 <= x <= 1)
    currencyCode string See currencies
    amountBreakdown array of Booking Amount Breakdown
    contact Contact
    guestIds array of strings The ID of the Guests
    allocationId string This ID of the Allocation to which the booking belongs
    createdAt timestamp The date that the booking was created. See dates
    cancelledAt timestamp The date that the booking was cancelled. See dates
    updatedAt timestamp The time the booking was last updated. See dates

    Contact Mirroring

    Where the contact field is a guest, you will see the same guest in the guestIds field.

    Get a List of Bookings

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/booking \
      -H 'Authorization: Bearer XXX' \
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "reference": "string",
          "externalReferences": ["123", "XYZ"],
          "bookingSetId": "string",
          "ratePlanId": "string",
          "channelManager": "string",
          "marketCode": "",
          "sourceCode": "",
          "status": "NO_SHOW",
          "origin": "string",
          "start": 0,
          "end": 0,
          "areaId": "string",
          "requestedAreaTypeId": "string",
          "allocationId": "string",
          "adultCount": 0,
          "childCount": 0,
          "infantCount": 0,
          "netAmount": 0,
          "taxAmount": 0,
          "grossAmount": 0,
          "taxRate": "string",
          "currencyCode": "string",
          "amountBreakdown": [...],
          "contact": { ... },
          "guestIds": [ ... ],
          "createdAt": 0,
          "updatedAt": 0,
          "cancelledAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": {}
    }
    

    Standard-Flow

    Use when trying to retrieve bookings between certain dates or according to certain criteria. Can also be used for an initial setup.

    HTTP Request

    GET /booking

    Query Parameters

    Parameter Type Description
    startDate date The earliest any returned booking should start. See dates
    endDate date The latest any returned booking should end. See dates
    areaId string The ID of the Area the booking should have.

    By default the API will return +/- 7 days. The maximum historic return (without contacting us) is 365 days in the past. There is no maximum return.

    Return Value

    Parameter Type Description
    data array of Bookings
    _meta object

    Get a Specific Booking

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/booking/:bookingId \
      -H 'Authorization: Bearer XXX' \
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "externalReferences": ["123", "XYZ"],
        "bookingSetId": "string",
        "ratePlanId": "string",
        "channelManager": "string",
        "marketCode": "string",
        "sourceCode": "string",
        "status": "NO_SHOW",
        "origin": "string",
        "start": 0,
        "end": 0,
        "areaId": "string",
        "requestedAreaTypeId": "string",
        "allocationId": "string",
        "adultCount": 0,
        "childCount": 0,
        "infantCount": 0,
        "netAmount": 0,
        "taxAmount": 0,
        "grossAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "amountBreakdown": [...],
        "contact": { ... },
        "guestIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "cancelledAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use when trying to retrieve a specific booking.

    HTTP Request

    GET /booking/:id

    Path Parameters

    Parameter Type Description
    id string The id of the booking you're trying to retrieve

    Create a Booking

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/booking \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "start": 1520025705, "end": 152400000, "requestedAreaTypeId": "", "ratePlanId": "", "guests": [], "adultCount": 0, "childCount": 0, "contact": {} }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "externalReferences": ["123", "XYZ"],
        "bookingSetId": "string",
        "ratePlanId": "string",
        "channelManager": "string",
        "marketCode": "string",
        "sourceCode": "string",
        "status": "NO_SHOW",
        "origin": "string",
        "start": 0,
        "end": 0,
        "areaId": "string",
        "requestedAreaTypeId": "string",
        "allocationId": "string",
        "adultCount": 0,
        "childCount": 0,
        "infantCount": 0,
        "netAmount": 0,
        "taxAmount": 0,
        "grossAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "amountBreakdown": [...],
        "contact": { ... },
        "guestIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "cancelledAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Edge-Case

    Should only be used to create a Booking when the PMS does not support creating via BookingSet.

    HTTP Request

    POST /booking

    Body Parameters

    Parameter Type Description
    start timestamp The start of the booking. See dates
    end timestamp The end of the booking. See dates
    requestedAreaTypeId string
    ratePlanId string
    guests array of Guests or Guest Ids Either can be provided
    adultCount integer
    childCount Number
    contact Contact

    Return Value

    Parameter Type Description
    data Booking
    _meta object

    Updating a Booking

    Example Request

    curl -X PATCH \
      https://api.getimpala.com/v2/hotel/:hotelId/booking/:bookingId \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "start": 1520025705, "end": 152400000, "requestedAreaTypeId": "", "ratePlanId": "", "guests": [], "adultCount": 0, "childCount": 0, "contact": {} }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "externalReferences": ["123", "XYZ"],
        "bookingSetId": "string",
        "ratePlanId": "string",
        "channelManager": "string",
        "marketCode": "string",
        "sourceCode": "string",
        "status": "NO_SHOW",
        "origin": "string",
        "start": "string",
        "end": "string",
        "areaId": "string",
        "requestedAreaTypeId": "string",
        "allocationId": "string",
        "adultCount": 0,
        "childCount": 0,
        "infantCount": 0,
        "netAmount": 0,
        "taxAmount": 0,
        "grossAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "amountBreakdown": [...],
        "contact": { ... },
        "guestIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "cancelledAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Should be used to update information on a booking.

    HTTP Request

    PATCH /booking/:id

    Path Parameters

    Parameter Type Description
    id string ID of the Booking to edit.

    Body Parameters

    Parameter Type Description
    start timestamp The start of the booking. See dates
    end timestamp The end of the booking. See dates
    requestedAreaTypeId string Changes the requestedAreaTypeId.
    ratePlanId string
    guests array of Guests or Guest Ids Either can be provided. Will replace all guests on the record.
    adultCount integer
    childCount integer
    contact Contact

    Return Value

    Parameter Type Description
    data Booking
    _meta object

    Checking in a Booking

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/booking/:bookingId/check-in \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "externalReferences": ["123", "XYZ"],
        "bookingSetId": "string",
        "ratePlanId": "string",
        "channelManager": "string",
        "marketCode": "string",
        "sourceCode": "string",
        "status": "NO_SHOW",
        "origin": "string",
        "start": "string",
        "end": "string",
        "areaId": "string",
        "requestedAreaTypeId": "string",
        "allocationId": "string",
        "adultCount": 0,
        "childCount": 0,
        "infantCount": 0,
        "netAmount": 0,
        "taxAmount": 0,
        "grossAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "amountBreakdown": [...],
        "contact": { ... },
        "guestIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "cancelledAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to check in a booking.

    HTTP Request

    POST /booking/:id/check-in

    Path Parameters

    Parameters Type Description
    id string ID of the Booking

    Return Value

    Returns an object of Parameter Type Description
    data Booking
    _meta object

    Checking out a Booking

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/booking/:bookingId/check-out \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "externalReferences": ["123", "XYZ"],
        "bookingSetId": "string",
        "ratePlanId": "string",
        "channelManager": "string",
        "marketCode": "string",
        "sourceCode": "string",
        "status": "NO_SHOW",
        "origin": "string",
        "start": "string",
        "end": "string",
        "areaId": "string",
        "requestedAreaTypeId": "string",
        "allocationId": "string",
        "adultCount": 0,
        "childCount": 0,
        "infantCount": 0,
        "netAmount": 0,
        "taxAmount": 0,
        "grossAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "amountBreakdown": [...],
        "contact": { ... },
        "guestIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "cancelledAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to check out a booking.

    HTTP Request

    POST /booking/:id/check-out

    Path Parameters

    Parameters Type Description
    id string ID of the Booking

    Return Value

    Parameter Type Description
    data Booking
    _meta object

    Cancelling a Booking

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/booking/:bookingId/cancel \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "reference": "string",
        "externalReferences": ["123", "XYZ"],
        "bookingSetId": "string",
        "ratePlanId": "string",
        "channelManager": "string",
        "marketCode": "string",
        "sourceCode": "string",
        "status": "NO_SHOW",
        "origin": "string",
        "start": "string",
        "end": "string",
        "areaId": "string",
        "requestedAreaTypeId": "string",
        "allocationId": "string",
        "adultCount": 0,
        "childCount": 0,
        "infantCount": 0,
        "netAmount": 0,
        "taxAmount": 0,
        "grossAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "amountBreakdown": [...],
        "contact": { ... },
        "guestIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "cancelledAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to cancel a booking.

    HTTP Request

    POST /booking/:id/cancel

    Path Parameters

    Parameters Type Description
    id string ID of the Booking

    Return Value

    Parameter Type Description
    data Booking
    _meta object

    Getting all Guests on a Booking

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/booking/:bookingId/guest \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "title": "string",
          "firstName": "string",
          "middleName": "string",
          "lastName": "string",
          "sexCode": 0,
          "emails": [ ... ],
          "phoneNumbers": [ ... ],
          "languageCode": "string",
          "nationalityCode": "string",
          "dateOfBirth": "string",
          "placeOfBirth": "string",
          "notes": "string",
          "classifications": [ ... ],
          "documents": [ ... ],
          "addresses": [ ... ],
          "createdAt": 0,
          "updatedAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to retrieve a list of all guests for a booking

    HTTP Request

    GET /booking/:id/guest

    Path Parameters

    Parameters Type Description
    id string ID of the Booking

    Return Value

    Parameter Type Description
    data array of Guests
    _meta object

    Getting the Bill for a Booking

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/booking/:bookingId/bill \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "dueDate": "string",
          "issuedDate": "string",
          "charges": [ ... ],
          "payments": [ ... ],
          "status": "OPEN",
          "isPaid": true,
          "bookingId": "string",
          "guestId": "string",
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to retrieve a list of bills for a booking

    HTTP Request

    GET /booking/:id/bill

    Path Parameters

    Parameters Type Description
    id string ID of the Booking

    Return Value

    Parameter Type Description
    data array of Bills
    _meta object

    Booking Set

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

    Schema

    Sample Object

    {
      "id": 1,
      "parentId": null,
      "reference": "XFKJRJFF",
      "start": 1530025705,
      "end": 1530284905,
      "contact": {
        "type": "guest",
        "id": 1,
      },
      "bookingIds": [456],
      "createdAt": 1530025705,
      "updatedAt": null,
      "_extras": { ... },
      "_meta": { ... },
    }
    
    Parameter Type Description
    id string
    parentId string Some PMS support nested BookingSets.
    reference string
    start timestamp The start of the bookings in the set. See dates
    end timestamp The end of the bookings in the set. See dates
    contact Contact
    bookingIds array of strings The IDs of Bookings within the Set
    createdAt timestamp The date that the booking set was created. See dates
    updatedAt timestamp The time the booking set was last updated. See dates

    Get all Booking Sets

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/booking-set \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "parentId": "string",
          "reference": "string",
          "start": 0,
          "end": 0,
          "contact": { ... },
          "bookingIds": [ ... ],
          "createdAt": 0,
          "updatedAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": {}
    }
    

    Standard-Flow

    Use when trying to retrieve bookings for the first time where the PMS supports. Do not use to poll what new bookings have been created. (see Handling Bookings)

    HTTP request

    GET /booking-set

    Query parameters

    Parameter Type Description
    startDate date The earliest record you wish to return. See dates
    endDate date The latest record you wish to return. See dates

    Get Specific Booking Set

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/booking-set/:bookingSetId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "parentId": "string",
        "reference": "string",
        "start": 0,
        "end": 0,
        "contact": { ... },
        "bookingIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Return a Booking Set with a specific ID

    HTTP Request

    GET /booking-set/:id

    Path Parameters

    Parameter Type Description
    id string The ID of the Booking Set you're retrieving

    Create a Booking Set

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/booking-set \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "parentId": "", "reference": "", "contact": {}, "bookings": [] }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "parentId": "string",
        "reference": "string",
        "start": 0,
        "end": 0,
        "contact": { ... },
        "bookingIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to create booking sets, bookings and the associated guests.

    HTTP Request

    POST /booking-set

    Body Parameters

    Parameter Type Description
    parentId string Some PMS support nested BookingSets
    reference string
    contact Contact
    bookings array of ids or Bookings Providing booking objects will create new bookings

    Change a Booking Set

    Example Request

    curl -X PATCH \
      https://api.getimpala.com/v2/hotel/:hotelId/booking-set \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "parentId": "", "reference": "", "contact": {}, "bookings": [] }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "parentId": "string",
        "reference": "string",
        "start": 0,
        "end": 0,
        "contact": { ... },
        "bookingIds": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Edge-Case

    Used to update a booking set

    HTTP Request

    PATCH /booking-set/:id

    Body Parameters

    Parameter Type Description
    parentId string Some PMS support nested BookingSets
    reference string
    contact Contact
    bookings array of ids or Bookings Providing booking objects will create new bookings

    Booking Status

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

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

    Booking Amount Breakdown

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

    Schema

    Parameter Type Description
    duration string Booking Amount Breakdown Duration.
    start timestamp The start of the period delimited by duration. See dates.
    netAmount integer Amount before tax. See prices.
    grossAmount integer Amount after tax. See prices.
    taxAmount integer Tax expressed as an amount. See prices.
    taxRate string Tax expressed as a fractional decimal (0 <= x <= 1).

    Booking Amount Breakdown Duration

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

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

    Charge

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

    Schema

    Parameter Type Description
    id string The ID of the Charge
    billId string The Bill that the charge belongs to
    netAmount integer Amount before tax. See prices
    grossAmount integer Amount after tax. See prices
    taxAmount integer Tax expressed as an amount. See prices
    taxRate string Tax expressed as a fractional decimal (0 <= x <= 1)
    currencyCode string See currencies
    description string
    notes string
    isVoid boolean
    chargedAt timestamp See dates caveats

    Company

    A Company can be referenced from a Booking of a business traveler or from a Guest who is generally staying for business travel. When a booking is made by a Travel Agency, their Company is linked to the booking, too.

    Schema

    See below for the schema of the standard Company object.

    Parameter Type Notes
    id string
    companyType Company Type
    reference string
    name string
    addresses array of Addresses
    emails array of Strings
    phoneNumbers array of Strings
    taxId string The tax ID or VAT number of the business

    Getting a specific Company

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/company/:companyId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "companyType": "string",
        "reference": "string",
        "name": "string",
        "emails": [ ... ],
        "phoneNumbers": [ ... ],
        "addresses": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use when trying to retrieve information about a specific company.

    HTTP Request

    GET /company/:id

    Path Parameters

    Parameter Type Description
    id integer The ID of the Company

    Return Value

    Parameter Type Description
    data Company
    _meta object

    Creating a new Company

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/company \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "name": "", "taxid": "", "emails": [], "phoneNumbers": [], "addresses": [] }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "companyType": "string",
        "reference": "string",
        "name": "string",
        "emails": [ ... ],
        "phoneNumbers": [ ... ],
        "addresses": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Edge-Case

    Use when trying to create a new company independent of a particular booking. This endpoint is Edge-Case as it is expected that you will create bookings as part of the Booking creation in the vast majority of cases.

    HTTP Request

    POST /company

    Body Parameters

    Parameter Type Notes
    companyType Company Type
    reference string
    name string
    addresses array of Addresses
    emails array of Strings
    phoneNumbers array of Strings
    taxId string The tax ID or VAT number of the business

    Return Value

    Parameter Type Description
    data Company
    _meta object

    Updating an existing Company

    Example Request

    curl -X PATCH \
      https://api.getimpala.com/v2/hotel/:hotelId/company/:companyId \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "id": "", "name": "" }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "companyType": "string",
        "reference": "string",
        "name": "string",
        "emails": [ ... ],
        "phoneNumbers": [ ... ],
        "addresses": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to update the existing record of a company.

    HTTP Request

    PATCH /company/:id

    Path Parameters

    Parameter Type Description
    id string The ID of the guest.

    Body Parameters

    Parameter Type Notes
    companyType Company Type
    reference string
    name string
    addresses array of Addresses
    emails array of Strings
    phoneNumbers array of Strings
    taxId string The tax ID or VAT number of the business

    Return Value

    Parameter Type Description
    data Company
    _meta object

    Company Type

    Company Type is a string with the following possible values:

    Value Meaning
    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.

    Contact

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

    Schema

    {
      "type": "guest",
      "data": {
        "title": "Mr.",
        "firstName": "Joe",
        "lastName": "Jones",
      },
    }
    
    Parameter Type Description
    type string guest or company
    data Object Optional, if type is guest then an object that matches the Guest schema
    id string Optional

    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.

    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.

    Schema

    Parameter Type
    email boolean
    sms boolean
    phone boolean

    Document

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

    Schema

    Parameter Type Description
    type string The type of document i.e. "Passport", "Drivers Licence".
    number string The relevant identification/issue number for the document.

    Extra

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

    Schema

    Parameter Type Description
    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 See currencies
    createdAt timestamp The date that the extra was created. See dates
    updatedAt timestamp The time the extra was last updated. See dates

    Getting a list of Extras

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/extra \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "isActive": true,
          "name": "string",
          "code": "string",
          "description": "string",
          "billingScheme": "ONCE",
          "billingFrequency": "EVERY_BLOCK",
          "netAmount": 0,
          "grossAmount": 0,
          "taxAmount": 0,
          "taxRate": "string",
          "currencyCode": "string",
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to get all the extras available at a hotel.

    HTTP Request

    GET /extra

    Return Value

    Parameter Type Description
    data array of Extras
    _meta Object

    Getting a specific Extra by id

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/extra/:extraId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "isActive": true,
        "name": "string",
        "code": "string",
        "description": "string",
        "billingScheme": "ONCE",
        "billingFrequency": "EVERY_BLOCK",
        "netAmount": 0,
        "grossAmount": 0,
        "taxAmount": 0,
        "taxRate": "string",
        "currencyCode": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to get a specific extra available at the hotel.

    HTTP Request

    GET /extra/:id

    Return Value

    Parameter Type Description
    data Extra
    _meta Object

    Guest

    A Guest represents a human person staying at a hotel.

    Schema

    See below for the schema of the standard Guest object.

    Parameter Type Notes
    id string
    title string
    firstName string
    middleName string
    lastName string
    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
    phoneNumbers array of Strings
    languageCode string See caveats
    nationalityCode string See caveats
    dateOfBirth string
    placeOfBirth string
    loyaltyPrograms array of LoyaltyPrograms
    notes string
    classifications array of GuestClassifications
    documents array of Documents
    addresses array of Addresses
    optIns OptInInfo Topics of communication the guest has opted in to
    contactBy ContactByInfo Communication methods the guest has opted in to
    createdAt timestamp The date that the guest was created. See dates
    updatedAt timestamp The time the guest was last updated. See dates

    Getting all Guests

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/guest?startDate=2018-01-01&endDate=2018-01-31 \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "title": "string",
          "firstName": "string",
          "middleName": "string",
          "lastName": "string",
          "sexCode": 0,
          "emails": [ ... ],
          "phoneNumbers": [ ... ],
          "languageCode": "string",
          "nationalityCode": "string",
          "dateOfBirth": "string",
          "placeOfBirth": "string",
          "notes": "string",
          "classifications": [ ... ],
          "documents": [ ... ],
          "addresses": [ ... ],
          "createdAt": 0,
          "updatedAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Edge-Case

    This is a very poorly supported endpoint amongst PMS and exists only support those few use cases where the PMS supports it.

    HTTP Request

    GET /guest

    Query Parameters

    Parameter Type Description
    startDate date The first date for which to check new or updated guests
    endDate date The last date for which to check new or updated guests

    Return Value

    Parameter Type Description
    data array of Guests
    _meta object

    Getting a specific Guest

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/guest/:guestId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "title": "string",
        "firstName": "string",
        "middleName": "string",
        "lastName": "string",
        "sexCode": 0,
        "emails": [ ... ],
        "phoneNumbers": [ ... ],
        "languageCode": "string",
        "nationalityCode": "string",
        "dateOfBirth": "string",
        "placeOfBirth": "string",
        "notes": "string",
        "classifications": [ ... ],
        "documents": [ ... ],
        "addresses": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use when trying to retrieve information about a specific guest.

    HTTP Request

    GET /guest/:id

    Path Parameters

    Parameter Type Description
    id integer The ID of the Guest

    Return Value

    Parameter Type Description
    data Guest
    _meta object

    Creating a new Guest

    Example Request

    curl -X POST \
      https://api.getimpala.com/v2/hotel/:hotelId/guest \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "title": "", "firstName": "", "middleName": "", "lastName": "", "sexCode": 0, "emails": [], "phoneNumbers": [], "languageCode": "", "nationalityCode": "", "dateOfBirth": "", "placeOfBirth": "", "notes": "", "classifications": [], "documents": [], "addresses": [] }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "title": "string",
        "firstName": "string",
        "middleName": "string",
        "lastName": "string",
        "sexCode": 0,
        "emails": [ ... ],
        "phoneNumbers": [ ... ],
        "languageCode": "string",
        "nationalityCode": "string",
        "dateOfBirth": "string",
        "placeOfBirth": "string",
        "notes": "string",
        "classifications": [ ... ],
        "documents": [ ... ],
        "addresses": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Edge-Case

    Use when trying to create a new guest independent of a particular booking. This endpoint is Edge-Case as it is expected that you will create bookings as part of the Booking creation in the vast majority of cases.

    HTTP Request

    POST /guest

    Body Parameters

    Parameter Type Notes
    title string
    firstName string
    middleName string
    lastName string
    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
    phoneNumbers array of Strings
    languageCode string See caveats
    nationalityCode string See caveats
    dateOfBirth string
    placeOfBirth string
    loyaltyPrograms array of LoyaltyPrograms
    notes string
    classifications array of GuestClassifications
    documents array of Documents
    addresses array of Addresses

    Return Value

    Parameter Type Description
    data Guest
    _meta object

    Updating an existing Guest

    Example Request

    curl -X PATCH \
      https://api.getimpala.com/v2/hotel/:hotelId/guest/:guestId \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "title": "", "firstName": "", "middleName": "", "lastName": "", "sexCode": 0, "emails": [], "phoneNumbers": [], "languageCode": "", "nationalityCode": "", "dateOfBirth": "", "placeOfBirth": "", "notes": "", "classifications": [], "documents": [], "addresses": [] }'
    

    Example Response

    {
      "data": {
        "id": "string",
        "title": "string",
        "firstName": "string",
        "middleName": "string",
        "lastName": "string",
        "sexCode": 0,
        "emails": [ ... ],
        "phoneNumbers": [ ... ],
        "languageCode": "string",
        "nationalityCode": "string",
        "dateOfBirth": "string",
        "placeOfBirth": "string",
        "notes": "string",
        "classifications": [ ... ],
        "documents": [ ... ],
        "addresses": [ ... ],
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use to update the existing record of a guest.

    HTTP Request

    PATCH /guest/:id

    Path Parameters

    Parameter Type Description
    id string The ID of the guest.

    Body Parameters

    Parameter Type Notes
    title string
    firstName string
    middleName string
    lastName string
    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 Will replace existing emails.
    phoneNumbers array of Strings Will replace existing phoneNumbers
    languageCode string See caveats
    nationalityCode string See caveats
    dateOfBirth string
    placeOfBirth string
    loyaltyPrograms array of LoyaltyPrograms Will replace existing loyalty programs
    notes string
    classifications array of GuestClassifications Will replace existing classifications
    documents array of Documents Will replace existing documents
    addresses array of Addresses Will replace existing addresses

    Return Value

    Parameter Type Description
    data Guest
    _meta object

    Getting a Guest's Bills

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/guest/:guestId/bill \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "reference": "string",
          "dueDate": 0,
          "issuedDate": 0,
          "charges": [ ... ],
          "payments": [ ... ],
          "status": "OPEN",
          "isPaid": true,
          "bookingId": "string",
          "guestId": "string"
        },
      ],
      "_meta": { ... }
    }
    

    Edge-Case

    This endpoint is a placeholder in case a future PMS has billing attached to guests and for whatever reason this cannot mapped through Booking.

    There are no cases where it is currently necessary to implement this endpoint.

    The Standard-Flow endpoint for achieving the same result is to use the Booking resource to retrieve the relevant bill.

    HTTP Request

    GET /guest/:id/bill

    Path Parameters

    Parameter Type Description
    id string The ID of the guest.

    Return Value

    Parameter Type Description
    data array of Bills
    _meta object

    Guest Classification

    An extra identifier by which to classify a guest.

    Read Options

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

    Write Options

    It is not currently supported to write a guest classification.

    Loyalty Program

    Schema

    Parameter Type Description
    code string The code representing the scheme
    membershipNumber string
    memberSince timestamp See dates

    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.

    Schema

    Parameter Type Description
    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

    Payment

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

    Schema

    Parameter Type Description
    id string
    billId string
    amount integer 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 PaymentType
    paidAt timestamp See dates

    Payment Type

    A Payment Type is a string with the following possible values:

    Value Meaning Write Support?
    CASH All PMS
    CARD Covers all card types All PMS
    BANK_TRANSFER
    CHARGE_TO_COMPANY
    CHECK
    VOUCHER
    OTHER PMS provided a response which mapped to "other" or a fringe payment method

    Rate Plan

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

    Schema

    Parameter Type Description
    id string The ID of the RatePlan
    isActive boolean Is the rate plan currently bookable
    isPublic boolean Is the rate plan available publicly or is qualified somehow
    rateSetId string Will be null in PMS that do not support rate sets
    name string
    rateRestrictions array of RateRestrictions
    rateSupplements array of RateSupplements
    parentRatePlanId string The ID of the RatePlan to which this RatePlan belongs
    createdAt timestamp See dates
    updatedAt timestamp See dates

    Get all Rate Plans

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/rate-plan \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "isActive": true,
          "isPublic": true,
          "rateSetId": "string",
          "name": "string",
          "restrictions": [ ... ],
          "supplements": [ ... ],
          "parentRatePlanId": "string",
          "createdAt": 0,
          "updatedAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve all Rate Plans at the property.

    HTTP Request

    GET /rate-plan

    Query Parameters

    Parameter Type Description
    accessCode string A code used to gain access to 'extra' rate plans not available to the public

    By default the API will return all publicly available rate plans. Providing a valid accessCode will return any private rate plans available using that code in addition to the publicly available rate plans. A rate plan's visibility is determined by any rate restrictions it has where type is ACCESS_RESTRICTION.

    Return Value

    Parameter Type Description
    data array of RatePlans
    _meta Object

    Get a specific Rate Plan

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/rate-plan/:ratePlanId \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": {
        "id": "string",
        "isActive": true,
        "isPublic": true,
        "rateSetId": "string",
        "name": "string",
        "restrictions": [ ... ],
        "supplements": [ ... ],
        "parentRatePlanId": "string",
        "createdAt": 0,
        "updatedAt": 0,
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve a specific Rate Plan at the property.

    HTTP Request

    GET /rate-plan/:id

    Path Parameters

    Parameter Type Description
    id string The ID of the RatePlan

    Return Value

    Parameter Type Description
    data RatePlan
    _meta Object

    Get the price of a Rate Plan

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/rate-plan/:ratePlanId/price \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "currency": "string",
          "date": 0,
          "price": { ... },
          "areaTypeId": "string",
          "supplements": [ ... ],
          "restrictions": [ ... ],
          "ratePlanId": "string",
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to retrieve the prices listed by the property (both base and area specific) between two dates.

    HTTP Request

    GET /rate-plan/:id/price

    Path Parameters

    Parameter Type Description
    id string The ID of the RatePlan

    Query Parameters

    Parameter Type Description
    startDate date Required. The first date to return prices for. See dates
    endDate date Required. The last date to return prices for. See dates
    areaTypeId string Optional. If not provided then the base rate price will be returned.

    Return Value

    Parameter Type Description
    data array of RatePrices
    _meta Object

    Make a pricing decision for a Rate Plan

    Example Request

    curl -X PUT \
      https://api.getimpala.com/v2/hotel/:hotelId/rate-plan/:ratePlanId/price \
      -H 'Authorization: Bearer XXX' \
      -H 'Content-Type: application/json' \
      -d '{ "date": 1543363200, "amountDescription": { "type": "ABSOLUTE", "value": 8499 }, "areaTypeId": "" }'
    

    Example Response

    {
      "data": {
        "currency": "string",
        "date": "string",
        "price": { ... },
        "areaTypeId": "string",
        "supplements": [ ... ],
        "restrictions": [ ... ],
        "parentRatePlanId": "string",
        "_extras": { ... },
        "_meta": { ... }
      },
      "_meta": { ... }
    }
    

    Standard-Flow

    Use this to change the price for a RatePlan at a date (either for a specific AreaType or the base rate).

    HTTP Request

    PUT /rate-plan/:id/price

    Body Parameters

    Parameter Type Description
    date date Required. See dates
    amountDescription AmountDescription Required
    areaTypeId string Optional. Will attempt to change the base price if omitted.

    Return Value

    Parameter Type Description
    data RatePrice
    _meta Object

    Rate Price

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

    Schema

    Parameter Type Description
    currency string
    date timestamp See dates
    price AmountDescription
    areaTypeId string Will be omitted if the RatePrice represents a base price
    ratePlanId string The ID of the rate plan the price is for
    supplements RateSupplements See below
    restrictions RateRestrictions See below

    supplements and restrictions may appear on the RatePrice object rather than the parent RatePlan in PMS where there are per-AreaType restrictions and supplements

    For how to request a rate plan's price see getting the price of a rate plan

    Rate Restriction

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

    Schema

    Parameter Type Description
    startDate timestamp The date that the restriction application begins (may be null for timeless restriction). See dates
    endDate timestamp 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 below.
    createdAt timestamp See dates
    updatedAt timestamp See dates

    daysCovered

    One of the following:

    Rate Restriction Type

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

    Options

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

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

    Rate Sets are largely Edge-Case within Impala and should only be used in the case where you have specific support requirements at a specific PMS.

    For more information, see Handling Rates.

    Schema

    Parameter Type Description
    id string This ID of the RateSet
    isActive boolean Is the rate set currently bookable?
    name string
    ratePlanIds array of strings
    createdAt timestamp See dates
    updatedAt timestamp See dates

    Get all Rate Sets

    Example Request

    curl -X GET \
      https://api.getimpala.com/v2/hotel/:hotelId/rate-set \
      -H 'Authorization: Bearer XXX'
    

    Example Response

    {
      "data": [
        {
          "id": "string",
          "isActive": true,
          "name": "string",
          "ratePlanIds": [ ... ],
          "createdAt": 0,
          "updatedAt": 0,
          "_extras": { ... },
          "_meta": { ... }
        }
      ],
      "_meta": { ... }
    }
    

    Edge-Case

    Use this, where absolutely necessary to retrieve rate sets.

    HTTP Request

    GET /rate-set

    Return Value

    Parameter Type Description
    data array of RateSets
    _meta Object

    Rate Supplement

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

    Schema

    Parameter Type Description
    quantity integer e.g. The number of additional guests
    type RateSupplementType
    amount AmountDescription
    billingScheme BillingScheme
    createdAt timestamp See dates
    updatedAt timestamp See dates

    Rate Supplement Type

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

    It is often used by PMS to describe tax.

    Options