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": "+12025550187"
}

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.

Responses

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": "+12025550187" }
  },
  "requestId": "req_e5f6g7h8"
}

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

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.

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.

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

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/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

Responses

Success (200)

No Changes (200)

Guest Not Found (404)

Room Occupied (409)

Idempotency

Example

​Endpoint

​Headers

​Request body

​Field reference

​Responses

​Success (200)

​No Changes (200)

​Guest Not Found (404)

​Room Occupied (409)

​Idempotency

​Example

Endpoint

Headers

Request body

Field reference

Responses

Success (200)

No Changes (200)

Guest Not Found (404)

Room Occupied (409)

Idempotency

Example