version 2.1

The Checkfront API allows developers to expand and build on the Checkfront Booking Platform. The API makes it easy to create web, desktop & mobile applications that integrate and with your Checkfront account.

Our API is built around open, standard and secure technologies to streamline development and maintain integrity of your data.

The Checkfront API extends the following functionality:

• Query inventory availability.
• Get date based rate and pricing information.
• Create a new booking.
• Update an existing booking.
• Retrieve customer information.

This document assumes you have some knowledge of programming, and API implementations -- if not, please see our list of existing plug-ins and extensions or contact us to for in introduction to a qualified Checkfront developer in your area.

Some functionality documented here may not be available to you based on your plan, or access level of your account.

The Checkfront API uses a REST interface. This means that method calls are made over the Internet by sending standard HTTPs GET or POST requests to the Checkfront API REST server.

Nearly any computer language can be used to communicate over HTTP with the REST server including remote web sites, mobile devices and desktop applications.

Checkfront makes use of the open standard OAuth2 to provide secure and transparent authentication with the API. OAuth allows you to make your Checkfront account available to external applications without needing to provide your login and password.

All queries to the API are required to be made over a SSL authenticated OAuth2 session. Checkfront currently supports Draft 20 of the OAuth2 spec. For those switching from OAuth1, you'll notice it's significantly easier to work with, and generally performs better.

If your app isn't going to be distributed outside of your organization, you can generate oAuth2 access keys within the app to by-pass the initial authentication routine.

Please see our SDK's or support libraries for OAuth2 in your preferred environment.

Every Checkfront account operates in their own segregated environment, secure by a unique domain. In most cases, this is : https://your-company.checkfront.com. In this document this will be referred to as your Checkfront URL or your-company.checkfront.com (this may differ depending on your country).

https://your-company.checkfront.com/api/2.1/
https://your-company.checkfront.com/oauth/

All response is formatted in JSON (JavaScript Object Notation).All modern languages are able to quickly parse JSON. See: PHP: json_decode, Ruby: JSON.parse, .Net Json.NET, Javascript / jQuery: jQuery.getJSON.

• All JSON should be UTF-8 encoded.
• Date and time values ISO 8601 formatted, eg: YYYY-MM-DD, HH:MM:SS.
• Dates are specified in the timezone configured in the account unless otherwise noted.
• Booleans are either 1 (true) or 0 (false).
• Currency values are decimal formatted, e.g: 119.20.

API throttle limit: We reserve the right to tune the limitations, but they are always set high enough to allow a well-behaving interactive program to do its job.

When the rate limit is exceeded Checkfront will send an HTTP 503 status code. The number of seconds until the throttle is lifted is sent via the "Retry-After" HTTP header, as specified in RFC 2616.

Once authenticated, a basic request to the API will return some general information about the account you are connecting to. This header information is included in all successful calls to the API, but may be left out of examples in this document.

GET: http://demo.checkfront.com/api/2.1/

{
    "version":"2.1",
    "id":"demo.checkfront.com",
    "name":"Demo",
    "currency_id":"USD",
    "currency_symbol":"$",
    "session_id":"rmvm4jf7kh02n6dde8s9f20me1"
}

Error Messages

{
    "error":"invalid_request",
    "error_description":"The access token was not found."
}

API notifications provide the ability to send an automated notification when a new booking is created or updated. You can configure API notifications in your account under Manage / API / Notifications.

Our SDKs (software development kit) handles most of the complex authentication (OAuth2) issues involved with consuming the Checkfront API. They also include sample code and additional documentation and up and running with the API in no time.

All of our SDKs are open source and are available on Github. If you have a module to contribute, please let us know.

Use of this API is strictly bound by the terms as specified in Checkfront API Terms of Service.

API Objects provide read and write access to Checkfront data sets. You can access Checkfront objects through standard the REST interface.

API Objects currently include: Inventory, Booking and Customer.

The inventory object provides access to your master inventory. This allows you to query items, determine availability and pricing for a given period. The information returned can be used to create a booking in the system.

##Categories

Items are organized by categories in the system. A full list of available categories can be retrived via the category object.

You can query a list of available items based on search critera supplied in the API call.

When no dates are passed in the API call, a full list of enabled items in the inventory. When a date is passed, the API will return a "rated" response that includes pricing and availablity.

###Booking Paramaters

