> For the complete documentation index, see [llms.txt](https://support.holidayhero.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.holidayhero.com/api/connect-api.md).

# Connect API

## The Connect API <a href="#the-connect-api" id="the-connect-api"></a>

The Connect API acts on behalf of **a business**. An application authorised against a workspace can read and write that workspace's data the same way an operator could in the dashboard — but programmatically, and without a person in the loop.

If you are choosing between APIs first, see [API Overview](/api/api-overview.md).

Connect is where integrations live: the PMS bridge, the CRM sync, the nightly report, the internal tool that does the thing your team currently does by hand.

***

### What it is good for <a href="#what-it-is-good-for" id="what-it-is-good-for"></a>

#### Keeping data in sync <a href="#keeping-data-in-sync" id="keeping-data-in-sync"></a>

The most common reason to build on Connect. Your system owns something, and HolidayHero should reflect it.

* **Properties** — create and maintain listings, their descriptions, images, documents and the content attached to them.
* **Reservations** — push bookings as they are made, update them when they change, cancel them when they are cancelled. Read them back with everything HolidayHero has added since.
* **Guests** — who is on a stay, how to reach them, what they have told us.
* **Availability and scheduling** — calendar events, tasks and the operational rhythm around a stay.

Sync can run in either direction, or both. Many integrations push reservations in and pull check-in data, conversations and upsell activity back out.

#### Automating operations <a href="#automating-operations" id="automating-operations"></a>

Anything a person does repeatedly in the dashboard can be done for them.

* Create and assign **tasks** off the back of events in your own systems.
* Send messages into a **conversation**, or hand a thread between the AI and a human.
* Manage **check-in**: read submissions, act on them, mark no-shows.
* Publish **announcements** to the right guests at the right moment.
* Drive the **guest journey** — what a guest is shown, and when.

#### Extending the platform <a href="#extending-the-platform" id="extending-the-platform"></a>

Connect is not only a data pipe. Several parts of the platform exist specifically so that an integration can add to it rather than work around it.

* **Custom fields.** Attach your own structured data to almost any record — a housekeeping status, a loyalty tier, a foreign key back into your system — and read it back later. Your data travels with the record and stays yours.
* **Messaging channels.** Bridge a messaging surface we do not natively speak into HolidayHero, so threads from your PMS or OTA land in the same inbox and can be answered by the same people and the same AI. See the [channel integration guide](/api/connect-api/messaging-integration.md) if this is what you are building.
* **Smart devices.** Register locks, thermostats and sensors, expose them to guests and staff, and log what happened.
* **Suppliers and experiences.** Bring your own inventory of things a guest can book, with your own pricing, and let it be sold through the guest experience.
* **Payment providers.** Connect the account that upsell revenue settles into.

#### Reporting <a href="#reporting" id="reporting"></a>

Read stays, conversations, engagement, check-ins, upsell activity and the audit trail of what happened when, and load it into whatever you already use to measure the business.

***

### How access works <a href="#how-access-works" id="how-access-works"></a>

Access is granted by the customer, per workspace, and can be withdrawn by them at any time.

1. **You get an application.** We register it and issue a client ID and secret. The application declares what it needs — read or write, and over what.
2. **A customer authorises it.** They are shown what the application is asking for and approve it for a specific workspace. That approval is what creates the connection.
3. **You exchange that for tokens.** Standard OAuth 2.0 authorisation code flow, with refresh — your integration keeps working without anyone re-approving it, and access ends cleanly if they revoke.
4. **Every call is scoped to that workspace.** There is no way to reach beyond it, deliberately.

An application can be installed by many customers. Each installation is independent: separate approval, separate tokens, separate data.

***

### Being told when things happen <a href="#being-told-when-things-happen" id="being-told-when-things-happen"></a>

Polling is a poor way to stay current, so you do not have to.

An application can subscribe to the events it cares about — a reservation created or changed, a guest checked in, a conversation or message, an upsell requested or confirmed, content edited, a task completed, and many more. We deliver each one to an endpoint you provide, as it happens, signed so you can verify it came from us.

You choose which events you want. Subscribing to everything is possible and rarely what you want.

***

### Working with it <a href="#working-with-it" id="working-with-it"></a>

* **One endpoint, one schema.** Explore it with any GraphQL client; types and fields describe themselves.
* **Ask for what you need.** A single query can walk from a reservation to its listing, its guest, its content and its conversation without a second round trip.
* **Lists are paginated.** Everything that can return many records does, consistently.
* **Writes tell you what was wrong.** A rejected write comes back with the field and the reason, so your integration can distinguish bad input from a failed call and retry appropriately.
* **Times are UTC**, in and out.
* **Develop against a test workspace.** We give you one, so nothing you try touches a real guest.

***

### Distributing what you build <a href="#distributing-what-you-build" id="distributing-what-you-build"></a>

If what you have built is useful to more than one customer, it can be listed so other HolidayHero customers can find and install it themselves — with their own approval, their own workspace and their own data. Integrations can be free or paid; if paid, billing is handled through the platform rather than by you.

Talk to us early if this is the direction you are heading. What you build for one customer and what you list for everyone are not always the same shape, and it is cheaper to know that at the start.

***

### Where to start <a href="#where-to-start" id="where-to-start"></a>

Tell us what you want to keep in sync, or what you want to add. We will confirm whether it already exists, point you at the parts of the schema that matter, and set you up with an application and a test workspace.