> For the complete documentation index, see [llms.txt](https://docs.hostelmate.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostelmate.co/api-documentation/guests/get.md).

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