Using the NewBook API for third-party integrations

The NewBook API gives authorised third-party applications read and write access to a NewBook account's reservation data, rate plans, guest profiles and channel configuration. This article covers the general principles of NewBook API connectivity and how the modules from CloudBookMod establish and maintain that connection.

NewBook API authentication

The NewBook API uses API-key authentication. Every NewBook account can generate one or more API keys from the administration section of the NewBook interface (typically under Administration → Integrations → API Access). The API key is a long alphanumeric string passed in the header of every request so that NewBook can identify the calling application and the property account it is authorised to access.

NewBook API keys can usually be scoped to specific permissions. Common scopes include: read reservations, write reservations, read rates, write rates, read guest profiles, write guest profiles, read channel configuration and read reporting data. Third-party applications should request only the minimum scopes required for their function — a least-privilege approach that limits exposure if a key is compromised.

API keys must be treated as sensitive credentials. They grant full access to the connected NewBook property within their scope. They must be stored encrypted, transmitted over HTTPS only and rotated regularly. When you connect a module through CloudBookMod, your NewBook API key is stored AES-256 encrypted and is never accessible in clear text.

Reading reservation data from NewBook

The NewBook API exposes endpoints to query reservations over a date range. A typical response includes: reservation ID, guest name, arrival and departure dates, room type, rate plan, total amount, payment status, source channel and guest contact details. This data is the basis for most third-party integrations.

For modules such as the Guest Registration & Digital Waivers and Guest CRM, the pattern is: (1) query NewBook for reservations arriving in the next 14 days; (2) for each reservation, retrieve the associated guest profile; (3) process the guest data inside the module's function (for example, send a pre-arrival portal link); (4) write the collected data back into the NewBook reservation. Steps 1 and 2 are read operations; step 4 is a write operation that requires the "write reservations" or "write guest profiles" scope.

Rate management via the NewBook API

The NewBook API supports read and write operations on rate plans. A typical write call specifies: the rate plan ID (as defined in your NewBook account), the arrival date or date range, the room type(s) and the new rate. Rate updates sent through the API are reflected in the NewBook channel manager and then distributed to connected OTAs on the standard NewBook update cycle.

Rate distribution via the API is the core function used by the Multi-Property Central Dashboard and Multi-Property Central Dashboard modules. The flow is: (1) read current rates and occupancy from NewBook; (2) compute a recommended or rule-triggered rate; (3) send the new rate to NewBook via the API; (4) NewBook distributes the update to connected channels. Steps 1 and 3 require the "read rates" and "write rates" scopes respectively.

Webhook and event-driven integrations

In addition to polled calls, NewBook supports webhook delivery for certain reservation events. Once configured on your NewBook account (typically under Administration → Integrations → Webhooks), NewBook sends an HTTP POST to a pre-defined URL when specific events occur — new reservation created, reservation modified or check-out completed.

Webhook-based integrations are used by the Guest CRM module for post-stay flows. When NewBook fires a "check-out completed" webhook, the module triggers the appropriate post-stay email sequence immediately without having to poll NewBook every few minutes. This event-driven architecture reduces API call volume and improves response time for time-sensitive communications.

Rate limiting and API call management

NewBook enforces rate limits on API calls to protect the platform from overload. Exceeding the limit results in HTTP 429 (Too Many Requests) responses. Well-designed third-party modules implement exponential back-off when they hit rate-limit errors and batch requests where possible rather than making individual per-night calls.

CloudBookMod modules are built to respect NewBook rate limits. Rate updates are batched wherever possible. Polling intervals are set conservatively. When several modules are active on the same NewBook account, calls are coordinated to avoid unnecessarily high call volume.

Staying compatible with NewBook API changes

NewBook publishes regular updates to its API. Some add new endpoints or fields (non-breaking changes); others may deprecate or modify existing endpoints (potentially breaking changes for dependent applications). CloudBookMod monitors the NewBook API changelog and tests every module against each release. When a breaking change is detected, affected modules are updated and a compatibility patch is shipped, typically within 48 hours.