Introduction
This document provides instructions on using our REST API to work with NewBook.
As with all our documentation, a basic understanding of what NewBook is and how our clients operate will help understand these requests and responses.
Please note that any examples below should not be used on your development servers. These are only examples and do not work.
Release Notes
Authentication
To use the NewBook REST API you must authenticate via HTTP Basic Authentication using a username and password.
These details will be provided to you along with this document.
You must also supply an API Key with each JSON request to specify which NewBook Instance you are querying.
You must use HTTPS to communicate with the NewBook REST API, for both testing and real live use.
Your JSON request must be sent via POST.
Please contact NewBook Support if you are unsure about which endpoint or region to use.
URL: https://api.newbook.cloud/rest
Region Options:URL: https://testapi.newbook.cloud/rest
Region Options:Building an example Request
In this example we will build an Authentication Test Request using the Test Endpoint.
HTTP Method: POST
HTTP Basic Auth Username: [as provided]
HTTP Basic Auth Password: [as provided]
URL: https://testapi.newbook.cloud/rest (see Authentication for alternate URLs]
POST data: [see right hand side Request JSON]
request_action must be provided to tell the REST API which action to execute. For this example we will use auth_test.
region must be provided to tell the REST API the NewBook Region of the Client you're trying to connect to. See Authentication for alternate regions.
Handling Errors
If a request has an error (missing parameters, invalid requests, server errors, etc.) a response with success set to "false" will be returned.
Handling Paginated Lists
The majority of our *_list requests are paginated, to minimize server load and ensure a timely response.
Requests default to showing results from 0 (data_offset), and limits results to the first 100 (data_limit).
Further, the response indicates how many results are currently being returned (data_count), and how many results there are in total (data_total).
Using data_offset, data_limit, and data_total you will be able to paginate through the results.
You can increase data_limit to a maximum of 1000. Anything over this value will be capped at 1000.
You can request data_limit higher than data_total however data_count will still be the number of results returned.
API Keys Request
Return a list of API Keys (NewBook Instances) which your username & password can connect with.
Authentication Test Request
Verify the username, password, and API Key in your possession work as expected.
Bookings: List
Retrieve a list of Bookings within the given time period.
The only required fields are period_from, period_to and list_type - the rest are optional
If guest_id is provided it will limit results to an individual Guest
| list_type | Shows Bookings which: |
|---|---|
| arrived1 | have Arrived during the specified dates Optional parameter mode with value projected changes the behaviour to what should have Arrived |
| arriving2 | are expected to Arrive during the specified dates |
| cancelled3 | have been Cancelled during the specified dates |
| departed1 | have Departed during the specified dates |
| departing4 | are expected to Depart during the specified dates |
| inhouse4 | are currently In-House (dates not required) |
| placed2 | were placed during the specified dates |
| staying2 | are expected to stay during the specified dates |
| no_show | have been marked as No Show and were meant to arrive during the specified dates |
restrict_mail_outs controls whether to return Guests which have opted to be contacted "automatically" i.e. by systems not expressly related to their specific booking (aka marketing opt-in). In NewBook, this is enabled on all Guests by default unless the Instance decides to disable it by default. If you send 1, i.e. only return Guests who allow contact "automatically", and the Guest has already opted-out, the booking data in the return response will still be present but the Guests array will be empty.
booking_reason, booking_source, booking_method and booking_demographic are allowed to be integers or arrays of integers. They all correspond to values specific to the Instance - you need to determine the values you want before trying to query for matching bookings.
search is optional and when provided it will restrict the results to the matching Guests. It will search their name, contact details (phone, email, etc) and membership details for a match
The Guests array returned may contain more than one entry for multi-Guest Bookings - you can determine the main Guest as indicated by the primary_client field
If the Bookings: List request has account_breakdown as true this will also affect the Guests array returned
The default_client_account_id field in the Booking array can be used to charge to the Booking Client Account, this may be different from the account_id where the Booking is part of a Group and the Guests are not paying individually
The inventory_item field holds all the Inventory Items on the Booking.
title can be any string; NewBook does not restrict users to specific titles for Guests
contact_details
Bookings: Get Details
Retrieve the details of a single Booking.
booking_id must be provided to retrieve the Booking.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
The returned data from this request is identical to Bookings: List but for the specific Booking alone.
If no such Booking ID exists, the success response parameter will be "false" and no data will be returned.
Bookings: Retrieve Current in Site
Check a particular Site to see if a Guest is currently In-House
site_id or site_name must be provided. If you use site_name it must match character for character.
The returned data from this request is identical to Bookings: List but for the specific Booking alone.
If no such Site exists, the success response parameter will be "false" and no data will be returned.
Bookings: Pull Availability & Pricing
Retrieve a list of Categories with the number of Sites available and the calculated tariff (cost) for bookings.
A URL is returned to see the same results via NewBook Online if required.
You can also provide children, infants and animals as numeric parameters (like the adults parameter).
You can also provide site_id, category_id and category_type_id parameters.
You can also provide length and width parameters to find Sites with matching sizes.
Providing any of the above restricts the results returned.
To see additional information in the response, you can provide daily_mode as "true". When this is done, each object in the tariffs_available array in the response will gain a new key tariffs_quoted, which is an object for each day requested detailing specifics about the price for that day.
"2020-07-06": {
"label": "Special",
"type_id": "8",
"tariff_id": "45",
"stop_sell": "0",
"minimum_periods": "7",
"maximum_periods": "0",
"base_min_combined": "1",
"base_max_combined": "7",
"tariffs_period_id": "19",
"tariff_applied_id": "480",
"original_amount": "112.85",
"calculated_amount": "112.85",
"base_adult": 0,
"base_child": 0,
"base_infant": 0,
"base_animal": 0,
"base_combined": "2",
"base_day_based": "1",
"additionals_day_based": "0",
"reset_night_counter": "1",
"min_days_in_advance": "0",
"max_days_in_advance": "0",
"stop_sell_occupancy_percentage": "0",
"amount": "112.85",
"dynamic_base": null,
"extras_combined": "1",
"special_deal": "0",
"dynamic": 0,
"overridden": "standard",
"close_arrival": 0,
"close_departure": 0
}
In addition, when daily_mode is provided as "true" the sites_available, sites_message, sites_code, and sites_extra_info keys in the response change from a single value into an object with a key/value for each day requested:
"sites_available": {
"2020-07-06": 2,
"2020-07-07": 6,
"2020-07-08": 6,
"2020-07-09": 3,
"2020-07-10": 6,
"2020-07-11": 0
},
"sites_message": {
"2020-07-06": "Minimum Advance Days has not been met, so there are no Sites available",
"2020-07-07": "Minimum Advance Days has not been met, so there are no Sites available",
"2020-07-08": "Minimum Advance Days has not been met, so there are no Sites available",
"2020-07-09": "",
"2020-07-10": "",
"2020-07-11": ""
}
"sites_code": {
"2020-07-06": 8,
"2020-07-07": 8,
"2020-07-08": 8,
"2020-07-09": 0,
"2020-07-10": 0,
"2020-07-11": 3
}
"sites_extra_info": {
"2020-07-06": "3",
"2020-07-07": "3",
"2020-07-08": "3",
"2020-07-09": "",
"2020-07-10": "",
"2020-07-11": ""
}
Another parameter you can provide is return_sites which when "true" changes sites_available in the response from just a number to an array of objects detailing the available Sites:
"sites_available": [{
"site_id": "6",
"site_name": "Room 5",
"category_id": "16",
"category_name": "Single Room",
"period_from": "2020-07-06 14:00:00",
"period_to": "2020-07-13 10:00:00",
"gl_account_id": "20",
"gl_category_id": "1",
"tax_free": "1",
"vacancy_length": 1080
},{
"site_id": "15",
"site_name": "Room 8",
"category_id": "16",
"category_name": "Single Room",
"period_from": "2020-07-06 14:00:00",
"period_to": "2020-07-13 10:00:00",
"gl_account_id": "20",
"gl_category_id": "1",
"tax_free": "1",
"vacancy_length": 45
}],
Availability is returned per-Category. For each Category in the data returned, the below are useful to understand why sites_available may be "0":
| sites_code | Reasoning |
|---|---|
| 0 | No error occurred - a successful result |
| 1 | Requested parameters were invalid and calculation cannot be done |
| 2 | The Site is not yet opened, or already closed, over the date range requested |
| 3 | NewBook has computed there is no availability for the requested parameters |
| 4 | There is no availability due to a Special Date blocking |
| 5 | An Allotment takes the last remaining availability |
| 6 | The Category is configured for Dirty Sites to be exempt from availability, and the Site is dirty, therefore it is unavailable (same-day arrivals only) |
| 7 | The Instance Setting for Daily Stop Sell Time has passed (same-day arrivals only) |
| 8 | The Instance Setting Minimum Advance Days for Online Bookings has not been met |
| 9 | The Instance Setting Maximum Advance Days for Online Bookings has been exceeded |
In addition, each Category returns one or more Tariffs. For each Category -> Tariff in the data returned, the below are useful to understand why tariff_success may be "false":
| tariff_code | Reasoning |
|---|---|
| 0 | No error occurred - a successful result |
| 1 | Requested parameters were invalid and calculation cannot be done |
| 2 | The Tariff Minimum Occupants has not been met |
| 3 | The Tariff Maximum Occupants has been exceeded |
| 4 | The Tariff Minimum Days in Advance for Bookings has not been met |
| 5 | The Tariff Maximum Days in Advance for Bookings has been exceeded |
| 6 | The Tariff Minimum Nights for Bookings has not been met |
| 7 | The Tariff Maximum Nights for Bookings has been exceeded |
| 8 | The Tariff is not applicable due to a Special Date blocking |
| 9 | The Tariff has a Closed to Arrival Override for the days requested - Bookings cannot use this Tariff to arrive on the date requested |
| 10 | The Tariff has a Closed to Departure Override for the days requested - Bookings cannot use this Tariff to depart on the date requested |
| 11 | The Tariff has a Stop-Sold Override for the days requested |
The sort key is returned, in both object and array return, to indicate the sorting order the Instance has established for the categories returned. This should be respected in your code as the sequential order the Instance intended for the categories returned.
inventory_items will be returned if they are associated with the Tariff or Category inside NewBook. Beyond the name and amount, they expose two important aspects:
This request is one which can return either an array of objects or an object of objects (default) identified by their Category ID. This can be controlled by adding
to your request parameters. When provided, data is returned as requested.{"return": "array"}
Bookings: Create Availability Email
An Availability Email is NewBook recording a set of parameters for a potential Booking, such as arrival and departure dates, number of adults, children, infants etc. and a particular Category and Tariff.
A URL is returned (online_booking_url) to accept the potential Booking and convert it to an actual Booking via NewBook Online. Thanks to most of the data being pre-filled, there is very little input required from the Guest to complete a Booking.
Calling this method will create an Availability Email, but despite its name this will not send an email to the Guest.
You can also provide children, infants and animals as numeric parameters (like the adults parameter).
Regarding specifying a Guest:
expire_quote_on is optional, and it controls the date from which the Guest cannot accept the offer via NewBook Online. It defaults to +2 weeks from the date of the Availability Email (this default can be changed by the Instance in NewBook Settings).
source_id is optional, and is used on the resulting Booking if the Guest accepts the offer via NewBook Online. It must be a valid source_id or the request will fail.
The response for this request is identical to the response for Bookings: Pull Availability & Pricing, except for the below:
In comparison to the Bookings: Pull Availability & Pricing request, the data key in the response of this method is an array of objects by default, not an object of objects.
This request is one which can return either an array of objects (default) or an object of objects identified by their Category ID. This can be controlled by adding
to your request parameters. When provided, data is returned as requested.{"return": "object"}
Bookings: Create
Bookings can be submitted to NewBook by using this method. Please note that these are treated equal to NewBook Online bookings and are subject to fees per booking received.
For now, the Guest will not receive an email from this process as it is expected that the implementing code will be responsible for that kind of communication. The Instance will receive an email as per normal for incoming bookings.
You can also provide children, infants and animals as numeric parameters (like the adults parameter).
You can also provide the category_id for this request to automatically allocate an available Site from that Category, or manually supply a specific site_id.
Regarding specifying a Guest:
The following parameters are optional and save onto the Guest:
The following parameters are optional and save onto the Booking:
If specified, tariffs_quoted must cover the entire date range of the booking and must follow this format:
[{"specific date":{"tariff_quoted_id":sourced from NewBook,"price":number}]
If specified, repeat_charges must be a single array and must follow this format:
[{"interval":amount}]
Note: Bookings can have neither of the above, and therefore be set up with "No Billing", but they cannot have both of repeat_charges and tariffs_quoted - please use only one billing method
If specified, inventory_items must follow this format:
[{
"inventory_item_id":sourced from NewBook,
"description":text value,
"amount":number,
"qty":number,
"per_adult":number,
"per_child":number,
"per_infant":number,
"per_animal":number,
"adults":number,
"children":number,
"infants":number,
"animals":number
}]
If specified, status must be one of the following:
You should have a proper understanding of what the different statuses are intended to be used for before use. Please contact NewBook Support for more information here.
If not specified, NewBook will use the value given in the Setting Status for Bookings with no payment or failed payment
If specified, notes must be an array, even if only 1 note is delivered
If specified, booking_group_id must match an existing Bookings Group within NewBook. The Booking will then inherit the Bookings Groups Bill To options.
custom_fields can optionally be provided based on the response to Custom Fields:
dietary_requirements can optionally be provided based on the response to Dietary Requirements.
If specified, allow_dirty_arrivals must be "true" or "false". This parameter will tell NewBook whether or not a same day Booking can be placed in a Dirty Site. The Instance controls the default of this on each Category.
If specified, allow_backtoback_bookings must be "true" or "false". This parameter will tell NewBook whether a Booking can be placed if another Booking is Departing on the same day. The Instance controls the default of this, for each day of the week, on each Category.
account_id in the response can be used to push charges or payments onto the account, as separate REST requests
Bookings: Update
Update an existing Booking.
booking_id is required
All other parameters are optional, please see Bookings: Create for more details.
Bookings: Update Market Segment
Bulk update existing Bookings with a new Market Segment
booking_id is required
market_segment_id is required and must be a single Market Segment ID
This method will only update the Market Segment field (instead of all fields on a single Booking and the validation involved in that process) allowing for the Market Segment to be updated faster (and in bulk).
Bookings: Update Booking Source
Bulk update existing Bookings with a new Booking Source.
booking_id is required and may be either a single ID or an array of IDs. Unmatched IDs will be ignored
source_id is required and must be a single Booking Source ID
This method will only update the Booking Source field and will not alter or update any other field on the Booking. This request is significantly faster than Bookings: Update for bulk updating Booking Source.
Booking Sources: List
Pull the list of Booking Sources from within NewBook.
name is optional and when provided it will restrict the results to the matching Booking Sources
show_inactive is optional and when provided it will include inactive Booking Sources in the response
Booking Sources: Create
Create a new Booking Source within NewBook.
parent_id must be a valid option from the bookings_sources list where available_as_parent is true. This can only be omitted if is_parent is true.
is_parent is optional and when provided as true this request will create a parent Booking Source. parent_id will be ignored if this is set to true.
Booking Methods: List
Pull the list of Booking Methods from within NewBook.
name is optional and when provided it will restrict the results to the matching Booking Methods
Booking Reasons: List
Pull the list of Booking Reasons from within NewBook.
name is optional and when provided it will restrict the results to the matching Booking Reasons
Booking Demographics: List
Pull the list of Booking Demographics from within NewBook.
name is optional and when provided it will restrict the results to the matching Booking Demographics
Booking Market Segments: List
Pull the list of Booking Market Segments from within NewBook.
name is optional and when provided it will restrict the results to the matching Booking Market Segments
Bookings Groups: Create
No emails will be sent when creating a Group Booking. These will be handled on an individual basis when adding Bookings to the Group
Regarding specifying a Guest:
The following parameters are optional and save onto the Guest:
The following parameters are optional and save onto the Booking Group:
If specified, inventory_items must follow this format:
[{
"inventory_item_id":sourced from NewBook,
"description":text value,
"amount":number,
"per_adult":number,
"per_child":number,
"per_infant":number,
"per_animal":number,
"adults":number,
"children":number,
"infants":number,
"animals":number
}]
If specified, status must be one of the following:
You should have a proper understanding of what the different statuses are intended to be used for before use. Please contact NewBook Support for more information here.
If not specified, NewBook will use the value given in the Setting Status for Bookings with no payment or failed payment
If specified, notes must be an array, even if only 1 note is delivered
account_id in the response can be used to push charges or payments onto the account, as separate REST requests
booking_group_id in the response can be used to link Bookings to the Group, as separate REST requests
Guests: List
Retrieve/search the Guest database.
search is optional and when provided it will restrict the results to the matching Guests. It will search their name, contact details (phone, email, etc) and membership details for a match
account_id is optional and when provided it will restrict the results to the matching Client Accounts.
membership_type and membership_number can optionally be provided to search for Guests with particular membership details
membership_type when provided must match on of the values from a Memberships: List request
created_when is optional and when supplied, restricts the returned Guests to only those which were created on the date given
staff_id is optional and when supplied, restricts the returned Leads to those assigned to that User (see Users: List)
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
contact_details, custom_fields and membership_details are arrays which will be empty when no data of that type is available
The membership expiry_date can optionally be null when no date is available
title can be any string; NewBook does not restrict users to specific titles for Guests
contact_details
staff_id and staff_sharing will only be returned for CRM clients
Guests: Create
Create a Guest to use for placing Bookings, Availability Emails, Online Logins, and more.
firstname and lastname are required, the rest is optional but recommended
membership_type and membership_number (and optionally membership_expiry as YYYY-MM-DD) can be provided to create a Membership for the Guest.
duplicate_matching can optionally be provided as one of the following options:
When not provided, this determination falls back to the Instance Setting called When adding a Guest, Detect Duplicates using, which defaults to name.
If duplicates are encountered, and if your connection with NewBook has the privilege for Guests: List, this request will return the existing_guest_ids which were found to be duplicated by the data provided:
custom_fields can optionally be provided based on the response to Custom Fields:
dietary_requirements can optionally be provided based on the response to Dietary Requirements.
To create a new Online Login for this Guest (optional)
online_username and online_password are required to create an Online User for this Guest. Note that online_username must be an email address. If the provided online_username already exists, the whole guests_create request will fail saying the provided online_username is already in use. NewBook implements password complexity requirements: at least 8 characters, at least one upper case letter, at least one lower case letter, and at least one number.
Guests: Get Details
Retrieve an existing Guest record.
guest_id or account_id must be provided to retrieve the details of a particular Guest.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
The returned data from this request is identical to Guests: List but for the specific Guest alone
If no such Guest exists, the success response parameter will be "false" and no data will be returned.
Guests: Update
Update an existing Guest.
guest_id or account_id must be provided to update the details of a particular Guest.
contact_email and contact_phone can be provided to create or update Contact Details for a Guest. These values will also check & not double up if the new information already exists on the Guest
If you would like to prevent the updating of existing Contact Details please supply update_existing_details as "false"
notes will add new details to the Guest (not replace the existing information) and will check & not double up if the new information already exists on the Guest.
membership_type and membership_number (and optionally membership_expiry as YYYY-MM-DD) can be provided to create or update a Membership for the Guest. These values will also check & not double up if the new information already exists on the Guest (based on membership_type).
To create a new Online Login for this Guest (optional)
online_username and online_password are required to create an Online User for this Guest. Note that online_username must be an email address. If the provided online_username already exists, the whole guests_update request will fail saying the provided online_username is already in use. NewBook implements password complexity requirements: at least 8 characters, at least one upper case letter, at least one lower case letter, and at least one number.
To update an existing Online Login for this Guest (optional)
Either online_user_id or online_account_id is required, and can be retrieved using the Online Users: Get request.
If you are updating the password for the Online User, NewBook implements password complexity requirements: at least 8 characters, at least one upper case letter, at least one lower case letter, and at least one number.
online_username is optional, but if provided must be an email address. If the provided online_username already exists and isn't specifically for this Online User (identified by online_user_id or online_account_id), the whole guests_update request will fail saying the provided online_username is already in use.
The Online User for and for_id cannot be updated.
Accommodation Categories: List
Retrieve a list of Accommodation Categories including all the stored information about the Category.
category_id can optionally be provided to limit results to a particular Category ID
type_id can optionally be provided to limit results to a particular Category Type ID
Accommodation Sites: List
Pull the list of possible Sites from NewBook.
category_id can optionally be provided to limit results to a particular Category ID
type_id can optionally be provided to limit results to a particular Category Type ID
show_deactivated can optionally be provided as "true" to include de-activated Sites
Accommodation Features: List
Retrieve the list of possible Accommodation Features in NewBook.
Accommodation Sites: Get/Set Status
Retrieve/update the Status of a particular Site in NewBook.
site_id or site_name must be provided to indicate the appropriate Site, but only 1 is required
site_status is optional and should only be provided when you wish to update the Status - valid options:
message will be filled only when site_status is updated
Site Maps
Pull a list of Site Maps and their Markers from NewBook.
Sites: Update
Update the details of a particular site inside of NewBook.
site_id must be provided to update a particular Sites details.
Please see below for a list of optional details that can be updated on the Site. At least one of these must be provided.
Companies: List
Retrieve the list of Companies for recording non-Booking-specific charges.
search is optional and when provided it will restrict the results to the matching Companies. It will search their name and contact details (phone, email, etc) for a match
account_id is optional and when provided it will restrict the results to the matching Client Accounts.
type_id is optional and when provided will limit the results to the matching Company Type
created_when is optional and when supplied, restricts the returned Companies to only those which were created on the date given
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
Company Types: List
Retrieve the list of Company Types for limiting the Company List.
Companies: Update
Update a particular Company
company_id is required
contact_email and contact_phone can be provided to create or update Contact Details for a Company. These values will also check & not double up if the new information already exists on the Company
If you would like to prevent the updating of existing Contact Details please supply update_existing_details as "false"
notes will add new details to the Company (not replace the existing information) and will check & not double up if the new information already exists on the Company.
Companies Staff: List
Retrieve the list of Companies Staff for recording non-Booking-specific charges.
account_id is optional and when provided it will restrict the results to the matching Client Accounts.
company_id is optional and when provided will limit the results to the matching Company
created_when is optional and when supplied, restricts the returned Staff to only those which were created on the date given
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
Companies Staff: Update
Update a particular Company Staff
company_staff_id or account_id must be provided to update the details of a particular Company Staff member.
contact_email and contact_phone can be provided to create or update Contact Details for a Company Staff. These values will also check & not double up if the new information already exists on the Company Staff
If you would like to prevent the updating of existing Contact Details please supply update_existing_details as "false"
notes will add new details to the Company Staff (not replace the existing information) and will check & not double up if the new information already exists on the Company Staff.
Travel Agents: List
Retrieve the list of Travel Agents for recording non-Booking-specific charges.
name is optional and when provided it will restrict the results to the matching Travel Agents
created_when is optional and when supplied, restricts the returned Travel Agents to only those which were created on the date given
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
Events: List
Retrieve a list of Events within the given time period.
The only required fields are period_from, period_to and list_type - the rest are optional
| list_type | Shows Events which: |
|---|---|
| incoming1 | are expected to Arrive during the specified dates |
| ongoing2 | are currently In-House (dates not required) |
| departing2 | are expected to Depart during the specified dates |
| departed | have Departed during the specific dates |
| placed1 | were placed during the specified dates |
| cancelled | have been Cancelled during the specified dates |
| staying1 | are expected to stay during the specified dates |
| quoted3 | were placed during the specified dates |
search is optional and when provided it will restrict the results to the matching Billing or Contact Client Accounts.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
The billing_client_account_id field in the Event array can be used to charge to the Event Client Account, this may be different from the event_account_id when the Event is billing to Group, Company, etc
Please note unlike other responses, in the Events: List response account_breakdown is prefixed as event_account_breakdown to disambiguate against the other keys.
The inventory_item field holds all the Inventory Items on the Event.
Events: Get Details
Retrieve the details of a single Event.
event_id must be provided to retrieve the Event.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
The returned data from this request is identical to Events: List but for the specific Event alone.
If no such Event ID exists, the success response parameter will be "false" and no data will be returned.
Please note unlike other responses, in the Events: Get Details response account_breakdown is prefixed as event_account_breakdown to disambiguate against the other keys.
Leads: List
Retrieve/search the Leads database.
id is optional and when provided it will restrict the results to those with a matching id
search is optional and when provided it will restrict the results to the matching Leads. It will search their name, contact person (first name and last name), and contact details (phone, email, etc) for a match
created_when is optional and when supplied, restricts the returned Leads to only those which were created on the date given
staff_id is optional and when supplied, restricts the returned Leads to those assigned to that User (see Users: List)
status_id is optional and when provided it will restrict the results to Leads with a matching Status (see Lead Statuses: List).
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
contact_details and custom_fields are arrays which will be empty when no data of that type is available
Leads: Create
Create a Lead within NewBook.
name and/or firstname + lastname must be provided
status_id is required. You must provide a valid option from the Lead Statuses: List request.
source_id is optional. You must provide a valid option from the Lead Sources: List request.
lead_type_id can optionally be provided as an array. All options must be valid options from the Lead Types: List request.
lead_categories_id can optionally be provided as an array. All options must be valid options from the Lead Categories: List request.
lead_interest_id can optionally be provided as an array. All options must be valid options from the Lead Interests: List request.
duplicate_matching can optionally be provided as one of the following options:
When not provided, this determination falls back to the Instance Setting called When adding a Lead, Detect Duplicates using, which defaults to name_and_email.
If duplicates are encountered, and if your connection with NewBook has the privilege for Leads: List, this request will return the existing_lead_ids which were found to be duplicated by the data provided:
custom_fields can optionally be provided based on the response to Custom Fields:
Leads: Update
Update an existing Lead within NewBook.
lead_id is required
contact_email and contact_phone can be provided to create or update Contact Details for a Lead. These values will also check & not double up if the new information already exists on the Lead
If you would like to prevent the updating of existing Contact Details please supply update_existing_details as "false"
notes will add new details to the Lead (not replace the existing information) and will check & not double up if the new information already exists on the Lead.
Leads: Activity History
Retrieve Activity History for an existing Lead within NewBook.
lead_id is required
Lead Categories: List
Retrieves the list of available Lead Categories.
Lead Interests: List
Retrieves the list of available Lead Interests.
Lead Sources: List
Retrieves the list of available Lead Sources.
Lead Sources: Create
Create a new Lead Source within NewBook.
Lead Statuses: List
Retrieves the list of available Lead Statuses.
The IDs of the Lead Statuses in the example here are negative; these are defaults NewBook creates
Lead Types: List
Retrieves the list of available Lead Types.
Security Gates: List
Retrieve the list of Security Gates configured within NewBook
Security Areas: List
Retrieve the list of Security Areas configured within NewBook.
security_gates contains the list of Gates the Security Area is authorised for.
Access Codes: List
Retrieve the Access Codes valid within the current 48 hour window (+ and - 24 hours).
created_when is optional and when supplied, restricts the returned Access Codes to only those which were created on the date given
The booking data fields are returned if the access_code given is related to a Booking
Access Codes: Search
Searches Access Codes valid within the current 48 hour window (+ and - 24 hours).
search_term when numeric will search the access code id and when it contains letters will search the car rego details for all access codes
fuzzy_search_length is an optional parameter that can only be used on alpha-numeric search terms (e.g. not all numbers) and will specify the number of characters the car rego can be different by
The booking data fields are returned if the access_code given is related to a Booking
search_term_difference will be the number of characters this Access Code is different from search_term
Access Codes: Push History
Records access history for particular Access Codes and their Bookings.
access_history an array of individual access attempts, containing:
Access Codes: Get History
Returns access history for particular Access Codes.
Can be provided any combination of the below filters to limit results:
GL Accounts: List
Pull the list of GL Accounts from within NewBook.
code, short_description, and long_description are all optional and when any of them are provided they will restrict the results to the matching GL Accounts (each field searches specifically)
If refundable is set to 1 (true) it means any charges raised in this GL Account is are Security Deposits aka Bonds. When these are paid off, the assumption is that money will eventually be returned to the Guest (or converted to other income e.g. "Property Damage")
Sub Client Accounts: List
Pull the list of Sub Client Accounts (aka GL Categories) from within NewBook.
Clients Accounts: List
Retrieve a list of Client Accounts.
for (optional): An array of the type of Client Account to return
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
Clients Accounts: Get
Retrieve a particular Client Account.
account_id: The Account ID to query
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
Charges: Create
Used to charge to a Client Account.
account_id: The Client Account ID retrieved in a previous request
generated_when (optional): The datetime to record for the charge. Defaults to the current timestamp
gl_account_code: The GL Account code to record for the Charge. You can use gl_account_id instead by using the GL Accounts: List request for list of valid IDs
gl_category_id: Use the Sub Client Accounts: List request to retrieve a list of valid IDs
tax_free: 1 = Tax Free, 0 = Has Tax
payment_type (optional): tells NewBook how the Payment was received - valid options:
inventory_item_id (optional): links this Charge to a matching Inventory Item for reporting purposes
booking_id (optional): tells NewBook which Booking this Charge is related to, useful for when the Booking is billing to a Company Client Account
If payment_type was provided in the request, you will receive a payment_id in the response
Charges: List
Used to retrieve a list of Charges
account_id: Can optionally filter the list by Client Account ID
account_for: Can optionally filter the list by Client Account Type, possible options include:
period_from + period_to: Can optionally be provided together to find Charges raised or voided within that time period.
Credits: Create
Used to add negative charges to a Client Account (not to be used for payments - that is a separate request).
account_id: The Client Account ID retrieved in a previous request
generated_when (optional): The datetime to record for the credit. Defaults to the current timestamp
gl_account_code: The GL Account code to record for the Charge. You can use gl_account_id instead by using the GL Accounts: List request for list of valid IDs
gl_category_id: Use the Sub Client Accounts: List request to retrieve a list of valid IDs
tax_free: 1 = Tax Free, 0 = Has Tax
refund_type (optional): tells NewBook if the Credit has been Refunded - valid options:
inventory_item_id (optional): links this Credit to a matching Inventory Item for reporting purposes
booking_id (optional): tells NewBook which Booking this Credit is related to, useful for when the Booking is billing to a Company Client Account
If refund_type was provided in the request, you will receive a refund_id in the response
Credits: List
Used to retrieve a list of Credits
account_id: Can optionally filter the list by Client Account ID
account_for: Can optionally filter the list by Client Account Type, possible options include:
period_from + period_to: Can optionally be provided together to find Credits raised or voided within that time period.
Payments: Create
Used to add payments to a Client Account.
account_id (required): The Client Account ID retrieved in a previous request
amount (required): The amount to record as paid
description (required): A textual label for the payment - can be anything but is required
type (required): Please see the Payment Types request for a list of valid types
type_reference: Alpha-numeric descriptor for the payment
generated_when: The datetime to record for the payment. Defaults to the current timestamp
gl_category_id: Use the Sub Client Accounts: List request to retrieve a list of valid IDs
deposit: 1/0; Whether or not this payment should be considered "Deposits Held" for reporting purposes
auto_receipt (optional): Please see the System Templates: List request for a list of valid System Templates. Alternatively you can provide "default" to utilise the Default Receipt Template.
If you have a Credit Card Gateway linked to NewBook and are using the same Gateway within your application, you can provide the following parameters to record the payment as a Credit Card Transaction for future use* within NewBook:
* when provided this way, the payment can be refunded through the Gateway from within NewBook if required. The payment can also have its Gateway status verified inside NewBook if required (e.g. validate it legitimately succeeded/failed).
Payments: List
Used to retrieve a list of Payments
account_id: Can optionally filter the list by Client Account ID
account_for: Can optionally filter the list by Client Account Type, possible options include:
period_from + period_to: Can optionally be provided together to find Payments received or voided within that time period.
If get_paid_by is provided as "true" the Payment object in the response will include the following additional information:
"paid_by": "24",
"paid_by_for": "guests",
"paid_by_for_id": "15",
"paid_by_for_name": "Jane Doe"
You can run the Payments Types request to get the list of possible Payment Types.
transaction_method can be one of the following:
Payment Types
Pull a list of Payment / Refund Types from NewBook.
Refunds: Create
Used to add refunds to a Client Account.
account_id: The Client Account ID retrieved in a previous request
generated_when (optional): The datetime to record for the refund. Defaults to the current timestamp
gl_category_id: Use the Sub Client Accounts: List request to retrieve a list of valid IDs
type: please see the Payment Types request for a list of valid types
type_reference (optional): alpha-numeric descriptor for the refund
Refunds: List
Used to retrieve a list of Refunds
account_id: Can optionally filter the list by Client Account ID
account_for: Can optionally filter the list by Client Account Type, possible options include:
period_from + period_to: Can optionally be provided together to find Refunds given or voided within that time period.
If get_refunded_to is provided as "true" the Refund object in the response will include the following additional information:
"refunded_to": "24",
"refunded_to_for": "guests",
"refunded_to_for_id": "15",
"refunded_to_for_name": "Jane Doe"
You can run the Payments Types request to get the list of possible Refund Types.
transaction_method can be one of the following:
Token: Store
Used to store a credit card token created outside of NewBook
The token must be created using the same credit card gateway account as used in NewBook otherwise processing payments will fail
for: Must be one of the following:
for_id: ID of the above entity to store the token against
token: Credit card token created using the same credit card gateway account as used in NewBook
last_digits: Last 4 digits of the credit card number to be displayed within the NewBook interface
card_type: Must be one of the results from Payment Types that is marked as "is_card": "1"
expiry: Credit card expiry date. An object matching this format:
{
month: "MM",
year: "YYYY"
}
card_name: Can optionally override the name on the card
gateway_id: Can optionally store the token against a specific NewBook credit card gateway connection other than the default
Quotes: List (CRM)
Used to retrieve a list of Quotes
account_id: Can optionally filter the list by Client Account ID
account_for: Can optionally filter the list by Client Account Type, possible options include:
period_from + period_to: Can optionally be provided together to find Invoices generated or voided within that time period.
Quotes: PDF Content (CRM)
Used to retrieve the PDF content for a Quote.
Invoices: List
Used to retrieve a list of Invoices
account_id: Can optionally filter the list by Client Account ID
account_for: Can optionally filter the list by Client Account Type, possible options include:
period_from + period_to: Can optionally be provided together to find Invoices generated or voided within that time period.
fetch_guests: Can optionally be provided to include the guest_id for each Invoice (where available).
fetch_items: Can optionally be provided to include details about each Item on Invoices.
If get_invoiced_to is provided as "true" the Invoice object in the response will include the following additional information:
"invoiced_to": "24",
"invoiced_to_for": "guests",
"invoiced_to_for_id": "15",
"invoiced_to_for_name": "Jane Doe"
Invoices: PDF Content
Used to retrieve the PDF content for an Invoice.
Receipts: List
Used to retrieve a list of Receipts
account_id: Can optionally filter the list by Client Account ID
account_for: Can optionally filter the list by Client Account Type, possible options include:
period_from + period_to: Can optionally be provided together to find Receipts generated or voided within that time period.
fetch_guests: Can optionally be provided to include the guest_id for each Receipt (where available).
fetch_invoices: Can optionally be provided to include the Invoice + Payment Type breakdown for each Receipt (where available).
If get_receipted_to is provided as "true" the Receipt object in the response will include the following additional information:
"receipted_to": "24",
"receipted_to_for": "guests",
"receipted_to_for_id": "15",
"receipted_to_for_name": "Jane Doe"
total: Will be a negative value for Payment Receipts and a positive value for Refund Receipts. This is to reflect how the Receipt affects their Client Account Balance.
Receipts: PDF Content
Used to retrieve the PDF content for a Receipt.
Contact Templates: List
Retrieve a list of available Contact Templates for sending.
type will always be "body" to indicate an Email template and "sms" for an SMS template
bind the type of object the template can be sent to e.g. bookings, guests, etc
Contact Templates: Send
Send a Contact Template.
template_id is required and can be retrieved from Contact Templates: List
data_type is required and must match the bind of the Contact Template
data_id is required and must be an existing object e.g. if data_type is "bookings" it must be a valid Booking ID
send_via is required and must be one of
Contact Templates: Create
Used to create new Contact Templates
name and content are required, the rest are optional.
If email_subject is left blank then name will be used instead.
All available options for the following values are available from the Contact Templates: Options request:
counter_signable is only applicable when type is set to "signed_document"
When a template is sent via Email (PDF) the email_content will be sent as the email, and content will be attached as a PDF
text_content is sent as well as the email, as some email programs require a plain-text alternative version, but most will not display it. When this template is sent via Marketing Campaigns, the Plain Text Content alternative version is required.
When send_via is set to sms then only the sms_content is sent
Contact Templates: Get
Used to retrieve a Contact Template
Retrieve a contact template by providing its id
Returns all fields, even if they were not provided when the template was created
Contact Templates: Update
Update an existing Contact Template.
id is required, all other fields are optional
The other fields are the same as those provided in Contact Templates: Create
Contact Templates: Options
Returns a list of available options for Contact Templates: Create optional values.
The results returned will depend on what is available in your database.
If an array key and value is returned, the array key is what is provided to Contact Templates: Create
The results returned by header and footer can also be used for email_header and email_footer respectively
System Templates: List
Retrieve a list of available System Templates.
type will always be "body" to indicate an Email template and "sms" for an SMS template
bind the type of object the template can be sent to e.g. bookings, guests, receipts, etc
System Templates: Create
Used to create new System Templates
name, description and content are required, the rest are optional.
If email_subject is left blank then name will be used instead.
Valid fields:
System Templates: Get
Used to retrieve a System Template
Retrieve a system template by providing its id
Returns all fields, even if they were not provided when the template was created
System Templates: Update
Used to update a System Template
Any field except ID can be updated
last_updated is set to the time that the request is processed
Valid fields:
Reporting: NewBook Status
Pull data showing a wide range of information about the Instance.
Some of the data objects in the response have keys for rest_action and rest_parameters. With these, you can submit a secondary request to elaborate on the returned value
In future releases, more of these data objects will have this ability
Reporting: Earned Revenue
Pull data from the Earned Revenue Report for the dates specified.
Optionally data_display can be provided as "list" to show each Charge/Credit individually on this report
Optionally providing get_booking_data as "true" when using list mode will also return some basic Booking data
Reporting: Transaction Flow
Pull data from the Transaction Flow Report for the dates specified.
Reporting: Reconciliation
Pull data from the Reconciliation Report for the dates specified.
Reporting: Daily Audit Summary
Pull data from the Daily Audit Summary for the dates specified.
debitor_gl_account can be provided to apply a GL Account to Debtors Ledger result rows
creditor_gl_account can be provided to apply a GL Account to Creditors Ledger result rows
payment_gl_account can be provided to apply a GL Account to Payment/Refund result rows
Reporting: Balances Dated
Pull data from the Balances Dated Report.
period_from - which date to determine the balance as of (inclusive)
natures - determines which types of accounts will be displayed on the list:
Reporting: Occupancy
Retrieves a list of Categories and their occupancy for the given period.
This request is one which can return either an array of objects or an object of objects (default) identified by their Category ID. This can be controlled by adding
to your request parameters. When provided, data is returned as requested.{"return": "array"}
To determine the number of available Sites for a given date, subtract the occupied, maintenance, and allotted values from the available value.
Reporting: Inventory Items
Pull data from the Inventory Items Report for the dates specified.
Reporting: Survey Answers
Retrieves a list of Guests and their responses to Survey Questions, based off when the Guest answered.
survey_id can optionally be provided to limit results to a particular Survey ID
answer_type can optionally be provided to limit results of a particular type of questions - valid options:
active_only can optionally be provided to limit results to active surveys only
Reporting: Surveys Completed
Provides a breakdown of Surveys Sent vs Completed.
period_range can be one of the following:
period_increment is optional, and is only really required when using custom ranges
active_only can optionally be provided to limit results to active surveys only
Tasks: List
Retrieve a list of outstanding Tasks from NewBook
task_type must be an ID returned from Task Types: List.
show_uncomplete is optional and should only be provided when you wish see tasks outstanding from previous dates (before the period_from). The default value is false which shows all outstanding tasks for the current period
created_when is optional and when supplied, restricts the returned tasks to only those which were created on the date given. It references the date the task itself was created, opposed to period_from and period_to which reference the date/s the task is scheduled for
booking_site_id and booking_site_name are optionally returned when the Task is associated with a Booking
Task Types: List
Retrieve a list of the different Task Types
Tasks: Create
Create a new Task.
location_type is required and must be one of:
location_id is required when the location_type is not "none" and must be a valid Booking/Guest/etc ID
location_name when location_type is set to "accommodation_sites" or "facilities" this can be provided instead of location_id and must be a valid Site/Facility Name
location_occupy when location_type is set to "accommodation_sites" this can optionally be provided as "1" to block that Site from availability
type_id is required, a valid list of options can be retrieved from the Task Types: List
description is required
period_from is required
period_to is required
Tasks: Update
Mark an individual Task as Started or Completed.
The only required field for task_update is task_id, however at least 1 other field must be provided in order to update the Task.
period_from must be before period_to
location_type must be one of the following:
Site information (site_id, site_name, etc) is returned only when the Task associated with a Booking or Site
If the site_status did not change to Clean as expected it means that either the Site is still occupied, or there are other outstanding Housekeeping Tasks to be completed
Tickets: List
Retrieve a list of all Tickets.
account_id can optionally be provided to limit results to a particular Client Account
Tickets can have a status and corresponding status_name of the following values:
status_when is set to the current timestamp when a Ticket changes status. This is different to updated_when, which will be incremented if textual change is done or a new note is added to the Ticket.
Tickets: Create
Create a new Ticket.
account_id is required
queue_id is required, a valid list of options is available from Ticket Queue: List
subject is required
content is required and is expected to be valid HTML
contact_name is required
contact_email is required
Tickets: Update
Update an existing Ticket.
ticket_id is required
status can optionally be provided, valid options include
priority can optionally be provided, valid options include
content can optionally be provided to add an additional response to the Ticket, the response will be treated as coming from the client
Ticket Queue: List
Retrieve a list of available Ticket Queues.
Surveys: List
Retrieves a list of the Surveys set up in the database.
Gift Vouchers: List
Pull the list of Gift Vouchers from within NewBook.
name is optional and when provided it will restrict the results to the matching Gift Voucher
Inventory Items: List
Pull the list of Inventory Items from within NewBook.
name is optional and when provided it will restrict the results to the matching Inventory Items
Discounts: List
Pull the list of Discounts from within NewBook.
name is optional and when provided it will restrict the results to the matching Discounts
Memberships: List
Pull the list of Memberships from within NewBook.
name is optional and when provided it will restrict the results to the matching Memberships
If a discount_id is returned in the data, you can cross reference the result of a Discounts: List request to determine how much of a discount is granted based on the membership
Facilities: List
Pull the list of active Facilities that are available online from within NewBook.
facility_status will be either Open or Maintenance. Permanently closed Facilities will not be returned by this request.
category_name and category_id refer to the Facility Category.
additional_information comes from the default Inventory Item for the Facility. For more details of this Inventory Item, the Inventory Items: List request can be used with the inventory_item_name from this data.
Custom Fields
Pull a list of Custom Fields configured from within NewBook.
for must be provided as one of the following options:
type will be one of the following options:
Notes Types: List
Pull a list of allowed Note Types from within NewBook.
The note_type_default will be used for Notes: Create if a manual note_type_id is not supplied
Notes: Create
Add a Note to a Booking, Guest, Lead or Quote.
note_for must be equal to one of the following values:
note_for_id corresponds to the particular note_for that this note will be attached to
note_type_id is optional, and will use the System Default if not provided as per the Note Types: List request.
Phone Calls: Import Calls
Push a list of call history to NewBook for importing.
call_origin is recommended to be the phone extension (these can be allocated to the appropriate Site from the Phones section within NewBook)
call_duration is in seconds
To have the phone calls billed automatically (which is optional), please provide the following parameters:
e.g.
{
"region": "your_region_here",
"api_key": "your_api_key_here",
"request_action": "phone_calls",
"autocharge": "true",
"autocharge_gl_account_id": "2",
"autocharge_gl_category_id": "2",
"phone_calls": []
}
autocharge_invoice can optionally be provided as "true" to have NewBook create an Invoice for the Phone Call Charges. The Response JSON will have an array of invoice_ids returned in the data section.
PostMaster Accounts: List
Retrieve the list of PostMaster Accounts.
A PostMaster Account is usually used for recording non-Booking-specific charges i.e. generic income such as a till.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
Multiple Charges: Create
Used to record multiple sales to a Client Account in NewBook.
sales: an array of different sales to record
creating an array for credits instead of charges (same options apply e.g. description, amount) will allow a "negative charge" to save - internally NewBook handles this as Credits not negative Charges
creating an array for refunds instead of payments (same options apply e.g. description, amount) will allow for recording monies given back to the Guest
If the credits array was provided in the request, you will receive a credit_ids array in the response
If the payments array was provided in the request, you will receive a payment_ids array in the response
If the refunds array was provided in the request, you will receive a refund_ids array in the response
Subscriptions: List (CRM)
Pull the list of active Subscriptions from NewBook.
account_id can optionally be provided to limit results to a particular Client Account
gl_account_id can optionally be provided to limit results to a particular GL Account
Notifications: List
Pull a list of Notifications from NewBook.
staff_id is optional and when provided it will restrict the results to the matching Notifications. You have to know the ID of the particular staff member before running this query. The ID of the staff member can be found in the NewBook web interface
created_when is optional and when supplied, restricts the returned Notifications to only those which were created on the date given
Online Users: Get
Perform a login check for a NewBook Online User.
username is required
password is optional, but should be provided if you are using this method for authentication. When provided, if it does not match for the Online User requested, the whole online_users_get request will fail saying no record found.
Online Users: Create
Create a NewBook Online User.
username is required and must be an email address. If the provided username already exists, this request will return an error.
password is required. NewBook implements password complexity requirements: at least 8 characters, at least one upper case letter, at least one lower case letter, and at least one number.
for and for_id are required. This is the object associated with the Online User Login. Currently only guests, companies_staff, and travel_agents_staff are supported for options.
Online Users: Update
Update a NewBook Online User.
Either user_id or account_id is required, and can be retrieved using the Online Users: Get request.
If you are updating the password for the Online User, NewBook implements password complexity requirements: at least 8 characters, at least one upper case letter, at least one lower case letter, and at least one number.
username is optional, but if provided must be an email address. If the provided username already exists and isn't specifically for this Online User (identified by user_id or account_id), the whole online_users_update request will fail saying the provided username is already in use.
The Online User for and for_id cannot be updated.
Dietary Requirements: List
List all Dietary Requirements, for use when adding or updating Guests.
Users: List
Pull a list of active Users.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
Incidents: List
Pull a list of incidents.
id is optional and when provided the REST API will only retrieve an Incident with the matching ID.
search is optional and when provided it will restrict the results to the matching Incidents. It will search the following fields (inclusively) for a match:
period_from and period_to will restrict the results from later or earlier than the specified times respectively. Both can be provided to find results from a specific period.
location_name is returned as null when location_type and location_id are provided.
Using data_offset, data_limit, and data_total you will be able to paginate through the results.
You can increase data_limit to a maximum of 1000. Anything over this value will be capped at 1000.
You can request data_limit higher than data_total however data_count will still be the number of results returned.
See Handling Paginated Lists for more information.
Would you like to integrate with NewBook? You can access the NewBook REST and OTA APIs by registering for a developers account with us. Just a few simple steps and you will be on your way to developing with us!
Have you already registered for a developers account with NewBook? Click login below to use our login form.