# Guest Get

> **Important — `guestId` vs `guest.id`**: The `guestId` field returned by the Guests API is **different** from the `id` field embedded inside booking responses (`booking.guest.id`). Using a `guest.id` from a booking response to call `GET /api/v1/client/guests/{guestId}` will return `404 guest_not_found`. To get a guest's `guestId`, use the [Search Guests](#search-guests) endpoint and read the `guestId` field from the result. Guests are created automatically when a booking is created.

***

## Get Guest by ID

Retrieve a full guest profile by their `guestId`.

#### Endpoint

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

#### Example `curl`

```bash
curl "https://api.hostelmate.co/api/v1/client/guests/f1b2c3d4-5678-49ab-9cde-112233445566" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json"
```

#### Response (200 OK)

```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": false
  },
  "createdAt": "2025-10-02T11:05:13Z",
  "updatedAt": "2025-10-02T11:05:13Z",
  "bookings": {
    "total": 1,
    "lastBooking": "2025-10-02T11:05:13Z"
  }
}
```

***

## Search Guests

Search for guests using filters. Use this endpoint to find a guest's `guestId` before calling other guest endpoints.

#### Endpoint

```http
GET /api/v1/client/guests
```

#### Query Parameters

<table><thead><tr><th width="104.3515625">Parameter</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>email</code></td><td>string</td><td>Exact email match.</td></tr><tr><td><code>phone</code></td><td>string</td><td>Partial phone number match.</td></tr><tr><td><code>name</code></td><td>string</td><td>Partial match on first or last name (case-insensitive).</td></tr><tr><td><code>country_code</code></td><td>string</td><td>ISO 3166-1 alpha-2 country code (e.g., <code>GB</code>).</td></tr><tr><td><code>nationality</code></td><td>string</td><td>ISO 3166-1 alpha-2 nationality code.</td></tr><tr><td><code>created_after</code></td><td>string</td><td>Return guests created on or after this date (YYYY-MM-DD).</td></tr><tr><td><code>created_before</code></td><td>string</td><td>Return guests created on or before this date (YYYY-MM-DD).</td></tr><tr><td><code>page</code></td><td>integer</td><td>Page number (default: 1, minimum: 1).</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Results per page (default: 20, max: 100).</td></tr></tbody></table>

#### Example `curl`

```bash
curl "https://api.hostelmate.co/api/v1/client/guests?name=John&country_code=GB&page=1&limit=10" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json"
```

#### Response (200 OK)

```json
{
  "guests": [
    {
      "guestId": "f1b2c3d4-5678-49ab-9cde-112233445566",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+447712345678",
      "country_code": "GB",
      "createdAt": "2025-10-02T09:20:17Z",
      "bookings": {
        "total": 3,
        "lastBooking": "2025-09-15T14:30:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

***

#### Validation Rules

* `page` minimum: 1.
* `limit` range: 1–100.
* `created_after` and `created_before` must use YYYY-MM-DD format.
* `country_code` and `nationality` must be valid ISO 3166-1 alpha-2 codes.
* All string search parameters are case-insensitive.

***

#### Error Codes

<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>Invalid query parameters (wrong date format, invalid pagination value, etc.).</td></tr><tr><td>404</td><td><code>guest_not_found</code></td><td>No guest found for the provided <code>guestId</code>. Verify you are using <code>guestId</code> from the Guests API, not <code>guest.id</code> from a booking response.</td></tr><tr><td>422</td><td><code>invalid_country_code</code></td><td>The <code>country_code</code> or <code>nationality</code> value is not a recognized ISO 3166-1 alpha-2 code.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Unexpected server error.</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/get.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.