Guests
search_guests read
Section titled “search_guests ”Search guests by name / phone / email AND/OR filter by dietary tag or allergy. All filters AND together; multiple values within `dietary` or `allergies` OR within that field. Use this for “find all peanut-allergic customers”, “every vegan we have”, “John Smith with shellfish allergy”. Match is case-insensitive across all filters. Paginated (default 25, max 100).
Required scope: guests.read
| Parameter | Type | Required | Description |
|---|---|---|---|
brand |
string | no | Brand slug. Optional in JWT mode; required in multi-brand API-key mode. |
query |
string | no | Optional name / phone / email substring. Skip when filtering purely by dietary or allergies. |
dietary |
array | no | Dietary tags to match (e.g. [“vegan”], [“gluten-free”,“kosher”]). Case-insensitive. Multiple values OR. |
allergies |
array | no | Allergens to match (e.g. [“peanuts”], [“shellfish”,“soy”]). Case-insensitive. Multiple values OR. |
limit |
number | no | |
page |
number | no |
get_dietary_summary read
Section titled “get_dietary_summary ”Aggregate counts of dietary preferences and allergies across the whole guest base. Returns total guests, how many have any dietary tag, how many have any allergy, and ranked tag-by-tag counts. Use for ‘most common allergy?’, ‘how many vegans do we have?’, ‘allergy hotlist’. Tags are normalized (lowercase, trimmed) so ‘Vegan’/‘vegan’/’ VEGAN ’ fold into one bucket.
Required scope: guests.read
| Parameter | Type | Required | Description |
|---|---|---|---|
brand |
string | no | Brand slug. Optional in JWT mode; required in multi-brand API-key mode. |
topN |
number | no | How many top tags to return per category. Default 10. |
get_guest read
Section titled “get_guest ”Fetch a single guest profile by id. Includes name, phone, email, dietary, allergies, and any per-brand notes.
Required scope: guests.read
| Parameter | Type | Required | Description |
|---|---|---|---|
brand |
string | no | Brand slug. Optional in JWT mode; required in multi-brand API-key mode. |
id |
string | yes |
get_guest_history read
Section titled “get_guest_history ”Visit history rollup for a guest: total visits, completed/cancelled/no-show counts, last visit date, recent reservations. The aggregation runs against the brand’s reservations collection — not cached, so call sparingly.
Required scope: guests.read
| Parameter | Type | Required | Description |
|---|---|---|---|
brand |
string | no | Brand slug. Optional in JWT mode; required in multi-brand API-key mode. |
id |
string | yes | |
recentLimit |
number | no | Number of recent reservations to include in the response. |
update_guest write
Section titled “update_guest ”Patch the per-brand guest profile: name, email, dietary, allergies, birthday (MM-DD), anniversary (MM-DD), tags, internal staff notes. Use this whenever the operator mentions a preference, milestone, or note worth remembering. Phone is intentionally NOT mutable here — phone changes happen at the customer-merge level.
Required scope: guests.write
| Parameter | Type | Required | Description |
|---|---|---|---|
brand |
string | no | Brand slug. Optional in JWT mode; required in multi-brand API-key mode. |
id |
string | yes | |
name |
string | no | |
dietary |
array | no | |
allergies |
array | no | |
email |
string | no | |
birthday |
string | no | Birthday as MM-DD (year-agnostic). Pass null to clear. |
anniversary |
string | no | Anniversary as MM-DD (year-agnostic). Pass null to clear. |
tags |
array | no | Operator tags (“VIP”, “press”, “do-not-seat-near-bar”, etc.). Replaces the existing list. |
internalNotes |
string | no | Per-brand staff notes. Surface every visit. Pass null to clear. |
idempotencyKey |
string | no |