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.
The NewBook REST API currently implements throttling after 100 requests per minute. Requests beyond this limit are denied.
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 by the NewBook Support team.
You must also supply the region and api_key parameters with each JSON request to specify which NewBook Region and Instance you are querying.
It is a requirement to use HTTPS to communicate with the NewBook REST API, for both testing and real live use. Your JSON request must be sent via HTTP POST.
URL: https://api.newbook.cloud/rest/request_action
Each REST API request has a distinct "action" which must be used in place of request_action in the above URL.
URL: https://testapi.newbook.cloud/rest/request_action
Each REST API request has a distinct "action" which must be used in place of request_action in the above URL.
Please contact NewBook Support if you are unsure about which Endpoint or Region to use.
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 who should have Arrived, opposed to who actually Arrived |
| arriving2 | are expected to Arrive during the specified dates |
| cancelled | have been Cancelled during the specified dates |
| departed1 | have Departed during the specified dates |
| departing3 | are expected to Depart during the specified dates |
| inhouse3 | 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 |
| quoted | are only Quotes (not actually staying) during the specified dates |
| waitlist | are only Waitlisted (not actually staying) during the specified dates |
| all |
returns all Bookings, this will be a Paginated List. period_from can be optionally provided to limit the response to Bookings created/modified after the specified timestamp period_to can be optionally provided to limit the response to Bookings created/modified before the specified timestamp |
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
The Equipment array returned has the data of all the equipment related to the booking. It returns an empty array if the booking has no equipment added
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 (online_booking_url) to convert the enquiry to an actual Booking via NewBook Online.
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.
You can supply the following parameters for detailed Site matching based on particular Equipment Sizes or Equipment Types:
Providing any of the above restricts the results returned.
You can also provide discount_id parameter to have the response factor that provided Discount for the Booking. Please be advised some clients set up a required discount_code too like a "password" to unlock a given discount_id. If that is done, you must supply both to use the Discount.
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.
"2022-08-11": {
"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": {
"2022-08-11": 0,
"2022-08-12": 1,
"2022-08-13": 5,
"2022-08-14": 1,
"2022-08-15": 1,
"2022-08-16": 4
},
"sites_message": {
"2022-08-11": "Minimum Advance Days has not been met, so there are no Sites available",
"2022-08-12": "Minimum Advance Days has not been met, so there are no Sites available",
"2022-08-13": "Minimum Advance Days has not been met, so there are no Sites available",
"2022-08-14": "",
"2022-08-15": "",
"2022-08-16": ""
}
"sites_code": {
"2022-08-11": 8,
"2022-08-12": 8,
"2022-08-13": 8,
"2022-08-14": 0,
"2022-08-15": 0,
"2022-08-16": 0
}
"sites_extra_info": {
"2022-08-11": "3",
"2022-08-12": "3",
"2022-08-13": "3",
"2022-08-14": "",
"2022-08-15": "",
"2022-08-16": ""
}
In addition, when daily_mode is provided as "true" the response will have stay_through_sites_available, stay_through_sites_message, stay_through_sites_code, and stay_through_sites_extra_info per the original keys which would have been returned in the response:
{
"stay_through_sites_available": 1,
"stay_through_sites_message": "",
"stay_through_sites_code": 0,
"stay_through_sites_extra_info": ""
}
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": "2022-08-11 14:00:00",
"period_to": "2022-08-18 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": "2022-08-11 14:00:00",
"period_to": "2022-08-18 10:00:00",
"gl_account_id": "20",
"gl_category_id": "1",
"tax_free": "1",
"vacancy_length": 45
}],
Another parameter you can provide is return_membership_discount_pricing which when "true" calculates all the applicable Membership Discounts in each tariffs_available object:
"membership_discount_pricing": [
{
"discount_id": "1",
"discount_name": "Membership Discount",
"discount_amount": 90.00,
"membership_id": "2",
"membership_name": "your membership program",
"membership_description": "Get a great discount by using your Membership!
",
"membership_icon": "https://driveau.newbook.cloud/instance_manager_e240bdef70fa7392a0332a76c7431a46_5f8532ea266d2.png",
"service_class": "Membership_Service_NAME",
"service_level": "Your Configured Membership Service Level"
}
]
If the membership_discount_pricing is empty it means the calculated discount amount was $0, or there is no applicable membership discount for this combination of Category and Tariff.
Another parameter you can provide is return_general_discount_pricing which when "true" calculates all the applicable Discounts in each tariffs_available object, without needing to perform this request with the discount_id parameter:
"discount_pricing": [
{
"discount_id": "2",
"discount_code": "gen_disc",
"discount_name": "General Discount",
"discount_amount": 100.00,
}
]
If you were to redirect guests to NewBook Online, you could use the discount_code returned above to have the booking engine grant that same discount.
If the discount_pricing is empty it means the calculated discount amount was $0, or there is no applicable discount for this combination of Category and Tariff.
Another parameter you can provide is return_promo_code_pricing which when "true" will return all available tariffs, even the ones ordinarily locked behind a promo_code requirement. Such tariffs are returned with the others in the tariffs_available array:
"tariffs_available": [
{
"tariff_label": "Promotional Tariff",
"site_selection_allowed": true,
"site_selection_fee": "3.00",
"tariff_short_description": "Special Tariff",
"tariff_success": "true",
"tariff_message": "",
"tariff_code": 0,
"tariff_extra_info": "",
"promo_code": "special",
"inventory_items": [],
"deposits": [],
"tariff_total": 120,
}
]
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 convert the enquiry 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:
Regarding specifying Equipment:
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_applied_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 supply only one of the above billing methods.
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 (this ordering has no meaning):
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. You can control which Client Account the Booking will bill to by supplying default_client_account_id which must be either "new_id" to denote the Client Account of the Booking about to be created, or a valid Client Account ID (e.g. the Group account). If this is omitted then NewBook will analyse other Bookings in the Group - if any of those bill to themselves, so to will this Booking.
custom_fields can optionally be provided based on the response to the Custom Fields request, to retrieve the different Fields set up in the instance:
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
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 Cancellation Reasons: List
Pull the list of Booking Cancellation Reasons from within NewBook.
name is optional and when provided it will restrict the results to the matching Booking Cancellation Reasons
show_inactive is optional and when provided it will include inactive Booking Cancellation Reasons in the response
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 (this ordering has no meaning):
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
booking_group_id in the response can be used in the bookings_create request to create Bookings in the Group. Remember also to set the default_client_account_id to the Group account_id if you want the Group to handle the billing for your new Booking(s).
Rate Override
Add a Rate Override
The following parameters are required:
The following parameters are optional:
Activity Setup
Returns description and image details for Activities enabled for Online use.
Please note that Activities have Configurations, and Configurations have Timeslots.
E.g. the Activity might be Jumping Castle, the Configurations might be "Single Child" vs "Family Ticket", and the Timeslots might be "9am-10am, 10am-11am, 11am-12pm".
This request shows the top level data of the Activity only (its name, facility, description, images if any, and Configurations).
If you need to see occupant limits (which are per-Timeslot) please use the Activity Availability and Pricing request.
activity_id can be provided as an array to limit the response to particular Activities.
facility_id the ID of the Facility this Activity occurs in (see Facilities: List)
Activity Availability and Pricing
Returns Activity availability and pricing for the requested dates/occupants.
period_from and period_to are required parameters to restrict the pricing request to a particular date/time period.
adults is required to advise the number of Adults participating in the Activity.
children, infants, animals can be optionally provided to advise of Children, Infants or Animals participating in the Activity.
activity_id can be optionally provided as an array to limit the response to particular Activities.
configuration_id can be optionally provided as an array to limit the response to particular Activity Configurations.
Each activity_configurations object shows included_occupants, extra_occupants and max_occupants:
Using the Create Ticket request will validate the parameters you supply against the above logic.
If there is no way to sell a given Timeslot, the timeslot_ticket object will not be present, timeslot_code will have one of the values listed below, and timeslot_message will show a human-readable error message.
Each timeslot_ticket object:
timeslot_code is a numeric representation of timeslot_message for you to use in constructing your own messages to your Guests it you prefer:
| timeslot_code | Reasoning |
|---|---|
| 0 | No error occurred - a successful result |
| 1 | The Activity Participant limit has been exceeded for this Timeslot |
| 2 | The Activity Ticket Participant limit has been exceeded |
| 3 | The Activity requires at least 1 participant |
Ticket List
Returns a list of Booked Activities aka Tickets.
All of the below are optional -
activity_id can be provided as an array to limit the response to particular Activities.
ticket_id can be provided as an array to limit the response to particular Tickets.
for, for_id can be provided to limit the response to a particular Booking/Guest. e.g.
{
"for": "bookings",
"for_id": 1234
}
account_id can be provided to limit the response to Ticket billing to a particular Client Account.
period_from, period_to can be provided to limit the response to a particular date range.
show_cancelled can be provided as "true" to show Cancelled Activity Tickets.
Create Ticket
Book an Activity / Create an Activity Ticket.
All fields in the Request JSON are required except for children, infants, animals and account_id.
Most of these fields can be retrieved from the timeslot_ticket object returned in the Availability and Pricing request.
for, for_id advises who the Ticket is for e.g.
{
"for": "bookings",
"for_id": 1234
}
account_id can be provided to advise which Client Account to bill to, if omitted the Default Client Account of the connected object will be used e.g. the Booking Default Client Account.
You will receive a ticket_id when the request successfully books an Activity.
Update Ticket
Update an Activity Ticket.
ticket_id is required to advise which Ticket you are updating.
cancel is an optional parameter, when provided as "true" NewBook will cancel the Ticket.
All other parameters are optional and documented on the Create Ticket request.
You will receive the same ticket_id when the request successfully updates the Activity Ticket.
Ticket PDF Content
Retrieve the HTML markup required to print a PDF version of the Activity Ticket.
Facility Hire: Availability and Pricing
Returns the Facility Hire Availability and Pricing for the requested dates.
period_from and period_to are required parameters to restrict the availability request to a particular date/time period.
facility_id is a required parameter provided as an array to limit the response to particular Facilities
adults, children, infants, animals can be optionally provided for hiring the Facility, as these may affect pricing.
Availability is returned per Facility. For each Facility, the below explains the response keys:
Facility Hie: List
Returns a list of Facility Hires.
All of the below are optional -
facility_ids can be provided as an array to limit the response to particular Facilities.
for, for_id can be provided to limit the response to a particular Booking/Guest e.g.
{
"for": "bookings",
"for_id": 1234
}
period_from, period_to can be provided to limit the response to a particular datetime range.
show_cancelled (default "false") can be provided as "true" to show Facility Hires which have been cancelled.
Facility Hire: Create
Create a Facility Hire.
adults is required however children, infants, animals can be optionally provided for hiring the Facility, as these may affect pricing.
facility_id is the ID of the Facility to be hired (see Facilities: List)
for, for_id advises the Booking/Guest this Facility Hire should be attributed to, and must already exist in the Instance database e.g.
{
"for": "bookings",
"for_id": 1234
}
success will be false when the Facility is unavailable to Hire for the requested duration.
When the Facility Hire is successful, you will receive hire_id in the data response.
Facility Hire: Update
Update a Facility Hire.
hire_id is required to advise which Facility Hire you are updating.
status is an optional parameter, when provided as 0 NewBook will cancel the Facility Hire.
All other parameters are optional, and are defined in Facility Hire: Create.
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 one of the ID 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)
sort_ascending is optional and when supplied as true, sorts the Guests by ID ascending. Defaults to false (sort the Guests by ID descending).
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
The Equipment array returned has the data of all the equipment related to the guest. It returns an empty array if the guest has no equipment
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
account_id will be null when the Instance is part of a Shared Guest Database and there has been no Guest Activity at this particular Instance.
period_from can be optionally provided to limit the response to Guests created/modified after the specified timestamp
period_to can be optionally provided to limit the response to Guests created/modified after the specified timestamp
Guests: Create
Create a Guest to use for placing Bookings, Availability Emails, Online Logins, and more.
contact_email and contact_phone can be provided to create or update Contact Details for a Guest. When updating, these values will also check & not double up if the new information already exists on the Guest. And 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. This can either be provided as a string, or as array of objects containing the following options:
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. When updating, these values will also check & not double up if the new information already exists on the Guest (based on membership_type).
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, NewBook will automatically update the record of the first duplicate found.
Regarding specifying Equipment:
custom_fields can optionally be provided based on the response to the Custom Fields request, to retrieve the different Fields set up in the instance:
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.
All other parameters are optional, please see Guests: Create for more details.
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.
Guests: Deletion History
Retrieves a list of Guest ID's that have been deleted from NewBook.
period_from can be optionally provided to limit the response to Guests deleted after the specified timestamp
period_to can be optionally provided to limit the response to Guests deleted after the specified timestamp
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
Membership: Purchase
Grant a Membership to one of the connected Membership Types to an existing Guest
Despite the request name, no purchase transaction or account charging is involved here. This request expects you to have handled that on your side of the integration.
membership_type is required and must match one of the ID values from a Memberships: List request.
Further, only results from the Memberships: List request with a membership_service_id and membership_service_level defined are able to be purchased with this request.
Guests: Merge
Merge one or more duplicate guests into a primary guest. When a duplicate guest has details not already in the primary guest it will be added. If the primary guest had different existing details then, depending on addtional parameters below, the details will be ignored or added as notes.
Warning, merging a guest cannot reversed, so please ensure you are merging the correct guests.
primary_id [number] Provides the primary guest id for the duplicate guests to merged into. This guest will keep its original details.
duplicate_ids [number array] Provides array of guest ids to be merged into the primary guest.
merge_tasks [true|false] Provides single or list of guest ids to be merged into the primary guest.
address_note_type_id [null|int] optional If a Note Type ID is provided then any mismatched address details against the duplicated guest will be added to the primary guest as a note of that type.
custom_fields_note_type_id [null|int] optional If a Note Type ID is provided then any unique custom fields against the duplicated guest will be added to the primary guest as a note of that type.
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
Each Category details its Sites in an array. Each Site has all the same attributes as per the sites_list request.
Sites can optionally inherit Features from their parent Category (see the accommodation_category_list request). When this is the case, site_features_specified will be false, the site_features array will be empty, and the Features should be referenced from the parent Category. When this is not the case, site_features_specified will be true, and only those Features specified on the Site are valid (including an empty site_features array meaning none).
Categories have a set of Images, and Sites do as well. Those returned in site_images should be displayed in conjunction with those from the Category.
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 deactivated Sites
Sites can optionally inherit Features from their parent Category (see the accommodation_category_list request). When this is the case, site_features_specified will be false, the site_features array will be empty, and the Features should be referenced from the parent Category. When this is not the case, site_features_specified will be true, and only those Features specified on the Site are valid (including an empty site_features array meaning none).
Categories have a set of Images, and Sites do as well. Those returned in site_images should be displayed in conjunction with those from the Category.
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. When updating, these values will also check & not double up if the new information already exists on the Company. And 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. This can either be provided as a string, or as array of objects containing the following options:
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. When updating, these values will also check & not double up if the new information already exists on the Company Staff. And 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. This can either be provided as a string, or as array of objects containing the following options:
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.
contact_email and contact_phone can be provided to create or update Contact Details for a Lead. When updating, these values will also check & not double up if the new information already exists on the Lead. And 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. This can either be provided as a string, or as array of objects containing the following options:
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, NewBook will automatically update the record of the first duplicate found.
custom_fields can optionally be provided based on the response to the Custom Fields request, to retrieve the different Fields set up in the instance:
Leads: Update
Update an existing Lead within NewBook.
lead_id is required
All other parameters are optional, please see Leads: Create for more details.
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
tax_rates: (optional) Instead of NewBook calculating the Tax Amounts for you, use this parameter to manually provide Tax Amounts
[
{"tax_id":sourced from NewBook,"tax_amount":number},
{"tax_id":sourced from NewBook,"tax_amount":number}
]
tax_id: is based on the response to 3rd Party Tax Rates
payment_amount (optional): tells NewBook how much the Payment taken was. When specified, payment_type will also be required to create the Payment.
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
tax_rates: (optional) Instead of NewBook calculating the Tax Amounts for you, use this parameter to manually provide Tax Amounts
[
{"tax_id":sourced from NewBook,"tax_amount":number},
{"tax_id":sourced from NewBook,"tax_amount":number}
]
tax_id: is based on the response to 3rd Party Tax Rates
refund_amount (optional): tells NewBook how much the Refund processed was for. When specified, refund_type will also be required to create the Refund.
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.
Transaction Fees: Get
Used to calculate Transaction Fees for the requested Payment Type
amount (required): The amount to calculate transaction fee.
type (required): Please see the Payment Types request for a list of valid types.
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. Please note that balance transfers are not currently supported for use as a Payment Type
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, default 0; Whether or not this payment should be considered Deposits Held for reporting purposes
invoice_id: (optional): Reconcile towards the nominated Invoice. If you need to, you can use the Invoices: List request to retrieve a Invoice(s) for an account, and return one of those IDs. This parameter can be provided as either a single Invoice ID or an array of Invoice IDs. Using this parameter will ignore reconcile_payment.
reconcile_payment (optional): 1/0, default 0; Whether saving this payment should attribute it towards existing charges on the account. This is encouraged, but for backwards-compatibility, the default behaviour is 0.
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. Please note that balance transfers are not currently supported for use as a Payment Type
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 which 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
3rd Party Tax Rates
Used to retrieve Tax Rates that can be used when creating Charges / Credits with custom Tax Amounts.
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.
In NewBook, each Site has an option "Contribute to Occupancy Reports". It can be Yes or No. When Yes, the Site is factored into the Occupancy Report calculations. When No, it is ignored from the Occupancy Report.
The REST API Occupancy Report will factor all Sites even if their "Contribute to Occupancy Reports" option inside NewBook was set to No.
This behaviour in the REST API can be controlled using a parameter factor_site_contribute_to_occupancy_option as true.
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
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 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.
output_message is optional, and will default to true when not provided. This controls whether the note will display at the top of the associated page.
task_list is optional, and will default to false when not provided. This controls whether the note will display on any tasks lists.
check_for_duplicates is optional, and will default to true if not provided.
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",
"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
tax_free: 1 = Tax Free, 0 = Has Tax
tax_rates: (optional) Instead of NewBook calculating the Tax Amounts for you, use this parameter to manually provide Tax Amounts
[
{"tax_id":sourced from NewBook,"tax_amount":number},
{"tax_id":sourced from NewBook,"tax_amount":number}
]
tax_id: is based on the response to 3rd Party Tax Rates
tax_free: 1 = Tax Free, 0 = Has Tax
tax_rates: (optional) Instead of NewBook calculating the Tax Amounts for you, use this parameter to manually provide Tax Amounts
[
{"tax_id":sourced from NewBook,"tax_amount":number},
{"tax_id":sourced from NewBook,"tax_amount":number}
]
tax_id: is based on the response to 3rd Party Tax Rates
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 a list of 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
include_cancelled can optionally be provided as true to include Cancelled Subscriptions; defaults to false, which will return Active & Stopped Subscriptions.
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 and owners 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)
Send show_inactive as true to include deactivated Users in the response
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.
State List
Returns the list of States which Instances can use in their address information, per the set up in Instance Manager.
If you like, you can supply a country_id to limit the results to the States of that Country.
Country List
Returns the list of Countries which Instances can use in their address information, per the set up in Instance Manager.
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.