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 a daily batch reconciliation — for example, once every morning at 08:00.

This endpoint has the tightest rate limit of the five — see Rate Limits. One scheduled sync a day is enough; use check-in, update and checkout for everything in between.

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": "+12025550143",
      "roomNumber": "301",
      "checkInDate": "2026-02-18",
      "checkOutDate": "2026-02-22",
      "language": "en"
    },
    {
      "pmsGuestId": "RES-2026-002",
      "firstName": "Maria",
      "lastName": "Garcia",
      "phone": "+12025550168",
      "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, at most 500 per request — a longer list returns `FIELD_INVALID`. 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 it works

A room freed by a checkout in a sync can be taken by a room move or a new guest in that same sync, and a room freed by a move can be taken by a new guest.

Manual guests are never touched. Guests entered manually by hotel staff are completely ignored during sync. Only guests with source “pms” are compared and affected.

Responses

Success (200)

{
  "status": "synced",
  "summary": {
    "received": 2,
    "checkedIn": 1,
    "updated": 0,
    "checkedOut": 3,
    "unchanged": 1,
    "manualSkipped": 2,
    "failed": 0
  },
  "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"
}

Partial sync (409)

Some operations can be refused while others land — a room mid-checkout, for example. When that happens the sync does not report success, because a refusal swallowed into a synced leaves your system and RecepAI diverged with nobody told.

HTTP/1.1 409 Conflict

{
  "status": "partial",
  "code": "SYNC_INCOMPLETE",
  "message": "Some guests could not be synced. The counts below are what actually happened; retry to complete the rest.",
  "summary": {
    "received": 2,
    "checkedIn": 1,
    "updated": 0,
    "checkedOut": 0,
    "unchanged": 0,
    "manualSkipped": 0,
    "failed": 1
  },
  "details": {
    "checkedIn": [
      { "pmsGuestId": "RES-2026-002", "roomNumber": "405", "lastName": "Garcia" }
    ],
    "checkedOut": [],
    "updated": []
  },
  "failed": [
    {
      "pmsGuestId": "RES-2026-003",
      "roomNumber": "301",
      "operation": "checkin",
      "code": "ROOM_CLOSING"
    }
  ],
  "requestId": "req_q7r8s9t0"
}

Field	Description
`summary`	The counts are true — they describe what actually happened, not what was attempted
`details`	The operations that DID land
`failed[].operation`	`checkin`, `update` or `checkout`
`failed[].code`	Why that one operation was refused. The same codes as Error Handling

Send the same sync again. A partial sync deliberately does not consume its idempotency key, so a resend is not blocked — and because sync reconciles against the list as it then stands, the second run retries what the first could not. Treating a 409 here as “fix the payload and give up” leaves the two systems diverged.

Field reference

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
`failed`	Operations the sync could not complete. `0` on a full success; see Partial sync (409) when it is not.

Idempotency

This endpoint requires an Idempotency-Key header. Resending the same key within 24 hours replays the original response instead of repeating the operation, and a 4xx response does not consume the key. See Idempotency for the rules and the recommended key format.

Example

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": "+12025550143",
        "roomNumber": "301",
        "checkInDate": "2026-02-18",
        "checkOutDate": "2026-02-22",
        "language": "en"
      },
      {
        "pmsGuestId": "RES-2026-002",
        "firstName": "Maria",
        "lastName": "Garcia",
        "phone": "+12025550168",
        "roomNumber": "405",
        "checkInDate": "2026-02-16",
        "checkOutDate": "2026-02-20",
        "language": "de"
      }
    ]
  }'

Getting Started

Endpoints

Reference

POST /guests/sync

Endpoint

Headers

Request body

How it works

Responses

Success (200)

Partial sync (409)

Field reference

Idempotency

Example

​Endpoint

​Headers

​Request body

​How it works

​Responses

​Success (200)

​Partial sync (409)

​Field reference

​Idempotency

​Example

Endpoint

Headers

Request body

How it works

Responses

Success (200)

Partial sync (409)

Field reference

Idempotency

Example