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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostelmate.co/api-documentation/guests/update.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.