# Guest Get

## Get Guest by ID

Sometimes you just need to pull up a very specific guest profile without digging through search results. Use this endpoint to query a guest directly by their unique ID!\
**Note:** Don't worry about creating them manually; guests automatically get set up in our system the moment you finalize a reservation through the [Booking Create](https://docs.hostelmate.co/api-documentation/bookings-create) API.

#### Endpoint

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

#### Example `curl`

```bash
curl "/api/v1/client/guests/f1b2c3d4-5678-49ab-9cde-112233445566" \
  -H "accept: application/json" \
  -H "origin: https://docs.hostelmate.co"
```

***

#### Response (200 OK)

If we find them, you'll get a lovely structured response 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": "",
    "city": "London",
    "postal_code": "",
    "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

Not sure what their ID is? No problem at all! You can effortlessly hunt down guests using an array of flexible search filters, completely supported by clean pagination to keep your screens fast.

#### 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>Track them down by their exact email address.</td></tr><tr><td><code>phone</code></td><td>string</td><td>Find them via phone number (a partial match works beautifully here!).</td></tr><tr><td><code>name</code></td><td>string</td><td>Hunt them down by first or last name (we accept partial matches!).</td></tr><tr><td><code>country_code</code></td><td>string</td><td>Only want guests from a specific area? Filter by country code.</td></tr><tr><td><code>nationality</code></td><td>string</td><td>Filter down to a specific nationality.</td></tr><tr><td><code>created_after</code></td><td>string</td><td>Grab guests who newly joined us after a specific date (YYYY-MM-DD).</td></tr><tr><td><code>created_before</code></td><td>string</td><td>Find older guests by grabbing those created before a specific date (YYYY-MM-DD).</td></tr><tr><td><code>page</code></td><td>integer</td><td>Which page to look at for your pagination setup (default: 1).</td></tr><tr><td><code>limit</code></td><td>integer</td><td>How many guests should we cram onto a single page? (default: 20, max: 100).</td></tr></tbody></table>

#### Example `curl`

```bash
curl "/api/v1/client/guests?name=John&country_code=GB&page=1&limit=10" \
  -H "accept: application/json" \
  -H "origin: https://docs.hostelmate.co"
```

***

#### Response (200 OK)

We'll gather everyone who matched your search nicely into this tidy layout:

```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"
      }
    },
    {
      "guestId": "a2b3c4d5-6789-4abc-9def-223344556677",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "phone": "+447788990011",
      "country_code": "GB",
      "createdAt": "2025-09-28T16:45:22Z",
      "bookings": {
        "total": 1,
        "lastBooking": "2025-09-28T16:45:22Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

***

#### Validation Rules

Just to make sure everything links up correctly, keep these quick tips in mind:

* `page` always needs to be a positive number (minimum: 1).
* `limit` requires a number chilling between 1 and 100.
* Both `created_after` and `created_before` really prefer the standard YYYY-MM-DD date format.
* If you throw in a `country_code` or `nationality`, they must strictly be valid ISO 3166-1 alpha-2 codes.
* Oh, and our search parameters are fully case-insensitive, so type freely!

***

#### Error Codes

Don't panic if an error pops up, refer to this handy list to figure out what happened:

<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 slipped up with the query parameters (maybe a slightly wrong date or pagination value).</td></tr><tr><td>404</td><td><code>guest_not_found</code></td><td>Sadly, we couldn't find anyone matching that unique <code>guestId</code>!</td></tr><tr><td>422</td><td><code>invalid_country_code</code></td><td>The lovely country code or nationality you fed us wasn't recognized as valid.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Our system sneezed! It's a completely unexpected error on our side.</td></tr></tbody></table>