Skip to main content

​
Endpoint

POST https://app.recepai.ai/api/pms/v1/{slug}/guests/update
Updates an existing in-house guest’s details. Uses partial update semantics — only include the fields that changed. The guest is identified by pmsGuestId.

​
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

Only include pmsGuestId (required) and the fields that changed: 
{
  "pmsGuestId": "RES-2026-001",
  "roomNumber": "305",
  "checkOutDate": "2026-02-24",
  "phone": "+905559876543"
}

​
Field Reference

FieldTypeRequiredDescription
pmsGuestIdstringYesThe guest to update (your PMS identifier)
roomNumberstringNoNew room number. Triggers an automatic room move.
firstNamestringNoUpdated first name
lastNamestringNoUpdated last name
phonestringNoUpdated phone (E.164 format)
checkInDatestringNoUpdated check-in date (YYYY-MM-DD)
checkOutDatestringNoUpdated checkout date (YYYY-MM-DD)
languagestringNoUpdated language preference (ISO 639-1)
adultsintegerNoUpdated number of adults
childrenintegerNoUpdated number of children
nationalitystringNoUpdated nationality (ISO 3166-1 alpha-2)
emailstringNoUpdated email address
Room changes are automatic. When you update roomNumber, RecepAI handles the room move internally — deactivating the old room assignment and creating a new one. You don’t need to check out and re-check-in the guest.

​
Response: Success (200)

The response includes a changes object showing exactly what was modified: 
{
  "status": "updated",
  "guestId": "abc123-def456",
  "pmsGuestId": "RES-2026-001",
  "changes": {
    "roomNumber": { "from": "301", "to": "305" },
    "checkOutDate": { "from": "2026-02-22", "to": "2026-02-24" },
    "phone": { "from": null, "to": "+905559876543" }
  },
  "requestId": "req_e5f6g7h8"
}
FieldDescription
changesObject showing each changed field with its previous (from) and new (to) value
If no fields actually changed (all submitted values are identical to current values), the response still returns 200 with an empty changes object.

​
Response: Guest Not Found (404)

Returned when no active guest with the given pmsGuestId exists: 
{
  "status": "error",
  "code": "GUEST_NOT_FOUND",
  "message": "No active guest found with pmsGuestId: RES-2026-001",
  "requestId": "req_e5f6g7h8"
}
This error means the guest was either never checked in via the PMS API, or has already been checked out. If you receive this unexpectedly, use GET /guests to see which guests are currently active.

​
Response: Room Occupied (409)

If you try to move a guest to a room that’s already occupied: 
{
  "status": "error",
  "code": "ROOM_OCCUPIED",
  "message": "Room 305 is already occupied by an active guest",
  "currentGuest": {
    "pmsGuestId": "RES-2026-002",
    "lastName": "Garcia",
    "checkInDate": "2026-02-16"
  },
  "requestId": "req_e5f6g7h8"
}

​
Example: Room Change + Extended Stay

curl -X POST https://app.recepai.ai/api/pms/v1/grand-hotel/guests/update \
  -H "Authorization: Bearer pms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update_RES2026001_room_20260219" \
  -d '{
    "pmsGuestId": "RES-2026-001",
    "roomNumber": "305",
    "checkOutDate": "2026-02-24"
  }'