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 notesemail(optional): Full-text search on the email fieldphone(optional): Full-text search on the phone fieldcompany(optional): Full-text search on the company fieldlocale(optional): Filter by locale (en,deorit)labelIds(optional): Filter by label IDs. Guests must have all of them.hasEmail(optional): Only guests with emailhasPhone(optional): Only guests with phonelimit(optional): Max results (default/max: 100)page(optional): Page numbersortBy(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 identifierfirstName: 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,deorit)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
- Search first - Use search endpoint to check if guest exists
- Validate email/phone - Ensure correct format
- Use E.164 format - Phone numbers with country code (e.g.,
+436605512234) - Provide an email - Guests are only matched by email and name
- Consistent locale - Set appropriate locale for communications