Booking parameters are defined globally in your system, and can also be configured per item. Your parameters specify the number of items to book, for example Child and Adult. These are completely configurable in your account under Manage / Settings / Configure.

To query specific pricing an availability you need to pass the appropriate parameters in your api call, using the ID's specified in your system configuration.

Let's say for instance you have 2 parameters configured. Adults (id: adults), Children (id: children). To get pricing for 2 a adults and one child you would pass: param[adults]=2&param[children]=1 in your API call.

GET /api/2.1/item/19start_date=20131230&end_date=20131230&end_date=20131230&param[adults]=2&param[children]=1

Booking parameters have many options, and can be configured to control inventory in very specific ways. See the Checkfront support centre for more information.

To get detailed pricing and availbility on a specific item, supply the item_id in the API call path along with any of the filter paramaters. For example, to get item 19:

GET /api/2.1/item/19/?start_date=20131230&end_date=20131230&end_date=20131230

The item SLIP is a string returned when making a rated query to a specific item. The slip contains the information needed to make a booking. Do not attempt to reverse engineer this as the format changes. It must be optioned vi a rated API call.

The booking object can be used in conduction with the item object to create a new booking on the system.

##Sessions

When creating a booking, the details of the booking are stored in an API session. This allows you to add multiple items to a booking, remove items and also updates the server with your intent to book the item(s) to prevent over bookings.

To start a new session, you must have the booking SLIP returned when querying item to be booked.

Description:|Set or update a booking session.

POST /api/2.1/session?slip=3.20130303X1-guests.1

{
"version": "2.1",
"host_id": "demo.checkfront.com",
"name": "My Company",
"request": {
"obj": "booking/session",
"status": "SUCCESS",
"results": 0
},
"booking": {
"session": {
"id": "rtdv4osethqurlmqgi55mcrkm4",
"slip": {
"1": "3.20130303X1-guests.1",
}
},

You can fetch the details of the purposed booking by accessing the session object. The item details will be returned with any request to the booking session.

GET /api/2.1/session?slip=3.20130303X1-guests.1

If you wish to add multiple items at once, you can supply the SLIP in the form of an array.

GET /api/2.1/session?slip=[]3.20130303X1-guests.1&slip[]=2.20130303X1-guests.2

Depending on your platform or SDK, the session can be passed in the form of a cookie or in the query string. For the sake of documenation we'll pass it in the query string.

GET /api/2.1/session?slip=3.20130303X1-guests.1&slip=rtdv4osethqurlmqgi55mcrkm4

When the required items are added to your booking session, you can create the booking.

New bookings require customer information, and other fields as defined by your system configuration.

You can dynamically fetch the fields required to complete the booking by calling the booking/form object along with the session, before calling booking/create.

This returns an array of fields and their properties that need to be used when creating the booking.

To create a booking, submit the fields from the booking/form object along with the session id.

If a booking is successfully created, you will be returned a completion url. If payment is required, this will be the payment page, otherwise it will be the receipt page.

There is currently no way to complete a payment via the API.

##Check-in & Check-out

You can check-in, and checkout a booking. By default, a note is created under the name of the account when a booking is checked in, or checked out. VOID, and CANCELLED bookings can not be checked-in or out.

POST /api/2.1/booking/JHLL-20131230/checkin

##Bookmark Bookmarks are made available in the Checkfront mobile apps, and are listed under bookings while logged into the platform. You can add or remove a bookmark to a specific booking for a specific account.

Notes can be added to bookings. By default the authenticated account will be used.

The status of an existing booking can be modified using the booking/status object.

The booking journal provides access to existing bookings in the system. You can query bookings by customer id, or individually by id.

You can filter bookings based on the available arguments, or fetch a single booking by supplying the booking_id in the path of the API call. If a single booking is requested, the response is returned in a single "booking" array. If multiple items are requested, the response is in a "bookings" array.

If selecting bookings based on a date range, both the start date and end dates are required. The dates are specific to the start and end date of items in the booking. A booking contain items in the invoice not in the time range if other items match.

The customer object provides access to customers in the system. Customers are created when a booking is made.

There is currently no way to create customers via the API, outside of creating a booking.

You can query customers based on indexed fields, including email address, name and customer id.

GET /api/2.1/customer/[email protected]&options[bookings]=1

Follow @checkfront on Twitter for the latest news.

Have questions on the API? E-mail us at [email protected].