Guests API

The Guests API allows you to manage guest profiles, preferences, and history.

Endpoints

List Guests

GET /api/v1/guests

Query Parameters:

Parameter	Type	Description
search	string	Search by name, email, or phone
email	string	Filter by email address
phone	string	Filter by phone number
loyalty_number	string	Filter by loyalty number
vip_status	string	Filter by VIP status
cursor	string	Pagination cursor
limit	integer	Results per page (default: 20, max: 100)

Example Request:

curl -X GET "https://api.hmpcloud.com/v1/guests?search=john" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Property-ID: prop_abc123"

Response:

{
  "data": [
    {
      "id": "guest_abc123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@email.com",
      "phone": "+91-9876543210",
      "nationality": "IND",
      "vip_status": "GOLD",
      "loyalty_number": "HMP123456",
      "total_stays": 12,
      "total_revenue": 250000.00,
      "last_stay": "2026-01-15",
      "created_at": "2024-05-10T08:00:00Z"
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Get Guest

GET /api/v1/guests/:id

Response:

{
  "data": {
    "id": "guest_abc123",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@email.com",
    "phone": "+91-9876543210",
    "nationality": "IND",
    "date_of_birth": "1985-06-15",
    "gender": "MALE",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "Mumbai",
      "state": "Maharashtra",
      "postal_code": "400001",
      "country": "IN"
    },
    "id_documents": [
      {
        "type": "PASSPORT",
        "number": "J1234567",
        "expiry": "2030-05-10",
        "country": "IND"
      }
    ],
    "preferences": {
      "room_type": "DELUXE",
      "floor": "HIGH",
      "bed_type": "KING",
      "smoking": false,
      "pillow_type": "SOFT",
      "newspaper": "TIMES_OF_INDIA",
      "dietary": ["VEGETARIAN"]
    },
    "vip_status": "GOLD",
    "loyalty": {
      "member_number": "HMP123456",
      "tier": "GOLD",
      "points_balance": 15000,
      "lifetime_points": 75000
    },
    "statistics": {
      "total_stays": 12,
      "total_nights": 45,
      "total_revenue": 250000.00,
      "average_rate": 5555.56,
      "first_stay": "2024-05-10",
      "last_stay": "2026-01-15"
    },
    "created_at": "2024-05-10T08:00:00Z",
    "updated_at": "2026-01-20T10:30:00Z"
  }
}

Create Guest

POST /api/v1/guests

Request Body:

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@email.com",
  "phone": "+91-9876543211",
  "nationality": "USA",
  "date_of_birth": "1990-03-20",
  "gender": "FEMALE",
  "address": {
    "line1": "456 Oak Avenue",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  }
}

Response: 201 Created

{
  "data": {
    "id": "guest_def456",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@email.com",
    "created_at": "2026-01-22T12:00:00Z"
  }
}

Update Guest

PUT /api/v1/guests/:id

Request Body:

{
  "phone": "+91-9876543212",
  "preferences": {
    "room_type": "SUITE",
    "floor": "HIGH"
  }
}

Response: 200 OK

Delete Guest

DELETE /api/v1/guests/:id

Response: 204 No Content

Note: Guests with reservation history cannot be deleted, only anonymized for GDPR compliance.

Guest Stay History

Get Stay History

GET /api/v1/guests/:id/stays

Response:

{
  "data": [
    {
      "reservation_id": "res_xyz789",
      "confirmation_number": "HTLABC20260115001",
      "arrival_date": "2026-01-15",
      "departure_date": "2026-01-18",
      "room_number": "405",
      "room_type": "Deluxe Room",
      "total_charges": 18000.00,
      "status": "CHECKED_OUT"
    },
    {
      "reservation_id": "res_abc456",
      "confirmation_number": "HTLABC20251110001",
      "arrival_date": "2025-11-10",
      "departure_date": "2025-11-12",
      "room_number": "302",
      "room_type": "Standard Room",
      "total_charges": 10000.00,
      "status": "CHECKED_OUT"
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Guest Preferences

Update Preferences

PUT /api/v1/guests/:id/preferences

Request Body:

{
  "room_type": "SUITE",
  "floor": "HIGH",
  "bed_type": "KING",
  "smoking": false,
  "pillow_type": "FIRM",
  "newspaper": "ECONOMIC_TIMES",
  "minibar": ["STILL_WATER", "ORANGE_JUICE"],
  "dietary": ["VEGETARIAN", "NO_GLUTEN"],
  "special_occasions": [
    {
      "type": "BIRTHDAY",
      "date": "06-15"
    },
    {
      "type": "ANNIVERSARY",
      "date": "09-20"
    }
  ]
}

Merge Guests

Merge duplicate guest profiles:

POST /api/v1/guests/merge

Request Body:

{
  "primary_guest_id": "guest_abc123",
  "merge_guest_ids": ["guest_dup001", "guest_dup002"]
}

Response:

{
  "data": {
    "merged_guest_id": "guest_abc123",
    "profiles_merged": 2,
    "reservations_transferred": 5
  }
}

GDPR Operations

Export Guest Data

GET /api/v1/guests/:id/export

Returns all data associated with the guest in JSON format.

Anonymize Guest

POST /api/v1/guests/:id/anonymize

Anonymizes guest data while preserving statistical records.

VIP Status Values

Status	Description
STANDARD	Regular guest
SILVER	Frequent guest
GOLD	Valued guest
PLATINUM	Premium guest
VIP	Very Important Person
VVIP	Top priority guest

Error Responses

Duplicate Email

{
  "error": "duplicate_email",
  "message": "A guest with this email already exists",
  "existing_guest_id": "guest_abc123"
}

Status: 409 Conflict

Related Documentation

• Reservations API
• CRM Overview