Skip to main content

Manage Guests

Working with guest profiles in the Molzait API.

Overview​

Guest profiles store contact information and reservation history. Reusing guest profiles enables:

  • Faster reservation creation
  • Personalized service
  • Reservation history tracking
  • Guest preferences

Search Guests​

Search for guests using various filters:

Request​

GET /external/guests?search={query}&limit={limit}&page={page}

Parameters​

  • search (optional): Search query for names, email, phone, company, or notes
  • email (optional): Filter by exact email
  • phone (optional): Filter by exact phone
  • company (optional): Filter by company name
  • locale (optional): Filter by locale (en or de)
  • labelIds (optional): Filter by label IDs
  • hasEmail (optional): Only guests with email
  • hasPhone (optional): Only guests with phone
  • limit (optional): Max results (default/max: 100)
  • page (optional): Page number
  • sortBy (optional): Sort field (e.g., lastName:asc, totalVisits:desc)

Example - Search by Email​

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.molzait.com/external/guests?email=john.doe@example.com"

Example - Search by Text​

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.molzait.com/external/guests?search=john&limit=10&page=1"

Example - Search by Phone​

Phone numbers should be in E.164 format (e.g., +436605512234). URL-encode the + as %2B:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.molzait.com/external/guests?phone=%2B436605512234"

Response​

[
  {
    "id": "e5e25ac76a2e-4f6d-8f8d-98e64ad283c3",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+436605512234",
    "company": "BestCorp Inc.",
    "locale": "de",
    "notes": "Likes to drink red wine",
    "labels": []
  }
]

Note: The API does not support creating or updating guest profiles directly. Guests are automatically created and updated through reservation operations.

Guest Fields​

Guests have the following fields:

  • id: Unique guest identifier
  • firstName: Guest first name (optional)
  • lastName: Guest last name (required)
  • email: Email address (optional)
  • phone: Phone number in E.164 format (optional)
  • company: Company name (optional)
  • locale: Preferred locale (en or de)
  • notes: Internal notes (optional)
  • labels: Array of label objects

Using Guests in Reservations​

Guests are automatically created or matched when creating reservations. Simply provide the guest information:

{
  "attendees": 2,
  "day": "2024-01-02",
  "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
  "minutes": 600,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+436605512234",
  "locale": "en"
}

Guest Deduplication​

Molzait automatically detects and merges duplicate guests by:

  • Exact email match
  • Exact phone match

When creating reservations, if a matching guest exists, it will be reused automatically.

Best Practices​

  1. Search first - Use search endpoint to check if guest exists
  2. Validate email/phone - Ensure correct format
  3. Use E.164 format - Phone numbers with country code (e.g., +436605512234)
  4. Provide email or phone - At least one contact method for better matching
  5. Consistent locale - Set appropriate locale for communications

Next Steps​