# Guest Update

## Update a Guest

Whenever a guest asks to change their details, or you just need to fix a typo, you can use this endpoint to smoothly update their profile information. You are able to easily modify their **contact details**, **address**, **preferences**, and other essential guest information.\
When you send updates, our system will double-check everything, making sure the new info is valid and won't clash with any existing accounts.

#### Endpoint

```http
PATCH /api/v1/client/guests/{guestId}
```

#### Example `curl`

```bash
curl "/api/v1/client/guests/f1b2c3d4-5678-49ab-9cde-112233445566" \
  -X PATCH \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "origin: https://docs.hostelmate.co" \
  --data-raw '{
    "guest": {
      "phone": "+447712345678",
      "address": {
        "line1": "Westminster",
        "city": "London",
        "postal_code": "SW1A 1AA",
        "country_code": "GB"
      },
      "preferences": {
        "language": "en",
        "newsletter": false,
        "marketing": true
      }
    }
  }'
```

> **Pro-Tip:** This is a **partial** update! That means you only need to include the exact fields you want to change. No need to send over data that's staying exactly the same.

***

#### Request Payload

Here's exactly what you can include in your update.

**Top-level Fields**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>guest</code></td><td>object</td><td>The main container for all your updates, covering contact details, address, and preferences.</td></tr></tbody></table>

**Guest Object (updatable)**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>first_name</code></td><td>string</td><td>The guest's updated first name.</td></tr><tr><td><code>last_name</code></td><td>string</td><td>The guest's updated last name.</td></tr><tr><td><code>email</code></td><td>string</td><td>The guest's updated email address. (Just make sure it's a valid email format!)</td></tr><tr><td><code>phone</code></td><td>string</td><td>The guest's updated phone number. We highly recommend using the E.164 format.</td></tr><tr><td><code>country_code</code></td><td>string</td><td>The guest's new country code. (Needs to be ISO 3166-1 alpha-2)</td></tr><tr><td><code>address</code></td><td>object</td><td>The guest's updated postal address (see the breakdown below).</td></tr><tr><td><code>date_of_birth</code></td><td>string</td><td>The guest's updated date of birth (Use the format: YYYY-MM-DD).</td></tr><tr><td><code>nationality</code></td><td>string</td><td>The guest's updated nationality. (Needs to be ISO 3166-1 alpha-2)</td></tr><tr><td><code>preferences</code></td><td>object</td><td>The guest's updated preferences (see the breakdown below).</td></tr></tbody></table>

**Address Object**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>line1</code></td><td>string</td><td>The main street address line.</td></tr><tr><td><code>city</code></td><td>string</td><td>The city they reside in.</td></tr><tr><td><code>postal_code</code></td><td>string</td><td>Their postal or ZIP code.</td></tr><tr><td><code>country_code</code></td><td>string</td><td>Their country code in ISO 3166-1 alpha-2 format (e.g., <code>GB</code>).</td></tr></tbody></table>

**Preferences Object**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>language</code></td><td>string</td><td>Their preferred language code (e.g., <code>en</code>, <code>fr</code>).</td></tr><tr><td><code>newsletter</code></td><td>boolean</td><td>Let us know if they want to subscribe to newsletters.</td></tr><tr><td><code>marketing</code></td><td>boolean</td><td>Let us know if they consented to marketing communications.</td></tr></tbody></table>

***

#### Response (200 OK)

If everything goes perfectly, you'll receive a response looking like this:

```json
{
  "guestId": "f1b2c3d4-5678-49ab-9cde-112233445566",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+447712345678",
  "country_code": "GB",
  "address": {
    "line1": "Westminster",
    "city": "London",
    "postal_code": "SW1A 1AA",
    "country_code": "GB"
  },
  "date_of_birth": "1990-05-15",
  "nationality": "GB",
  "preferences": {
    "language": "en",
    "newsletter": false,
    "marketing": true
  },
  "updatedAt": "2025-10-02T11:05:13Z"
}
```

***

#### Validation Rules

To keep your data pristine, we enforce a few simple rules:

* You only have to send the data you want to change! Missing fields are safely ignored and left as-is.
* If you decide to send an `email`, we'll check to make sure it's valid and isn't already claimed by another guest.
* The `date_of_birth` needs to use the classic YYYY-MM-DD format.
* Both `country_code` and `nationality` require standard ISO 3166-1 alpha-2 codes.
* If you include a `phone` number, the standard E.164 format works best!

***

#### Error Codes

Sometimes things don't go according to plan! Here's a quick cheat sheet for interpreting the errors:

<table><thead><tr><th width="104.3515625">HTTP</th><th width="92.70703125">Code</th><th>Description</th></tr></thead><tbody><tr><td>400</td><td><code>bad_request</code></td><td>Something looks slightly off with the fields or payload structure you provided.</td></tr><tr><td>404</td><td><code>guest_not_found</code></td><td>We couldn't seem to find a guest sharing that specific <code>guestId</code>.</td></tr><tr><td>409</td><td><code>email_conflict</code></td><td>Looks like that new email address is already being used by another guest!</td></tr><tr><td>422</td><td><code>invalid_country_code</code></td><td>The country code or nationality you gave us doesn't seem valid.</td></tr><tr><td>422</td><td><code>invalid_date_format</code></td><td>The date format for <code>date_of_birth</code> wasn't recognized.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>An unexpected server hiccup occurred on our end.</td></tr></tbody></table>