> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recepai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /guests/sync

> Send your complete in-house guest list for full reconciliation.

## Endpoint

```
POST https://app.recepai.ai/api/pms/v1/{slug}/guests/sync
```

Sends your PMS's complete in-house guest list. RecepAI compares it with its current roster and automatically:

* **Checks in** guests that are new (in your list but not in RecepAI)
* **Updates** guests whose details changed (room, checkout date, phone, etc.)
* **Checks out** guests that are gone (in RecepAI but not in your list)

This is designed for **nightly batch reconciliation** — for example, running once every morning at 08:00 to ensure RecepAI and your PMS are perfectly in sync.

## Headers

| Header            | Required | Description                                                                                 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------- |
| `Authorization`   | Yes      | `Bearer pms_live_xxx` or `Bearer pms_test_xxx`                                              |
| `Content-Type`    | Yes      | `application/json`                                                                          |
| `Idempotency-Key` | Yes      | Unique key for this request (1–255 chars). See [Idempotency](/api/pms/testing#idempotency). |

## Request Body

```json theme={null}
{
  "syncMode": "full",
  "guests": [
    {
      "pmsGuestId": "RES-2026-001",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+905551234567",
      "roomNumber": "301",
      "checkInDate": "2026-02-18",
      "checkOutDate": "2026-02-22",
      "language": "en"
    },
    {
      "pmsGuestId": "RES-2026-002",
      "firstName": "Maria",
      "lastName": "Garcia",
      "phone": "+491234567890",
      "roomNumber": "405",
      "checkInDate": "2026-02-16",
      "checkOutDate": "2026-02-20",
      "language": "de"
    }
  ]
}
```

| Field      | Type   | Required | Description                                                                                                                                        |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `syncMode` | string | **Yes**  | Must be `"full"` — indicates this is a complete guest list replacement.                                                                            |
| `guests`   | array  | **Yes**  | Your complete list of current in-house guests. Each guest object uses the same fields as [POST /guests/checkin](/api/pms/checkin#field-reference). |

<Warning>
  **Send ALL your in-house guests.** Any PMS-sourced guest in RecepAI that is NOT in your `guests` array will be automatically checked out. If you send an empty array, all PMS guests will be checked out.
</Warning>

## How Sync Works

RecepAI processes the sync in a specific order to prevent room conflicts:

<Steps>
  <Step title="Checkouts first">
    Guests that exist in RecepAI (source: pms) but are NOT in your list are checked out. This frees up their rooms.
  </Step>

  <Step title="Updates second">
    Guests that exist in both lists but with different data are updated. This includes room moves — the checkout step ensures the target room is available.
  </Step>

  <Step title="New check-ins last">
    Guests in your list that don't exist in RecepAI are checked in. By this point, rooms freed by checkouts and moves are available.
  </Step>
</Steps>

<Info>
  **Manual guests are never touched.** Guests entered manually by hotel staff (source: "receptionist") are completely ignored during sync. Only guests with source "pms" are compared and affected.
</Info>

## Response: Success (200)

```json theme={null}
{
  "status": "synced",
  "summary": {
    "received": 2,
    "checkedIn": 1,
    "updated": 0,
    "checkedOut": 3,
    "unchanged": 1,
    "manualSkipped": 2
  },
  "details": {
    "checkedIn": [
      { "pmsGuestId": "RES-2026-002", "roomNumber": "405", "lastName": "Garcia" }
    ],
    "checkedOut": [
      { "pmsGuestId": "RES-2026-098", "roomNumber": "201", "lastName": "Johnson" },
      { "pmsGuestId": "RES-2026-099", "roomNumber": "512", "lastName": "Williams" },
      { "pmsGuestId": "RES-2026-100", "roomNumber": "308", "lastName": "Brown" }
    ],
    "updated": []
  },
  "requestId": "req_m3n4o5p6"
}
```

## Summary Fields

| Field           | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| `received`      | Number of guests in your `guests` array                                |
| `checkedIn`     | Guests that were new and checked in                                    |
| `updated`       | Guests whose data was updated (including room moves)                   |
| `checkedOut`    | PMS guests that were in RecepAI but not in your list — now checked out |
| `unchanged`     | Guests that were identical in both systems — no action taken           |
| `manualSkipped` | Guests entered manually by hotel staff — completely ignored by sync    |

## Rate Limit

This endpoint has a stricter rate limit due to its heavy processing:

| Limit             | Value  |
| ----------------- | ------ |
| Requests per hour | **10** |

<Tip>
  **Recommended schedule:** Run the sync once per morning (e.g., 08:00 local time). This catches any events that might have been missed by real-time check-in/checkout calls during the previous day.

  For real-time updates throughout the day, use the individual [check-in](/api/pms/checkin), [update](/api/pms/update), and [checkout](/api/pms/checkout) endpoints.
</Tip>

## Example: cURL

```bash theme={null}
curl -X POST https://app.recepai.ai/api/pms/v1/grand-hotel/guests/sync \
  -H "Authorization: Bearer pms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync_20260219_morning" \
  -d '{
    "syncMode": "full",
    "guests": [
      {
        "pmsGuestId": "RES-2026-001",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "+905551234567",
        "roomNumber": "301",
        "checkInDate": "2026-02-18",
        "checkOutDate": "2026-02-22",
        "language": "en"
      },
      {
        "pmsGuestId": "RES-2026-002",
        "firstName": "Maria",
        "lastName": "Garcia",
        "phone": "+491234567890",
        "roomNumber": "405",
        "checkInDate": "2026-02-16",
        "checkOutDate": "2026-02-20",
        "language": "de"
      }
    ]
  }'
```