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): Full-text search over names, email, phone, company and notes
  • email (optional): Full-text search on the email field
  • phone (optional): Full-text search on the phone field
  • company (optional): Full-text search on the company field
  • locale (optional): Filter by locale (en, de or it)
  • labelIds (optional): Filter by label IDs. Guests must have all of them.
  • 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). Default: totalVisits:desc.

The API uses only one of search, email, phone and company, in this order. The others are ignored. email, phone and company are not exact matches. Compare the returned values yourself when you need an exact match.

Guests belong to the account. The result includes guests of all restaurants of the account.

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, de or it)
  • 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 matching​

When you create a reservation, the API reuses an existing guest when one has:

  • the same email, and
  • the same first name and last name (case-insensitive)

The API updates the matched guest with the data from the request. Otherwise it creates a new guest. Phone numbers are not used for matching, and existing duplicates are not merged.

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 an email - Guests are only matched by email and name
  5. Consistent locale - Set appropriate locale for communications

Next Steps​