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

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

Example curl

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)

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

GET /api/v1/client/guests

Query Parameters

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

Example curl

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)

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

HTTP	Code	Description
400	bad_request	Invalid query parameters (wrong date format, invalid pagination value, etc.).
404	guest_not_found	No guest found for the provided guestId. Verify you are using guestId from the Guests API, not guest.id from a booking response.
422	invalid_country_code	The country_code or nationality value is not a recognized ISO 3166-1 alpha-2 code.
500	server_error	Unexpected server error.