Skip to main content

​
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

HeaderRequiredDescription
AuthorizationYesBearer pms_live_xxx or Bearer pms_test_xxx
Content-TypeYesapplication/json
Idempotency-KeyYesUnique 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"
    }
  ]
}
FieldTypeRequiredDescription
syncModestringYesMust be "full" — indicates this is a complete guest list replacement.
guestsarrayYesYour 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:
1

Checkouts first

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

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.
3

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

FieldDescription
receivedNumber of guests in your guests array
checkedInGuests that were new and checked in
updatedGuests whose data was updated (including room moves)
checkedOutPMS guests that were in RecepAI but not in your list — now checked out
unchangedGuests that were identical in both systems — no action taken
manualSkippedGuests entered manually by hotel staff — completely ignored by sync

​
Rate Limit

This endpoint has a stricter rate limit due to its heavy processing:
LimitValue
Requests per hour10
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"
      }
    ]
  }'