POST /guests/update

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

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

Only include pmsGuestId (required) and the fields that changed:

{
  "pmsGuestId": "RES-2026-001",
  "roomNumber": "305",
  "checkOutDate": "2026-02-24",
  "phone": "+905559876543"
}

Field Reference

Field	Type	Required	Description
`pmsGuestId`	string	Yes	The guest to update (your PMS identifier)
`roomNumber`	string	No	New room number. Triggers an automatic room move.
`firstName`	string	No	Updated first name
`lastName`	string	No	Updated last name
`phone`	string	No	Updated phone (E.164 format)
`checkInDate`	string	No	Updated check-in date (`YYYY-MM-DD`)
`checkOutDate`	string	No	Updated checkout date (`YYYY-MM-DD`)
`language`	string	No	Updated language preference (ISO 639-1)
`adults`	integer	No	Updated number of adults
`children`	integer	No	Updated number of children
`nationality`	string	No	Updated nationality (ISO 3166-1 alpha-2)
`email`	string	No	Updated 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"
}

Field	Description
`changes`	Object showing each changed field with its previous (`from`) and new (`to`) value

Response: No Changes (200)

If all submitted values are identical to the current values, the response returns 200 with status: "unchanged" and an empty changes object:

{
  "status": "unchanged",
  "guestId": "abc123-def456",
  "pmsGuestId": "RES-2026-001",
  "changes": {},
  "requestId": "req_e5f6g7h8"
}

This is not an error — it simply means the data was already up to date. Your integration can treat "unchanged" the same as "updated" for success handling.

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

Getting Started

Endpoints

Reference

POST /guests/update

Endpoint

Headers

Request Body

Field Reference

Response: Success (200)

Response: No Changes (200)

Response: Guest Not Found (404)

Response: Room Occupied (409)

Example: Room Change + Extended Stay

​Endpoint

​Headers

​Request Body

​Field Reference

​Response: Success (200)

​Response: No Changes (200)

​Response: Guest Not Found (404)

​Response: Room Occupied (409)

​Example: Room Change + Extended Stay

Endpoint

Headers

Request Body

Field Reference

Response: Success (200)

Response: No Changes (200)

Response: Guest Not Found (404)

Response: Room Occupied (409)

Example: Room Change + Extended Stay