> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/integrations/pms-integrations.md).

# PMS integrations

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/pms-integrations.md).
{% endhint %}

Hotels run a **property management system** (**PMS**) for their rooms. A PMS integration keeps each room's **room status** the same in Snapfix and the PMS: a status set in Snapfix goes to the PMS, and a status set in the PMS comes into Snapfix. Each PMS has its own Snapfix service that talks to it. There are services for nine PMSs: Cloudbeds, Clock PMS+, Comtrol, Guestline, Hotsoft, Jonas Chorum, Oracle Opera Cloud, Protel and Stayntouch ([Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md)). Some of them also bring in rooms, guests and stays, and a PMS change can create housekeeping tasks or an inspection. Whether Clock PMS+ and Protel run is open \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. Deputy, another integration service, reads staff rosters and is not a PMS.

## Rules

### Linking

* A PMS is linked per **building**, by a row in that PMS's building mapping table, such as [`guestline_BuildingSiteMapping`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_buildingsitemapping.md); each room is linked by a row in its room mapping table, such as [`guestline_RoomMapping`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_roommapping.md). Laravel skips a PMS whose mapping table does not exist, and the staging database has none for Clock PMS+ or Protel \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].
* The building rows are written by the php-apis onboarding actions, which no repo calls, so how buildings are linked today is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]. Those actions let any signed-in user relink a paying site's building to another PMS account ([Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md)).
* Staff link Guestline sites on the admin app's [Guestline](https://docs.snapfix.com/how-the-apps-work/screens/integrations/guestline.md) page: the Guestline login, the site's Guestline admin, and a mapping of Guestline housekeeping codes to the red, amber and green statuses. The page writes its own tables, which the Guestline sync never reads, so a link saved there changes nothing in the sync \[[ASK-153](https://github.com/snapfix/docs/blob/main/ASK.md#ask-153-should-the-admin-apps-guestline-page-feed-the-guestline-sync)]. The page cannot link groups.
* Anyone signed in to the admin app can use the page, and the server calls behind it check no staff role.
* The page's switches that turn a Guestline site or group on or off always fail on the server; whether that is meant is open \[[ASK-152](https://github.com/snapfix/docs/blob/main/ASK.md#ask-152-should-the-guestline-pages-on-and-off-switches-work)]. They are GET requests that change data.
* No plan or subscription check applies to a PMS link. A building can be linked to more than one PMS.

### Sending Snapfix changes

* A status change made on the web, alone or in bulk, by a completed task or by a task rule goes to every PMS linked to the building. Laravel sends it 10 seconds later, and skips a change that a newer change of the same room has overtaken (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:27`, `:39`, `:58-61`, `:98-104`; `app/Http/Controllers/v1/Versions/v1_0/App/RoomController.php:272`; `app/Traits/Room/RoomMultiActions.php:111`, `:243`; `app/Services/TaskCompletionService.php:127`; `app/Services/AssetJobService.php:4935`).
* A status change made in the apps goes through php-apis to one PMS only: the first of Guestline, Hotsoft, Opera, Stayntouch, Cloudbeds, Jonas Chorum and Comtrol whose room mappings hold a room of the synced batch. It never goes to Clock PMS+ or Protel, and it skips changes to a fixed list of out-of-order statuses \[[ASK-83](https://github.com/snapfix/docs/blob/main/ASK.md#ask-83-which-room-status-changes-should-create-inspections-and-cleaning-tasks-and-reach-the-pms)] (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45405-45441`, `:45467-45576`).
* When a push fails, times out or is refused, nothing records the failure and nothing sends it again. Five services answer a refused login with HTTP `200`, which Laravel logs as a success.
* Each service handles the change in its own way:

| PMS          | What the service does with a Snapfix change                                                         |
| ------------ | --------------------------------------------------------------------------------------------------- |
| Cloudbeds    | Queues it and sends the whole outbound queue to Cloudbeds before it answers                         |
| Clock PMS+   | Refuses it: the route takes only changes whose source is Clock, and Snapfix's own changes have none |
| Comtrol      | Queues it for the site's next poll                                                                  |
| Guestline    | Queues it for Guestline                                                                             |
| Hotsoft      | Queues it for the outbound sync                                                                     |
| Jonas Chorum | Sends it to Jonas Chorum at once                                                                    |
| Opera        | Queues it and sends the whole outbound queue before it answers                                      |
| Protel       | Queues it for Protel                                                                                |
| Stayntouch   | Checks the room's status in Stayntouch, queues it and sends the outbound queue before it answers    |

### Receiving PMS changes

* A PMS change reaches Snapfix through its service: from the service's inbound sync, or at once from a PMS push (the Cloudbeds and Stayntouch webhooks and the Jonas Chorum listener). The service posts it to [`POST /v1/internal/rooms/{uuid}/status`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-v1internalroomsuuidstatus) with the building's own login, not a user's sign-in.
* The login is two values of the building's mapping row, compared as plain text. Several are identifiers rather than secrets, so anyone who holds a building's pair can post its room changes ([PMS logins](https://docs.snapfix.com/engineering-reference/api/integrations.md#pms-logins)). A PMS can set only its building's statuses, and only on rooms of that building.
* The change sets the room's status, and its secondary status when one is sent, and is logged with the PMS as its source. It also cancels the room's red departure cleans created today, in the site's time zone, when the next stay is back-to-back \[[ASK-83](https://github.com/snapfix/docs/blob/main/ASK.md#ask-83-which-room-status-changes-should-create-inspections-and-cleaning-tasks-and-reach-the-pms)].
* When the room comes back from "OUT OF ORDER" or "OUT OF SERVICE", the change can create an inspection in the name of the site's admin user, and no cleaning tasks \[[ASK-83](https://github.com/snapfix/docs/blob/main/ASK.md#ask-83-which-room-status-changes-should-create-inspections-and-cleaning-tasks-and-reach-the-pms)]. Otherwise, when housekeeping is on for the room and the site has an admin user, it generates the room's cleaning tasks for the day, in the site's time zone or UTC when the site has none (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/Internal/InternalController.php:100`, `:112-158`; [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md), [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md)).
* A PMS change is not sent back to any PMS. Only the multi-room route, which nothing calls, would push its changes to every PMS of the building, the sender included \[[ASK-161](https://github.com/snapfix/docs/blob/main/ASK.md#ask-161-is-post-v1internalroomsstatusmulti-still-needed-and-should-it-push-a-pmss-own-change-back)].
* The building's "manual room status" setting is not read before a PMS change \[[ASK-84](https://github.com/snapfix/docs/blob/main/ASK.md#ask-84-what-should-the-building-setting-manual-room-status-do)].

### Timing

* Each service runs its own timers. Guestline starts them at startup when one of its sync settings is on; Cloudbeds, Jonas Chorum and Opera when `PERIODIC_SYNC_IN_UVICORN` is on. Clock PMS+, Hotsoft, Protel and Stayntouch have the periodic start commented out, so their syncs run only from trigger routes that no repo calls; Stayntouch also has a daily fallback sync \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] (guestline\_py\_server @ 6aa8239243, `app/main.py:148-154`; cloudbeds\_py\_server @ 17b14a0ee2, `app/main.py:159`; hotsoft\_py\_server @ e30355215a, `app/main.py:46-48`; stayntouch\_py\_server @ 21e55b9071, `app/main.py:313-325`).
* By default the inbound sync runs every 60 seconds (120 for Cloudbeds and Jonas Chorum) and the outbound sync every 300 seconds. The production values are not in the repos \[[ASK-155](https://github.com/snapfix/docs/blob/main/ASK.md#ask-155-which-settings-do-the-pms-services-use-in-production)].
* The Clock PMS+, Guestline, Protel and Stayntouch polls return every unsent change again on each poll, because they mark none as delivered \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)]. Which vendor systems call the poll and post routes is not in the repos \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

### Rooms, guests and tasks

* Eight services create Snapfix rooms from the PMS; Comtrol only reads them (for example jonaschorum\_py\_server @ ca557086fd, `app/core/background_tasks.py:590-640`).
* Cloudbeds, Guestline, Jonas Chorum, Opera and Stayntouch also write guests and stays ([`tPri_RoomGuests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomguests.md), [`tPri_RoomGuestStatus`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomgueststatus.md)).
* Cloudbeds creates a "Pre arrival maintenance blitz" task when a guest checks out (cloudbeds\_py\_server @ 17b14a0ee2, `app/core/cloudbeds_building_sync.py:38-42`). Cloudbeds and Stayntouch ask Snapfix to generate a room's housekeeping tasks after a reservation change (stayntouch\_py\_server @ 21e55b9071, `app/core/housekeeping_hooks.py:29-35`).

## Flow

```mermaid
flowchart TD
  web["Web change, bulk change, completed task or task rule"] --> wait["Laravel waits 10 seconds, skips overtaken changes"]
  wait --> each["Sent to each linked PMS service"]
  app["App change, synced later"] --> php["php-apis sends it to the first mapped PMS"]
  php --> svc["PMS service"]
  each --> svc
  svc --> out["Sent to the PMS at once, by the outbound timer, or on the PMS's poll"]
  pms["Change made in the PMS"] --> inb["PMS service: inbound timer or PMS push"]
  inb --> internal["POST /v1/internal/rooms/{uuid}/status with the building's login"]
  internal --> save["Status saved and logged, not sent back"]
  save --> tasks["Cancels departure cleans; may add cleaning tasks or an inspection"]
```

## Platforms

| Capability                                         | Web                                                                                                                                                                                                       | iOS             | Android         |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------- |
| Link a PMS to a building                           | Guestline only, in the staff admin app, and the sync does not read it \[[ASK-153](https://github.com/snapfix/docs/blob/main/ASK.md#ask-153-should-the-admin-apps-guestline-page-feed-the-guestline-sync)] | No              | No              |
| Link the other PMSs                                | No screen; the onboarding actions have no caller \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]                                         | No              | No              |
| See a synced room status                           | Yes ([Room status](https://docs.snapfix.com/product/features/rooms/room-status.md))                                                                                                                       | Yes             | Yes             |
| Change a room's status, which then goes to the PMS | Yes, to every linked PMS                                                                                                                                                                                  | Yes, to one PMS | Yes, to one PMS |

## Screens

* [Guestline](https://docs.snapfix.com/how-the-apps-work/screens/integrations/guestline.md): the staff admin app page for Guestline links (web).
* [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md): where the synced status shows and where people change it.

## API and data

* [Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md): the PMS services, their hosts and logins ([PMS logins](https://docs.snapfix.com/engineering-reference/api/integrations.md#pms-logins)), and [`POST /v1/internal/rooms/{uuid}/status`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-v1internalroomsuuidstatus), where the services apply PMS changes.
* The service routes, by PMS:

| PMS          | Snapfix changes reach the service by                                                                                                                                 | PMS changes reach the service by                                                                                                                                                                                                                                                                               |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloudbeds    | [`GET /{roomStatusChangeLogUUID} (Cloudbeds)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-roomstatuschangeloguuid-cloudbeds)             | [`POST /webhook/receive`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-webhookreceive) (Cloudbeds webhooks) and the inbound sync                                                                                                                                                    |
| Clock PMS+   | [`GET /{uuid}`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-uuid), which refuses them                                                     | [`POST /api/v1/outbound (Clock)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-apiv1outbound-clock); Clock polls [`GET /api/v1/inbound (Clock)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-apiv1inbound-clock)                                         |
| Comtrol      | [`GET /{roomStatusChangeLogUUID} (Comtrol)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-roomstatuschangeloguuid-comtrol)                 | [`POST /outbound`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-outbound); Comtrol polls [`GET /inbound`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-inbound)                                                                                           |
| Guestline    | [`GET /api/v1/{roomStatusChangeLogUUID} (Guestline)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-apiv1roomstatuschangeloguuid-guestline) | The inbound sync; Guestline may poll [`GET /api/v1/inbound (Guestline)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-apiv1inbound-guestline)                                                                                                                                        |
| Hotsoft      | [`GET /api/v1/{roomStatusChangeLogUUID} (Hotsoft)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-apiv1roomstatuschangeloguuid-hotsoft)     | The inbound sync                                                                                                                                                                                                                                                                                               |
| Jonas Chorum | [`GET /chorum/{log_uuid}`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-chorumlog_uuid)                                                    | [`POST /chorum/listener/submit`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-chorumlistenersubmit) (Jonas Chorum's push) and the inbound sync                                                                                                                                      |
| Opera        | [`GET /{roomStatusChangeLogUUID} (Opera)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-roomstatuschangeloguuid-opera)                     | The inbound sync                                                                                                                                                                                                                                                                                               |
| Protel       | [`GET /{log_uuid} (Protel)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-log_uuid-protel)                                                 | [`POST /api/v1/outbound (Protel)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-apiv1outbound-protel); Protel polls [`GET /api/v1/inbound (Protel)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-apiv1inbound-protel)                                    |
| Stayntouch   | [`GET /{log_uuid} (Stayntouch)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-log_uuid-stayntouch)                                         | [`POST /webhook`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-webhook) (Stayntouch webhooks) and the daily fallback sync; Stayntouch may poll [`GET /api/v1/inbound (Stayntouch)`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-apiv1inbound-stayntouch) |

* The Guestline page's calls: [`GET /guestline-parents`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-guestline-parents), [`GET /guestline-parent/{gl_parent_uuid}/businesses`](https://docs.snapfix.com/engineering-reference/api/integrations.md#get-guestline-parentgl_parent_uuidbusinesses), [`POST /guestline-parent`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-guestline-parent), [`PUT /guestline-parent/{uuid}`](https://docs.snapfix.com/engineering-reference/api/integrations.md#put-guestline-parentuuid), the two switches, and the Guestline login check [`admin_guestline_login`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_guestline_login).
* Tables: [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md) (room status), [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) (every status change with its source, which each push reads), [`guestline_parent`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_parent.md) and [`guestline_business`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_business.md) (the admin page's link), [`guestline_RoomStatusMapping`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_roomstatusmapping.md) (the mapping the Guestline sync reads), and each PMS's mapping and queue tables, such as [`guestline_OutboundQueue`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_outboundqueue.md) ([database tables](https://docs.snapfix.com/engineering-reference/db/tables.md)).

## Depends on

* [Room status](https://docs.snapfix.com/product/features/rooms/room-status.md): the statuses both sides keep the same.
* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md): the rooms and buildings that get mapped.
* [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md) and [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md): the tasks and inspections a PMS change can create.
* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): completing a task with a status action changes the room's status and sends it on.
* [Staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md) and [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md): the Guestline page, and the Accounts page's second Guestline dialog.

## Edge cases

* **PMS unreachable when a change is sent:** the change is lost for that PMS until the room changes again.
* **Two PMSs on one building:** web and task changes go to both; app changes go to one.
* **Wrong login or room of another building:** `401` or `403` from the internal route. When the database stays unreachable, the service gets `503` with `Retry-After: 1`.
* **Large backlog:** Cloudbeds, Opera and Stayntouch send their whole unsent backlog before they answer one change, so Laravel's push can give up after 30 seconds; it does not retry.
* **Room not in the PMS mapping:** the service answers "Room mapping not found" with HTTP `200` ([PMS result object](https://docs.snapfix.com/engineering-reference/api/integrations.md#pms-result-object)).
* **Housekeeping off, or no site admin:** a PMS change saves the status and creates no cleaning tasks.
* **Guestline page:** its site picker selects a site by itself, it lists at most 50 links, and a switch that ever succeeded would mark the first row of the table.
* **Stored logins and open routes:** Comtrol keeps site logins in plain text; the Guestline service encrypts and decrypts PMS passwords for anyone; the Guestline page stores passwords encrypted with a key written in apipy's code, and the Accounts page's dialog stores a plain copy; the Guestline login calls skip certificate checks; Hotsoft's room status route accepts any login; several services have open trigger and cache routes and unchecked webhooks.
* **Time zones:** the cancelled departure cleans and the generated cleaning tasks use the site's day.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/integrations/pms-integrations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
