Guest Get

Get Guest by ID

Retrieve a specific guest's information by their unique ID. Note: Guests are created automatically when making bookings through the Booking Create API.

Endpoint

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

Example curl

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

---

Response (200 OK)

{
  "guestId": "f1b2c3d4-5678-49ab-9cde-112233445566",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "[phone]",
  "country_code": "AE",
  "address": {
    "line1": "Sheikh Zayed Rd",
    "city": "Dubai",
    "postal_code": "00000",
    "country_code": "AE"
  },
  "date_of_birth": "1990-05-15",
  "nationality": "US",
  "preferences": {
    "language": "en",
    "newsletter": true,
    "marketing": false
  },
  "createdAt": "2025-10-02T09:20:17Z",
  "updatedAt": "2025-10-02T11:05:13Z",
  "bookings": {
    "total": 3,
    "lastBooking": "2025-09-15T14:30:00Z"
  }
}

---

Search Guests

Search for guests using various criteria with pagination support.

Endpoint

GET /api/v1/client/guests

Query Parameters

Parameter	Type	Description
email	string	Search by exact email address.
phone	string	Search by phone number (partial match).
name	string	Search by first or last name (partial match).
country_code	string	Filter by country code.
nationality	string	Filter by nationality.
created_after	string	Filter guests created after this date (YYYY-MM-DD).
created_before	string	Filter guests created before this date (YYYY-MM-DD).
page	integer	Page number for pagination (default: 1).
limit	integer	Number of results per page (default: 20, max: 100).

Example curl

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

---

Response (200 OK)

{
  "guests": [
    {
      "guestId": "f1b2c3d4-5678-49ab-9cde-112233445566",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "[phone]",
      "country_code": "AE",
      "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": "[email protected]",
      "phone": "[phone]",
      "country_code": "AE",
      "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

• page must be a positive integer (minimum: 1).

• limit must be between 1 and 100.

• created_after and created_before must be valid dates in YYYY-MM-DD format.

• country_code and nationality must be valid ISO 3166-1 alpha-2 codes if provided.

• Search parameters are case-insensitive.

---

Error Codes

HTTP	Code	Description
400	bad_request	Invalid query parameters (e.g., invalid date format, invalid pagination values).
404	guest_not_found	No guest with the specified guestId (for single guest requests).
422	invalid_country_code	Invalid country code or nationality in query parameters.
500	server_error	Unexpected error.