POST /guests/sync

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.

Request Body

{
  "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.

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.

How Sync Works

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

Checkouts first

Guests that exist in RecepAI (source: pms) but are NOT in your list are checked out. This frees up their rooms.

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.

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.

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.

Response: Success (200)

{
  "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

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, update, and checkout endpoints.

Example: cURL

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"
      }
    ]
  }'

Getting Started

Endpoints

Reference

POST /guests/sync

Endpoint

Headers

Request Body

How Sync Works

Response: Success (200)

Summary Fields

Rate Limit

Example: cURL

​Endpoint

​Headers

​Request Body

​How Sync Works

​Response: Success (200)

​Summary Fields

​Rate Limit

​Example: cURL

Endpoint

Headers

Request Body

How Sync Works

Response: Success (200)

Summary Fields

Rate Limit

Example: cURL