> 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/api-overview.md).

# API Overview

HolidayHero is built API-first. Everything the product does for you in the dashboard — properties, reservations, guest content, check-in, conversations, upsells — is also available to your own systems and your own developers.

There are two public APIs, and which one you want depends on **who is on the other end**.

<table><thead><tr><th width="184.9375"></th><th width="284.27734375">Connect API</th><th>Guest API</th></tr></thead><tbody><tr><td>Acts on behalf of</td><td>Your business — a workspace</td><td>An individual guest</td></tr><tr><td>Typical use</td><td>Data sync, automation, extending the platform</td><td>A guest-facing app or website</td></tr><tr><td>Sees</td><td>Everything in the workspace it was granted</td><td>Only that guest's own stay</td></tr><tr><td>Built by</td><td>Your PMS, your ops team, an integration partner</td><td>Your web or app team</td></tr></tbody></table>

Both are **GraphQL**. One endpoint, one schema, you ask for exactly the fields you need and nothing else. Both are introspect able, so your developers can explore the whole surface from a GraphQL client without waiting on a reference document.

***

### What people build <a href="#what-people-build" id="what-people-build"></a>

The list is deliberately open-ended — these are patterns we see, not a menu.

**Keeping systems in step.** Your PMS, channel manager or CRM stays the source of truth for properties and bookings, and HolidayHero mirrors it. Reservations arrive as they are made, guest details stay current, cancellations propagate. Nobody rekeys anything.

**Putting your own data to work.** Housekeeping schedules, access codes, loyalty tiers, package inclusions — pushed in so the guest experience and the AI can use them, and read back out when something changes on our side.

**Guest-facing surfaces you own.** Your existing hotel app, your booking confirmation page, your in-room tablet or kiosk. The guest experience runs on our data and our AI, but every pixel is yours.

**Reacting to what happens.** A guest checks in, a conversation opens, an upsell is booked, a task is completed — your systems can be told the moment it happens rather than polling for it.

**Extending the platform.** New content types, new messaging channels, new device integrations, new suppliers. The platform is designed to be added to, not just read from.

**Reporting and analytics.** Pull stays, conversations, engagement and upsell activity into your own warehouse and blend it with everything else you measure.

***

### The mental model <a href="#the-mental-model" id="the-mental-model"></a>

A handful of concepts carry most of the platform. Once these land, the rest of the API is guessable.

* **Workspace** — your tenant. Everything belongs to exactly one, and every credential is scoped to one. A group with several properties may run one workspace or several.
* **Listing** — a property, unit or room type. What a guest stays in.
* **Reservation** — a stay: a listing, dates, and the people on it.
* **Guest** — a person on a reservation. One reservation can have several; one person can have many stays over time.
* **Content** — the things you tell a guest about: house information, local recommendations, amenities, announcements, guides. Written once, attached to the listings it applies to.
* **Conversation** — a thread with a guest, whoever is answering it — your team, the AI, or a messaging channel bridged in from elsewhere.
* **Upsell** — something extra a guest can request or buy during their stay.

***

### Getting started <a href="#getting-started" id="getting-started"></a>

1. **Tell us what you want to build.** We will point you at the right API, and flag anything the platform already does that you might otherwise build twice.
2. **We issue you credentials.** An application, with a client ID and secret, scoped to what it needs. Both APIs authorise with OAuth 2.0 — nobody hands around a permanent key, and access can be withdrawn without changing code.
3. **Explore the schema.** Point a GraphQL client at the endpoint and read the schema itself. Types and fields carry their own descriptions.
4. **Build against a test workspace.** You get a workspace of your own to develop in, so nothing you try lands on a real guest.

Both APIs are versionless and additive: we add fields and types, we do not silently change or remove the ones you already use. Anything that must change is announced ahead of time.

***

### Things worth knowing up front <a href="#things-worth-knowing-up-front" id="things-worth-knowing-up-front"></a>

* **All times are UTC.** Every timestamp you send and every timestamp you receive. Convert for display in your own client, never in transit.
* **IDs are opaque.** Treat them as strings, store them as strings, do not parse or generate them.
* **Writes report their own failures.** A rejected write comes back as a structured error you can act on, not as a crash — so your integration can tell "this input was wrong" from "the call did not go through".
* **Everything is workspace-scoped.** A credential physically cannot reach another customer's data. This is enforced by the platform, not by your query.
* **Multiple languages are first-class.** Content can carry translations, and the guest is served the right one automatically.

***

### Which one do I need? <a href="#which-one-do-i-need" id="which-one-do-i-need"></a>

Ask who the request is being made *for*.

If it is for **the business** — sync a booking, publish content, read a report, automate an operation — that is [Connect](/api/connect-api.md).

If it is for **one guest, in their own hands** — show them their stay, let them chat, let them check in or buy something — that is [Guest](/api/guest-api.md).

Plenty of integrations use both: Connect keeps the data flowing behind the scenes, and the Guest API powers the screen the guest actually looks at.

Not sure? Ask us. Describing what you want to happen is usually enough for us to tell you which side of the line it falls on.