> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recepai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /guests/update

> Update guest details or move them to a different room.

## 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](/api/pms/testing#idempotency). |

## Request Body

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

```json theme={null}
{
  "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                             |

<Info>
  **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.
</Info>

## Response: Success (200)

The response includes a `changes` object showing exactly what was modified:

```json theme={null}
{
  "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 |

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:

```json theme={null}
{
  "status": "error",
  "code": "GUEST_NOT_FOUND",
  "message": "No active guest found with pmsGuestId: RES-2026-001",
  "requestId": "req_e5f6g7h8"
}
```

<Note>
  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](/api/pms/list-guests) to see which guests are currently active.
</Note>

## Response: Room Occupied (409)

If you try to move a guest to a room that's already occupied:

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```