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
2024.03
- Member Transactions: List request added
2024.01
- Guests List - added service_id and level to the membership_details response.
- Credit Card Authorisations: Create request added
- Credit Card Authorisations: Update request added
- Credit Card Authorisations: Delete request added
- Facilities List - show_inactive request parameter added, defaults to false. hireable_only request parameter added, defaults to true.
2023.11
- Charges Get - request added
- Credits Get - request added
- Payments Get - request added
- Refunds Get - request added
2023.10
- Users - List, Get, Create and Update - Added department id and name to each request.
- Users - Added Get request
- Facility Hire Get and List - Added Facility Category id and name to responses.
- Bookings Pull Availability & Pricing - Added parameters around how guaranteed Allotments alter the availability response.
- Bookings Group Update - Added
- Notes Update - Added. Retrieved notes now contain an id field to aid usage of this new endpoint.
- Contact Documents List, Create and Sign requests added
- Invoices: Get request added
- Receipts: Get request added
- Invoices: List - Added requests parameters fetch_items_booking_details
- Direct Debit Authorisations List, Get, Create, and Update - request added
- Special Dates List, Create, Get and Update requests added
- Facility Hire - added custom_fields to List, Get, Create and Update
- Clients Accounts: List, Clients Accounts: Get - Added requests parameters client_account_item_breakdown, client_account_tax_reconciliation, client_account_booking_details
- Software Mappings List, Create, Get and Update requests added
2023.09
- Bookings Create, Update - additional parameter override_min_stay added
- Bookings Create and Update response is now the whole Booking object per the Bookings: Get response.
- Facility Hire Create and update - response updated to include the full Facility Hire Object.
- Facility Hire: Get - request added
2023.08
- Allotments List, Create, Get and Update requests added
- Allotment Override - request added
- Bookings List, Get - occupant_charges parameter added to tariffs_quoted
- Bookings List, Get, Bookings Groups List, get, Guests List, Guests Get - added client_account_booking_details parameter
- Guests: Get and Guests: List - Added display_guest_facility_hires and display_cancelled_guest_facility_hires to the request parameters to include Guest Facility Hires
- Bookings: Get and Bookings: List - Added display_guest_facility_hires and display_cancelled_guest_facility_hires to the request parameters to include Guest Facility Hires
- Bookings: Get and Bookings: List - Added display_cancelled_booking_activities and display_cancelled_booking_facility_hires to the request parameters to include cancelled Activities and Facility Hire for the Booking
- Bookings Groups: Get and Bookings Groups: List - Added display_cancelled_group_activities and display_cancelled_group_facility_hires to the request parameters to include cancelled Activities and Facility Hire for the Group
2023.07
- Guests: Get and Guests: List - Added display_guest_activities and display_cancelled_guest_activities to the request parameters to include guest activity tickets
- Bookings: Get and Bookings: List - Added display_guest_activities and display_cancelled_guest_activities to the request parameters to include guest activity tickets
- Rates List, Get, Create, and Update - request added
- Rate Applications List, Get, Create and Update requests added
- Bookings Rule Templates List, Get, Create and Update requests added
- Users: List - additional response data has been added
2023.06
- Bookings List, Create, Update - additional parameters and response data have been added
- Bookings Groups List, and Get requests added
- Guests List and Get - added show_inactive_equipment parameter
- Bookings: List, Bookings: Get, Guests: List, Guests: Get, Bookings Groups: List, Bookings Groups: Get, Payments: List, and Refunds: List - added type_id to the response
- Payments Types - added id to the response
2023.05
- Bookings: Pull Availability & Pricing - Added adjustment_fees to the response
- Guests: Update - Added id to the equipment parameters for updating existing Guest Equipment
2023.04
- Rate Periods: List, Create, Update and Get requests added
- Rate Types List, Get, Create and Update requests added
- Activities: Ticket List - Added booking_site_id, booking_site_name, booking_category_id, and booking_category_name to the response
- Bookings: Pull Availability & Pricing - return_all_membership_discount_pricing_options parameter added
2023.03
- Bookings: Get - client_account_item_breakdown parameter added
- Bookings: Get - client_account_tax_reconciliation parameter added
- Guests: List - client_account_item_breakdown and client_account_tax_reconciliation parameters added
- Guests: Get - client_account_item_breakdown and client_account_tax_reconciliation parameters added
2023.02
- Payments Reconciliation Create - request added
- Refunds Reconciliation Create - request added
- Metering Types List, Get, Create and Update requests added
- Inventory Items Create, Update, Get and List - repeat_charge_booking_market_segment_id added
- Bookings Create - booking_market_segment_id added to Repeat Charges
- Bookings: Get - client_account_item_breakdown parameter added
- Bookings: Get - client_account_tax_reconciliation parameter added
2023.01
- Sites: Get - request added
- Sites: Create - request added
- Sites: List, Update - metering_types added
- Metering Types: List - request added
- Meter Readings: Create - request added
- Bookings: Create - additional parameters have been added
- Charges: Create, List - generated_by added
- Credits: Create, List - generated_by added
- Payments: Create, List - generated_by added
- Refunds: Create, List - generated_by added
- Notes: Create - added created_when option to set the timestamp of a note
- Accommodation Categories Create, Update and Get - requests added
- Inventory Items Create, Update and Get - requests added
- Facility Categories List, Create, Update and Get requests added
- Facility Features List, Create and Update requests added
- Facilities Create, Update and Get requests added
- Client Account Profiles List, Create, Update and Get requests added
- Metering Tariffs List, Create, Update and Get requests added
- Charges: Create has received the ability to specify what the charge is linked to
- Credits: Create has received the ability to specify what the credit is linked to
2022.11
- Notes: Create - added user_id option to set the author of the note
- Bulk Upload - request added
- GL Accounts: Create and Update requests added
- GL Accounts Groups: List, Create and Update requests added
- Create Audit Trail - request added
- Users: Create and Update requests added
- Discounts: List - can now use discounts_list or previous discount_list endpoint for consistency with new requests
- Discounts: Create - request added
- Discounts: Get - request added
- Discounts: Update - request added
- Contact Emails: Create - request added
- Contact SMS: Create - request added
- Activity Setup - configuration_online parameter added to activity configurations
2022.10
- Reports: Daily Audit Summary - download_content_type option added
- Site Sizes List, Create, and Update requests added
- Sites: Update - site_size_id option added to assign a Site Size to a Site
2022.07
- Guests: List - sort_ascending option added
2022.06
- Guests: Merge - request added
- Membership Purchase - request added
- Site Maps - added ability to limit to a single Map, and request availability validation along with the returned data
- Bookings Create - required_features added for when you know what features you need, but not the specific Site ID
2022.05
- Transaction Fees: Get - request added
- Facility Hire: Availability and Pricing, List, Create, and Update requests added
2022.03
- Bookings: List - added ability to pull all Bookings, added Access Codes to the response data.
- Guests: Deletion History - request added
2022.02
- Activity Setup, Availability and Pricing, Ticket List, Create Ticket, Update Ticket, and Ticket PDF Content requests added
2022.01
- Booking Cancellation Reasons: List request added
- Reporting: Occupancy - will now return the number of gross and net revenue figures
2021.02
- Charges: Create - will now be able to accept an optional parameter of payment_amount. This paired with the payment_type will allow you to create a Payment for a specified amount different to the Charge amount.
- Credits: Create - will now be able to accept an optional parameter of refund_amount. This paired with the refund_type will allow you to create a Refund for a specified amount different to the Credit amount.
- Notes: Create - will now be able to accept an optional parameter of check_for_duplicates.
- Access Codes: List - now also returns guest_id and guest_name for the associated Access Code.
- Bookings: Pull Availability & Pricing - now returns extra tariffs when requested with any of the following: membership pricing when requested with return_membership_discount_pricing, and discount pricing when requested with return_general_discount_pricing, and tariffs locked behind promo_codes when requested with return_promo_code_pricing.
2020.10
- Leads: Create, Guests: Create - will now automatically update the first existing record when a duplicate is found
- Users: List - will now be able to accept an optional parameter of show_inactive. This will allow the list to return deactivated Users.
2020.06
- Gift Vouchers: List - will now return sell_online and redeem_online, instead of allow_online
- Subscriptions: List - created_when returned in response; new include_cancelled parameter to optionally include Cancelled Subscriptions; status and stopped_when returned in response data
- 3rd Party Tax Rates request added
- Added tax_rates as an optional parameter to Charges: Create, Credits: Create and Create Multiple Charges
2020.03
- Reporting: Occupancy - will now return the number of Sites reserved by Allotments
- All requests which returned account information e.g. Guests: Get can now be requested with account_breakdown to return the balance of each Sub Client Account (gl_category)
- Charges: List, Credits: List - will now return their Tax amounts
2019.12
- Bookings: List - will now return Booking Notes in addition to Guest Notes
- Multiple Charges: Create - invoice_system_template_id parameter added
2019.07
- Token: Store request added
- Inventory Items: List - will now return Newbook Online Category Restrictions.
- Companies: List - account_currency_code, auto_debit added to each object in the response
- Incidents: List - will return a list of Incidents.
- Leads: List - will now return the following additional fields: Source, Method, Status Reason, Inventory Items, Categories, Interests, Types, Notes, Points, Parent Lead ID, Interest Level, Expected Revenue, Title, Other Name, Created By, Assigned When.
- Guests: List - will now return the following additional fields: Notes
- Quotes: List - will now return the following additional fields: Notes
2019.04
- Facilities: List request added
- Update Booking Source request added
- Online Users: Create request added
- (Important) Live Endpoints - the Live Endpoints have been consolidated into a single URL, with the Newbook Region required to be delivered as a parameter in the request body. All other URLs are deprecated.
- Events: List, Events: Get requests added
- Security Areas: List - Security Gate associations added to the response
2018.11
- Booking Sources: List - show_inactive added as optional request parameter; parent_id, domain_referer and active added to each object in the response
- Booking Sources: Create - you can now create parent Booking Sources by setting the new is_parent request parameter to true
- Companies: List: - type_id added to each object in the response
- System Templates: List, Create, Get, Update - requests added
- Bookings Create: - qty added to the list of potential inventory_item parameters
- Leads: Create - duplicate Lead IDs now returned when the leads_create request encounters such
- Guests: Create - duplicate Guest IDs now returned when the guests_create request encounters such
- Guests: List, Leads: List - can now be filtered by staff_id for CRMs. Staff Sharing is also returned for CRMs.
- Users: List - request added
- Leads: List - status_id added as optional request parameter, created_when, modified_when, status_when, lead_types added to response object
- Lead Statuses: List - response extended to include what Type of status it is
- Booking Market Segments: List, Bookings: Update Market Segment - requests added
- Lead Activity History - request added
- Payments: Create - auto_receipt parameter added
2018.08
- Bookings: Pull Availability & Pricing - sort added to each object in the response; inventory_items added to each tariffs_available element in the response
- Bookings: Get - will return success:"false" in the response when the requested Booking does not exist
- Bookings: List / Get - will now return booking_market_segment_id and booking_market_segment_name in the response
- Bookings: Retrieve Current In Site - will return success:"false" in the response when the requested Site does not exist
- Contact Templates: Create, Update, Options - requests added
- Requests which return Custom Field data - Custom Fields now have their type returned along with the data
- Tasks: Create - location_name can now be used for Site and Facility Tasks
2018.05
- (Important) Test Endpoint - the old testing URL has been deprecated. All integrators are encouraged to move to the new testing URL if test access is still required.
- Payments: List, Refunds: List - transaction_method added to response
- Reporting: Reconciliation - payment_transaction_method added to response
- Bookings: Pull Availability & Pricing and Create Availability Email - data can optionally be returned as an array instead of an object
- Create Booking, Update Booking - the guest_id used for a Booking is now returned in the response
- Payments: List - optional get_paid_by parameter added
- Refunds: List - optional get_refunded_to parameter added
- Invoices: List - optional get_invoiced_to parameter added
- Receipts: List - optional get_receipted_to parameter added
- Create Booking - optional allow_dirty_arrivals, allow_backtoback_bookings parameters added
2018.02
- Lists: allow_contact changed to allow_transactional and allow_marketing on individual contact details.
- Guests: Get - allow_contact changed as above.
- Bookings: Get - allow_contact changed as above.
- Leads: Categories, Types, Sources, Sources: Create requests added
- Leads: Create - duplicate detection added
- Guests: Create - duplicate detection updated, dietary_requirements added
- Guests: Get - dietary_requirements added
- Guests: Update - dietary_requirements added
- Bookings: List - dietary_requirements added
- Bookings: Get - dietary_requirements added
- Custom Fields - request added
- Dietary Requirements: List - request added
2017.12
- (Important) Building an example Request - passing the request_action in the URL has been deprecated in favour of passing it as a JSON parameter. Support for passing it in the URL will be removed in a later release.
- Task Types: List request added
- Tasks: Create request added
- Ticket Queue: List request added
- Tickets: List, Get, Create, Update requests added
- Bookings: List, Get - discounts added to the results
- Contact Templates: List, Send requests added
- Bookings: Update request added
- Tasks: List - returned parameters have changed for Booking Tasks
- Charges: Create - booking_id and inventory_item_id parameters added
- Credits: Create - booking_id and inventory_item_id parameters added
- Multiple Charges: Create - booking_id and inventory_item_id parameters added
2017.10
- Subscriptions: List - inventory_item_id field added to the results
- Bookings: Get request added
- Guests: List - account_id parameter added
- Companies: List - account_id parameter added
- Companies Staff: List request added
- Companies Staff: Update request added
- Online Users: Get request added
- Online Users: Update request added
- Invoices: List - fetch_guests, fetch_items parameters added
- Receipts: List - fetch_guests, fetch_invoices parameters added
2017.08
- Client Accounts: List request added
- Client Accounts: Get request added
- Multiple Charges: Create - invoice_description parameter added
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 provide 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.
Live Endpoint
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.
- Region Options:
- au - Australia
- ap - Asia Pacific
- eu - Europe
- us - United States
Test Endpoint (must be specifically requested; access is not automatic)
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.
- Region Options:
- staging - Australia
Please contact Newbook Support if you are unsure about which Endpoint or Region to use.
Authentication Examples
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 Notes:
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.
Building an example Request
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 Errors Examples
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).
Notes:
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.
Handling Paginated Lists
API Keys Request
Return a list of API Keys (Newbook Instances) which your username & password can connect with.
API Keys Request Example
Authentication Test Request
Verify the username, password, and API Key in your possession work as expected.
Authentication Test Request Example
Bookings: List
Retrieve a list of Bookings within the given time period.
Request Notes:
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 before the specified period_to date, including Bookings before this date which are not yet Arrived - period_from will be ignored in this case. To limit results to those within the specified dates, please use list_type of arrived and the mode parameter of projected (see above) |
| 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 |
| staying1 | 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 |
- 1 ignores bookings of status Cancelled, No Show, Quote, Waitlist, and Owner Occupied
- 2 shows only bookings of status Confirmed and Unconfirmed
- 3 shows only bookings of status Arrived
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
display_guest_notes is optional and when provided as false, it will ignore any guest notes from the response. Not providing the field will behave the same as providing it as true which will display the full array of the guest notes.
client_account_tax_reconciliation can optionally be provided as true to include the amount of tax based on the reconciliation of payments / refunds. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_booking_details can optionally be provided as true to include Booking details for Charges and Credits. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_item_breakdown can optionally be provided as true to include all accounting items saved on the Booking Client Account in the Booking response. Please see the Bookings: Get request for an example of the response data.
display_guest_activities can optionally be provided as true to include the Guests Activity Tickets in the Guest response. display_cancelled_guest_activities can also be provided to include Cancelled Activity Tickets. Please see the Guests: Get request for an example of the Guest Activity response data.
display_guest_facility_hires can optionally be provided as true to include the Guests Facility Hires in the Guest response. display_cancelled_guest_facility_hires can also be provided to include Cancelled Facility Hires. Please see the Guests: Get request for an example of the Guest Facility Hire response data.
display_cancelled_booking_activities can optionally be provided as true to include Cancelled Activity Tickets for the Booking.
display_cancelled_booking_facility_hires can optionally be provided as true to include Cancelled Facility Hire for the Booking.
Response Notes:
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
Inventory Item data:
The inventory_item array holds all the Inventory Item objects for the Booking.
- stay_cost_contribution indicates whether the amount is Included in the price of each night, or if it Increases the price of each night, or if it is Excluded from the price of each night (still counts as an add on cost but is not subject to discounts).
- When the inventory_item gl_account_id key is null this means match the Booking gl_account_id
- When the inventory_item gl_category_id key is null this means match the Booking gl_category_id
- The discounts_apply key on each inventory_item indicates whether this item contributes to Discount Calculation
Guest Data
title can be any string; Newbook does not restrict users to specific titles for Guests
contact_details
- allow_transactional: Guest allows general contact related to Bookings or accounts
- allow_marketing: Guest allows marketing contact such as newsletters
Tariffs Quoted Data
tariffs_quoted array of objects shows the quoted tariff for each night
- original_amount the figure the Newbook platform originally computed as the price to stay for this night.
-
calculated_amount the figure the user (staff member logged and using Newbook PMS) has saved as the price to stay for this night
This figure defaults to original_amount, but the user can have the ability to override the price if they need to -
charge_amount the total calculated stay cost (calculated_amount) excluding additional costs that are charged separately
This is the figure which should be treated as the base price to stay for the night
The following components, when present, are subtracted from calculated_amount to yield charge_amount:- Inventory items which are included in stay cost
- Additional Occupant Type charges
-
occupant_charges returns an array of additional occupant type charges
This will be empty unless LOS GL Account Overrides have been enabled and configured for occupant types
Bookings: List Example
Bookings: Get
Retrieve the details of a single Booking.
Request Notes:
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).
Provide display_guest_notes as false if you wish to ignore the guest notes. Not providing the field will behave the same as providing it as true which will display the full array of the guest notes.
Send access_code_mappings as true to also return a list of Access Code mapping details to other software integrations such as Access Control Systems.
client_account_tax_reconciliation can optionally be provided as true to include the amount of tax based on the reconciliation of payments / refunds. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_booking_details can optionally be provided as true to include Booking details for Charges and Credits. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_item_breakdown can optionally be provided as true to include all accounting items saved on the Booking Client Account in the Booking response.
e.g.
{
"charges": [
{
"id": "3062",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Standard Rate (2024-04-19)",
"amount": 100,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "tariffs_quoted",
"link_type_id": "123",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": "9.09"
}
]
}
],
"credits": [
{
"id": "4351",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Discount",
"amount": 5,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "discounts_quoted",
"link_type_id": "1024",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": 0.45
}
]
}
],
"payments": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"paid_by": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Accommodation",
"amount": 100,
"tendered": 100,
"type": "cash",
"type_id": "4",
"type_reference": "",
"deposit": "0",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [],
"charges": [
{
"link_id": 1,
"charge_id": 3062,
"reconciled_amount": 100,
"timestamp": "2024-04-19",
"voided_when": null
}
]
}
],
"refunds": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"refunded_to": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Refunding Discount Overpayment",
"amount": 5,
"tendered": 5,
"type": "cash",
"type_id": "4",
"type_reference": "",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [
{
"link_id": 1,
"credit_id": 4351,
"reconciled_amount": 5,
"timestamp": "2024-04-19",
"voided_when": null
}
],
"payments": []
}
]
}
display_guest_activities can optionally be provided as true to include the Guests Activity Tickets in the Guest response. display_cancelled_guest_activities can also be provided to include Cancelled Activity Tickets.
e.g.
{
"activities": [
{
"ticket_id": 8,
"activity_id": 2,
"name": "Golf",
"duration": "7",
"duration_interval": "day",
"facility_id": null,
"facility_name": null,
"facility_category_id": null,
"facility_category_name": null,
"configuration_name": "Golf - 18 Holes",
"id": 8,
"period_from": "2024-04-23 09:00:00",
"period_to": "2024-04-23 11:00:00",
"activity_configuration_id": 2,
"for": "guests",
"for_id": 1,
"adults": 2,
"children": 0,
"infants": 0,
"animals": 0,
"configuration_included_adults": null,
"configuration_included_children": null,
"configuration_included_infants": null,
"configuration_included_animals": null,
"inventory_item_id": 11,
"account_id": null,
"gl_category_id": 1,
"gl_account_id": 1,
"description": "Golf - 18 holes of golf",
"interval": "once",
"interval_multiplier": "1",
"amount": 0,
"per_adult": 80,
"per_child": 40,
"per_infant": 0,
"per_animal": 0,
"tax_free": "0",
"cancelled_when": null,
"cancelled_by": null,
"created_when": "2024-04-12 11:32:00",
"created_by": "-2",
"for_name": "John Doe",
"booking_site_id": null,
"booking_site_name": null,
"booking_category_id": null,
"booking_category_name": null,
"inventory_items": [
{
"ticket_id": "8",
"inventory_item_id": null,
"gl_category_id": null,
"gl_account_id": null,
"description": "Cart Hire",
"interval": "once",
"interval_multiplier": "0",
"amount": "45.00",
"per_adult": "0.00",
"per_child": "0.00",
"per_infant": "0.00",
"per_animal": "0.00",
"tax_free": "0",
"guest_visible": "1",
"charge_id": "351"
}
],
"units": 1,
"calculated_total": 205,
"total_paid": 0,
"payment_status": "Unpaid",
"access_codes": [],
"custom_fields": [],
"payment_plans": []
}
]
}
display_guest_facility_hires can optionally be provided as true to include the Guests Facility Hires in the Guest response. display_cancelled_guest_facility_hires can also be provided to include Cancelled Facility Hires.
e.g.
{
"facilities_hire": [
{
"id": "2",
"facility_id": "2",
"period_from": "2024-04-23 12:00:00",
"period_to": "2024-04-23 13:00:00",
"length": "1 hour",
"amount": "55.00",
"per_adult": "0.00",
"per_child": "0.00",
"per_infant": "0.00",
"per_animal": "0.00",
"tax_free": "0",
"adults": "1",
"children": "0",
"infants": "0",
"animals": "0",
"hire_account_for_id": "51",
"hire_account_for_name": "John Doe",
"hire_account_for": "guests",
"hire_account_balance": "0.00",
"billing_account_for_id": "51",
"billing_account_for_name": "John Doe",
"billing_account_for": "guests",
"billing_account_balance": "55.00",
"inventory_item_id": "2",
"gl_category_id": "1",
"gl_account_id": "9",
"description": "Kayak Hire",
"override_tax_rate_ids": [],
"units": 1
}
]
}
display_cancelled_booking_activities can optionally be provided as true to include Cancelled Activity Tickets for the Booking.
display_cancelled_booking_facility_hires can optionally be provided as true to include Cancelled Facility Hire for the Booking.
Example Booking Detail Attributes on charges, credits, payments, refunds when client_account_booking_details is true.
e.g.
{
"guest_visible": "1",
"discounts_apply": "1",
"booking_id": "1234",
"booking_name": "John Doe",
"booking_status": "Confirmed",
"booking_site_id": "2",
"booking_period_from": "2024-04-19 11:30:00",
"booking_period_to": "2024-04-20 14:00:00",
"booking_reference_id": "",
"activity_booked_id": null
}
Response Notes:
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: Get Example
Bookings: Push Notification
Newbook can send a push notification every time a Booking is created or updated.
The endpoint that data is pushed to needs to be configured against the REST API User credentials. This is done by the Newbook Support team. Please contact Newbook Support if you wish to have this configured for your REST API user account.
Only one push notification endpoint can be configured per REST API User per Newbook Instance.
Request Notes:
The push notification data is similar to Bookings: Get, but only contains the booking information within the data property.
The push notification is sent as a POST request to the configured endpoint.
Bookings: Retrieve Current in Site
Check a particular Site to see if a Guest is currently In-House
Request Notes:
site_id or site_name must be provided. If you use site_name it must match character for character.
Response Notes:
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: Retrieve Current in Site Example
Bookings: Pull Availability & Pricing
Advisory Notice
bookings_availability_pricing is designed to be used with most or all of its parameters provided.
Your integration should be making this request LAST, to check the pricing and availability for a specified date range, and Category or Site.
Such a request will be performant. A result will be returned to your integration quickly.
If you make this request without those parameters (to be clear, this is not advised!) the request will not be performant, as Newbook has to analyse availability information for all the Categories and all the Rate Types set up within the Instance.
Such a request will take a long time to return a result. This is not a bug or a defect in the Newbook platform - it is a misuse of this request.
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.
Request Notes:
You can provide site_id, category_id and category_type_id parameters.
You can provide length and width parameters to find Sites with matching sizes.
You can provide children, infants and animals as numeric parameters (like the adults parameter).
You can provide the following parameters for detailed Site matching based on particular Equipment Sizes or Equipment Types:
- equipment_length, equipment_width and equipment_height (optional) to filter by sizing.
- You can optionally provide equipment_measurement_unit as m for metres (default) or ft for feet, if you need Newbook to convert these for you.
- equipment_type_ids to filter by supported Equipment Types.
Providing any of the above restricts the results returned.
You can 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 provide both to use the Discount.
When discount_id or discount_code parameters are provided, each object in the tariffs_available array will also include discount_success as a string boolean indicating if the Discount has applied to this Tariff, discount_total as a float indicating the Discount amount to be granted, and discount_message which will have a human-readable explanation when discount_success is false.
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.
"2024-04-20": {
"label": "Special",
"type_id": "8",
"tariff_id": "45",
"tariff_name": "Special Rate",
"stop_sell": "0",
"minimum_periods": "7",
"maximum_periods": "0",
"base_min_combined": "1",
"base_max_combined": "7",
"tariffs_period_id": "19",
"tariffs_period_name": "All Year",
"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": {
"2024-04-20": 1,
"2024-04-21": 0,
"2024-04-22": 5,
"2024-04-23": 3,
"2024-04-24": 6,
"2024-04-25": 3
},
"sites_message": {
"2024-04-20": "Minimum Advance Days has not been met, so there are no Sites available",
"2024-04-21": "Minimum Advance Days has not been met, so there are no Sites available",
"2024-04-22": "Minimum Advance Days has not been met, so there are no Sites available",
"2024-04-23": "",
"2024-04-24": "",
"2024-04-25": ""
}
"sites_code": {
"2024-04-20": 8,
"2024-04-21": 8,
"2024-04-22": 8,
"2024-04-23": 0,
"2024-04-24": 0,
"2024-04-25": 0
}
"sites_extra_info": {
"2024-04-20": "3",
"2024-04-21": "3",
"2024-04-22": "3",
"2024-04-23": "",
"2024-04-24": "",
"2024-04-25": ""
}
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": "2024-04-20 14:00:00",
"period_to": "2024-04-27 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": "2024-04-20 14:00:00",
"period_to": "2024-04-27 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": [
{
"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",
"discount_id": "1",
"discount_name": "Membership Discount",
"discount_amount": 90.00
}
]
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.
You can provide return_all_membership_discount_pricing_options along with return_membership_discount_pricing. When both are provided as "true", an array will be returned of all membership discount options, including discounts configured with a discount code. This will adjust the membership_discount_pricing array to the following:
"membership_discount_pricing": [
{
"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",
"discounts": [
{
"discount_id": "1",
"discount_code": null,
"discount_name": "Membership Discount",
"discount_amount": 90.00
},
{
"discount_id": "2",
"discount_code": "promo",
"discount_name": "Membership Discount (20%)",
"discount_amount": 120.00
}
]
]
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
}
]
Allotment Notes:
Important: Allotments will only be considered during availability calculations if using daily_mode.
Guaranteed Allotments will reduce site availability in the response unless allotment data below is provided in the request.
You can provide any of the Allotment type IDs to allow the availability calculations to consider guaranteed allotments that you might be booking for. For example, if the Booking was going to be for a Company that has an Allotment setup, you can provide the company_id to include availability from that Allotment in the response.
Parameters you can provide that relate to Allotments:
- company_id - The Company a Guest might belong to
- travel_agent_id - The Travel Agent that might be requesting availability
- membership_id - The Membership Type ID that a Guest might have an active Membership for (see Guests: List request for more details)
- guests_memberships_id - The Guests Membership ID
- guest_id - If this is provided, any Company or Membership details linked to the Guest will be used for Allotment availability, without having to specify them directly.
Response Notes:
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_message provides you with the internal reasoning Newbook has used to determine availability - you can present this message to your Guests if you like
-
sites_code is a numeric representation of sites_message for you to use in constructing your own messages to your Guests it you prefer
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 - sites_extra_info is populated when there is a specific value in relation to sites_code above. It can be an integer, a date, a string, etc.
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_message provides you with the internal reasoning Newbook has used to determine why this tariff is not applicable - you can present this message to your Guests if you like
-
tariff_code is a numeric representation of tariff_message for you to use in constructing your own messages to your Guests it you prefer
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 - tariff_extra_info is populated when there is a specific value in relation to tariff_code above. It can be an integer, a date, a string, etc.
- online_cart_url is populated when the Tariff and Category are available for Booking. Following this link will open up a Booking Cart on Newbook Online. This first erases any cart data the guest may have assembled.
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:
- amount_already_included_in_tariff_total: when "true", the Inventory Item amount is already factored in the tariff_total, however when "false" the expectation is your software will add the amount into the total cost - and make the Guest aware of this addition
- discounts_apply: whether or not the Inventory Item amount has been discounted if the Booking has a discount associated. Some Inventory Items are just not eligable for this e.g. Security Bonds. This setup is up to the Instance.
adjustment_fees will be returned if they are associated with the Tariff or Category inside Newbook. An example of this response is:
"adjustment_fees": [
{
"type": "cancellation",
"inventory_item_id": "70",
"gl_category_id": "2",
"gl_account_id": "48",
"description": "Cancellation Fee",
"tax_free": "0",
"override_tax_rate_ids": [],
"start_billing_from": "2023-05-16",
"computed_amount": 30
}
]
Note: Providing guests_memberships_id or membership_id in the request will suppress adjustment fees that are restricted to other membership types. Providing neither will suppress adjustment fees that are restricted with membership types other than Non Member.
The above fields are:
- type (enum) - This will be either of the following:
- cancellation - This states that this type of adjustment fee is to be treated as a cancellation fee. This fee will be charged to the Guest if the date is after the start_billing_from date.
- modification - This states that this type of adjustment fee is to be treated as an Online Modification Fee. This fee will only be charged to Guests that modify their Booking on Newbook Online when the date is after the start_billing_from date.
- inventory_item_id (int or null) - This can either be null or an integer referencing the ID of an existing Inventory Item.
- gl_category_id (int or null) - This can either be null or an integer referencing the ID of an existing Sub Client Account. If this is null, it will instead match the Sub Client Account of the Booking.
- gl_account_id (int or null) - This can either be null or an integer referencing the ID of an existing GL Account. If this is null, it will instead match the GL Account of the Booking.
- description (string) - This is a short description of the adjustment fee.
- tax_free (boolean) - This states whether the adjustment fee is tax-free or not.
- override_tax_rate_ids (array) - This is an array of any tax ids if the adjustment fee has overridden taxes.
- start_billing_from (date) - This is the date that the adjustment fee is set to begin charging. Provided as yyyy-mm-dd.
- computed_amount (float) - This is the computed amount to charge for the adjustment fee if the cancellation date is on or after the start_billing_from.
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: Pull Availability & Pricing Example
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.
Request Notes:
You can provide children, infants and animals as numeric parameters (like the adults parameter).
Regarding specifying a Guest:
- If you have already used the guests_create request to create a new Guest, or the Guests: List request to find an existing Guest, you can simply provide guest_id and the other guests_create parameters will not be used or required.
- However if you are trying to match an existing Guest, guest_firstname, guest_lastname, address_street, address_city and address_postcode are all required, and only one of guest_email or guest_phone is required, but both are acceptable.
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.
Response Notes:
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 Availability Email Example
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.
Request Notes:
You can provide the category_id for this request to automatically allocate an available Site from that Category, or manually provide site_id either as a string value or an array of strings. Newbook will use only one Site on a resulting Booking, so providing an array is providing "options" - Newbook will validate them all and then use the first valid Site.
You can provide an array of required_features. This data will be used to find an applicable Site; all provided Features will need to match. If multiple matching Sites are found, Newbook will use the first one. If no matching Sites are found, the request will abort and you will receive a "No availability" response.
You can provide children, infants and animals as numeric parameters (like the adults parameter).
Regarding specifying a Guest:
- If you have already used the guests_create request to create a new Guest, or the Guests: List request to find an existing Guest, you can simply provide guest_id and the other guests_create parameters will not be used or required. A valid guests_memberships_id for this guest can optionally be provided for use with the booking.
- However if you are trying to match an existing Guest, guest_firstname, guest_lastname, address_street, address_city and address_postcode are all required, and only one of guest_email or guest_phone is required, but both are acceptable.
Regarding specifying Equipment:
- The equipment parameter is optional in creating a booking. However, if provided, it must be in array format, because a booking can have multiple equipment added to it as shown in the example request.
- The following are the parameters for creating equipment on a booking:
- equipment_name (required)
- equipment_make
- equipment_model
- equipment_type (must be a number)
- equipment_length (must be a number)
- equipment_width (must be a number)
- equipment_height (must be a number)
- equipment_registration
- equipment_registration_expiry
- The equipment are saved onto the Equipment table and linked to the booking and guest. Please note that if an equipment is being added for an existing guest, the guest_id parameter should be specified, instead of the guest_firstname and guest_lastname parameters. Also note that if the equipment_registration is not specified, a new equipment will be created for the guest.
Regarding specifying Repeat Charges:
- The repeat_charges parameter is optional. However, if provided, it must be an array of objects, each following the below format.
- The following are the parameters for creating repeat charges on a booking:
- type (string) required, must be one of:
- charges
- credits
- account_id (int or "new_id") required, must match a valid Client Account ID or be "new_id" when creating a new Booking to use the Booking Client Account.
- gl_account_id (int) required, must match a valid GL Account ID.
- gl_category_id (int) required, must match a valid GL Category ID.
- description (string) required.
- amount (float) required.
- inventory_item_id (int) optional, when provided it must match a valid Inventory Item ID.
- interval (string) required, must be one of:
- day
- week
- month
- year
- interval_multiplier (int) required. This is the multiplier for the above interval. E.g. When this is 2, and the interval above is "week", then charges will be raised every 2 weeks.
- period_from (string) must be formatted as YYYY-MM-DD.
- period_from_linked (boolean) when true, the Repeat Charge will match the Booking period_from (Arrival Date) even when it changes.
- period_to (string) must be formatted as YYYY-MM-DD.
- period_to_linked (boolean) when true, the Repeat Charge will match the Booking period_to (Departure Date) even when it changes.
- next_run (string) when the repeat charge will begin its billing, must be formatted as YYYY-MM-DD.
- tax_free (boolean)
- override_tax_rate_ids (array) array of valid Tax Rate IDs,
- benefit_guest (boolean)
- generate_invoice (boolean) when true, the Repeat Charge will automatically generate invoices.
- include_in_stay_cost (int) whether the Repeat Charge Inventory Item contributes to Booking Stay Cost - Accommodation Income - on all reports which present such a figure, must be one of:
- 0 means this Inventory Item is Excluded from Stay Cost, and will not factor as Stay Costs on the reports mentioned above. Use case: Booking Fees.
- 1 means Increase Stay Cost, i.e. this Inventory Item is part of the Stay Cost calculations but is costed on top of the nightly price. Use Case: optional Breakfast Package.
- travel_agent_commission (float) whether travel agent should earn commission from the attached Inventory Item.
- guest_visible (boolean) whether the attached Inventory Item should appear as its own line on Invoices/Receipts/Client Account Statements.
- prorata_start (string) the initial Charge will calculate as a Daily Amount to this date, then rollover normally, must be formatted as YYYY-MM-DD.
- prorata_end (boolean) the final Charge will calculate as a Daily Amount if the final charge does not cover an entire period.
- status (int) must be one of:
- 1 = Active
- 2 = Stopped
- 0 = Cancelled
- disburse_to_owners (boolean) whether money received should be forwarded to Trust Owners during Disbursement.
- invoice_description (string) if not provided, defaults to use the Description and Charge Dates.
- generate_daily_charges (boolean) generates charges day-by-day instead of in bulk for the entire duration. When true this will force enable Automatically Generate Invoice.
- invoice_system_template_id (int) optional, the system template to use for invoices, must match a valid System Template ID.
- invoice_email_template_id (int) optional, the contact template to use for automatic invoice emails, defaults to null meaning do not send automatically. Must match a valid Contact Template ID.
- booking_market_segment_id (int) optional, the booking market segment to assign to the repeat charge, defaults to null. Must match a valid Booking Market Segment ID
- type (string) required, must be one of:
The following parameters are optional and save onto the Guest:
- address_street
- address_city
- address_postcode
- address_state_name
- address_country_name
- guest_phone
- guest_email
- membership_number
- membership_program
- membership_expiry
- dietary_requirements
If specified, dietary_requirements can be provided based on the response to Dietary Requirements request.
The following parameters are optional and save onto the Booking:
- tariffs_quoted
- repeat_charges
- inventory_items
- status
- reason_id
- source_id
- method_id
- demographic_id
- company_id
- company_staff_id
- travel_agent_id
- travel_agent_staff_id
- discount_id
- eta
- notes
- flagged
- locked
- booking_group_id
- create_charges
- market_segment_id
- booked_by
- booked_when
- arrived_by
- arrived_when
- departed_by
- departed_when
- cancelled_by
- cancelled_when
- booking_id
- additional_guests
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}] - tariff_applied_id is optional in each object
Note: Bookings can have neither of tariffs_quoted or repeat_charges, and therefore be set up with No Billing, but they cannot have both of tariffs_quoted and repeat_charges - please provide 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 }] - inventory_item_id is required in each array, but everything else is optional
If specified, status must be one of the following (this ordering has no meaning):
- Arrived
- Cancelled
- Confirmed
- Departed
- No Guest Data (Incomplete)
- No-Show
- Owner Occupied
- Quote
- Unconfirmed
- Waitlist
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 providing 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.
If specified, custom_fields must be based on the response to the Custom Fields request, to retrieve the different Custom Fields set up in the instance:
"custom_fields": [
{
"field_id": 2,
"field_value": 8
}
]
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.
If specified, suppress_generate_billing must be "true" or "false". This parameter will tell Newbook whether to ignore its default handling in terms of generating Booking billing.
If specified, override_min_stay must be "true" or "false". This parameter will tell Newbook whether to allow a Booking to be placed even if the Minimum Stay Duration is not satisfied.
If specified, additional_guests must follow this format:
-
[{ "guest_id": sourced from Newbook, "guest_type": adults, children, infants "guest_type_id": number }] - guest_id is required in each array object.
- guest_type can either be: adults, children, or infants. By default, this is adults.
- guest_type_id is the ordered number of the occupant. For example, if the booking occupies 2 adults, the ID of the additional guest is 2 (The primary guest is the first adult). If the booking occupies 2 children, the ID of the first child is 1 and the second child is 2.
- Take note that additional guests are limited to the number of occupants set on this request.
You may provide remote_import as "true" to tell Newbook to simplify the Booking View page inside the PMS (for users). This simplified version of the page will respect items present on the Client Account to denote the total value of the Booking, rather than the normal breakdown of individual billing items/discounts/money received & outstanding. When a user edits such a Booking inside the PMS, they will be prompted to convert the Booking to Newbook financial calculations, or abort the editing process.
Response Notes:
The successful response is the same as the Bookings: Get response, with the addition of guest_id and invoice_ids.
Bookings: Create Example
Bookings: Update
Update an existing Booking.
Request Notes:
booking_id is required
All other parameters are optional, please see Bookings: Create for more details.
If specified, repeat_charges can update existing repeat charges by including the repeat_charge_id property. When repeat_charge_id is ommitted, a new Repeat Charge will be created.
[{
"repeat_charge_id": sourced from Newbook
fields to update...
}]
Bookings: Update Example
Bookings: Update Market Segment
Bulk update existing Bookings with a new Market Segment
Request Notes:
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 Market Segment Example
Bookings: Update Booking Source
Bulk update existing Bookings with a new Booking Source.
Request Notes:
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.
Bookings: Update Source Example
Booking Sources: List
Pull the list of Booking Sources from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Booking Sources
show_inactive is optional, default false, and when provided it will include inactive Booking Sources in the response
Booking Sources: List Example
Booking Sources: Create
Create a new Booking Source within Newbook.
Request Notes:
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 Sources: Create Example
Booking Cancellation Reasons: List
Pull the list of Booking Cancellation Reasons from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Booking Cancellation Reasons
show_inactive is optional, default false, and when provided it will include inactive Booking Cancellation Reasons in the response
Booking Cancellation Reasons: List Example
Booking Methods: List
Pull the list of Booking Methods from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Booking Methods
Booking Methods: List Example
Booking Reasons: List
Pull the list of Booking Reasons from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Booking Reasons
Booking Reasons: List Example
Booking Demographics: List
Pull the list of Booking Demographics from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Booking Demographics
Booking Demographics: List Example
Booking Market Segments: List
Pull the list of Booking Market Segments from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Booking Market Segments
Booking Market Segments: List Example
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.
Request Notes:
Regarding specifying a Guest:
- If you have already used the guests_create request to create a new Guest, or the Guests: List request to find an existing Guest, you can simply provide guest_id and the other guests_create parameters will not be used or required.
- However if you are trying to match an existing Guest, guest_firstname, guest_lastname, address_street, address_city and address_postcode are all required, and only one of guest_email or guest_phone is required, but both are acceptable.
The following parameters are optional and save onto the Guest:
- address_street
- address_city
- address_postcode
- address_state_name
- address_country_name
- guest_phone
- guest_email
- membership_number
- membership_program
- membership_expiry
- dietary_requirements
If specified, dietary_requirements can be provided based on the response to Dietary Requirements request.
The following parameters are optional and save onto the Booking Group:
- inventory_items
- status
- notes
- eta
- reason_id
- source_id
- method_id
- demographic_id
- company_id
- company_staff_id
- travel_agent_id
- travel_agent_staff_id
- discount_id
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 }] - inventory_item_id is required in each array, but everything else is optional
If specified, status must be one of the following (this ordering has no meaning):
- Arrived
- Cancelled
- Confirmed
- Departed
- No Guest Data (Incomplete)
- No-Show
- Owner Occupied
- Quote
- Unconfirmed
- Waitlist
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.
Response Notes:
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).
Bookings Groups: Create Example
Bookings Groups: Update
Updates an existing Bookings Group.
Request Notes:
booking_group_id is required
All other parameters are optional, please see Bookings Groups: Create for more details.
Bookings Groups: Update Example
Bookings Groups: List
Retrieve a list of Group Bookings within the given time period.
Request Notes:
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 Group 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 before the specified period_to date, including Group Bookings before this date which are not yet Arrived - period_from will be ignored in this case. To limit results to those within the specified dates, please use list_type of arrived and the mode parameter of projected (see above) |
| 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 |
| staying1 | 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 |
| all |
returns all Group Bookings, this will be a Paginated List. |
- 1 ignores Group Bookings of status Cancelled, No Show, Quote, and Owner Occupied
- 2 shows only Group Bookings of status Confirmed and Unconfirmed
- 3 shows only Group Bookings of status Arrived
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 Group 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 Group Booking data in the return response will still be present but the Guests array will be empty.
search is optional and when provided it will restrict the results to the matching Guest associated with the Group. It will search their name, contact details (phone, email, etc) and membership details for a match
display_guest_activities can optionally be provided as true to include the Guests Activity Tickets in the Guest response. display_cancelled_guest_activities can also be provided to include Cancelled Activity Tickets. Please see the Guests: Get request for an example of the Guest Activity response data.
display_guest_facility_hires can optionally be provided as true to include the Guests Facility Hires in the Guest response. display_cancelled_guest_facility_hires can also be provided to include Cancelled Facility Hires. Please see the Guests: Get request for an example of the Guest Facility Hire response data.
display_cancelled_group_activities can optionally be provided as true to include Cancelled Activity Tickets for the Group.
display_cancelled_group_facility_hires can optionally be provided as true to include Cancelled Facility Hire for the Group.
Response Notes:
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 Groups: 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
Inventory Item data:
The inventory_item array holds all the Inventory Item objects on the Booking.
- stay_cost_contribution indicates whether the amount Increases the stay cost revenue, or if it is Excluded from the stay cost revenue
Guest data
title can be any string; Newbook does not restrict users to specific titles for Guests
contact_details
- allow_transactional: Guest allows general contact related to Bookings or accounts
- allow_marketing: Guest allows marketing contact such as newsletters
Bookings Groups: List Example
Bookings Groups: Get
Retrieve the details of a single Group Booking.
Request Notes:
id must be provided to retrieve the Group Booking.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category).
client_account_tax_reconciliation can optionally be provided as true to include the amount of tax based on the reconciliation of payments / refunds. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_item_breakdown can optionally be provided as true to include all accounting items saved on the Group Client Account in the Group response.
e.g.
{
"charges": [
{
"id": "3062",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Standard Rate (2024-04-19)",
"amount": 100,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "tariffs_quoted",
"link_type_id": "123",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": 9.09
}
]
}
],
"credits": [
{
"id": "4351",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Discount",
"amount": 5,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "discounts_quoted",
"link_type_id": "1024",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": 0.45
}
]
}
],
"payments": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"paid_by": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Accommodation",
"amount": 100,
"tendered": 100,
"type": "cash",
"type_id": "5",
"type_reference": "",
"deposit": "0",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [],
"charges": [
{
"link_id": 1,
"charge_id": 3062,
"reconciled_amount": 100,
"timestamp": "2024-04-19",
"voided_when": null
}
]
}
],
"refunds": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"refunded_to": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Refunding Discount Overpayment",
"amount": 5,
"tendered": 5,
"type": "cash",
"type_id": "5",
"type_reference": "",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [
{
"link_id": 1,
"credit_id": 4351,
"reconciled_amount": 5,
"timestamp": "2024-04-19",
"voided_when": null
}
],
"payments": []
}
]
}
Example Booking Detail Attributes on charges, credits, payments, refunds when client_account_booking_details is true.
e.g.
{
"guest_visible": "1",
"discounts_apply": "1",
"booking_id": "1234",
"booking_name": "John Doe",
"booking_status": "Confirmed",
"booking_site_id": "2",
"booking_period_from": "2024-04-19 11:30:00",
"booking_period_to": "2024-04-20 14:00:00",
"booking_reference_id": "",
"activity_booked_id": null
}
display_guest_activities can optionally be provided as true to include the Guests Activity Tickets in the Guest response. display_cancelled_guest_activities can also be provided to include Cancelled Activity Tickets. Please see the Guests: Get request for an example of the Guest Activity response data.
display_guest_facility_hires can optionally be provided as true to include the Guests Facility Hires in the Guest response. display_cancelled_guest_facility_hires can also be provided to include Cancelled Facility Hires. Please see the Guests: Get request for an example of the Guest Facility Hire response data.
display_cancelled_group_activities can optionally be provided as true to include Cancelled Activity Tickets for the Group.
display_cancelled_group_facility_hires can optionally be provided as true to include Cancelled Facility Hire for the Group.
Response Notes:
The returned data from this request is identical to Bookings Groups: List but for the specific Group alone.
If no such Group ID exists, the success response parameter will be "false" and no data will be returned.
Bookings Groups: Get Example
Bookings Rule Templates: List
List Bookings Rule Templates.
Request Notes:
name (string) optional, filters results by name.
show_inactive (boolean) optional, when provided with a truthy value it will include inactive Bookings Rule Templates in the response.
Response Notes:
An array of objects will be returned. Each object will contain the following parameters.
- name (string) name of the Bookings Rule Template.
- type (string) type of Bookings Rule Template.
- inventory_items
- deposit_rules
- adjustment_fees
- active (boolean) determines if the Bookings Rule Template is visible.
- associated_tariffs (array) an array of associated Rates objects with the following format:
- id (integer) associated rate ID.
- tariff_name (string) associated rate name.
If type is set to inventory_items:
- inventory_items (array) an array of Inventory Item objects. See the Create request for more information on the parameters contained within each object.
If type is set to deposit_rules:
- deposit_rules (array) an array of Deposit Rule objects. See the Create request for more information on the parameters contained within each object.
If type is set to adjustment_fees:
- adjustment_fees (array) an array of Adjustment Fee objects. See the Create request for more information on the parameters contained within each object.
Bookings Rule Templates: List Example
Bookings Rule Templates: Get
Retrieve a single Bookings Rule Template.
Request Notes:
- id (integer) required, an existing Bookings Rule Template.
Response Notes:
See the List description for details on the object parameters that will be returned.
Bookings Rule Templates: Get Example
Bookings Rule Templates: Create
Creates a new Bookings Rule Template.
Request Notes:
The following parameters are required.
- name (string) name of the Bookings Rule Template
- type (integer) type of Bookings Rule Template. Options may include:
- inventory_items
- deposit_rules
- adjustment_fees
Please see below for a list of optional details that can be provided.
- active (boolean) determines if the Bookings Rule Template is visible.
If type is set to inventory_items:
- inventory_items (array) an array of Inventory Item objects with the following format:
- id (integer) an existing Inventory Item ID.
If type is set to deposit_rules:
- deposit_rules (array) an array of Deposit Rule objects with the following format:
- deposit_due (integer|date) an integer representing the number of days or a specific date depending on the deposit_due_type.
- deposit_due_type (string) when the deposit is due. Options may include:
- days_before (default)
- days_after
- specific_date
- booked_days_in_advance (integer) how many days in advance the Booking must be placed.
- deposit_type (string) how the deposit is calculated. Options may include:
- percentage (default)
- percentage_inc_prev_deposits
- nights
- nights_average
- fixed
- fixed_per_night
- fixed_per_adult
- fixed_per_child
- fixed_per_person
- fixed_per_adult_per_night
- fixed_per_child_per_night
- fixed_per_person_per_night
- deposit_amount (float) deposit amount required.
- minimum (float) the minimum total deposit amount allowed.
- maximum (float) the maximum total deposit amount allowed (0 = Unlimited). Defaults to 0 / Unlimited.
- allow_offline (boolean) determines if the rule is available for offline Bookings.
- allow_online (boolean) determines if the rule is available for online Bookings.
If type is set to adjustment_fees:
- adjustment_fees (array) an array of Adjustment Fee objects with the following format:
- type (string) the type of Adjustment Fee. Options may include:
- cancellation_fee
- online_modification_fee
- id (integer) an existing Inventory Item ID.
- description (string) description of the Adjustment Fee.
- gl_category_id (integer) an existing GL Category ID.
- gl_account_id (integer) an existing GL Account ID.
- fee_applies_days (integer) the number of days to restrict the Adjustment Fee based on the fee_applies_method.
- fee_applies_method (string) the calculation method for the Adjustment Fee. Options may include:
- before_booking_arrival (default)
- after_booking_placed
- amount_type (string) the calculation method for the Adjustment Fee amount. Options may include:
- fixed (default)
- amount (float) the amount of the Adjustment Fee.
- gst_free (boolean) determines if the Adjustment Fee is GST free.
- type (string) the type of Adjustment Fee. Options may include:
Bookings Rule Templates: Create Example
Bookings Rule Templates: Update
Updates an existing Bookings Rule Template.
Request Notes:
- id (integer) required, an existing Bookings Rule Template.
If type is set to inventory_items:
- inventory_items (array) optional, in addition to the parameters outlined in the Create request, the following options are also available:
- id (integer) an existing Inventory Item ID to update.
- remove (boolean) optional, deactivates the existing Inventory Item when set to true.
If type is set to deposit_rules:
- deposit_rules (array) optional, in addition to the parameters outlined in the Create request, the following options are also available:
- id (integer) an existing Deposit Rule ID to update.
- remove (boolean) optional, deactivates the existing Deposit Rule when set to true.
If type is set to adjustment_fees:
- adjustment_fees (array) optional, in addition to the parameters outlined in the Create request, the following options are also available:
- id (integer) an existing Adjustment Fee ID to update.
- remove (boolean) optional, deactivates the existing Adjustment Fee when set to true.
Additional parameters are defined in Bookings Rule Templates: Create.
Bookings Rule Templates: Update Example
Rates: List
Retrieve a list of configured Rates based on the provided parameters.
Request Notes:
All available fields for this request are optional
id (array of ints) optional - This is an array of Rate IDs to restrict the response to.
has_inventory_items (boolean) optional - This will restrict the response to Rates with / without Inventory Items. Not providing this field will show all Rates regardless of their Inventory Items.
master_rate_id (string | array of ints) optional - This is an array of Master Rate IDs to filter the Rates to those configured to have the provided Master Rate associated with the Rate. This also supports providing the following values:
- master - This will include Rates configured as a Master Rate
- standalone - This will include Rates configured as a Standalone Rate
applied_after (date - yyyy-mm-dd) optional - This is a date to show all Rates that have applications after this particular date. The Rates shown are inclusive of this particular date.
applied_before (date - yyyy-mm-dd) optional - This is a date to show all Rates that have applications before this particular date. The Rates shown are inclusive of this particular date.
category_id (array of ints) optional - This is an array containing Category IDs to restrict the response to only Rates applied to any of these particular Categories.
rate_type_id (array of ints) optional - This is an array containing Rate Type IDs to restrict the response to only Rates applied to those particular Rate Types
per_person (boolean) optional - This will restrict the response to Rates that either are or are not a per-person rate. Omitting this field will result in all Rates showing regardless of whether they are a per-person rate.
allow_site_selection (boolean) optional - This will restrict the response to Rates that have / don't have site selection enabled on Newbook Online. This field can also be omitted to not restrict the filtering
show_inactive (boolean) optional, default false - If false, or not specified, inactive Rates are not included.
Rates: List Example
Rates: Get
Request Notes:
id (int) required
show_inactive (boolean) optional, default true - If false and the id belongs to an inactive Rate, a validation error is returned.
Rates: Get Example
Rates: Create
Request Notes:
using_master (string - enum) required - It can be any of the following options:
- standalone - This is for creating a standalone rate
- master - This option specifies that the rate is a master rate
- dependant - This options specifies that the rate is a dependant rate
master_id (int) required if using_master = dependant, otherwise this cannot be provided - When provided, this will need to be an ID of an existing Rate configured as a Master Rate.
name (string) required - It is the name of the rate you are creating and has a maximum length of 200 characters
dynamic (string - enum) required - This will need to be one of the following options:
- none - This option specifies that the rate does not have dynamic pricing.
- online - This option states that the rate has dynamic pricing on Newbook Online, or any connected 3rd Party Channels
- interface - This options states that the rate has dynamic pricing inside the Newbook interface only
- all - This states that the rate has dynamic pricing online as well as inside the interface
dynamic_min (float) optional, default: 0.00 - Lower bound for dynamic pricing. Rates will never be lower than this.
dynamic_max (float) optional, default: 0.00 - Upper bound for dynamic pricing. Rates will never be higher than this.
dynamic_base (float | null) optional, default: null - Used to calculate revenue lost or earned on the Dynamic Pricing Report by comparing this Rates Dynamic Base against its Dynamic Minimum/Maximum.
dynamic_method (enum - string) optional, default: "linear" - What formula to use to calculate the rate
- linear - Prices are interpolated linearly between dynamic_min and dynamic_max. This is recommended for Off-Peak Rates.
- exponential - Prices increase exponentially from dynamic_min to dynamic_max. This is recommended for Peak Rates.
dynamic_occupancy (enum - string) optional, default: "category" - Which Occupancy Percentage should be used to work out the Dynamic Pricing formula.
- category - Use the percentage of the category occupied.
- category_type - Use the percentage of the category type occupied.
- instance - Use the percentage of the property occupied.
dynamic_occupancy_min (float) optional, default: 0.00 - The level of occupancy as a percentage from 0.00 to 100.00 at which dynamic pricing will start to increase prices from dynamic_min. If the occupancy level is below this percentage, dynamic_min will be used.
base_day_based (int - enum) required - This controls the format of the pricing on the rate and needs to be one of the following options:
- 0 - Repeat for Listed Nights
- 1 - Repeat for Days of Week
- 2 - Use Last Listed Night
- 3 - Use Matching Occupancy Level
- 4 - Use Guest Equipment (This is only available for Marina instances that have Equipment enabled)
- 5 - No Billing
base_day_based_occupancy (string - enum) required if base_day_based = 3 - This can be one of the following options:
- category - This states that the occupancy level is determined based on the associated Category
- category_type - This states that the occupancy level is determined based on the overall Category Type
- instance - This states that the occupancy level is determined based on the entire Instance
additionals_day_based (string - enum) required - This controls the format of the additional occupant pricing on the rate and needs to be one of the following options:
- 0 - Use Last Listed Price
- 1 - Repeat for Days of Week
- 2 - Use Last Listed Night
- 3 - Repeat for Listed Nights
active (boolean) optional, default: true - This states whether the rate is active. This will default to true if not provided.
extras_combined (boolean) optional, default: false - This states whether your rate is configured to charge based on combined occupants or individual occupants.
- true - base_combined can be used
- false default - the base_adult, base_child, base_infant, base_animal fields can be used
base_adult (int) required if extras_combined = false - This is the number of adults included in the base pricing on the rate.
base_child (int) optional, default: 0 - This is the number of children included in the base pricing on the rate.
base_infant (int) optional, default: 0 - This is the number of infants included in the base pricing on the rate.
base_animal (int) optional, default: 0 - This is the number of animals included in the base pricing on the rate.
base_combined (int) required if extras_combined = true - This is the number of combined occupants included in the base pricing on the rate.
per_person (boolean) required - This controls whether the rate allows standard base pricing, or only specific pricing per occupant.
minimum_charge_per_period (float) optional, default: 0.00 - This specifies the minimum amount the rate will charge per night.
base_min_combined (int) optional, default: 0 - This controls the minimum number of guests required to book the rate. This will default to 0, which means it won't limit bookings based on occupants.
base_max_combined (int) optional, default: 0 - This controls the maximum number of guests required to book the rate. This will default to 0, which means it won't limit bookings based on occupants. This must be equal or greater than base_min_combined if both are not 0
min_days_in_advance (int) optional, default: 0 - This controls the minimum number of days in advance a booking needs to be made to use this rate. 0 means there is no restriction in place.
max_days_in_advance (int) optional, default: 0 - This controls the maximum number of days in advance a booking needs to be made to use this rate. 0 means there is no restriction in place. This must be equal or greater than min_days_in_advance if both are not 0
minimum_periods (int) optional, default: 1 - This controls the minimum number of nights a booking has to stay to be valid for the rate.
maximum_periods (int) optional, default: 0 - This controls the maximum number of nights a booking can stay to be valid for the rate. 0 means there is no limit. This must be equal or greater than minimum_periods if it's not 0
invoice_control (boolean) optional, default: false - This controls whether Bookings on this rate should automatically raise Invoices for Quoted Tariffs for each period specified in the below controls.
- true - automatically raise Invoices for the Quoted Tariffs for each period specified
- false - invoice and invoice_control
invoice_interval_multiplier (int) available if invoice_control = true, default: 0. This along with the invoice_interval controls how many days / weeks are invoiced at a time.
invoice_interval (string - enum) available if invoice_control = true, default: "day". This along with invoice_interval_multiplier controls the number of days / weeks to group the invoices into. This can be one of the following options:
- day
- week
- month
- year
system_template_invoices (int | null) optional, default: null. This references an invoice system template ID which is used when invoices are raised through the invoice_control setting. null which will result in the Category default being used.
system_template_receipts (int | null) optional, default: null. This references a receipt system template ID which is used when receipts are generated for bookings on this rate. This is only available when invoice_control is true. null will result in the Category default being used.
base_max_adults (int | null) optional, default: null - This specifies the maximum number of adults allowed on a booking to be able to book this rate. null means that there is no limit.
base_max_children (int | null) optional, default: null - This specifies the maximum number of children allowed on a booking to be able to book this rate. null means that there is no limit.
base_max_infants (int | null) optional, default: null - This specifies the maximum number of infants allowed on a booking to be able to book this rate. null means that there is no limit.
base_max_animals (int | null) optional, default: null - This specifies the maximum number of animals allowed on a booking to be able to book this rate. null means that there is no limit.
stop_sell_occupancy_percentage (int) optional, default: 0 - This which states at what occupancy percentage this rate should be stop-sold. 0 will disable this setting.
stop_sell_occupancy_calculation (string - enum) optional, default: "category" - This relates to the stop_sell_occupancy_percentage option and controls what the occupancy calculation is based on. This can be one of the following:
- category
- category_type
- instance
reset_night_counter (boolean) optional, default: true. This determines whether the night counter resets when switching rate periods.
pre_auth_amount (float) optional, default: 0.00. This specifies the dollar amount / percentage to pre-auth for a booking at checkin. This pairs with the pre_auth_type to determine how the amount is determined.
pre_auth_type (string - enum) available if pre_auth_amount is provided, default: "percentage" - This determines how the amount entered in pre_auth_amount is used. This can be one of the following options:
- percentage - Percentage of Total
- nights - Number of Nights
- nights_average - Number of Nights (Average)
- fixed - Fixed Amount
- fixed_per_night - Fixed Amount per Night
- fixed_per_adult - Fixed Amount per Adult
- fixed_per_child - Fixed Amount per Child
- fixed_per_person - Fixed Amount per Person
special_deal (int - enum) optional - This controls how the rate appears on Newbook Online. This can be one of the following options:
- 0 - No (Default)
- 1 - Hot
- 2 - Special
- 3 - Save
- 4 - Promotion
first_deposit_required (boolean) optional, default: true - This controls whether the booking requires a deposit payment upfront when booking on Newbook Online.
allow_cancellations (int | null) optional, default: null - This controls how many days before arrival a booking can be cancelled on Newbook Online. null means that cancellations are disabled on Newbook Online for this rate.
allow_modifications (int | null) optional, default: null - This controls how many days before arrival a booking can be modified on Newbook Online. null means that modifications are disabled on Newbook Online for this rate.
site_selection_allowed (boolean) optional, default: false - This controls whether bookings on this rate can choose their site on Newbook Online.
site_selection_inventory_item_id (int | null) optional, default: null - This references the ID of an existing Inventory Item in the system. This inventory item is used for the billing of any site selection fees.
site_selection_fee (float) optional, default: 0.00 - This specifies the charge amount for the site selection fee. This pairs with the site_selection_fee_type to determine how the fee is charged.
site_selection_fee_type (string - enum) available if site_selection_fee is provided, default: "per_night" - This controls how the site_selection_fee is charged. This can be one of the following options:
- per_night - Per Night
- per_booking - Per Booking
inclusions (string - html) optional, default: "" - This is some text description to specify what is included in the rate. This is shown on Newbook Online. This supports basic html to help format the display.
period_amounts (array of objects) required if base_day_based is not 5 - This will need to be provided as an array with the format provided below. The format changes based on base_day_based. This changes in the following ways
- if base_day_based = 0 (Repeat for Listed Nights) then the period_amounts provided are handled as the first record is for the first night, the second record is for the second night, etc. The last record is used for all subsequent nights.
- if base_day_based = 1 (Repeat for Days of Week) then exactly 7 period_amounts need to be provided. One being for each day of the week ordered from Monday to Sunday.
- if base_day_based = 2 (Use Last Listed Night) then this behaves the same as 0 (Repeat for Listed Nights).
- if base_day_based = 3 (Use Matching Occupancy Level) then each entry in period_amounts is based on the occupancy percentages. This requires full coverage from 0 - 100% over all the entries.
- if base_day_based = 4 (Use Guest Equipment) then each entry in period_amounts is based on the equipment length dimensions. You will also need to include equipment_length_calculation in each entry in period_amounts.
- if base_day_based = 5 (No Billing) then the period_amounts field cannot be used.
"period_amounts": [
{
"id": 1,
"amount": 150.00,
"dynamic_min": 100.00,
"dynamic_max": 220.00,
"minimum_periods": 1,
"charge_additionals": 1,
"remove": 0
},
{
"id": 2,
"amount": 130.00,
"dynamic_min": 100.00,
"dynamic_max": 220.00,
"minimum_periods": 1,
"charge_additionals": 1,
"remove": 0
}
]
- id (int) required if editing a rate.
- amount (float) required - This specifies the particular amount
- dynamic_min (float | null) available if base_day_based = 1 or 3, default: null.
- If base_day_based = 1 (Repeat for Days of Week) then this field holds the minimum amount
- If base_day_based = 3 (Use Matching Occupancy Level) then this field will behave as the minimum occupancy percentage which is inclusive.
- dynamic_max (float | null) available if base_day_based = 1 or 3, default: null - must be equal or greater than dynamic_min if both are not null.
- If base_day_based = 1 (Repeat for Days of Week) then this field holds the maximum amount
- If base_day_based = 3 (Use Matching Occupancy Level) then this field will behave as the maximum occupancy percentage which is inclusive.
- equipment_length_calculation (int - enum) required if base_day_based = 4. This field must match one of the following:
- 0 - Fixed Price
- 1 - Multiplier per unit of measure that the instance has configured
- minimum_periods (int) required if base_day_based is not 4 - This specifies the minimum stay duration required to be eligible for this particular pricing.
- charge_additionals (boolean) required if base_day_based is not 4 - This determines whether this particular pricing will charge additionals.
- remove (boolean) optional, default: false. If true will remove the associated period amount
additionals required - This will need to be provided as an array with the format provided below. The format changes based on additionals_day_based. This changes in the following ways
- If additionals_day_based = 0 (Use Last Listed Price) then the additionals provided are handled as the first record is for the first additional occupant, the second record is for the second additional occupant, etc. The last record is used for all subsequent additional occupants.
- If additionals_day_based = 1 (Repeat for Days of Week) then exactly 7 additionals need to be provided. One being for each day of the week ordered from Monday to Sunday.
- If additionals_day_based = 2 (Use Last Listed Night) then the additionals provided are handled as the first record is for the first night, the second record is for the second night, etc. The last record is used for all subsequent nights.
- If additionals_day_based = 3 (Repeat for Listed Nights) then this behaves the same as 2 (Use Last Listed Night).
"additionals": [
{
"id": 1,
"adult_amount": 30.00,
"child_amount": 20.00,
"infant_amount": 10.00,
"animal_amount": 5.00,
"remove": 0
},
{
"id": 2,
"adult_amount": 25.00,
"child_amount": 15.00,
"infant_amount": 5.00,
"animal_amount": 0.00,
"remove": 0
}
]
- id (int) required if editing a rate.
- adult_amount (float) required - This specifies the amount charged for additional adults.
- child_amount (float) required - This specifies the amount charged for additional children.
- infant_amount (float) required - This specifies the amount charged for additional infants.
- animal_amount (float) required - This specifies the amount charged for additional animals.
- remove (boolean) optional, default: 0 - If true will remove the associated additional occupant amount
load_from_master (object) available if using_master = 'dependant'. This is an object that maps each field to a boolean of whether they are loaded from the master rate or not.
"load_from_master": {
"base_adult":true,
"base_child":true,
"base_infant":true,
"base_animal":true,
"base_combined":true,
"extras_combined":true,
"minimum_charge_per_period":true,
"base_min_combined":true,
"base_max_adults":true,
"base_max_combined":true,
"base_max_children":true,
"base_max_infants":true,
"base_max_animals":true,
"min_days_in_advance":true,
"stop_sell_occupancy_percentage":true,
"max_days_in_advance":true,
"stop_sell_occupancy_calculation":true,
"minimum_periods":true,
"reset_night_counter":true,
"maximum_periods":true,
"pre_auth_amount":true,
"pre_auth_type":true,
"invoice_control":true,
"invoice_interval_multiplier":true,
"invoice_interval":true,
"system_template_invoices":true,
"system_template_receipts":true,
"special_deal":true,
"first_deposit_required":true,
"allow_cancellations":true,
"allow_modifications":true,
"site_selection_allowed":false,
"site_selection_inventory_item_id":false,
"site_selection_fee":false,
"site_selection_fee_type":false,
"inclusions":false
}
discounts - This is an array of rate discounts
"discounts": [
{
"id": 1,
"applies_after": 3,
"applies_every": 1,
"applies_retroactively": false,
"base_type": "Percentage Total",
"base_amount": 20.00,
"additional_type": "Percentage Total",
"additional_amount": 20.00,
"cm_code": "",
"remove": 0
}
]
- id (int) required if editing a rate.
- applies_after (int) required if creating a discount - This specifies the number of nights (inclusive) a booking must stay before it receives the discount.
- applies_every (int) required if creating a discount - This specifies how often the discount is given. E.g. every 3 nights.
- applies_retroactively (boolean) required if creating a discount - This specifies whether a once the booking is eligible for a discount, will it apply retroactively or not.
- base_type (string - enum) required - This can be one of the following options:
- Percentage Total - Percentage off of total Base
- Dollars Total - Dollars off total Base
- base_amount (float) optional, default: 0.00 - for the amount of the discount. This will either be a dollar figure or a percentage based on base_type.
- additional_type (string - enum) required - This can be one of the following options:
- Percentage Each - Percentage off per Additional
- Dollars Each - Dollars off per Additional
- Percentage Total - Percentage off of total Additionals
- Dollars Total - Dollars off total Additionals
- additional_amount (float) optional, default: 0.00 - This is the amount of the discount for additional occupants. This will be either a dollar figure or a percentage based on additional_type. base_amount + additional_amount must be greater than 0
- cm_code (string) optional, default: "" - Specifies the channel manager code this discount will be provided to channels using. This is only supported on select third party channels.
- remove (boolean) optional, default: false - If true will remove the associated discount from the rate.
inventory_item_template_id (int | null) optional, default: null - If it's an int it's the ID of an existing Booking Rule Template, otherwise inventory_items will be used
inventory_items (array of objects) available if inventory_item_template_id != null - This will need to be provided as an array of the inventory item details as shown below:
"inventory_items": [
{
"id": 1,
"inventory_item_id": "100",
"description": "Breakfast",
"gl_category_id": 1,
"gl_account_id": 20,
"display_task_list": [
-6
],
"guest_visible": true,
"travel_agent_commission": false,
"include_in_stay_cost": 1,
"include_in_deposit": 1,
"include_in_payment_plan": true,
"discounts_apply": true,
"refundable": true,
"disburse_to_owners": false,
"item_type": "charges",
"qty": 1,
"amount": 20.00,
"per_adult": 0,
"per_child": 0,
"per_infant": 0,
"per_animal": 0,
"calculation_type": "fixed",
"tax_free": false,
"daytype": "once",
"ignore_other_tariffs": 0,
"remove": false
},
]
- id (int) required if editing an inventory item
- inventory_item_id (int | null) optional, default: null - ID of an existing Inventory Item. Providing this will use the Inventory Item details to fill the other fields.
- description (string) required - This is the description of the Inventory Item. This can be a maximum of 250 characters.
- gl_category_id (int | null) optional, default: null - ID of an existing Sub Client Account or null to use the Category default.
- gl_account_id (int | null) optional, default: null - ID of an existing GL Account or null to use the Category default.
- display_task_list (array of ints) optional, default: [] - IDs of Task Types for the Task Lists you want to show this Inventory Item on.
- guest_visible (boolean) optional, default: true - This for whether the Inventory Item is visible to the Guest or not.
- travel_agent_commission (boolean) optional, default: true - This for whether the Inventory Item is commissionable.
- include_in_stay_cost (int - enum) optional, default: 1 - This controls how the Inventory Item is contributed to the stay cost total. This can be one of the following options
- 0 - Exclude
- 1 - Increase
- 2 - Include
- include_in_deposit (int - enum) optional, default: 0 - This controls how the Inventory Item amount contributes to the deposit. This can be one of the following:
- 0 - Exclude
- 1 - As per Deposit Rule
- 2 - Final Deposit
- 3 - Initial Deposit
- include_in_payment_plan (boolean) optional, default: true - This determines whether the Inventory Item amount will be split up into the payment plan installments or if the full amount will be taken upfront.
- discounts_apply (boolean) optional, default: true - This controls whether discounts apply to this Inventory Item amount.
- refundable (boolean) optional, default: true - This controls whether the charges raised from this Inventory Item are voided when the Booking is cancelled.
- disburse_to_owners (boolean) optional, default: false - This controls whether the Inventory Item amount is disburable to owners.
- item_type (string - enum) optional, default: "charges" - This field determines whether the Inventory Item will raise Charges or Credits. This can be either of the following
- charges - Charges
- credits - Credits
- qty (float) optional, default: 1.00 - This controls the quantity of these Inventory Items to add to the Rate.
- amount (float) optional, default: 0.00 - This specifies the base amount of the Inventory Item.
- per_adult (float) optional, default: 0.00 - This specifies the amount per adult to charge for the Inventory Item.
- per_child (float) optional, default: 0.00 - This specifies the amount per child to charge for the Inventory Item.
- per_infant (float) optional, default: 0.00 - This specifies the amount per infant to charge for the Inventory Item.
- per_animal (float) optional, default: 0.00 - This specifies the amount per animal to charge for the Inventory Item.
- calculation_type (string - enum) optional, default: "fixed" - This controls how the Inventory Item amount is determined. It can be one of the following:
- fixed - Fixed Amount
- percentage_of_total - Percent of Total Rate
- percentage_of_night - Percent of Nightly Rate
- tax_free (boolean) optional, default: false - This controls whether the Inventory Item is tax-free or not.
- daytype (string - enum) optional, default: "once" - This controls how the Inventory Item is going to be charged. This can be one of the following:
- once - Once-Off
- every_qualifying_day - Particular Days
- every_interval - Repeat Interval
- interval_multiplier (int) optional, default: 0 - This pairs with the interval setting to determine how frequently this Inventory Item is charged.
- interval (string - enum) optional, default: "day" - This controls the frequency of when an Inventory Item is charged. E.g. If interval_multiplier is set to 3, and interval is week, then this will be charged every 3 weeks. The available options are:
- day
- week
- month
- year
- interval_limit (int) optional, default: 0 - This controls the maximum number of times this Inventory Item can be charged. Setting this to 0 removes the limit.
- daysofweek (array of strings - enum) optional, default: [] - This is an array of applicable days this Inventory Item is charged on. This can contain any of the following:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- ignore_other_tariffs (int - enum) optional, default: 0 - This controls what dates restrictions apply when creating charges for this Inventory Item on a Booking that is spanning multiple Rates. This can be either of the following:
- 0 - No Restrictions
- 1 - Dates with this Rate
- ignore_period_from (boolean) optional, default: false - This determines whether this Inventory Item ignores the arrival date of the Booking.
- ignore_period_to (boolean) optional, default: true - This determines whether this Inventory Item ignores the departure date of the Booking.
- remove (boolean) optional, default: false - If true will remove the associated Inventory Item from the rate.
deposit_template_id (int | null) optional, default: null - If it's an int it's the ID of an existing Booking Rule Template, otherwise deposits will be used.
deposits (array of objects) - available if deposit_template_id != null - This will need to be provided as an array of deposits as shown below:
"deposits": [
{
"id": 1,
"due_days": "0",
"due_type": "after",
"days_in_advance": "0",
"deposit_type": "percentage",
"deposit_amount": 20,
"minimum": 100.00,
"maximum": 200.00,
"offline_deposit": true,
"online_deposit": true,
"remove": false
}
]
- id (int) required if editing a deposit.
- due_type (string - enum) optional, default: "before" - This can be either of:
- before - Days Before Booking Arrival
- after - Days After Booking Placed
- date - Specific Date
- due_days (int) required if
due_type = before | after- Specifies the number of days before or after the Booking arrival date that the deposit is due. - due_date (string - yyyy-mm-dd) required if
date- Specifies the date the deposit is due. - days_in_advance (int) optional, default: 0 - This specifies the number of days in advance the booking has to be made to be eligible for this deposit rule.
- deposit_type (string - enum) optional, default: "percentage" - This controls how the deposit_amount is calculated. This can be one of the following:
- percentage - Percentage of Total
- percentage_inc_prev_deposits - Percentage of Total (including previous Deposits)
- nights - Number of Nights
- nights_average - Number of Nights (Average)
- fixed - Fixed Amount per Booking
- fixed_per_night - Fixed Amount per Night
- fixed_per_adult - Fixed Amount per Adult (per Booking)
- fixed_per_child - Fixed Amount per Child (per Booking)
- fixed_per_person - Fixed Amount per Person (per Booking)
- fixed_per_adult_per_night - Fixed Amount per Adult (per Night)
- fixed_per_child_per_night - Fixed Amount per Child (per Night)
- fixed_per_person_per_night - Fixed Amount per Person (per Night)
- deposit_amount (float) optional, default: 0.00 - This specifies the deposit amount.
- minimum (float) optional, default: 0.00 - This specifies the minimum amount to be charged for a deposit.
- maximum (float) optional, default: 0.00 - This specifies the maximum amount to be charged for a deposit.
- offline_deposit (boolean) optional, default: true - This determines whether the deposit applies to bookings made inside the Newbook interface.
- online_deposit (boolean) optional, default: false - This determines whether the deposit applies to bookings made on Newbook Online, or a third party.
- remove (boolean) optional, default: false - If true will remove the associated deposit from the rate.
adjustment_fee_template_id (int | null) optional, default: null - If it's an int it's the ID of an existing Booking Rule Template, otherwise adjustment_fees will be used
adjustment_fees (array of objects) available if adjustment_fee_template_id != null - This will need to be provided as an array of the adjustment fees as shown below:
"adjustment_fees": [
{
"id": 1,
"type": "cancellation",
"inventory_item_id": 125,
"description": "Cancellation Fee",
"gl_category_id": 1,
"gl_account_id": 34,
"within_days": 7,
"within_type": "booking_arriving",
"amount_type": "percentage",
"amount": 50.00,
"tax_free": false,
"remove": false
}
]
- id (int) required if editing an adjustment fee.
- type (string - enum) optional, default: "cancellation" - This controls the type of adjustment fee you are creating. This can be either of the following:
- cancellation - Cancellation Fee
- modification - Online Modification Fee
- inventory_item_id (int) optional, default: null - ID of an existing Inventory Item. Providing this will use the Inventory Item details to fill the other fields.
- description (string) optional, default: "" - This is the description of the Adjustment Fee. This can be a maximum of 250 characters.
- gl_category_id (int | null) optional, default: null - This can either be an ID of an existing Sub Client Account or null to use the Category default.
- gl_account_id (int | null) optional, default: null - This can either be an ID of an existing GL Account or null to use the Category default.
- within_days (int) optional, default: 0 - This specifies the number of days from within_type to determine if a booking adjustment incurs the charge.
- within_type (string - enum) optional, default: "booking_arriving" - This specifies the way of determining when the booking will incur a charge for the adjustment.
- booking_arriving - Before Booking Arrival
- booking_placed - After Booking Placed
- amount_type (string - enum) optional, default: "fixed" - This controls how the amount is calculated. This can be one of the following:
- percentage - Percentage of Total
- percentage_inc_prev - Percentage of Total (including previous Fees)
- nights - Number of Nights
- nights_average - Number of Nights (Average)
- fixed - Fixed Amount
- fixed_per_night - Fixed Amount per Night
- fixed_per_adult - Fixed Amount per Adult
- fixed_per_child - Fixed Amount per Child
- fixed_per_person - Fixed Amount per Person
- amount (float) optional, default: 0.00 - This specifies the adjustment fee amount.
- tax_free (boolean) optional, default: false - This controls whether the adjustment fee is tax-free or not.
- remove (boolean) optional, default: false - If true will remove the associated adjustment fee from the rate.
Rates: Create Example
Rates: Update
Request Notes:
id (int) required
All other parameters are optional, please see Rates: Create for more details.
Rates: Update Example
Rate Periods: List
Returns a list of active Rate Periods.
Request Notes:
show_inactive is optional and when provided with a truthy value, it will include inactive Rate Periods in the response.
Rate Periods: List Example
Rate Periods: Create
Creates a Rate Period.
Request Notes:
- name (string) is required.
-
daysofweek (array) should be an array containing lower case day names.
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- colour (string - hex) Hex code representation of a colour.
- tariffs_periods_dates (array) of dates that the Rate Period affects.
- period_from (date - yyyy-mm-dd)
- period_to (date - yyyy-mm-dd)
The following parameters are optional:
- active (boolean) whether the Tariff Period is active.
Rate Periods: Create Example
Rate Periods: Get
Returns a Rate Period.
Request Notes:
tariffs_period_id (int) ID of the Tariff Period to be returned.
Rate Periods: Get Example
Rate Periods: Update
Updates an existing Rate Period.
Request Notes:
tariffs_period_id (int - required) ID of the Rate Period to update.
Please see below for a list of optional details that can be updated on the Rate Period. At least one of these must be provided.
- name (string)
-
daysofweek (array) should be an array containing lower case day names.
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- colour (string - hex) Hex code representation of a colour.
- tariffs_periods_dates (array) of dates that the Rate Period affects.
- period_from (date - yyyy-mm-dd)
- period_to (date - yyyy-mm-dd)
- active (boolean) whether the Tariff Period is active.
Rate Periods: Update Example
Rates: Override
Creates a Rate Override
When a parameter is optional and not included, or set to null in the request, the original Rate value will not be overridden.
Request Notes:
Selection Details
- period_from (date - yyyy-mm-dd) inclusive
- period_to (date - yyyy-mm-dd) inclusive
-
daysofweek (array) should be an array containing lower case day names.
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- using_master (enum) must be from the following list:
- master This option must also provide the master_id parameter
- standalone This option must also provide the category_id, booking_channel_id and skip_warning. Can optionally include type_id and rate_code parameters
- active (boolean) whether the Rate Override is active.
When using_master has the value of master
- master_id (int | array of int) Master Rate IDs. Required when using_master is set to master.
When using_master has the value of standalone
- category_id (int | array of int) Category IDs. Required when using_master is set to standalone.
- type_id (int) Rate Type ID. Leaving this blank will apply the Rate Override to all Rate Types
- booking_channel_id (int | array of int) Booking Channel IDs
- skip_warning (Boolean) Skip Specific Channel booking_channel_id warning?
Daily Pricing Overrides
- override_type (enum) Required. Choose from the option below for how the rate will be overridden.
- fixed Override by a fixed amount. If set, must provide these additional parameters:
- fixed_override (float) Amount to override with.
- fixed_method (enum) optional - Not including this will override the rate amount
using fixed_override amount. Choose either below value to increase or decrease by the amount instead:
- increase Increase by fixed_override amount.
- decrease Decrease by fixed_override amount.
- dynamic Dynamically set the rate depending upon occupancy. If set, must provide these additional parameters:
- dynamic_min (float) Dynamic Min ($)
- dynamic_max (float) Dynamic Max ($)
- dynamic_base (float) Dynamic Base ($) This value is only used to compare against the Min and Max amounts to calculate the success of this Dynamic Rate.
- dynamic_method (enum)
- linear Off-Peak.
- exponential Peak.
- dynamic_occupancy (enum) Dynamic Occupancy. Which Occupancy Percentage should Newbook
use to work out the Dynamic Pricing formula.
- category Category.
- category_type Category Type.
- instance Instance.
- dynamic_occupancy_min (float) Minimum Occupancy (%)
- percentage if set, must provide these additional parameters:
- percentage_override (float) Percentage to override with.
- percentage_method (enum) Choose either below value to increase or decrease by the percentage:
- increase Increase by percentage_override.
- decrease Decrease by percentage_override.
- fixed Override by a fixed amount. If set, must provide these additional parameters:
- discounts (boolean) Optional Discounts Apply (Optional, NULL = Do not override)
Base Override Details
- stop_sell (boolean) Stop Sell (Optional, NULL = Do not override)
- active (boolean) whether the Tariff Period is active.
Daily Inclusion Overrides
- base_adult (integer) Adults included (Optional, NULL = Do not override)
- base_child (integer) Children included (Optional, NULL = Do not override)
- base_infant (integer) Infants included (Optional, NULL = Do not override)
- base_animal (integer) Animals included (Optional, NULL = Do not override)
- base_combined (integer) Included combined occupants (Optional, NULL = Do not override)
- adult_amount (float) Additional Adult Amount (Optional, NULL = Do not override)
- child_amount (float) Additional Child Amount (Optional, NULL = Do not override)
- infant_amount (float) Additional Infant Amount (Optional, NULL = Do not override)
- animal_amount (float) Additional Animal Amount (Optional, NULL = Do not override)
Other Daily Overrides
- minimum_sites_online (integer) Sites reserved from Newbook Online Bookings (Optional, NULL = Do not override)
- minimum_periods (integer) Minimum nights (Optional, NULL = Do not override)
- maximum_periods (integer) Maximum nights (Optional, NULL = Do not override)
- special_deal (enum) Newbook Online: "Special" (Optional, NULL = Do not override)
- 0 No
- 1 Hot
- 2 Special
- 3 Save
- 4 Promotion
- close_arrival (boolean) Close arrivals (Optional, NULL = Do not override)
- close_departure (boolean) Close departures (Optional, NULL = Do not override)
Rate Override JSON
Rate Types: List
Pull the list of Rate Types from within Newbook.
Request Notes:
name is optional and when provided it will restrict results to the matching Rate Types
show_inactive is optional, default false, and when provided with a truthy value, it will include inactive Rate Types in the response.
Rate Types: List Example
Rate Types: Create
Create a new Rate Type.
Request Notes:
name must be provided. This is the name of the Site.
The following parameters are optional:
- description (string)
- short_description (string)
- display_order (int) Determines the order in which the Rate Type is displayed.
- bookings_market_segment_id (int) An existing Booking Market Segment ID.
- active (boolean) Defaults to true if not provided.
- user_profile_restrictions (array) An array of user profiles that the Rate Type applies to with the following format:
- profile_id (int)
- available_discounts (array) An array of discounts that the Rate Type applies to with the following format:
- discount_id (int)
- los_gl_accounts (array) An array of Length of Stay (LOS) GL Accounts that the Rate Type applies to daily rates that meet the minimum night requirement:
- gl_account_id (int)
- name (string)
- min_nights (int)
Rate Types: Create Example
Rate Types: Get Details
Retrieve an existing Rate Type record.
Request Notes:
tariff_type_id must be provided to retrieve the details of a particular Rate Type.
Response Notes:
The returned data from this request is identical to Rate Types: List but for a specific Rate Type alone.
If no such Rate Type exists, the success response parameter will be "false" and no data will be returned.
Rate Types: Get Details Example
Rate Types: Update
Update a Rate Type.
Request Notes:
tariff_type_id is required to advise which Rate Type you are updating.
remove can be included in the user_profile_restrictions, available_discounts and los_gl_accounts objects, this flag will remove an existing association with matching ID if set to 1.
All other parameters are optional, and are defined in Rate Types: Create.
Rate Types: Update Example
Rate Applications: List
Lists Rate Applications.
Request Parameters:
- active_after (string - YYYY-MM-DD) optional, when provided filters results to those that are active equal to and after the provided date.
- active_before (string - YYYY-MM-DD) optional, when provided filters results to those that are active equal to and before the provided date.
- tariff_type_id (array) optional, accepts an array of Rate Type IDs (int) to filter by.
- category_id (array) optional, accepts an array of Category IDs (int) to filter by.
- booking_channel (integer) optional, when provided filters results by Booking Channel.
- has_channel_manager_ratecode (string) optional, when provided filters results by whether they have a Channel Manager RateCode:
- any, returns results regardless of whether they have a Channel Manager RateCode.
- yes, returns results that have a Channel Manager RateCode.
- no, returns results that do not have a Channel Manager RateCode.
- has_newbook_online_promo_code (string) optional, when provided filters results by whether they have a Newbook Online Promo Code:
- any, returns results regardless of whether they have a Promo Code.
- yes, returns results that have a Promo Code.
- no, returns results that do not have a Promo Code.
- show_inactive (boolean) optional, when true, it will include inactive Rate Applications.
Rate Applications: List Example
Rate Applications:
Create
Create a new Rate Application.
Request Parameters:
- tariff_type_id (integer) required, a valid Rate Type ID.
- tariff_id (integer) required, a valid Rate ID.
- tariff_period_id (integer) required, a valid Rate Period ID.
- category_id (integer) required, a valid Category ID.
- channel_manager_ratecode (string) optional, the Channel Manager RateCode to use.
- newbook_online_promo_code (string) optional, if provided the Rate will not be visible in Newbook Online until the Promo Code has been entered.
- booking_channels (array) optional, the 3rd Party Booking Channels to apply to this Rate Application, accepts an array of objects with the following structure:
- booking_channel_id (integer) required, a valid ID of a Booking Channel that is mapped to the Rate Application's Category and does not have a direct connection established.
- active (boolean) optional, whether the Booking Channel mapping is active for the Rate Application.
- companies (array) optional, the Companies to apply to this Rate Application, accepts an array of Company IDs.
- travel_agents (string) optional, the Travel Agents to apply to this Rate Application, accepts an array of Travel Agent IDs.
- active (boolean) optional, whether the Rate Application is active.
Rate Applications: Create Example
Rate Applications: Get Details
Retrieve an existing Rate Application.
Request Parameters:
- tariff_applied_id (integer) required, a valid Rate Application ID.
Response Notes:
The returned data from this request is identical to Rate Applications: List but for a specific Rate Type alone.
If no such Rate Type exists, the success response parameter will be "false" and no data will be returned.
Rate Applications: Get Details Example
Rate Applications:
Update
Update a Rate Application.
Request Parameters:
- tariff_applied_id (integer) required, the ID of the Rate Application to update.
- tariff_type_id (integer) optional, a valid Rate Type ID.
- tariff_id (integer) optional, a valid Rate ID.
- tariff_period_id (integer) optional, a valid Rate Period ID.
- category_id (integer) optional, a valid Category ID.
- channel_manager_ratecode (string) optional, the Channel Manager RateCode to use.
- newbook_online_promo_code (string) optional, if provided the Rate will not be visible in Newbook Online until the Promo Code has been entered.
- booking_channels (array) optional, the 3rd Party Booking Channels to apply to this Rate Application, accepts an array of objects with the following structure:
- booking_channel_id (integer) required, a valid ID of a Booking Channel that is mapped to the Rate Application's Category and does not have a direct connection established.
- active (boolean) optional, whether the Booking Channel mapping is active for the Rate Application.
- companies (array) optional, the Companies to apply to this Rate Application, accepts an array of Company IDs.
- travel_agents (string) optional, the Travel Agents to apply to this Rate Application, accepts an array of Travel Agent IDs.
- active (boolean) optional, whether the Rate Application is active.
Rate Applications: Update Example
Rate Periods: List
Returns a list of active Rate Periods.
Request Notes:
show_inactive is optional and when provided with a truthy value, it will include inactive Rate Periods in the response.
Rate Periods: List Example
Rate Periods: Create
Creates a Rate Period.
Request Notes:
- name (string) is required.
-
daysofweek (array) should be an array containing lower case day names.
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- colour (string - hex) Hex code representation of a colour.
- tariffs_periods_dates (array) of dates that the Rate Period affects.
- period_from (date - yyyy-mm-dd)
- period_to (date - yyyy-mm-dd)
The following parameters are optional:
- active (boolean) whether the Tariff Period is active.
Rate Periods: Create Example
Rate Periods: Get
Returns a Rate Period.
Request Notes:
tariffs_period_id (int) ID of the Tariff Period to be returned.
Rate Periods: Get Example
Rate Periods: Update
Updates an existing Rate Period.
Request Notes:
tariffs_period_id (int - required) ID of the Rate Period to update.
Please see below for a list of optional details that can be updated on the Rate Period. At least one of these must be provided.
- name (string)
-
daysofweek (array) should be an array containing lower case day names.
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- colour (string - hex) Hex code representation of a colour.
- tariffs_periods_dates (array) of dates that the Rate Period affects.
- period_from (date - yyyy-mm-dd)
- period_to (date - yyyy-mm-dd)
- active (boolean) whether the Tariff Period is active.
Rate Periods: Update Example
Discounts: List
Pull the list of Discounts from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Discounts
Discounts: List Example
Discounts: Create
Create a new Discount.
Request Notes:
The following parameters are required:
- name (string) is required
-
discount_type (string) must be from the following list:
- percentage
- nights
- cheapest_night_percentage
- nights_average
- fixed
- fixed_per_night
- fixed_per_adult
- fixed_per_child
- fixed_per_person
- fixed_per_adult_per_night
- fixed_per_child_per_night
- fixed_per_person_per_night
- discount_amount (float)
- minimum (float)
- maximum (float)
- active (boolean)
The following parameters are optional:
- minimum_stay_cost (float)
- min_valid_nights (int)
- gl_account_id (int) must match a valid GL Account ID if provided
- gl_category_id (int) must match a valid GL Category ID if provided
- bookings_source_id (int) must match a valid Booking Source ID if provided
- bookings_market_segment_id (int) must match a valid Booking Market Segment ID if provided
-
daysofweek (array) should be an array containing lower case day names
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- requires_code (boolean) should discount codes be required for this discount
-
discount_codes (array) of discount code objects
- id (int) should be provided if updating an existing code
- code (string) the discount code
- available_from (string) must be a valid date if provided
- available_to (string) must be a valid date if provided
- staying_from (string) must be a valid date if provided
- staying_to (string) must be a valid date if provided
- remove (boolean) will delete an existing code with matching ID if set to 1
- category_restrictions (array|null) optional, an array of valid Category IDs, or null for no Category restrictions
- tariff_period_restrictions (array|null) optional, an array of valid Rate Period IDs, or null for no Rate Period restrictions
- tariff_type_restrictions (array|null) optional, an array of valid Rate Type IDs, or null for no Rate Type restrictions
- user_profile_restrictions (array|null) optional, an array of valid User Profile IDs, or null for no User Profile restrictions
- membership_restrictions (array|null) optional, an array of valid Membership IDs, or null for no Membership restrictions
- category_type_restrictions (array|null) optional, an array of valid Category Type IDs, or null for no Category Type restrictions
Discounts: Create Example
Discounts: Get
Retrieve an existing Discount record.
Request Notes:
discount_id must be provided to retrieve the details of a particular Discount.
Response Notes:
The returned data from this request is identical to Discounts: List but for a specific Discount alone and with the addition of any associated Discount codes.
If no such Discount exists, the success response parameter will be "false" and no data will be returned.
Discounts: Get Example
Discounts: Update
Update a Discount.
Request Notes:
discount_id is required to advise which Discount you are updating.
All other parameters are optional, and are defined in Discounts: Create.
Discounts: Update Example
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.
Request Notes:
activity_id can be provided as an array to limit the response to particular Activities.
Response Notes:
facility_id the ID of the Facility this Activity occurs in (see Facilities: List)
Activity Configurations
activity_configurations the list of configurations for an Activity.
configuration_online indicates whether an Activity configuration is available from Newbook Online.
| Possible Values | Definition |
|---|---|
| 0 | No |
| 1 | All Carts |
| 2 | Standalone Cart Only |
Activity Setup Example
Activity Availability and Pricing
Returns Activity availability and pricing for the requested dates/occupants.
Request Notes:
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, and 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.
Response Notes:
Each activity_configurations object shows included_occupants, extra_occupants and max_occupants:
- included_occupants defines the number of adults/children/infants/animals which are included in the Timeslot calculated_total price. Null in these values means unlimited.
- extra_occupants defines the extra price to charge for the number of adults/children/infants/animals above each respective included_occupants number.
- max_occupants defines the total number of adults/children/infants/animals/combined which can use the Ticket. If you need to sell more occupants than these limits, you will need to use the Create Ticket request again. Null in these values means unlimited.
Using the Create Ticket request will validate the parameters you provide against the above logic.
inventory_items provides an array of Sub-Inventory Items that are chargeable for the Ticket.
timeslot_ticket
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:
- reflects the values you have provided in the request parameters in the adults/children/infants/animals keys
- shows how many remaining_adults/remaining_children/remaining_infants/remaining_animals and remaining_combined occupants are still able to be booked for the given Timeslot. Null in these values means unlimited. If an occupant type (or the combined figure) in the remaining_X keys reaches 0, any further Create Ticket requests using that occupant type will be rejected
- should be used in the Create Ticket request (excluding its remaining_X keys)
timeslot_code
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 |
Activity Availability and Pricing Example
Ticket List
Returns a list of Booked Activities aka Tickets.
Request Notes:
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 and 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.
Response Notes:
booking_site_id, booking_site_name, booking_category_id, and booking_category_name will only have data when the Activity Ticket is linked to a Booking, otherwise these fields will be null.
Ticket List Example
Create Ticket
Book an Activity / Create an Activity Ticket.
Request Notes:
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 and 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.
Response Notes:
You will receive a ticket_id when the request successfully books an Activity.
Create Ticket Example
Update Ticket
Update an Activity Ticket.
Request Notes:
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.
Response Notes:
You will receive the same ticket_id when the request successfully updates the Activity Ticket.
Update Ticket Example
Ticket PDF Content
Retrieve the HTML markup required to print a PDF version of the Activity Ticket.
Ticket PDF Content Example
Allotments: List
Pull the list of active Allotments that are available online from within Newbook.
Response Notes:
show_inactive (boolean) is optional and when provided with a truthy value, it will include inactive Allotments in the response.
for (string) is optional and when provided it will restrict the results to the matching value.
for_id (int) is optional and when provided it will restrict the results to the matching for_id.
period_from (date) is optional and when provided will include allotments with a period_to on or after this date.
period_to (date) is optional and when provided will include allotments with a period_from on or before this date.
Allotments: List Example
Allotments: Create
Creates an Allotment.
Request Notes:
The following parameters are required:
- for (string) Must be from the following list:
- travel_agents
- companies
- memberships
- for_id (int) ID of the particular Travel Agent, Company, or Membership.
- category_id (int) ID of the Accommodation Category.
- sites_allotted (int) how many guaranteed sites in the specified category are assigned to this allotment.
- release_interval (string) Along with release_interval_multiplier, determines when sites will be released from this allotment. Must be from the following list:
- day
- week
- month
- year
- release_interval_multiplier (int)
- period_from and period_to (date) period that this allotment is functional.
- active (boolean) whether or not this allotment is active.
The following parameters are optional:
- maximum_uses (int) defaults to unlimited. Maximum number of sites allowed to be used by this allotment.
- guaranteed (boolean) defaults to true. Where or not sites should be guaranteed for this allotment.
-
daysofweek (array) defaults to daily. Should be an array containing any of the following lower case day names:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
Allotments: Create Example
Allotments: Get
Returns an existing Allotment record.
Request Notes:
allotment_id must be provided to retrieve the details of a particular Allotment.
Allotments: Get Example
Allotments: Update
Updates an existing Allotment.
Request Notes:
allotment_id must be provided to update a particular Allotment.
All other parameters are optional, and are defined in Allotments: Create.
Allotments: Update Example
Allotment Override
Creates an Allotment Override.
Request Notes:
The following parameters are required:
- allotment_id (int) ID of the allotment being overridden.
- date (date) date of the allotment that is being overridden.
At least one, or more, of the following parameters are required:
- sites_allotted (int) Number of sits to be allotted. Null to use Allotment value.
- maximum_uses (int) Maximum sites allowed to be booked for the allotment. Null to use Allotment value.
- active (boolean) defaults to true. Whether this allotment override is active.
Allotments Overrides: Create Example
Facility Categories: List
Returns a list of active Facility Categories.
Request Notes:
show_inactive is optional, default false, and when provided with a truthy value, it will include inactive Facility Categories in the response.
Facility Categories: List Example
Facility Categories: Create
Creates a Facility Category.
Request Notes:
The following parameters are required:
- name (string: up to 200 characters) is required.
The following parameters are optional:
- max_adults (int)
- max_children (int)
- max_infants (int)
- max_animals (int)
- max_combined (int)
- display_order (int)
- hireable (boolean)
- housekeeping (boolean)
- restrict_start_time (time: H:i:s)
- restrict_end_time (time: H:i:s)
- restrict_hire_interval (string) must be from the following list:
- once
- minute
- hour
- day
- week
- month
- year
- restrict_hire_interval_multiplier (int)
- online_hire_interval (string) must be from the following list:
- once
- minute
- hour
- day
- week
- month
- year
- online_hire_interval_multiplier (int)
- online_hire_entire_duration (boolean)
- online_group_description (string: up to 250 characters)
- default_inventory_item_id (int) must match a valid Inventory Item ID if provided
- appointments (boolean)
- system_template_terms_and_conditions (int) must match a valid System Template ID if provided
- active (boolean)
- features (array) of existing Facility Feature IDs
Facility Categories: Create Example
Facility Categories: Get
Returns an existing Facility Category record.
Request Notes:
facility_category_id must be provided to retrieve the details of a particular Facility Category.
Facility Categories: Get Example
Facility Categories: Update
Updates an existing Facility Category.
Request Notes:
facility_category_id must be provided to update a particular Facility Category.
Please see below for a list of optional details that can be updated on the Facility Category. At least one of these must be provided.
All other parameters are optional, and are defined in Facility Categories: Create.
Facility Categories: Update Example
Facility Features: List
Returns a list of active Facility Features.
Request Notes:
show_inactive is optional, default false, and when provided with a truthy value, it will include inactive Facility Features in the response.
Facility Features: List Example
Facility Features: Create Example
Facility Features: Update
Updates an existing Facility Feature.
Request Notes:
facility_feature_id must be provided to update a particular Facility Feature.
Please see below for a list of optional details that can be updated on the Facility Feature. At least one of these must be provided.
- name
- active - supports values like "true", false, 1.
Facility Features: Update Example
Facilities: List
Pull the list of active Facilities that are available online from within Newbook.
Request Notes:
show_inactive is optional, default false, and when provided with a truthy value, it will include inactive Facilities in the response.
hireable_only is optional, default true, which enforces returning only those Facilities configured as able to be hired online.
Response Notes:
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.
Facilities: List Example
Facilities: Create
Creates a Facility.
Request Notes:
The following parameters are required:
- category_id (int) Facility Category that this Facility belongs to.
- name (string: up to 200 characters) is required.
The following parameters are optional:
- display_order (int)
- status (string) must be from the following list:
- Open
- Maintenance
- level_id (int)
- manager_id (int)
- opened_on (date: Y-m-d) defaults to today's date
- show_online (boolean)
- show_on_maps (boolean)
- active (boolean)
- features (array) of existing Facility Feature IDs
Facilities: Create Example
Facilities: Get
Returns an existing Facility record.
Request Notes:
facility_id must be provided to retrieve the details of a particular Facility.
The field override_category_features (boolean) is non-editable and is set to True when Features are linked to the Facility directly.
Facilities: Get Example
Facilities: Update
Updates an existing Facility.
Request Notes:
facility_id must be provided to update a particular Facility.
All other parameters are optional, and are defined in Facilities: Create.
Facilities: Update Example
Facility Hire: Availability and Pricing
Returns the Facility Hire Availability and Pricing for the requested dates.
Request Notes:
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, and animals can be optionally provided for hiring the Facility, as these may affect pricing.
Response Notes:
Availability is returned per Facility. For each Facility, the below explains the response keys:
- facility_id is the ID of the Facility
- facility_name is the name of the Facility
- facility_category_id is the ID of the Facility Category
- facility_category_name is the name of the Facility Category
- availability is an array of the timeslots, from the period_from to the period_to in increments of the Hire Interval set on the Facility, and the pricing for each period. For example, if the Hire Interval is 2 hours, the availability array will show increments of 2 hours between the period_from & period_to provided in the request.
- availability[][available] is a boolean which indicates if the Facility is available for the timeslot
- availability[][period_from] is the start of the timeslot
- availability[][period_to] is the end of the timeslot
- availability[][pricing] is an array of the pricing information for the timeslot
- pricing[][interval] is the Hire Interval for the Facility. It can be once, minute, hour, day, week, month, or year.
- pricing[][interval_multiplier] is an integer defining the duration of the Hire Interval. For example 15 minute, or 3 hour, or 1 day etc.
- pricing[][amount_per_interval] is the cost to hire the Facility per Hire Interval.
- pricing[][total_for_period] is the total cost for the timeslot.
Facility Hire: Availability and Pricing Example
Facility Hire: List
Returns a list of Facility Hires.
Request Notes:
All of the below are optional -
facility_ids can be provided as an array to limit the response to particular Facilities.
for and 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: List Example
Facility Hire: Get
Returns an existing Facility Hire record.
Request Notes:
hire_id must be provided to retrieve the details of a particular Facility Hire.
Facility Hire: Get Example
Facility Hire: Create
Create a Facility Hire.
Request Notes:
facility_id is the ID of the Facility to be hired (see Facilities: List)
hireable_only is optional, default true, which enforces hiring only those Facilities configured as able to be hired online. You can provide it as false to force the API to let you Hire a Facility not otherwise configured for this.
adults is required however children, infants, and animals can be optionally provided for hiring the Facility, as these may affect pricing.
for and 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
}
If specified, custom_fields must be based on the response to the Custom Fields request, to retrieve the different Custom Fields set up in the instance:
"custom_fields": [
{
"field_id": 2,
"field_value": 8
}
]
Response Notes:
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: Create Example
Facility Hire: Update
Update a Facility Hire.
Request Notes:
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.
Facility Hire: Update Example
Inventory Items: List
Pull the list of Inventory Items from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Inventory Items
You can provide a basic booking object named calculate_price_for_booking in the request parameters and Newbook will return a new key in the response, booking_inventory_calculated_price. The calculation factors the cost per occupant so you don't have to implement such logic in your application:
{
"calculate_price_for_booking": {
"period_from": "2024-04-19",
"period_to": "2024-04-20",
"total": 199.95,
"adults": 2,
"children": 1,
"infants": 0,
"animals": 0
}
}
If you use this, calculate_price_for_booking.period_from, calculate_price_for_booking.period_to and calculate_price_for_booking.total and at least one of the occupant keys are required for Newbook to return booking_inventory_calculated_price in the response. This is because the duration of the booking and its total cost can impact the price determination when an Inventory Item is configured that way:
{
"success": "true",
"data": [{
...
"booking_inventory_calculated_price": 14.50
}],
"message": ""
}
Inventory Items: List Example
Inventory Items: Create
Create a new Inventory Item.
Request Notes:
The following parameters are required:
- name (string) is required
- amount (float) is required
The following parameters are optional:
- description (string)
- cost_price (float)
- tax_free (boolean)
- push_to_pos (boolean)
- active (boolean)
- gl_category_id (null | int)
- gl_account_id (null | int)
- category_id (null | int)
- repeat_charge_interval_multiplier (boolean)
-
repeat_charge_interval (string) must be from the following list:
- day
- week
- month
- year
-
repeat_charge_type (string) must be from the following list:
- charges
- credits
- repeat_charge_prorata_end (boolean)
- repeat_charge_guest_visible (boolean)
- repeat_charge_travel_agent_commission (boolean)
- repeat_charge_include_in_stay_cost (boolean)
- repeat_charge_booking_market_segment_id (int)
-
booking_inventory_item_type (string) must be from the following list:
- charges
- credits
- booking_inventory_per_adult (float)
- booking_inventory_per_child (float)
- booking_inventory_per_infant (float)
- booking_inventory_per_animal (float)
-
booking_inventory_daytype (string) must be from the following list:
- once
- every_qualifying_day
- every_interval
-
booking_inventory_interval (string) must be from the following list:
- day
- week
- month
- year
- booking_inventory_interval_multiplier (int)
- booking_inventory_interval_limit (string)
-
booking_inventory_daysofweek (array) must be an array containing zero or more lower case day names:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
- booking_inventory_guest_visible (boolean)
- booking_inventory_travel_agent_commission (boolean)
- booking_inventory_include_in_stay_cost (boolean)
- booking_inventory_include_in_deposit (boolean)
- booking_inventory_include_in_payment_plan (boolean)
- booking_inventory_discounts_apply (boolean)
- booking_inventory_refundable (boolean)
- booking_inventory_ignore_period_from (boolean)
- booking_inventory_ignore_period_to (boolean)
- hire_interval_multiplier (int)
-
hire_interval (string) must be from the following list:
- once
- minute
- hour
- day
- week
- month
- year
- hire_per_adult (float)
- hire_per_child (float)
- hire_per_infant (float)
- hire_per_animal (float)
- hire_travel_agent_commission (boolean)
- barcode (string)
- section_code (string)
-
new_cpi_increases (array) an array of objects for each scheduled price increase/decrease
The type parameter must be from the following list:
- fixed_amount: Set new Fixed Amount
- inc_fixed_amount: Increase by Fixed Amount
- dec_fixed_amount: Decrease by Fixed Amount
- inc_percentage: Increase by Percentage
- dec_percentage: Decrease by Percentage
[ { "date": "2024-04-19", "amount": "25.00", "type": "fixed_amount" }, { "date": "2024-05-19", "amount": "10.00", "type": "dec_percentage" } ]
Inventory Items: Create Example
Inventory Items: Get
Retrieve an existing Inventory Item record.
Request Notes:
inventory_item_id must be provided to retrieve the details of a particular Inventory Item.
Response Notes:
The returned data from this request is identical to Inventory Items: List but for a specific Inventory Item alone.
If no such Inventory Item exists, the success response parameter will be "false" and no data will be returned.
Inventory Items: Get Example
Inventory Items: Update
Update an Inventory Item.
Request Notes:
inventory_item_id is required to advise which Inventory Item you are updating.
All other parameters are optional, and are defined in Inventory Items: Create.
-
cpi_increases (array) can also be provided to remove or update existing CPI Increases.
[ { "id": 4, "remove": true }, { "id": 5, "date": "2024-05-19", "amount": "10.00", "type": "fixed_amount" } ]
Inventory Items: Update Example
Guests: List
Retrieve/search the Guest database.
Request Notes:
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 provided, restricts the returned Guests to only those which were created on the date given
staff_id is optional and when provided, restricts the returned Leads to those assigned to that User (see Users: List)
sort_ascending is optional and when provided as true, sorts the Guests by ID ascending. Defaults to false (sort the Guests by ID descending).
show_inactive_equipment (boolean) Send as true to include inactive Guest Equipment in the response.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
- This feature is only available on CRMs
- You can provide staff_id_include as false to show Leads not assigned to that User
- If you provide unassigned into the request parameter staff_id Leads that are unassigned will be returned
- staff_id can be an array of User IDs
client_account_tax_reconciliation can optionally be provided as true to include the amount of tax based on the reconciliation of payments / refunds. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_booking_details can optionally be provided as true to include Booking details for Charges and Credits. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_item_breakdown can optionally be provided as true to include all accounting items saved on the Guest Client Account in the Guest response. Please see the Guests: Get request for an example of the response data.
display_guest_activities can optionally be provided as true to include the Guests Activity Tickets in the Guest response. display_cancelled_guest_activities can also be provided to include Cancelled Activity Tickets. Please see the Guests: Get request for an example of the Guest Activity response data.
display_guest_facility_hires can optionally be provided as true to include the Guests Facility Hires in the Guest response. display_cancelled_guest_facility_hires can also be provided to include Cancelled Facility Hires. Please see the Guests: Get request for an example of the Guest Facility Hire response data.
Response Notes:
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 membership service_id and level can optionally be null when no Membership Service or Membership Service Level are connected to the Membership.
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
- allow_transactional: Guest allows general contact related to Bookings or accounts
- allow_marketing: Guest allows marketing contact such as newsletters
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: List Example
Guests: Create
Create a Guest to use for placing Bookings, Availability Emails, Online Logins, and more.
Request Notes:
firstname and lastname are required. All other parameters are optional but recommended for greater data capture.
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 provide update_existing_details as "false".
Alternatively you can manage the Contact Details in more depth as an array:
"contact_details": [
{
"id": 1,
"type": "phone",
"content": "0756554600",
"notes": "Office landline",
"allow_transactional": "1",
"allow_marketing": "1",
"remove": 0
},
{
"id": 2,
"type": "email",
"content": "support@newbook.cloud",
"notes": "Work email address",
"allow_transactional": "1",
"allow_marketing": "0",
"remove": 0
}
]
- id can be optionally provided when updating a Guest to update or remove a particular Contact Detail
- type is required
- content is required
- notes is optional
- allow_transactional is optional and will default to true when not provided
- allow_marketing is optional and will use the Instance Setting Default when not provided
- remove is optional and when true it will remove the Contact Detail from the Guest
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:
- content is required and should contain the content of the note to be added
- 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 page.
- task_list is optional and will default to false when note provided. This controls whether the note will display on any tasks lists.
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).
Alternatively you can manage the memberships array directly:
"membership_details": [
{
"id": 1,
"type_id": 2,
"content": "1234567",
"expiry_date": "2025-02-25",
"remove": 0
}
]
- id can be optionally provided when updating a Guest to update or remove a particular Membership.
- type_id is required and must match one of the ID values from a Memberships: List request.
- content is required. This is the membership number.
- expiry_date is optional. This is the expiry date of the membership formatted as YYYY-MM-DD.
- remove is optional.
date_of_birth can optionally be provided as YYYY-MM-DD to store the guests date of birth
duplicate_matching can optionally be provided as one of the following options:
- false: do not find duplicates
- name: Name only
- phone: Phone only
- email: Email only
- name_and_phone: Name and Phone
- name_and_email: Name and Email
- name_and_email_and_phone: Name and Email and Phone
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:
- The equipment parameter is optional in creating a guest. However, if provided, it must be in array format, because a guest own multiple equipment as shown in the example request.
- The following are the parameters for creating equipment for a Guest:
- equipment_name (required)
- equipment_make
- equipment_model
- equipment_type (must be a number)
- equipment_length (must be a number)
- equipment_width (must be a number)
- equipment_height (must be a number))
- equipment_registration
- equipment_registration_expiry
- active (default true)
- The equipment are saved onto the Equipment table and linked to the guest. Please note that if the equipment_registration is not specified, a new equipment will be created for the guest
If specified, custom_fields must be based on the response to the Custom Fields request, to retrieve the different Custom Fields set up in the instance:
"custom_fields": [
{
"field_id": 2,
"field_value": 8
}
]
If specified, dietary_requirements can be provided based on the response to Dietary Requirements request.
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.
Response Notes:
The returned data from this request is identical to Guests: List but for the newly created Guest alone
Guests: Create Example
Guests: Get
Retrieve an existing Guest record.
Request Notes:
- guest_id or account_id (integer) must be provided to retrieve the details of a particular Guest.
- show_inactive_equipment (boolean) Send as true to include inactive Guest Equipment in the response.
- account_breakdown (boolean) Send as true to see the balance of each associated Sub Client Account (gl_category)
- client_account_tax_reconciliation (boolean) can optionally be provided as true to include the amount of tax based on the reconciliation of payments / refunds. The below client_account_item_breakdown will also need to be provided as true for this to function.
- client_account_item_breakdown can optionally be provided as true to include all accounting items saved on the Guest Client Account in the Guest response.
client_account_booking_details can optionally be provided as true to include Booking details for Charges and Credits. The below client_account_item_breakdown will also need to be provided as true for this to function.
Example response when client_account_item_breakdown is true:
{
"charges": [
{
"id": "3062",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Standard Rate (2024-04-19)",
"amount": 100,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "tariffs_quoted",
"link_type_id": "123",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": "9.09"
}
]
}
],
"credits": [
{
"id": "4351",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Discount",
"amount": 5,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "discounts_quoted",
"link_type_id": "1024",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": 0.45
}
]
}
],
"payments": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"paid_by": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Accommodation",
"amount": 100,
"tendered": 100,
"type": "cash",
"type_id": "4",
"type_reference": "",
"deposit": "0",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [],
"charges": [
{
"link_id": 1,
"charge_id": 3062,
"reconciled_amount": 100,
"timestamp": "2024-04-19",
"voided_when": null
}
]
}
],
"refunds": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"refunded_to": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Refunding Discount Overpayment",
"amount": 5,
"tendered": 5,
"type": "cash",
"type_id": "4",
"type_reference": "",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [
{
"link_id": 1,
"credit_id": 4351,
"reconciled_amount": 5,
"timestamp": "2024-04-19",
"voided_when": null
}
],
"payments": []
}
]
}
display_guest_activities can optionally be provided as true to include the Guests Activity Tickets in the Guest response. display_cancelled_guest_activities can also be provided to include Cancelled Activity Tickets.
e.g.
{
"activities": [
{
"ticket_id": 8,
"activity_id": 2,
"name": "Golf",
"duration": "7",
"duration_interval": "day",
"facility_id": null,
"facility_name": null,
"facility_category_id": null,
"facility_category_name": null,
"configuration_name": "Golf - 18 Holes",
"id": 8,
"period_from": "2024-04-23 09:00:00",
"period_to": "2024-04-23 11:00:00",
"activity_configuration_id": 2,
"for": "guests",
"for_id": 1,
"adults": 2,
"children": 0,
"infants": 0,
"animals": 0,
"configuration_included_adults": null,
"configuration_included_children": null,
"configuration_included_infants": null,
"configuration_included_animals": null,
"inventory_item_id": 11,
"account_id": null,
"gl_category_id": 1,
"gl_account_id": 1,
"description": "Golf - 18 holes of golf",
"interval": "once",
"interval_multiplier": "1",
"amount": 0,
"per_adult": 80,
"per_child": 40,
"per_infant": 0,
"per_animal": 0,
"tax_free": "0",
"cancelled_when": null,
"cancelled_by": null,
"created_when": "2024-04-12 11:32:00",
"created_by": "-2",
"for_name": "John Doe",
"booking_site_id": null,
"booking_site_name": null,
"booking_category_id": null,
"booking_category_name": null,
"inventory_items": [
{
"ticket_id": "8",
"inventory_item_id": null,
"gl_category_id": null,
"gl_account_id": null,
"description": "Cart Hire",
"interval": "once",
"interval_multiplier": "0",
"amount": "45.00",
"per_adult": "0.00",
"per_child": "0.00",
"per_infant": "0.00",
"per_animal": "0.00",
"tax_free": "0",
"guest_visible": "1",
"charge_id": "351"
}
],
"units": 1,
"calculated_total": 205,
"total_paid": 0,
"payment_status": "Unpaid",
"access_codes": [],
"custom_fields": [],
"payment_plans": []
}
]
}
display_guest_facility_hires can optionally be provided as true to include the Guests Facility Hires in the Guest response. display_cancelled_guest_facility_hires can also be provided to include Cancelled Facility Hires.
e.g.
{
"facilities_hire": [
{
"id": "2",
"facility_id": "2",
"period_from": "2024-04-23 12:00:00",
"period_to": "2024-04-23 13:00:00",
"length": "1 hour",
"amount": "55.00",
"per_adult": "0.00",
"per_child": "0.00",
"per_infant": "0.00",
"per_animal": "0.00",
"tax_free": "0",
"adults": "1",
"children": "0",
"infants": "0",
"animals": "0",
"hire_account_for_id": "51",
"hire_account_for_name": "John Doe",
"hire_account_for": "guests",
"hire_account_balance": "0.00",
"billing_account_for_id": "51",
"billing_account_for_name": "John Doe",
"billing_account_for": "guests",
"billing_account_balance": "55.00",
"inventory_item_id": "2",
"gl_category_id": "1",
"gl_account_id": "9",
"description": "Kayak Hire",
"override_tax_rate_ids": [],
"units": 1
}
]
}
Example Booking Detail Attributes on charges, credits, payments, refunds when client_account_booking_details is true.
e.g.
{
"guest_visible": "1",
"discounts_apply": "1",
"booking_id": "1234",
"booking_name": "John Doe",
"booking_status": "Confirmed",
"booking_site_id": "2",
"booking_period_from": "2024-04-19 11:30:00",
"booking_period_to": "2024-04-20 14:00:00",
"booking_reference_id": "",
"activity_booked_id": null
}
Response Notes:
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: Get Example
Guests: Update
Update an existing Guest.
Request Notes:
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.
To update an existing Equipment for this Guest (optional):
- Specify the equipment_id of the existing equipment within the equipment array.
- Omit equipment_id or set to null to allow creating a new equipment or automatically updating an existing equipment if a duplicate is found based on all possible equipment properties.
Guests: Update Example
Guests: Deletion History
Retrieves a list of Guest ID's that have been deleted from Newbook.
Request Notes:
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
Guests: Deletion History Example
Memberships: List
Pull the list of Memberships from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Memberships
Response Notes:
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
Memberships: List Example
Membership: Purchase
Grant a Membership to one of the connected Membership Types to an existing Guest
Request Notes:
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.
Membership: Purchase Example
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 be reversed, so please ensure you are merging the correct guests.
Request Notes:
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.
Guests: Merge Example
Member Transactions: List
Retrieve a list of transactions made by Members, including details such as tax amounts and booking details.
Only transactions related to Bookings where a Guest Membership was used will be returned.
Request Notes:
membership_type_id (int, required) An existing Membership Type ID to retrieve transactions for.
period_from (datetime, defaults to today).
period_to (datetime, defaults to today).
transaction_types (array, one or more of charges/credits/payments/refunds, defaults to all).
include_booking_details (boolean, defaults to true) This can be optionally provided and set as false to limit results to not show the booking details.
include_taxes (boolean, defaults to false) This can be optionally provided to include the tax amounts of each transaction.
booking_status (array, defaults to all) This can be optionally provided to limit results to a list of particular Booking Statuses.
When booking_status is provided, the period_from and period_to parameters are used to find Bookings that reached one of the provided statuses within the date range. All transactions related to the matching Bookings will be returned.
When booking_status is NOT provided, the period_from and period_to parameters are used to find any transactions that were generated within the date range.
Response Notes:
Each Transaction Type details its Transactions in an array.
Member Transactions: List Example
Accommodation Categories: List
Retrieve a list of Accommodation Categories including all the stored information about the Category.
Request Notes:
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
Response Notes:
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 Categories: List Example
Accommodation Categories: Create
Create a new Accommodation Category.
Request Notes:
The following parameters are required:
- name (string)
- gl_category_id (int) an existing Sub Client Account ID
- gl_account_id (int) an existing active GL Account ID
The following parameters are optional:
- short_description (string)
- description (string)
- website_url (url)
- display_order (int) determines the display order
- preference_order (int)
- minimum_sites_online (int)
- minimum_sites_cm (int)
- online_bookings_future_days_minimum (int)
- online_bookings_future_days_maximum (int)
- cm_bookings_future_days_minimum (int)
- cm_bookings_future_days_maximum (int)
- bookings_split_after (int)
- bookings_split_count (int)
- bookings_split_length (int)
- cm_bookings_split_after (int)
- cm_bookings_split_count (int)
- cm_bookings_split_length (int)
- max_adults (int|null)
- max_children (int|null)
- max_infants (int|null)
- max_animals (int|null)
- min_combined (int|null)
- max_combined (int|null)
- tax_free (boolean)
- system_template_receipts (int) an existing system template ID for receipts
- system_template_invoices (int) an existing system template ID for invoices
- system_template_clients_account_statement (int) an existing system template ID for client account statements
- system_template_receipts_trust (int) an existing system template ID for trust receipts
- system_template_invoices_trust (int) an existing system template ID for trust invoices
- system_template_clients_account_statement_trust (int) an existing system template ID for trust client account statements
- housekeeping (boolean) if the Category requires housekeeping
- occupancy (boolean) whether the Category will contribute to occupancy reports
- allow_dirty_bookings (boolean)
- allow_same_day_backtoback (boolean)
- allow_same_day_access_card_unavailable (boolean)
-
booking_action (string) action required when booking is placed. From the following list:
- do_nothing
- owner_approve
- instance_channel_manager_id (int) an existing channel manager ID
- cm_roomcode (string)
- type_id (int) an existing accommodation category ID
- default_tariff_type (int)
-
placeholder_image (string) Newbook Online Placeholder Image from the following list:
- category-ship
- category-cabin
- category-tent
- category-caravan
- virtual_tour_url (url)
- active (boolean)
- features (array) an array of objects
-
images (array) an array of objects with the following format
- image_type_id (int) an existing Accommodation Image Type ID
- image_data (string) a Base64 encoded jpeg, png, or webp image
- image_file_name (string) optional, the image file name
- category_hybrid_remote_id - This is the identifier used on your external PMS (only available for Newbook Hybrid instances)
Accommodation Categories: Create Example
Accommodation Categories: Get
Retrieve an existing Accommodation Category record.
Request Notes:
category_id must be provided to retrieve the details of a particular Accommodation Category.
Response Notes:
The returned data from this request is identical to Accommodation Categories: List but for a specific Accommodation Category alone.
If no such Accommodation Category exists, the success response parameter will be "false" and no data will be returned.
Accommodation Categories: Get Example
Accommodation Categories: Update
Update an Accommodation Category.
Request Notes:
category_id is required to advise which Accommodation Category you are updating.
All other parameters are optional, and are defined in Accommodation Categories: Create.
Accommodation Categories: Update Example
Accommodation Features: List
Retrieve the list of possible Accommodation Features in Newbook.
Accommodation Features: List Example
Accommodation Sites: List
Pull the list of possible Sites from Newbook.
Request Notes:
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
Response Notes:
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 Example
Accommodation Sites: Get/Set Status
Retrieve/update the Status of a particular Site in Newbook.
Request Notes:
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:
- Clean
- Dirty
Response Notes:
message will be filled only when site_status is updated
Accommodation Sites: Get/Set Status Example
Site Maps
Pull a list of Site Maps and their Markers from Newbook.
map_id is optional and when provided Newbook will return Markers from that Map alone.
period_from and period_to are optional and when provided, Newbook will force the Map Markers to return only for Sites, and will also perform an availability validation for the date range indicated. Please note, the Site still needs to have a Tariff applied and available for use on a booking before you can consider it sellable. This request does not validate the Tariff aspect.
adults, children, infants and animals are optional and when provided, Newbook will force the Map Markers to return only for Sites, and will also perform an occupant validation for the numbers requested. Please note, the Site still needs to have a Tariff applied and applicable for the occupant numbers for use on a booking before you can consider it sellable. This request does not validate the Tariff aspect.
Site Maps Example
Sites: Get
Pull the information for a specific Site in Newbook.
Request Notes:
site_id is a required parameter and needs to be the ID of the Site you are looking up.
Response Notes:
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.
Sites: Get Example
Sites: Create
Create a new site for a particular Category.
Request Notes:
name must be provided. This is the name of the Site.
category_id must be provided. This needs to be a valid Category ID as per the Category: List.
Please see below for a list of optional details that can be provided for the Site.
- short_description
- description
- opened_on - Supports either "null" to remove the opening date or a date to set the opening date
- closed_on - Supports either "null" to remove the closing date or a date to set the closing date
- status - Either "Clean" or "Dirty"
- gl_category_id - An existing Sub Client Account ID
- gl_account_id - An existing active GL Account ID
- show_online - A boolean for whether the Site is available on Newbook Online
- overbooking - A boolean for whether the Site allows overbooking. Overbooking means that multiple Bookings can be made for the same period
- occupancy - A boolean for whether the Site will contribute to occupancy reports
- notes - An array of notes to add to the Site
- site_size_id - An existing Site Size ID to assign to the Site
- street - The street of where the Site is located
- city - The city for where the Site is located
- state_id - The state for where the Site is located. This needs to match a valid State ID from States List
- postcode - The postcode for where the Site is located
- country_id - The country for where the Site is located. This needs to match a valid Country ID from Countries List
- lat - The latitude for the Site
- long - The longitude for the Site
- display_order - An integer for the display order of the Sites
- level_id - The level of the Site. This needs to match a valid Level ID from Newbook
- manager_id - The Manager of a specific Site. This needs to match a valid User ID from Users: List
- pos_identifier - The POS Identifier for the Site. This is used for POS Integrations to easily charge back to particular Bookings on that Site
- default_security_area - This is the Default Security Area used for Access Control for this particular Site
- override_category_features - A boolean for whether the Site should override the specified Accommodation Features from the Category
- features - This is only applicable when the "override_category_features" setting is true. This is an array of objects
- metering_types - This is an array of Metering Type IDs. This needs to match a valid Metering Type ID from Metering Types: List
- site_hybrid_remote_id - This is the identifier used on your external PMS (only available for Newbook Hybrid instances)
Sites: Create Example
Sites: Update
Update the details of a particular site inside of Newbook.
Request Notes:
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.
- name - Changes the name of the Site
- short_description
- description
- opened_on - Supports either "null" to remove the opening date or a date to set the opening date
- closed_on - Supports either "null" to remove the closing date or a date to set the closing date
- category_id - An existing Category ID to change where the Site belongs
- status - Either "Clean" or "Dirty"
- gl_category_id - An existing Sub Client Account ID
- gl_account_id - An existing active GL Account ID
- show_online - A boolean for whether the Site is available on Newbook Online
- overbooking - A boolean for whether the Site allows overbooking. Overbooking means that multiple Bookings can be made for the same period
- occupancy - A boolean for whether the Site will contribute to occupancy reports
- notes - An array of notes to add to the Site
- site_size_id - An existing Site Size ID to assign to the Site
- street - The street of where the Site is located
- city - The city for where the Site is located
- state_id - The state for where the Site is located. This needs to match a valid State ID from States List
- postcode - The postcode for where the Site is located
- country_id - The country for where the Site is located. This needs to match a valid Country ID from Countries List
- lat - The latitude for the Site
- long - The longitude for the Site
- display_order - An integer for the display order of the Sites
- level_id - The level of the Site. This needs to match a valid Level ID from Newbook
- manager_id - The Manager of a specific Site. This needs to match a valid User ID from Users: List
- pos_identifier - The POS Identifier for the Site. This is used for POS Integrations to easily charge back to particular Bookings on that Site
- default_security_area - This is the Default Security Area used for Access Control for this particular Site
- override_category_features - A boolean for whether the Site should override the specified Accommodation Features from the Category
- features - This is only applicable when the "override_category_features" setting is true. This is an array of objects
- metering_types - This is an array of Metering Type IDs. This needs to match a valid Metering Type ID from Metering Types: List
- site_hybrid_remote_id - This is the identifier used on your external PMS (only available for Newbook Hybrid instances)
Sites: Update Example
Site Sizes: List
Returns a list of active Site Sizes.
Request Notes:
show_inactive is optional, default false, and when provided with a truthy value, it will include inactive Site Sizes in the response.
Response Notes:
site_count is the number of active Sites that the Site Size is associated with.
Site Sizes: List Example
Site Sizes: Create
Creates a Site Size.
Request Notes:
- name is required.
- online and active will default to true if not provided.
- width, length and height will default to 0 if not provided. If provided, the values must be numeric.
Site Sizes: Create Example
Site Sizes: Update
Updates an existing Site Size.
Request Notes:
site_size_id must be provided to update a particular Site Size details.
Please see below for a list of optional details that can be updated on the Site Size. At least one of these must be provided.
- name
- online - supports values like "true", false, 1.
- active - supports values like "true", false, 1.
- width - must be numeric.
- length - must be numeric.
- height - must be numeric.
Site Sizes: Update Example
Companies: List
Retrieve the list of Companies for recording non-Booking-specific charges.
Request Notes:
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 provided, 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)
Companies: List Example
Company Types: List
Retrieve the list of Company Types for limiting the Company List.
Company Types: List Example
Companies: Update
Update a particular Company
Request Notes:
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 provide update_existing_details as "false".
Alternatively you can manage the Contact Details in more depth as an array:
"contact_details": [
{
"id": 1,
"type": "phone",
"content": "0756554600",
"notes": "Office landline",
"allow_transactional": "1",
"allow_marketing": "1",
"remove": 0
},
{
"id": 2,
"type": "email",
"content": "support@newbook.cloud",
"notes": "Work email address",
"allow_transactional": "1",
"allow_marketing": "0",
"remove": 0
}
]
- id can be optionally provided when updating a Company to update or remove a particular Contact Detail
- type is required
- content is required
- notes is optional
- allow_transactional is optional and will default to true when not provided
- allow_marketing is optional and will use the Instance Setting Default when not provided
- remove is optional and when true it will remove the Contact Detail from the Company
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:
- content is required and should contain the content of the note to be added
- 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 page.
- task_list is optional and will default to false when note provided. This controls whether the note will display on any tasks lists.
Companies: Update Example
Companies Staff: List
Retrieve the list of Companies Staff for recording non-Booking-specific charges.
Request Notes:
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 provided, 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: List Example
Companies Staff: Update
Update a particular Company Staff
Request Notes:
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 provide update_existing_details as "false".
Alternatively you can manage the Contact Details in more depth as an array:
"contact_details": [
{
"id": 1,
"type": "phone",
"content": "0756554600",
"notes": "Office landline",
"allow_transactional": "1",
"allow_marketing": "1",
"remove": 0
},
{
"id": 2,
"type": "email",
"content": "support@newbook.cloud",
"notes": "Work email address",
"allow_transactional": "1",
"allow_marketing": "0",
"remove": 0
}
]
- id can be optionally provided when updating a Company Staff to update or remove a particular Contact Detail
- type is required
- content is required
- notes is optional
- allow_transactional is optional and will default to true when not provided
- allow_marketing is optional and will use the Instance Setting Default when not provided
- remove is optional and when true it will remove the Contact Detail from the Company Staff
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:
- content is required and should contain the content of the note to be added
- 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 page.
- task_list is optional and will default to false when note provided. This controls whether the note will display on any tasks lists.
Companies Staff: Update Example
Travel Agents: List
Retrieve the list of Travel Agents for recording non-Booking-specific charges.
Request Notes:
name is optional and when provided it will restrict the results to the matching Travel Agents
created_when is optional and when provided, 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)
Travel Agents: List Example
Events: List
Retrieve a list of Events within the given time period.
Request Notes:
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 |
- 1ignores Events of status Cancelled, and Quote
- 2shows only Events of status Ongoing
- 3shows only Events of status Quote
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)
Response Notes:
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.
Inventory Item data:
The inventory_item array holds all the Inventory Item objects on the Event.
- stay_cost_contribution indicates whether the amount Increases the price of each night, or if it is Excluded from the price of each night.
Events: List Example
Events: Get
Retrieve the details of a single Event.
Request Notes:
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)
Response Notes:
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 response account_breakdown is prefixed as event_account_breakdown to disambiguate against the other keys.
Events: Get Example
Leads: List
Retrieve/search the Leads database.
Request Notes:
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 provided, restricts the returned Leads to only those which were created on the date given
staff_id is optional and when provided, restricts the returned Leads to those assigned to that User (see Users: List)
- You can provide staff_id_include as false to show Leads not assigned to that User
- If you provide unassigned into the request parameter staff_id Leads that are unassigned will be returned
- staff_id can be an array of User IDs
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)
Response Notes:
contact_details and custom_fields are arrays which will be empty when no data of that type is available
Leads: List Example
Leads: Create
Create a Lead within Newbook.
Request Notes:
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 provide update_existing_details as "false".
Alternatively you can manage the Contact Details in more depth as an array:
"contact_details": [
{
"id": 1,
"type": "phone",
"content": "0756554600",
"notes": "Office landline",
"allow_transactional": "1",
"allow_marketing": "1",
"remove": 0
},
{
"id": 2,
"type": "email",
"content": "support@newbook.cloud",
"notes": "Work email address",
"allow_transactional": "1",
"allow_marketing": "0",
"remove": 0
}
]
- id can be optionally provided when updating a Lead to update or remove a particular Contact Detail
- type is required
- content is required
- notes is optional
- allow_transactional is optional and will default to true when not provided
- allow_marketing is optional and will use the Instance Setting Default when not provided
- remove is optional and when true it will remove the Contact Detail from the Lead
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:
- content is required and should contain the content of the note to be added
- 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 page.
- task_list is optional and will default to false when note provided. This controls whether the note will display on any tasks lists.
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:
- false: do not find duplicates
- name: Name only
- phone: Phone only
- email: Email only
- name_and_phone: Name and Phone
- name_and_email: Name and Email
- name_and_email_and_phone: Name and Email and Phone
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.
If specified, custom_fields must be based on the response to the Custom Fields request, to retrieve the different Custom Fields set up in the instance:
"custom_fields": [
{
"field_id": 2,
"field_value": 8
}
]
Leads: Create Example
Leads: Update
Update an existing Lead within Newbook.
Request Notes:
lead_id is required
All other parameters are optional, please see Leads: Create for more details.
Leads: Update Example
Leads: Activity History
Retrieve Activity History for an existing Lead within Newbook.
Request Notes:
lead_id is required
Leads: Activity History Example
Lead Categories: List
Retrieves the list of available Lead Categories.
Lead Categories: List Example
Lead Interests: List
Retrieves the list of available Lead Interests.
Lead Interests: List Example
Lead Sources: List
Retrieves the list of available Lead Sources.
Lead Sources: List Example
Lead Sources: Create
Create a new Lead Source within Newbook.
Lead Sources: Create Example
Lead Statuses: List
Retrieves the list of available Lead Statuses.
Response Notes:
The IDs of the Lead Statuses in the example here are negative; these are defaults Newbook creates
Lead Statuses: List Example
Lead Types: List
Retrieves the list of available Lead Types.
Lead Types: List Example
Security Gates: List
Retrieve the list of Security Gates configured within Newbook
Security Gates: List Example
Security Areas: List
Retrieve the list of Security Areas configured within Newbook.
Response Notes:
security_gates contains the list of Gates the Security Area is authorised for.
Security Areas: List Example
Access Codes: List
Retrieve the Access Codes valid within the current 48 hour window (+ and - 24 hours).
Request Notes:
created_when is optional and when provided, restricts the returned Access Codes to only those which were created on the date given
Send access_code_mappings as true to also return a list of Access Code mapping details to other software integrations such as Access Control Systems.
Response Notes:
The booking data fields are returned if the access_code given is related to a Booking
Access Codes: List Example
Access Codes: Search
Searches Access Codes valid within the current 48 hour window (+ and - 24 hours).
Request Notes:
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
Send access_code_mappings as true to also return a list of Access Code mapping details to other software integrations such as Access Control Systems.
Response Notes:
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: Search Example
Access Codes: Push History
Records access history for particular Access Codes and their Bookings.
Request Notes:
access_history an array of individual access attempts, containing:
- access_code_id is required
- booking_id is optional; if not provided Newbook will try to determine the Booking based on the Access Code record in the database
- security_gate_id is required. It can be determined from the Security Gates: List request
- description is required to specified what happened for this entry.
- granted is optional. If not provided Newbook will determine this based on the description being "success"
- timestamp is optional. If not provided it will default to the current timestamp
Access Codes: Push History Example
Access Codes: Get History
Returns access history for particular Access Codes.
Request Notes:
Can be provided any combination of the below filters to limit results:
- access_code_id, booking_id and security_gate_id are allowed to be integers or arrays of integers corresponding to particular values found in Newbook.
- description is allowed to be a string or an array of strings and will only find exact matches for the description specified.
- period_from and period_to will restrict history to results from later or earlier than the specified times respectively. Both can be provided to find results from a specific period.
Access Codes: Get History Example
GL Accounts: List
Pull the list of GL Accounts from within Newbook.
Request Notes:
id, 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)
show_inactive is optional, default false, and when provided with a truthy value, it will include inactive GL Accounts in the response.
Response Notes:
If refundable is set to 1 (true) it means any charges raised in this GL Account 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)
GL Accounts: List Example
GL Accounts: Create
Creates a GL Account.
Request Notes:
- code is required.
- name is required.
- long_description
- refundable will default to false if not provided.
- reportable will default to true if not provided.
- gl_group_id must match the ID of an existing GL Account Group ID found at GL Accounts Groups: List if provided.
- active will default to true if not provided.
GL Accounts: Create Example
GL Accounts: Update
Updates an existing GL Account.
Request Notes:
gl_account_id must be provided to update a particular GL Accounts details.
Please see below for a list of optional details that can be updated on the GL Account. At least one of these must be provided.
- code
- name
- long_description
- refundable - supports values like "true", false, 1.
- reportable - supports values like "true", false, 1.
- active - supports values like "true", false, 1.
- gl_group_id must match the ID of an existing GL Account Group ID found at GL Accounts Groups: List if provided.
GL Accounts: Update Example
GL Accounts Groups: List
Pull the list of GL Account Groups from within Newbook.
Request Notes:
show_inactive is optional, default false, and when provided with a truthy value, it will include inactive GL Account Groups in the response.
id can also be optionally provided to filter results to a particular GL Account Group ID.
GL Accounts Groups: List Example
GL Accounts Groups: Create
Creates a GL Account Group.
Request Notes:
- name is required.
- prefix
- active will default to true if not provided.
GL Accounts Group: Create Example
GL Accounts Groups: Update
Updates an existing GL Account Group.
Request Notes:
gl_account_group_id must be provided to update a particular GL Account Groups details.
Please see below for a list of optional details that can be updated on the GL Account Group. At least one of these must be provided.
- name
- prefix
- active - supports values like "true", false, 1.
GL Accounts Group: Update Example
Sub Client Accounts: List
Pull the list of Sub Client Accounts (aka GL Categories) from within Newbook.
Sub Client Accounts: List Example
Clients Accounts: List
Retrieve a list of Client Accounts.
Request Notes:
for (optional): An array of the type of Client Account to return
account_breakdown, client_account_tax_reconciliation and client_account_item_breakdown can optionally be provided to return additional information about the Client Account. Please see Clients Accounts: Get for more details.
Clients Accounts: List Example
Clients Accounts: Get
Retrieve a particular Client Account.
Request Notes:
account_id: The Account ID to query
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
e.g.
{
"account_breakdown": [
{
"name": "Accommodation",
"gl_category_id": "1",
"balance": "0.00"
},
{
"name": "Extras",
"gl_category_id": "2",
"balance": "12.00"
}
]
}
client_account_tax_reconciliation can optionally be provided as true to include the amount of tax based on the reconciliation of payments / refunds. The below client_account_item_breakdown will also need to be provided as true for this to function.
client_account_item_breakdown can optionally be provided as true to include all accounting items saved on the Group Client Account in the Group response.
Example response when client_account_item_breakdown is true:
{
"charges": [
{
"id": "3062",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Standard Rate (2024-04-19)",
"amount": 100,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "tariffs_quoted",
"link_type_id": "123",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": "9.09"
}
]
}
],
"credits": [
{
"id": "4351",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Discount",
"amount": 5,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "discounts_quoted",
"link_type_id": "1024",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": 0.45
}
]
}
],
"payments": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"paid_by": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Accommodation",
"amount": 100,
"tendered": 100,
"type": "cash",
"type_id": "4",
"type_reference": "",
"deposit": "0",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [],
"charges": [
{
"link_id": 1,
"charge_id": 3062,
"reconciled_amount": 100,
"timestamp": "2024-04-19",
"voided_when": null
}
]
}
],
"refunds": [
{
"id": "2",
"account_id": "1796594",
"gl_category_id": "1",
"refunded_to": "135576",
"transaction_method": "manual",
"transaction_id": null,
"disbursed_booking_id": null,
"disbursed_gl_account_id": null,
"description": "Refunding Discount Overpayment",
"amount": 5,
"tendered": 5,
"type": "cash",
"type_id": "4",
"type_reference": "",
"generated_by": "1",
"generated_when": "2024-04-19",
"voided_by": "0",
"voided_when": null,
"credits": [
{
"link_id": 1,
"credit_id": 4351,
"reconciled_amount": 5,
"timestamp": "2024-04-19",
"voided_when": null
}
],
"payments": []
}
]
}
Example Booking Detail Attributes on charges, credits, payments, refunds when client_account_booking_details is true.
e.g.
{
"guest_visible": "1",
"discounts_apply": "1",
"booking_id": "1234",
"booking_name": "John Doe",
"booking_status": "Confirmed",
"booking_site_id": "2",
"booking_period_from": "2024-04-19 11:30:00",
"booking_period_to": "2024-04-20 14:00:00",
"booking_reference_id": "",
"activity_booked_id": null
}
Clients Accounts: Get Example
Charges: Create
Used to charge to a Client Account.
Request Notes:
account_id: The Client Account ID retrieved in a previous request
generated_by (int, optional): The User ID to set who generated the charge. Defaults to the User ID making the 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:
- cash
- cheque
- visa
- mastercard
- amex
- diners
- discover
- jcb
- eftpos
- eft (online banking funds transfer)
- eurocard
- bartercard
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
link_type (optional): tells Newbook which item this charge is linked to:
- tariffs_quoted
- repeat_charges
- bookings_inventory_items
- facilities_hire
- bookings_adjustment_fees
- bookings_groups_inventory_items
- bookings_groups_adjustment_fees
- meter_readings
- meter_services - This relates to a meter reading
link_type_id (required when link_type is provided): tells Newbook the ID of the associated link_type provided as specified above
link_period_from (optional): This is only used when the link_type/link_type_id is provided. This states the applicable start date of the link formatted as YYYY-MM-DD
link_period_to (optional): This is only used when the link_type/link_type_id is provided. This states the applicable end date of the link formatted as YYYY-MM-DD
Response Notes:
If payment_type was provided in the request, you will receive a payment_id in the response
Charges: Create Example
Charges: List
Used to retrieve a list of Charges
Request Notes:
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:
- leads
- guests
- bookings
- companies
- travel_agents
period_from + period_to: Can optionally be provided together to find Charges raised or voided within that time period.
Charges: List Example
Charges: Get
Retrieve a particular Charge
Request Notes:
id (int) the Charge ID to retrieve (required)
The other filtering parameters per Charges: List apply here but are optional.
Charges: Get Example
Credits: Create
Used to add negative charges to a Client Account (not to be used for payments - that is a separate request).
Request Notes:
account_id: The Client Account ID retrieved in a previous request
generated_by (int, optional): The User ID to set who generated the credit. Defaults to the User ID making the 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:
- cash
- cheque
- visa
- mastercard
- amex
- diners
- discover
- jcb
- eftpos
- eft (online banking funds transfer)
- eurocard
- bartercard
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
link_type (optional): tells Newbook which item this credit is linked to:
- discounts_quoted
- bookings_inventory_items
- repeat_charges
- meter_rebates - This relates to a meter reading
- bookings_groups_inventory_items
link_type_id (required when link_type is provided): tells Newbook the ID of the associated link_type provided as specified above
link_period_from (optional): This is only used when the link_type/link_type_id is provided. This states the applicable start date of the link formatted as YYYY-MM-DD
link_period_to (optional): This is only used when the link_type/link_type_id is provided. This states the applicable end date of the link formatted as YYYY-MM-DD
Response Notes:
If refund_type was provided in the request, you will receive a refund_id in the response
Credits: Create Example
Credits: List
Used to retrieve a list of Credits
Request Notes:
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:
- leads
- guests
- bookings
- companies
- travel_agents
period_from + period_to: Can optionally be provided together to find Credits raised or voided within that time period.
Credits: List Example
Credits: Get
Retrieve a particular Credit
Request Notes:
id (int) the Credit ID to retrieve (required)
The other filtering parameters per Credits: List apply here but are optional.
Credits: Get Example
Transaction Fees: Get
Used to calculate Transaction Fees for the requested Payment Type
Request Notes:
amount (required): The amount to calculate transaction fee.
type (required): Please see the Payment Types request for a list of valid types.
Transaction Fees: Get Example
Payments: Create
Used to add payments to a Client Account.
Request Notes:
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_by (int, optional): The User ID to set who generated the payment. Defaults to the User ID making the request.
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.
Recording Credit Card Transactions (optional)
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:
- type_reference (required): The Transaction ID from the Credit Card Gateway
- cc_name (required): The name on the Credit Card
- cc_last_digits (required): This must be the Last 4 digits of the Credit Card
- cc_gateway (required): The type of Credit Card Gateway, will be provided by 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: Create Example
Payments: List
Used to retrieve a list of Payments
Request Notes:
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:
- leads
- guests
- bookings
- companies
- travel_agents
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"
Response Notes:
You can run the Payments Types request to get the list of possible Payment Types.
transaction_method can be one of the following:
- manual - a manually recorded Payment
- cc_gateway - processed through a Credit Card Gateway
- dd_gateway - processed through a Direct Debit Gateway
- eftpos_terminal - processed through an Eftpos Terminal
Payments: List Example
Payments: Get
Retrieve a particular Payment
Request Notes:
id (int) the Payment ID to retrieve (required)
The other filtering parameters per Payments: List apply here but are optional.
Credits: Get Example
Payments Reconciliation: Create
Creates a Payments Reconciliation that links a Payment to Charges and/or Credits
Request Notes:
The following parameters are required:
- payment_id (int)
- credits (array) *
- charges (array) *
The following parameters are optional:
- timestamp (timestamp: yyyy-mm-dd 24hh:mi:ss)
Payments Reconciliation: Create Example
In the below example the payment would require an amount of $10 to balance.
Payment Types
Pull a list of Payment / Refund Types from Newbook.
Payment Types Example
Refunds: Create
Used to add refunds to a Client Account.
Request Notes:
account_id: The Client Account ID retrieved in a previous request
generated_by (int, optional): The User ID to set who generated the refund. Defaults to the User ID making the 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: Create Example
Refunds: List
Used to retrieve a list of Refunds
Request Notes:
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:
- leads
- guests
- bookings
- companies
- travel_agents
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"
Response Notes:
You can run the Payments Types request to get the list of possible Refund Types.
transaction_method can be one of the following:
- manual - a manually recorded Payment
- cc_gateway - processed through a Credit Card Gateway
- dd_gateway - processed through a Direct Debit Gateway
- eftpos_terminal - processed through an Eftpos Terminal
Refunds: List Example
Refunds: Get
Retrieve a particular Refund
Request Notes:
id (int) the Refund ID to retrieve (required)
The other filtering parameters per Refunds: List apply here but are optional.
Credits: Get Example
Refunds Reconciliation: Create
Creates a Refunds Reconciliation that links a Refund to Credits and/or Payments
Request Notes:
The following parameters are required:
- refund_id (int)
- credits (array) *
- payments (array) *
The following parameters are optional:
- timestamp (timestamp: yyyy-mm-dd 24hh:mi:ss)
Refunds Reconciliation: Create Example
In the below example the refund would require an amount of $100 to balance.
Credit Card Authorisation: Create
Used to store a Credit Card Authorisation Token created outside of Newbook
The Credit Card Authorisation Token must be created using the same credit card gateway account as used in Newbook otherwise processing payments will fail
Request Notes:
for (string) required: Must be one of the following:
- guests
- leads
- users
- companies
- companies_staff
- travel_agents
- travel_agents_staff
for_id (integer) required: ID of the above entity to create the credit card authorisation token against
token (string) required: Credit card token created using the same credit card gateway account as used in Newbook
last_digits (string) required: Last 4 digits of the credit card number to be displayed within the Newbook interface
card_name (string) optional: The name on the card
card_type (string) required: Must be one of the results from Payment Types which is marked as is_card=1
expiry (object) required: A future credit card expiry date. An object matching this format:
{
month: "MM",
year: "YYYY"
}
gateway_id: Can optionally store the credit card authorisation token against a specific Newbook credit card gateway connection other than the default
Credit Card Authorisation: Create Example
Credit Card Authorisation Token: Update
Used to update a stored Credit Card Authorisation Token
Request Notes:
id (integer) required: ID of the existing Credit Card Authorisation Token
for (string) required: Must be one of the following:
- guests
- leads
- users
- companies
- companies_staff
- travel_agents
- travel_agents_staff
The "for_id" of a Credit Card Authorisation Token cannot be changed. If this is required, it is advised to use the Credit Card Authorisation Delete method for the incorrect for_id, then use the Credit Card Authorisation Create method, with the correct for_id.
token (string) optional: Credit card token created using the same credit card gateway account as used in Newbook
last_digits (string) optional: Last 4 digits of the credit card number to be displayed within the Newbook interface
card_name (string) optional: The name on the card
card_type (string) optional: Must be one of the results from Payment Types which is marked as is_card=1
expiry (object) optional: A future credit card expiry date. An object matching this format:
{
"month": "MM",
"year": "YYYY"
}
Credit Card Authorisation Token: Update Example
Credit Card Authorisation Token: Delete
Used to delete a stored Credit Card Authorisation Token
Request Notes:
id (integer) required: ID of the existing Credit Card Authorisation Token
for (string) required: Must be one of the following:
- guests
- leads
- users
- companies
- companies_staff
- travel_agents
- travel_agents_staff
Credit Card Authorisation Token: Delete Example
Direct Debit Authorisations: List
Pull the list of Direct Debit Authorisations from within Newbook for a specific entity type.
Request Notes:
for (string) required: Must be one of the following entity types:
- guests
- companies
- companies_staff
- travel_agents
- travel_agents_staff
- users
- leads
- bank_accounts
- owners
for_id can be provided to limit results to a specific entity, e.g. a single Guest, by providing the Guest ID.
status can be provided to limit results to a specific status. See Direct Debit Authorisations: Create for more details.
Direct Debit Authorisations: List Example
Direct Debit Authorisations: Get
Retrieve an existing Direct Debit Authorisation from within Newbook for a specific entity.
Request Notes:
id (int) required: ID of the existing Direct Debit Authorisation
for (string) required: Must be one of the following entity types:
- guests
- companies
- companies_staff
- travel_agents
- travel_agents_staff
- users
- leads
- bank_accounts
- owners
Direct Debit Authorisations: Get Example
Direct Debit Authorisations: Create
Used to create a Direct Debit authorisation.
Request Notes:
for (string): Must be one of the following entity types:
- guests
- companies
- companies_staff
- travel_agents
- travel_agents_staff
- users
- leads
- bank_accounts
- owners
for_id (int): ID of the above entity to create the Direct Debit Authorisation for
bank_name (string): The name of the bank
bank_account_name (string): The bank account name
bank_account_number (string): The bank account number
bank_bsb_number (string): The bank BSB/routing number
status (int) optional: Must be one of the following:
- 1 - Pending Approval (default)
- 2 - Approved Manually
- 3 - Approved Signature
- 4 - Approved Payment Plan
- 5 - Deactivated
authorised_amount (float|null) optional: The amount to authorise for Direct Debits. 0 or null means unlimited.
apply_to_client_account_gl_categories (array, optional): One or more Sub Client Accounts to apply the Direct Debit Authorisation to within the Client Account for the entity, with the following parameters for each entry:
- gl_category_id (int) required: The ID of the Sub Client Account to apply the new Direct Debit Authorisation to as the Primary Authorisation
- primary_authorisation_auto_debit (int): Must be one of the following:
- 0 - No, batch/auto debit disabled (default)
- 1 - Manual, only batch debit enabled
- 2 - Auto, batch and auto debit enabled
- batch_debit_profile_id (int|null) optional: Must be an existing Clients Accounts Profiles ID or null to leave this unset
- auto_billing_limit (float|null) optional: The Direct Debit limit for this Sub Client Account. 0 or null means unlimited.
Note: the Direct Debit Authorisation status must be one of the approved states (2, 3 or 4) to allow apply_to_client_account_gl_categories to be applied.
Direct Debit Authorisations: Create Example
Direct Debit Authorisations: Update
Used to update an existing Direct Debit authorisation.
Request Notes:
id (int) required: ID of the existing Direct Debit Authorisation to update
for (string) required: Must be one of the following entity types:
- guests
- companies
- companies_staff
- travel_agents
- travel_agents_staff
- users
- leads
- bank_accounts
- owners
The "for_id" of a Direct Debit Authorisation Token cannot be changed. If this is required, it is advised to simply use the Direct Debit Authorisation Create method, with the correct for_id.
See Direct Debit Authorisations: Create for more details.
Direct Debit Authorisations: Update Example
3rd Party Tax Rates
Used to retrieve Tax Rates that can be used when creating Charges / Credits with custom Tax Amounts.
3rd Party Tax Rates Example
Quotes: List (CRM)
Used to retrieve a list of Quotes
Request Notes:
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:
- leads
- guests
- bookings
- companies
- travel_agents
period_from + period_to: Can optionally be provided together to find Invoices generated or voided within that time period.
Quotes: List (CRM) Example
Quotes: PDF Content (CRM)
Used to retrieve the PDF content for a Quote.
Quotes: PDF Content (CRM) Example
Invoices: List
Used to retrieve a list of Invoices
Request Notes:
id (int) a specific Invoice ID to retrieve (optional)
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:
- leads
- guests
- bookings
- companies
- travel_agents
invoiced_to: Can optionally filter the list by one or more Client Account ID's Invoiced To.
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).
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"
fetch_items_booking_details can optionally be provided as true to include Booking details for Charges and Credits. The below fetch_items will also need to be provided as true for this to function.
fetch_items can optionally be provided as true to include all Charges and Credits saved on the Invoice.
Example response when fetch_items is true:
{
"items": [
{
"id": "3062",
"type": "charges",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Standard Rate (2024-04-19)",
"amount": 100,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "tariffs_quoted",
"link_type_id": "123",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": "9.09"
}
]
},
{
"id": "4351",
"type": "credits",
"account_id": "1796594",
"gl_category_id": "1",
"gl_account_id": "32",
"description": "Discount",
"amount": 5,
"tax_free": "0",
"generated_by": "1",
"generated_when": "2024-04-19 11:30:00",
"inventory_item_id": null,
"voided_by": "0",
"voided_when": null,
"link_type": "discounts_quoted",
"link_type_id": "1024",
"link_period_from": "2024-04-19",
"link_period_to": "2024-04-19",
"taxes": [
{
"tax_id": 1,
"tax_name": "GST",
"tax_inclusive": true,
"tax_amount": 0.45
}
]
}
]
}
Invoices: List Example
Invoices: Get
Retrieve a particular Invoice
Request Notes:
id (int) the Invoice ID to retrieve (required)
The other filtering parameters per Invoices: List apply here but are optional.
Invoices: Get Example
Invoices: PDF Content
Used to retrieve the PDF content for an Invoice.
Invoices: PDF Content Example
Receipts: List
Used to retrieve a list of Receipts
Request Notes:
id (int) a specific Receipt ID to retrieve (optional)
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:
- leads
- guests
- bookings
- companies
- travel_agents
receipted_to: Can optionally filter the list by one or more Client Account ID's Receipted To.
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"
Response Notes:
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: List Example
Receipts: Get
Retrieve a particular Receipt
Request Notes:
id (int) the Receipt ID to retrieve (required)
The other filtering parameters per Receipts: List apply here but are optional.
Receipts: Get Example
Receipts: PDF Content
Used to retrieve the PDF content for a Receipt.
Receipts: PDF Content Example
Contact Templates: List
Retrieve a list of available Contact Templates for sending.
Request Notes:
return_all_types is optional, and will default to false when not provided.
Response Notes:
type will always be "body" or "sms", unless return_all_types is true, which can be one of the following:
- body - indicates an Email template
- sms - indicates an SMS template
- signed_document - indicates an e-Signature Document template
- internal_document - indicates an Internal Document template
- header - indicates a Header template
- footer - indicates a Footer template
- insert_field - for Insert Fields
- guestassist - for App Message templates
bind the type of object the template can be sent to e.g. bookings, guests, etc
Contact Templates: List Example
Contact Templates: Send
Send a Contact Template.
Request Notes:
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
- html_email - used for HTML emails
- pdf_email - will attach the Template Body as a PDF and use the Email HTML in the Email
- sms - used for SMS messages
Contact Templates: Send Example
Contact Templates: Create
Used to create new Contact Templates
Response Notes:
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:
- bind
- pdf_size
- type
- favourites
- sending_type
- send_via
- header
- email_header
- footer
- email_footer
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: Create Example
Contact Templates: Get
Used to retrieve a Contact Template
Response Notes:
Retrieve a contact template by providing its id
Returns all fields, even if they were not provided when the template was created
Contact Templates: Get Example
Contact Templates: Update
Update an existing Contact Template.
Response Notes:
id is required, all other fields are optional
The other fields are the same as those provided in Contact Templates: Create
Contact Templates: Update Example
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
Contact Templates: Update Example
System Templates: List
Retrieve a list of available System Templates.
Response Notes:
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: List Example
System Templates: Create
Used to create new System Templates
Response Notes:
name, description and content are required, the rest are optional.
If email_subject is left blank then name will be used instead.
Valid fields:
- name
- description
- content
- email_subject
- pdf_size
- bind
- table_font_size
- table_group_by
- type
- letterhead
- header
- footer
System Templates: Create Example
System Templates: Get
Used to retrieve a System Template
Response Notes:
Retrieve a system template by providing its id
Returns all fields, even if they were not provided when the template was created
System Templates: Get Example
System Templates: Update
Used to update a System Template
Response Notes:
Any field except ID can be updated
last_updated is set to the time that the request is processed
Valid fields:
- name
- description
- content
- email_subject
- pdf_size
- bind
- table_font_size
- table_group_by
- type
- letterhead
- header
- footer
System Templates: Update Example
Contact Emails: Create
Used to create an historical entry for an email sent.
Request Notes:
All fields except for the real_recipient_type and real_recipient_id are required and documented below:
- name the name / subject of the email
- recipient_type the type of recipient the email will be recorded against. The available options are:
- guests
- bookings
- bookings_groups
- events
- activities_bookings
- companies
- companies_staff
- travel_agents
- travel_agents_staff
- users
- facilities_hire
- appointments
- recipient_id the ID of the recipient based on the recipient_type above
- real_recipient_type the actual recipient the email was sent to. E.g. this will be the guest for a booking
- real_recipient_id the ID of the recipient based on the real_recipient_type above
- recipient_name the name of the recipient the email was sent to
- content the content of the email
- sender the name of the person who sent the email
- sent_by the User who sent the email, and should be a valid User ID as per the Users: List
- sent_on the timestamp of when the email was sent
Contact Emails: Create Example
Contact SMS: Create
Used to create an historical entry for an sms sent.
Request Notes:
All fields except for the real_recipient_type and real_recipient_id are required and documented below:
- name the name / subject of the sms
- recipient_type the type of recipient the sms will be recorded against. The available options are:
- guests
- bookings
- bookings_groups
- events
- activities_bookings
- companies
- companies_staff
- travel_agents
- travel_agents_staff
- users
- facilities_hire
- appointments
- recipient_id the ID of the recipient based on the recipient_type above
- real_recipient_type the actual recipient the sms was sent to. E.g. this will be the guest for a booking
- real_recipient_id the ID of the recipient based on the real_recipient_type above
- recipient_name the name of the recipient the sms was sent to
- content the content of the sms
- sender the name of the person who sent the sms
- sent_by the User who sent the sms, and should be a valid User ID as per the Users: List
- sent_on the timestamp of when the sms was sent
Contact SMS: Create Example
Contact Documents: List
Retrieve a list of contact documents for a given recipient.
Request Notes:
You can either provide recipient_type and recipient_id, or ids, or all of them.
recipient_type (string) required if recipient_id is provided - Entity type, this determines what the recipient_id field references.
"bookings": Contact Documents linked to a Booking ID"bookings_groups": Contact Documents linked to a Booking Group ID"events": Contact Documents linked to an Event ID"guests": Contact Documents linked to a Guest ID"companies": Contact Documents linked to a Company ID"companies_staff": Contact Documents linked to a Company Staff ID"travel_agents": Contact Documents linked to a Travel Agency ID"travel_agents_staff": Contact Documents linked to a Travel Agent Staff ID"quotes": Contact Documents linked to a Quote ID"subscriptions": Contact Documents linked to a Subscription ID"invoices": Contact Documents linked to an Invoice ID"receipts": Contact Documents linked to a Receipt ID"clients_accounts": Contact Documents linked to a Client Account ID"access_codes": Contact Documents linked to an Access Code ID"owners": Contact Documents linked to an Owner ID"gift_vouchers_codes": Contact Documents linked to a Gift Voucher ID"users": Contact Documents linked to an User ID"leads": Contact Documents linked to a Lead ID"purchase_orders": Contact Documents linked to a Purchase Order ID"availability_emails": Contact Documents linked to an Availability Email ID"activities_bookings": Contact Documents linked to an Activity ID"tickets": Contact Documents linked to a Ticket ID"tasks": Contact Documents linked to a Task ID"facilities_hire": Contact Documents linked to a Facility Hire ID"appointments": Contact Documents linked to an Appointment ID"jobs": Contact Documents linked to a Job ID
recipient_id (int) required if recipient_type is provided - ID of the recipient.
ids (array of ints) required if both recipient_type and recipient_id are not provided - Contact Documents IDs to limit the list to specific set of Contact Documents.
Contact Documents: List Example
Contact Documents: Create
Request Notes:
Create a Contact Document for a recipient from a contact template.
data_type (string) required - Entity type, this determines what the data_id field references.
"bookings": Contact Documents linked to a Booking ID"bookings_groups": Contact Documents linked to a Booking Group ID
data_id (int) required - ID of the recipient.
template_id (int) required - ID of the Contact Template to create the Contact Document from.
duplicate (bool) optional, default: false - If false and the recipient already has a Contact Document created from the same Contact Template, that existing Contact Template is returned instead, otherwise a new Contact Document is created.
Contact Documents: Create Example
Contact Documents: Sign
Request Notes:
If the Contact Document is already signed, this signature will be discarded without any errors.
contact_document_id (int) required - ID of the Contact Document to add a signature to.
first_name (string) required - First name of the person singing.
last_name (string) required - Last name of the person singing.
signature_image (string) required - The image data in base64 encoded PNG format, starting with "data:image/png;base64,". E.g.: "data:image/png;base64,BASE64_ENCODED_PNG_IMAGE_DATA".
signed_long (float | null) optional, default null - Longitude of geo location where singing took place.
signed_lat (float | null) optional, default null - Latitude of geo location where singing took place.
Contact Documents: Sign Example
Reporting: Newbook Status
Pull data showing a wide range of information about the Instance.
Response Notes:
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: Newbook Status Example
Reporting: Earned Revenue
Pull data from the Earned Revenue Report for the dates specified.
Request Notes:
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: Earned Revenue Example
Reporting: Transaction Flow
Pull data from the Transaction Flow Report for the dates specified.
Reporting: Transaction Flow Example
Reporting: Reconciliation
Pull data from the Reconciliation Report for the dates specified.
Reporting: Reconciliation Example
Reporting: Daily Audit Summary
Pull data from the Daily Audit Summary for the dates specified.
Request Notes:
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
download_content_typecan be provided to return a url to the report. The value of this parameter can be either csv, pdf, xml or xlsx specifying the type of the file for the report to be created as.
Reporting: Daily Audit Summary Example
Reporting: Balances Dated
Pull data from the Balances Dated Report.
Request Notes:
period_from - which date to determine the balance as of (inclusive)
natures - determines which types of accounts will be displayed on the list:
- 0 - Debtors only
- 1 - Debtors and Creditors
- 2 - Creditors only
Reporting: Balances Dated Example
Reporting: Occupancy
Retrieves a list of Categories and their occupancy for the given period.
Request Notes:
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.
accomm_revenue_only can optionally be provided to return accommodation revenue only. This is disabled by default. Can be 0 or 1.
Response Notes:
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: Occupancy Example
Reporting: Inventory Items
Pull data from the Inventory Items Report for the dates specified.
Reporting: Inventory Items Example
Reporting: Survey Answers
Retrieves a list of Guests and their responses to Survey Questions, based off when the Guest answered.
Request Notes:
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:
- net_promoter_score
- one_to_ten
- text_field
- enum_field
- task_text_field
- multiple_answers
- multiple_text
active_only can optionally be provided to limit results to active surveys only
Reporting: Survey Answers Example
Reporting: Surveys Completed
Provides a breakdown of Surveys Sent vs Completed.
Request Notes:
period_range can be one of the following:
- day
- week
- month
- year
- financial_year
- custom
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
Reporting: Surveys Completed Example
Software Mappings: List
List Software Mappings.
Request Notes:
- id (integer) optional. A specific Software Mapping ID to retrieve.
- connection_id (integer) optional. Filter results by specific Software Connection ID.
- software (string) optional. Filters results by Software Connection name.
- software_provider (string) optional. Filters results by software provider.
- software_type (string) optional. Filters results by the data type of the software side of the mapping.
- sort_ascending (bool) optional, default false. Order results by oldest first when true.
Software Mappings: List Example
Software Mappings: Create
Creates a new Software Mapping.
Request Notes:
- connection_id (integer) required. The Software Connection ID to create the mapping for.
- software (string) required. The name of the Software Connection the mapping is for.
- software_type (string) required. The data type being mapped on the Software Connection side.
- software_type_id (string) required. The data identifier for the mapping on the Software Connection side.
- newbook_type (string) required. The Newbook data type being mapped.
- newbook_type_id (integer) required. The ID of the Newbook entity being mapped.
- software_provider (string) optional. Any data to associate the mapping to a specific provider.
- details (string) optional. Any other specific details to store with the mapping.
- export_hash (string) optional. Hash of the data when mapping was exported.
- last_export (DateTime) optional. The date/time the mapping was last exported.
Software Mappings: Create Example
Software Mappings: Get
Retrieve a single Software Mapping.
Request Notes:
- id (integer) required, an existing Software Mapping ID.
Software Mappings: Get Example
Software Mappings: Update
Updates an existing Software Mapping.
Request Notes:
- id (integer) required, the Software Mapping ID to update.
- See Software Mappings: Create for details on request parameters that can be updated.
Software Mappings: Update Example
Special Dates: List
List Special Dates.
Request Notes:
- id (integer) optional, a specific Special Date ID to retrieve.
- name (string) optional, filters results by name.
- period_from (date) optional, filters results by date range.
- period_to (date) optional, filters results by date range.
- show_inactive (bool) optional, default false. Include inactive Special Dates in the response by setting this true.
Special Dates: List Example
Special Dates: Create
Creates a new Special Date.
Request Notes:
- name (string) required. Max 200 characters.
- description (string) optional.
- period_from (date) required. The starting date of the Special Date.
- period_to (date) optional. When not provided, will default to period_from, making it a single day period.
- active (boolean) optional. Defaults to true.
- yearly_event (boolean) optional. Defaults to false. Whether this Special Date repeats every year. You still need to provide a period_from, but Newbook itself will automatically utilise this Special Date every year per the day & month provided.
- type_id (int), must be one of the following values:
- 1 = Special Date (default)
- 2 = Information. All settings below are ignored when using this type.
- public_holiday (boolean) optional. Defaults to false. Whether the Special Date is a public holiday.
- allow_arrivals_offline (boolean) optional. Defaults to true. Whether to allow arrivals on this date for Bookings made within Newbook.
- allow_arrivals_online (boolean) optional. Defaults to true. Whether to allow arrivals on this date for Bookings made via Newbook Online.
- allow_departures_offline (boolean) optional. Defaults to true. Whether to allow departures on this date for Bookings made within Newbook.
- allow_departures_online (boolean) optional. Defaults to true. Whether to allow departures on this date for Bookings made via Newbook Online.
- force_period_offline (boolean) optional. Defaults to false. Whether to force Bookings to Book the entire period of the Special Date for Bookings made within Newbook.
- force_period_online (boolean) optional. Defaults to false. Whether to force Bookings to Book the entire period of the Special Date for Bookings made via Newbook Online.
Special Dates: Create Example
Special Dates: Get
Retrieve a single Special Date.
Request Notes:
- id (integer) required, an existing Special Date ID.
- show_inactive (bool) optional, default true. Does not return the inactive Special Dates if this is set to false.
Special Dates: Get Example
Special Dates: Update
Updates an existing Special Date.
Request Notes:
- id (integer) required, the Special Date ID to update.
- See Special Dates: Create for details on request parameters that can be updated.
Special Dates: Update Example
Tasks: List
Retrieve a list of outstanding Tasks from Newbook
Request Notes:
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 provided, 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
Response Notes:
booking_site_id and booking_site_name are optionally returned when the Task is associated with a Booking
Tasks: List Example
Task Types: List
Retrieve a list of the different Task Types
Task Types: List Example
Tasks: Create
Create a new Task.
Request Notes:
location_type is required and must be one of:
- none
- accommodation_sites
- facilities
- bookings
- bookings_groups
- guests
- companies
- leads
- quotes
- tickets
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: Create Example
Tasks: Update
Mark an individual Task as Started or Completed.
Request Notes:
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:
- bookings
- bookings_groups
- accommodation_sites
- facilities
- companies
- companies_staff
- events
- leads
- quotes
- guests
- activities
Response Notes:
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
Tasks: Update Example
Tickets: List
Retrieve a list of all Tickets.
Request Notes:
account_id can optionally be provided to limit results to a particular Client Account
Response Notes:
Tickets can have a status and corresponding status_name of the following values:
- 0: Open
- 1: Closed
- 2: Waiting on Client
- 3: Waiting on Third Party
- 4: Invalid/Spam
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: List Example
Tickets: Get Example
Tickets: Create
Create a new Ticket.
Request Notes
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: Create Example
Tickets: Update
Update an existing Ticket.
Request Notes
ticket_id is required
status can optionally be provided, valid options include
- 0 - Open
- 1 - Closed
- 2 - Waiting on Client
- 3 - Waiting on Third Party
- 4 - Invalid
priority can optionally be provided, valid options include
- low - Low
- normal - Normal
- medium - Medium
- high - High
content can optionally be provided to add an additional response to the Ticket, the response will be treated as coming from the client
Tickets: Update Example
Ticket Queue: List
Retrieve a list of available Ticket Queues.
Ticket Queue: List Example
Notes: Create
Add a Note to an entity within the system (e.g. Booking, Guest, Lead or Quote).
Request Notes:
for must be one of the following values:
- accommodation_sites
- accommodation_categories
- appointment
- availability_emails
- bookings
- bookings_groups
- charges
- clients_accounts
- companies
- companies_staff
- credits
- equipment
- equipment_guests
- events
- events_packages
- facilities_hire
- guests
- instances_booking_channels
- invoices
- leads
- payments
- postmaster_accounts
- projects
- quotes
- receipts
- refunds
- tasks
- travel_agents
- travel_agents_staff
for_id corresponds to the particular for that this note will be attached to
type_id is optional, and will use the System Default if not provided as per the Note Types: List request.
content the note content.
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.
user_id is optional, and will default to the api user if not provided. This sets the author for the note.
created_when is optional, and will default to the current timestamp if not provided. This sets the Creation timestamp for the Note.
Backwards Compatibility
This request still accepts the following parameters in place of the preferred parameters - as described above, with the "note_" prefix removed:
- note_for
- note_for_id
- note_content
- note_type_id
- note_content
Notes: Create Example
Notes: Update
Updates an existing Note for an entity within the system (e.g. Booking, Guest, Lead or Quote).
Request Notes:
id (integer) an existing Note to update
for must be one of the following values:
- accommodation_sites
- accommodation_categories
- appointment
- availability_emails
- bookings
- bookings_groups
- charges
- clients_accounts
- companies
- companies_staff
- credits
- equipment
- equipment_guests
- events
- events_packages
- facilities_hire
- guests
- instances_booking_channels
- invoices
- leads
- payments
- postmaster_accounts
- projects
- quotes
- receipts
- refunds
- tasks
- travel_agents
- travel_agents_staff
remove (boolean) optional, deactivates the existing note when set to true.
All other parameters are optional, please see Notes: Create for more details.
The value of for and for_id cannot be updated to point to a new entity within the system.
Notes: Update Example
Surveys: List
Retrieves a list of the Surveys set up in the database.
Surveys: List Example
Gift Vouchers: List
Pull the list of Gift Vouchers from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Gift Voucher
Gift Vouchers: List Example
Inventory Items: List
Pull the list of Inventory Items from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Inventory Items
You can provide a basic booking object named calculate_price_for_booking in the request parameters and Newbook will return a new key in the response, booking_inventory_calculated_price. The calculation factors the cost per occupant so you don't have to implement such logic in your application:
{
"calculate_price_for_booking": {
"period_from": "2024-04-19",
"period_to": "2024-04-20",
"total": 199.95,
"adults": 2,
"children": 1,
"infants": 0,
"animals": 0
}
}
If you use this, calculate_price_for_booking.period_from, calculate_price_for_booking.period_to and calculate_price_for_booking.total and at least one of the occupant keys are required for Newbook to return booking_inventory_calculated_price in the response. This is because the duration of the booking and its total cost can impact the price determination when an Inventory Item is configured that way:
{
"success": "true",
"data": [{
...
"booking_inventory_calculated_price": 14.50
}],
"message": ""
}
Inventory Items: List Example
Discounts: List
Pull the list of Discounts from within Newbook.
Request Notes:
name is optional and when provided it will restrict the results to the matching Discounts
Discounts: List Example
Custom Fields
Pull a list of Custom Fields configured from within Newbook.
Request Notes:
for must be provided as one of the following options:
- leads
- guests
- bookings
Response Notes:
type will be one of the following options:
- text
- number - accepts a numeric value
- checkbox - accepts 1 for Yes and 0 for No
- enum_field - accepts a single option from type_options
- multiple_enum_field - accepts multiple options from type_options
- date - expecting a date in the format YYYY-MM-DD
- currency - accepts a numeric value
- company_lookup - accepts a valid Company ID from the Companies: List
Custom Fields Example
Notes Types: List
Pull a list of allowed Note Types from within Newbook.
Response Notes:
The note_type_default will be used for Notes: Create if a manual note_type_id is not provided
Notes Types: List Example
Phone Calls: Import Calls
Push a list of call history to Newbook for importing.
Request Notes:
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:
- autocharge must be set to "true"
- autocharge_gl_account_id must be a valid ID from the GL Accounts: List
- autocharge_gl_category_id must be a valid ID from the Sub Clients Accounts: List
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.
Phone Calls: Import Calls Example
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.
Request Notes:
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category)
PostMaster Accounts: List Example
Multiple Charges: Create
Used to record multiple sales to a Client Account in Newbook.
Request Notes:
sales: an array of different sales to record
- account_id: The Client Account ID retrieved in a previous request
- gl_category_id: Use the Sub Client Accounts: List to retrieve a list of valid IDs
- generated_when: The datetime the sale was performed
- charges: an array of charges for the sale
- gl_account_code: The GL Account code to record for the Charge. You can optionally provide gl_account_id instead using a valid ID from the GL Accounts: List request
-
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
-
- 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
- credits: an array of credits for the sale
- gl_account_code: The GL Account code to record for the Credit. You can optionally provide gl_account_id instead using a valid ID from the GL Accounts: List request
-
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
-
- 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
- payments: an array of payments for the sale
- type: tells Newbook how the Payment was received - valid options:
- cash
- cheque
- visa
- mastercard
- amex
- diners
- discover
- jcb
- eftpos
- eft (online banking funds transfer)
- eurocard
- bartercard
- type: tells Newbook how the Payment was received - valid options:
- refunds: an array of refunds for the sale
- type: tells Newbook how the Refund was received - valid options:
- cash
- cheque
- visa
- mastercard
- amex
- diners
- discover
- jcb
- eftpos
- eft (online banking funds transfer)
- eurocard
- bartercard
- type: tells Newbook how the Refund was received - valid options:
- invoice_description (optional): When provided Newbook will create an Invoice with this description for the new charges. The Response JSON will have an array of invoice_ids returned in the data section.
- invoice_system_template_id (optional): When provided along with invoice_description Newbook will create an Invoice using the specified System Template.
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
Response Notes:
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
Multiple Charges: Create Example
Subscriptions: List (CRM)
Pull a list of Subscriptions from Newbook.
Request Notes:
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.
Subscriptions: List (CRM) Example
Notifications: List
Pull a list of Notifications from Newbook.
Request Notes:
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 provided, restricts the returned Notifications to only those which were created on the date given
Notifications: List Example
Online Users: Get
Perform a login check for a Newbook Online User.
Request Notes:
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: Get Example
Online Users: Create
Create a Newbook Online User.
Request Notes:
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: Create Example
Online Users: Update
Update a Newbook Online User.
Request Notes:
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.
Online Users: Update Example
Dietary Requirements: List
List all Dietary Requirements, for use when adding or updating Guests.
Dietary Requirements: List Example
Users: List
Pull a list of active Users.
Request Notes:
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category). Not available for Corporate API requests.
Send show_inactive as true to include deactivated Users in the response
Users: List Example
Users: Get
Retrieve the details for an existing User.
Request Notes:
user_id is required, an existing User ID.
Send account_breakdown as true to see the balance of each associated Sub Client Account (gl_category). Not available for Corporate API requests.
Users: Get Example
Users: Create
Creates a User. The User will be required to change their password after first login.
Request Notes:
- username is required
- password is required, and will be forced to change on first login. This will need to have at least 8 characters, at least one upper case letter, at least one lower case letter, and at least one number
- firstname is required
- date_of_birth must be a valid date if provided, formatted as YYYY-MM-DD
- email must be a valid email address if provided
- profile_id must match an existing User Profile ID
- department_id must match an existing User Department ID
- period_from must be a valid date time if provided
- period_to must be a valid date time if provided
- active defaults to true if not provided
Users: Create Example
Users: Update
Updates an existing User.
Request Notes:
user_id must be provided to update a particular User.
Please see the Users: Create request for the parameter explanations.
Users: Update Example
Client Account Profiles: List
List Client Account Profiles.
Request Notes:
- name (string) optional, filters results by name.
Client Account Profiles: List Example
Client Account Profiles: Get
Retrieve a single Client Account Profile.
Request Notes:
- client_account_profile_id (integer) required, an existing Client Account Profile.
Client Account Profiles: Get Example
Client Account Profiles: Create
Creates a new Client Account Profile.
Request Notes:
- name (string) required.
- type (string) required, must be one of the following values:
- batch_debit
- metering
- default (boolean) optional, if a default Client Account Profile for the provided type does not exist, the created Client Account Profile will be set to default.
Client Account Profiles: Create Example
Client Account Profiles: Update
Updates an existing Client Account Profile.
Request Notes:
- client_account_profile_id (integer) required, the Client Account Profile ID to update.
- name (string) optional.
- type (string) optional, if the Client Account Profile being updated is currently set as default, type cannot be changed. Must be one of the following values:
- batch_debit
- metering
- default (boolean) optional, if the Client Account Profile being updated is currently set as default, default cannot be set as false. Set another Client Account Profile as default instead. If a default Client Account Profile for the provided type does not exist, the updated Client Account Profile will be set to default.
Client Account Profiles: Update Example
Metering Tariffs: List
List Metering Tariffs.
Request Notes:
- name (string) optional, filters results by name.
Metering Tariffs: List Example
Metering Tariffs: Get
Retrieve a single Metering Tariff.
Request Notes:
- metering_tariff_id (integer) required, an existing Metering Tariff.
Metering Tariffs: Get Example
Metering Tariffs: Create
Creates a new Metering Tariff.
Request Notes:
- name (string) required.
- reading_description (string) required.
- profile_id (integer) required, an existing Client Account Profile ID.
- meter_type_id (integer) required, an existing Metering Type ID.
- reading_gl_account_id (integer) required, an existing GL Account ID.
- reading_gl_category_id (integer) required, an existing GL Category ID.
- reading_tax_free (boolean) required.
- service_item_id (integer) optional, an existing Inventory Item ID.
- rebate_item_id (integer) optional, an existing Inventory Item ID.
- reading_inventory_item_id (integer) optional, an existing Inventory Item ID.
- levels (array) optional, an array of Metering Levels and Prices with the following format:
- amount (float) required, the Price Per Unit, must be greater than or equal to 0.00.
- minimum (float) required, the Minimum Meter Reading Value, each Metering Tariff must have a Metering Tariff Level with a minimum set to 0.00.
Metering Tariffs: Create Example
Metering Tariffs: Update
Updates an existing Metering Tariff.
Request Notes:
- metering_tariff_id (integer) required, the Metering Tariff ID to update.
- name (string) optional.
- reading_description (string) optional.
- profile_id (integer) optional, an existing Client Account Profile ID.
- meter_type_id (integer) optional, an existing Metering Type ID.
- reading_gl_account_id (integer) optional, an existing GL Account ID.
- reading_gl_category_id (integer) optional, an existing GL Category ID.
- reading_tax_free (boolean) optional.
- service_item_id (integer) optional, an existing Inventory Item ID.
- rebate_item_id (integer) optional, an existing Inventory Item ID.
- reading_inventory_item_id (integer) optional, an existing Inventory Item ID.
- levels (array) optional, an array of Metering Levels and Prices with the following format:
- level_id (integer) optional, an existing Metering Level ID to update. If omitted, a new Metering Level will be created.
- remove (boolean) optional, deactivates the existing Metering Level when set to true.
- amount (float) optional, the Price Per Unit, must be greater than or equal to 0.00.
- minimum (float) optional, the Minimum Meter Reading Value, each Metering Tariff must have a Metering Level with a minimum set to 0.00
Metering Tariffs: Update Example
Metering Types: List
List Metering Types.
Request Notes:
- name (string) optional, filters results by name.
Metering Types: List Example
Metering Types: Get
Retrieve a single Metering Type.
Request Notes:
- metering_type_id (integer) required, an existing Metering Type ID as per Metering Types: List.
Metering Types: Get Example
Metering Types: Create
Creates a new Metering Type.
Request Notes:
- gl_category_id (integer) required, an existing Sub Client Account ID as per Sub Client Accounts: List.
- name (string) required.
- unit (string) optional, the unit label.
- rollover (float) optional, rollover at this unit amount, set as 0.00 to disable.
- max_reading_units (float) optional, the maximum units allowed per reading.
- negative (boolean) optional, whether to allow negative readings.
Metering Types: Create Example
Metering Types: Update
Updates an existing Metering Type.
Request Notes:
- metering_type_id (integer) required, an existing Metering Type ID as per Metering Types: List.
- gl_category_id (integer) optional, an existing GL Category ID as per Sub Client Accounts: List.
- name (string) optional.
- unit (string) optional, the unit label.
- rollover (float) optional, rollover at this unit amount, set as 0.00 to disable.
- max_reading_units (float) optional, the maximum units allowed per reading.
- negative (boolean) optional, whether to allow negative readings.
Metering Types: Update Example
Incidents: List
Pull a list of incidents.
Request Notes:
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:
- Incident Location
- Incident Description
- User First Name or Last Name
- Guest First Name or Last Name
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.
Incidents: List Example
States List
Returns the list of States which Instances can use in their address information, per the set up in Instance Manager.
Request Notes:
You can provide a country_id to limit the results to the States of that Country.
States List Example
Countries List
Returns the list of Countries which Instances can use in their address information, per the set up in Instance Manager.
Countries List Example
Bulk Upload
For each create/update request documented on this page, you can construct a file containing multiple JSON request bodies.
This allows you to perform multiple operations without the overhead of performing multiple HTTP requests.
Request Notes:
bulk_upload_file_path
Construct your file per these instructions, host the file where we will be able to access it, and send its URL as the parameter bulk_upload_file_path.
The file should be formatted as a JSON request body with one request per line. Each line will be individually processed on Newbook servers.
The format of each line should match the Newbook REST API documentation, e.g. when using this method for Guests: Create, each line should be the request documented for Guests: Create.
You can optionally include an external_reference in each line which will be returned in the processed response. The intended use case for this is for mapping between Newbook and your system.
Example file contents for the guests_create request:
{"firstname":"John","lastname":"Doe","street":"Level 2, 9 Ouyan Street","city":"Surfers Paradise","state_name":"QLD","postcode":"4217","country_name":"Australia","contact_phone":"0756554600","contact_email":"john.doe@test.com","notes":"Some notes","membership_type":"2","membership_number":"1234567","membership_expiry":"2025-01-19","date_of_birth":"1980-03-25","equipment":[{"equipment_name":"My Honda","equipment_make":"Honda","equipment_model":"Accord","equipment_type":"1","equipment_length":"5","equipment_width":"2","equipment_height":"2","equipment_registration":"222ABC","equipment_registration_expiry":"2024-04-20"},{"equipment_name":"My Toyota","equipment_make":"Toyota","equipment_model":"Camry","equipment_type":"1","equipment_length":"4","equipment_width":"2","equipment_height":"1"}],"external_reference":"f5a9f8b5-7b91-4c76-aab9-97a55271226e"}
{"firstname":"Jane","lastname":"Doe","street":"Level 2, 9 Ouyan Street","city":"Surfers Paradise","state_name":"QLD","postcode":"4217","country_name":"Australia","contact_phone":"0756554600","contact_email":"jane.doe@test.com","notes":"Some notes","membership_type":"2","membership_number":"1234567","membership_expiry":"2025-01-19","date_of_birth":"1980-03-25","equipment":[{"equipment_name":"My Honda","equipment_make":"Honda","equipment_model":"Accord","equipment_type":"1","equipment_length":"5","equipment_width":"2","equipment_height":"2","equipment_registration":"222ABC","equipment_registration_expiry":"2024-04-20"},{"equipment_name":"My Toyota","equipment_make":"Toyota","equipment_model":"Camry","equipment_type":"1","equipment_length":"4","equipment_width":"2","equipment_height":"1"}],"external_reference":"60cdcd56-41b9-47a4-b982-c85f3ebc6af4"}
{"firstname":"Bob","lastname":"Smith","street":"Level 2, 9 Ouyan Street","city":"Surfers Paradise","state_name":"QLD","postcode":"4217","country_name":"Australia","contact_phone":"0756554600","contact_email":"bob.smith@test.com","notes":"Some notes","membership_type":"2","membership_number":"1234567","membership_expiry":"2025-01-19","date_of_birth":"1980-03-25","equipment":[{"equipment_name":"My Honda","equipment_make":"Honda","equipment_model":"Accord","equipment_type":"1","equipment_length":"5","equipment_width":"2","equipment_height":"2","equipment_registration":"222ABC","equipment_registration_expiry":"2024-04-20"},{"equipment_name":"My Toyota","equipment_make":"Toyota","equipment_model":"Camry","equipment_type":"1","equipment_length":"4","equipment_width":"2","equipment_height":"1"}],"external_reference":"946aebee-2490-454b-9f58-e8257f93551c"}
request_identifier
Newbook will include this value in the eventual POST request sent to the response_endpoint once all the processing has finished (see below for more details).
The intended use case of this is to can help identify which Bulk Upload request has completed, if you were to call the Bulk Upload request multiple times in succession.
response_headers
A JSON string of key-value pairs that will be included in the header of the returned POST request.
response_endpoint
A URL for Newbook to send a POST request once the file from bulk_upload_file_path completes processing.
Newbook will send a POST request with this contents (note the matching request_identifier):
{
"success": "true",
"data":{
"request_identifier": "e03b50a6-9e6f-42de-ab8c-2b4106bbbb71",
"processed_response_file_path": "https://example.com/path_to_file_containing_processed_responses.json"
},
"message": ""
}
We don't expect a response to the above - any response will be discarded.
As the file in processed_response_file_path will only be available for 30 minutes, it will need to be retrieved by your system as soon as possible.
The format of this file will have a response for each line provided in the original bulk_upload_file_path.
The file will show a single JSON response per line, the format of which will match the Newbook REST API documentation, e.g. when using this method for Guests: Create, each line will be the response documented for Guests: Create.
On top of this, each line will have a line_number parameter to reflect the line number processed from the bulk_upload_file_path file, as well as an external_reference matching the value from the request data (conditionally - if this was provided).
This is useful if you have unique identifiers in your system and want to keep a reference to their Newbook ID.
Example file contents:
{"success":"true","data":{"id":"1","account_id":"10","line_number":1, "external_reference":"f5a9f8b5-7b91-4c76-aab9-97a55271226e"},"message":"Successfully created Guest"}
{"success":"true","data":{"id":"2","account_id":"11","line_number":2, "external_reference":"60cdcd56-41b9-47a4-b982-c85f3ebc6af4"},"message":"Successfully created Guest"}
{"success":"true","data":{"id":"3","account_id":"12","line_number":3, "external_reference":"946aebee-2490-454b-9f58-e8257f93551c"},"message":"Successfully created Guest"}
Bulk Upload Example
Create Audit Trail (Coming Soon)
Create an Audit Trail Entry (aka change event) for a Newbook table.
Request Notes:
All fields are required and documented below:
- table the name of the Newbook table that was changed e.g. guests, bookings.
- row the ID of the Booking/Guest/etc you're recording the change event for.
- field the name of the Newbook Field that has been changed.
- old_value the previous value of the field that was changed.
- user_id the User who modified the record, and should be a valid User ID as per the Users: List
- modified_when the timestamp the field was changed
Create Audit Trail: Example
Meter Readings: Create
Create a new Meter Reading.
Request Notes:
The following parameters are accepted:
- site_id: (int) required, must be a valid Site ID.
- type_id: (int) required, must be a valid Metering Type ID.
- value: (float) required, the meter reading value as a number.
- added_by: (int) optional, must be a valid User ID as per the Users: List.
- added_when: (string) optional, the datetime to record for the reading. Defaults to the current timestamp.