# Schemas

> The named schemas of Tamr's API: chat requests and events, dish cards, the menu, conversations, errors and every webhook payload, field by field.

Source: https://tamr.link/docs/api/schemas

The objects the API reference pages link to, field by field, from the committed OpenAPI spec. Nested objects show two levels deep; the spec at [tamr.link/api/v1/openapi.json](https://tamr.link/api/v1/openapi.json) has every level.

### ChatRequest

| Field | Type | Description |
| --- | --- | --- |
| `message` | string | 1 to 2,000 characters. |
| `conversationId` | string | May be absent. 1 to 200 characters. |
| `branch` | string | May be absent. An address: lower-case letters, digits and dashes. |
| `mode` | string | May be absent. One of `dine_in`, `pickup`, `delivery`. |
| `table` | string | May be absent. 1 to 40 characters. |
| `locale` | string | May be absent. A language tag, such as `ar` or `en-GB`. |
| `restrictions` | object | May be absent. |
| `restrictions.avoidAllergens` | array of string | At most 10 items. Each: One of `gluten`, `dairy`, `egg`, `nuts`, `sesame`, `soy`, `fish`, `shellfish`, `peanut`, `mustard`. |
| `restrictions.keepDiets` | array of string | At most 8 items. Each: One of `vegan`, `vegetarian`, `gluten_free`, `halal`, `kosher`, `dairy_free`, `nut_free`, `keto`. |
| `cart` | array of object | May be absent. At most 50 items. |
| `cart[].dishId` | string | 1 to 200 characters. |
| `cart[].variantId` | string | May be absent. 1 to 200 characters. |
| `cart[].optionIds` | array of string | May be absent. At most 20 items. 1 to 200 characters. |
| `cart[].quantity` | integer | 1 to 99. |
| `cart[].picks` | array of object | May be absent. At most 120 items. |
| `goal` | object | May be absent. |
| `goal.mode` | string | One of `cutting`, `maintain`, `bulking`. |
| `goal.kcal` | integer | May be absent. Calories for one meal: a ceiling when cutting or maintaining, a floor when bulking. 100 to 3,000. |
| `goal.proteinGrams` | integer | May be absent. Grams of protein for one meal, always a floor. 5 to 300. |
| `takes` | array of string | May be absent. At most 16 items. Matches `^[a-z][a-z_.]{0,47}$`. |
| `hide` | object | May be absent. |
| `hide.retailSuggestions` | boolean | May be absent. |
| `hide.loyalty` | boolean | May be absent. |
| `cardActions` | array of object | May be absent. At most 6 items. |
| `cardActions[].tool` | `"offer_to_order"` |  |
| `cardActions[].offeredAt` | string | At most 40 characters. |
| `cardActions[].outcome` | `"added"` |  |
| `cardActions[].lines` | array of object | 1 to 8 items. |

### ChatEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"start"` |  |
| `conversationId` | string | May be absent. 1 to 200 characters. |
| `messageId` | string | May be absent. 1 to 200 characters. |
| `delta` | string | May be absent. |
| `cardId` | string | May be absent. 1 to 200 characters. |
| `card` | [ChatCard](https://tamr.link/docs/api/schemas#chatcard) | May be absent. |

### ChatDone

| Field | Type | Description |
| --- | --- | --- |
| `finishReason` | string | One of `stop`, `length`, `content_filter`, `aborted`, `error`, `other`. An open list: read a value you don't know as `other`. |

### ChatCard

A card the waiter put on screen, with the dishes it shows. Fields per kind; an unknown kind reads as other.

| Field | Type | Description |
| --- | --- | --- |
| `kind` | string | One of `dishes`, `surprise_basket`, `quick_replies`, `dietary_filters`, `language_choice`, `staff_called`, `branch_info`, `booking_times`, `booking`, `saved`, `cart_proposal`, `order_offer`, `pay_offer`, `build`, `other`. An open list: read a value you don't know as `other`. |
| `dishes` | array of [DishSummary](https://tamr.link/docs/api/schemas#dishsummary) | May be absent. At most 20 items. |
| `layout` | string | May be absent. One of `card`, `carousel`, `comparison`, `pairing`, `other`. An open list: read a value you don't know as `other`. |
| `framing` | string | May be absent. At most 500 characters. |
| `aspect` | string | May be absent. At most 40 characters. |
| `special` | object | May be absent. |
| `special.headline` | string | At most 200 characters. |
| `special.blurb` | string or null | At most 500 characters. |
| `allergen` | string | May be absent. At most 200 characters. |
| `verification` | string | May be absent. One of `menu-data`, `text-match`, `other`. An open list: read a value you don't know as `other`. |
| `disclaimer` | string | May be absent. At most 1,000 characters. |
| `conflicts` | array of object | May be absent. At most 20 items. |
| `conflicts[].allergen` | string | At most 200 characters. |
| `conflicts[].dishes` | array of string | At most 20 items. At most 200 characters. |
| `build` | object | May be absent. |
| `build.buildId` | string | 1 to 64 characters. |
| `build.dish` | [DishSummary](https://tamr.link/docs/api/schemas#dishsummary) |  |
| `build.size` | string or null | At most 80 characters. |
| `build.needsSize` | boolean |  |
| `build.groups` | array of object | At most 20 items. |
| `build.complete` | boolean |  |
| `build.total` | string | An amount in minor units, as a string. |
| `build.nutrition` | object |  |
| `build.goalFit` | string | May be absent. One of `fits`, `over`, `under`, `unknown`, `other`. An open list: read a value you don't know as `other`. |
| `baskets` | array of object | May be absent. At most 3 items. |
| `baskets[].items` | array of object | At most 12 items. |
| `baskets[].total` | string | An amount in minor units, as a string. |
| `baskets[].nutrition` | object | May be absent. |
| `baskets[].goalFit` | string | May be absent. One of `fits`, `over`, `under`, `unknown`, `other`. An open list: read a value you don't know as `other`. |
| `budget` | string or null | May be absent. An amount in minor units, as a string. |
| `goal` | object | May be absent. |
| `goal.mode` | string | One of `cutting`, `maintain`, `bulking`, `other`. An open list: read a value you don't know as `other`. |
| `goal.fits` | array of string | At most 20 items. 1 to 200 characters. |
| `goal.unknown` | array of string | At most 20 items. 1 to 200 characters. |
| `prompts` | array of string | May be absent. At most 6 items. At most 60 characters. |
| `tags` | array of string | May be absent. At most 10 items. Each: One of `vegan`, `vegetarian`, `gluten_free`, `halal`, `kosher`, `dairy_free`, `nut_free`, `keto`, `spicy`, `high_protein`, `other`. An open list: read a value you don't know as `other`. |
| `languages` | array of string | May be absent. At most 12 items. A language tag, such as `ar` or `en-GB`. |
| `staffCall` | object | May be absent. |
| `staffCall.source` | string | One of `request`, `escalation`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `staffCall.kind` | string | May be absent. One of `order_now`, `water`, `check`, `extra_napkins`, `refill`, `other`. An open list: read a value you don't know as `other`. |
| `staffCall.reason` | string | May be absent. One of `diner_requested_staff`, `allergen_severe`, `off_menu_question`, `order_placement`, `complaint`, `reservation`, `payment`, `unknown_other`. An open list: read a value you don't know as `unknown_other`. |
| `staffCall.urgency` | string | May be absent. One of `normal`, `high`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `staffCall.alreadySent` | boolean |  |
| `branchInfo` | object | May be absent. |
| `branchInfo.name` | string or null | At most 200 characters. |
| `branchInfo.rows` | array of object | At most 10 items. |
| `bookingTimes` | object | May be absent. |
| `bookingTimes.date` | string | Matches `^\d{4}-\d{2}-\d{2}$`. |
| `bookingTimes.dateLabel` | string | At most 80 characters. |
| `bookingTimes.times` | array of string | At most 48 items. Matches `^(?:[01]\d\|2[0-3]):[0-5]\d$`. |
| `bookingTimes.asRequest` | boolean |  |
| `booking` | object | May be absent. |
| `booking.outcome` | string | One of `booked`, `already_booked`, `changed`, `cancelled`, `other`. An open list: read a value you don't know as `other`. |
| `booking.status` | string | One of `requested`, `confirmed`, `cancelled`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `booking.code` | string | At most 40 characters. |
| `booking.partySize` | integer | 1 to 500. |
| `booking.startsAt` | string (date-time) |  |
| `booking.timezone` | string | At most 60 characters. |
| `booking.dateLabel` | string | At most 80 characters. |
| `booking.time` | string | At most 20 characters. |
| `booking.locationName` | string | At most 200 characters. |
| `booking.confirmationNote` | string or null | At most 500 characters. |
| `booking.bookingId` | string | May be absent. 1 to 200 characters. |
| `booking.branch` | string | May be absent. An address: lower-case letters, digits and dashes. |
| `booking.date` | string | May be absent. Matches `^\d{4}-\d{2}-\d{2}$`. |
| `booking.time24` | string | May be absent. Matches `^(?:[01]\d\|2[0-3]):[0-5]\d$`. |
| `saved` | [DishSummary](https://tamr.link/docs/api/schemas#dishsummary) | May be absent. |
| `lines` | array of object | May be absent. At most 12 items. |
| `lines[].lineId` | string | Unique per proposed line: the host answers and dedupes by it. 1 to 200 characters. |
| `lines[].dishId` | string | Tamr's id for the dish. 1 to 200 characters. |
| `lines[].variantId` | string or null | Tamr's id for the size; null for a dish sold in one size. 1 to 200 characters. |
| `lines[].optionIds` | array of string | Tamr's ids for the chosen options. At most 20 items. 1 to 200 characters. |
| `lines[].externalId` | string or null | The host's id for the dish at this branch; null when not mapped. 1 to 200 characters. |
| `lines[].variantExternalId` | string or null | The host's id for the size; null when not mapped. 1 to 200 characters. |
| `lines[].optionExternalIds` | array of string or null | The host's ids for the options, one per entry of optionIds; null where not mapped. At most 20 items. |
| `lines[].title` | string | 1 to 200 characters. |
| `lines[].variantLabel` | string or null | The size as the menu labels it; null for a dish with one size. 1 to 80 characters. |
| `lines[].choices` | array of string | The chosen options' names, in the order of optionIds. At most 20 items. 1 to 80 characters. |
| `lines[].unitPrice` | string | An amount in minor units, as a string. |
| `lines[].currency` | string | A three-letter currency code (ISO 4217). |
| `lines[].imageUrl` | string or null | Matches `^https:\/\/[^\s]+$`. |
| `lines[].quantity` | integer | How many of the line. For a set, how many whole sets: picks included. 1 to 99. |
| `lines[].note` | string or null | The diner's own request for the kitchen ("no onions"). 1 to 140 characters. |
| `lines[].picks` | array of object | May be absent. A set's picks, in the order of its choices (#560). Absent on any other line. Each pick's count is per one set; quantity multiplies the whole set. At most 120 items. |
| `lines[].treat` | object | May be absent. A treat on the house (#455): price this line at zero, then redeem the id once the order is placed. Absent on any other line. |
| `offer` | object | May be absent. |
| `offer.items` | array of object | 1 to 8 items. |
| `offer.framing` | string or null | At most 120 characters. |
| `offer.offeredAt` | string (date-time) |  |
| `offer.added` | boolean | May be absent. |
| `notAdded` | array of object | May be absent. At most 12 items. |
| `notAdded[].dishId` | string | 1 to 200 characters. |
| `notAdded[].name` | string | 1 to 200 characters. |
| `notAdded[].reason` | string | One of `sold_out`, `not_served_now`, `size_required`, `choices_required`, `allergen_conflict`, `other`. An open list: read a value you don't know as `other`. |
| `reorder` | object | May be absent. |
| `reorder.which` | string | One of `usual`, `last`, `other`. An open list: read a value you don't know as `other`. |
| `reorder.placedAt` | string (date-time) |  |
| `reorder.dropped` | array of object | At most 100 items. |

### DishSummary

A dish as a card or the menu shows it: enough to draw it with no other call.

| Field | Type | Description |
| --- | --- | --- |
| `dishId` | string | 1 to 200 characters. |
| `name` | string | 1 to 200 characters. |
| `price` | string | An amount in minor units, as a string. |
| `currency` | string | A three-letter currency code (ISO 4217). |
| `imageUrl` | string or null | Matches `^https:\/\/[^\s]+$`. |
| `calories` | integer or null | 0 to 9,007,199,254,740,991. |
| `proteinGrams` | integer or null | 0 to 9,007,199,254,740,991. |
| `carbsGrams` | integer or null | 0 to 9,007,199,254,740,991. |
| `fatGrams` | integer or null | 0 to 9,007,199,254,740,991. |
| `allergens` | array of string | At most 10 items. Each: One of `gluten`, `dairy`, `egg`, `nuts`, `sesame`, `soy`, `fish`, `shellfish`, `peanut`, `mustard`. |
| `dietaryTags` | array of string | At most 11 items. Each: One of `vegan`, `vegetarian`, `gluten_free`, `halal`, `kosher`, `dairy_free`, `nut_free`, `keto`, `spicy`, `high_protein`, `other`. An open list: read a value you don't know as `other`. |
| `available` | boolean |  |
| `externalId` | string or null | 1 to 200 characters. |

### MenuResponse

| Field | Type | Description |
| --- | --- | --- |
| `menu` | object |  |
| `menu.name` | string | 1 to 200 characters. |
| `menu.locale` | string | A language tag, such as `ar` or `en-GB`. |
| `menu.currency` | string | A three-letter currency code (ISO 4217). |
| `categories` | array of object |  |
| `categories[].name` | string | 1 to 200 characters. |
| `categories[].dishes` | array of object |  |

### CatalogMenuResponse

One published menu as the host's backend keeps it: the dishes exactly as GET /api/v1/menu lists them, with the menu's ids and version.

| Field | Type | Description |
| --- | --- | --- |
| `menu` | object |  |
| `menu.menuId` | string | 1 to 200 characters. |
| `menu.menuSlug` | string | 1 to 200 characters. |
| `menu.name` | string | 1 to 200 characters. |
| `menu.locale` | string | A language tag, such as `ar` or `en-GB`. |
| `menu.currency` | string | A three-letter currency code (ISO 4217). |
| `menu.modes` | array of string | At most 3 items. Each: One of `dine_in`, `pickup`, `delivery`. |
| `menu.branch` | string or null | An address: lower-case letters, digits and dashes. |
| `menu.version` | integer | 0 to 9,007,199,254,740,991. |
| `menu.updatedAt` | string (date-time) |  |
| `categories` | array of object |  |
| `categories[].name` | string | 1 to 200 characters. |
| `categories[].dishes` | array of object |  |

### WaiterFace

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | 1 to 60 characters. |
| `avatarLetter` | string | 1 to 2 characters. |
| `greeting` | string | 1 to 500 characters. |
| `starters` | array of string | At most 8 items. 1 to 80 characters. |
| `voice` | boolean |  |
| `languages` | array of string | At most 12 items. A language tag, such as `ar` or `en-GB`. |
| `brand` | object | May be absent. The restaurant's brand: the menu's kit over the organization's. Every field optional. |
| `brand.accent` | string | May be absent. Matches `^#[0-9a-fA-F]{6}$`. |
| `brand.accentSecondary` | string | May be absent. Matches `^#[0-9a-fA-F]{6}$`. |
| `brand.paper` | string | May be absent. Matches `^#[0-9a-fA-F]{6}$`. |
| `brand.displayFont` | string | May be absent. One of `fraunces`, `cormorant`, `playfair`, `dm-serif`, `eb-garamond`, `crimson`, `other`. An open list: read a value you don't know as `other`. |
| `brand.uiFont` | string | May be absent. One of `geist`, `inter`, `system`, `manrope`, `sora`, `dm-sans`, `other`. An open list: read a value you don't know as `other`. |
| `brand.displayFontUrl` | string | May be absent. Matches `^https:\/\/[^\s]+$`. |
| `brand.uiFontUrl` | string | May be absent. Matches `^https:\/\/[^\s]+$`. |
| `brand.logoUrl` | string | May be absent. Matches `^https:\/\/[^\s]+$`. |
| `ordersGoTo` | string | One of `tamr`, `app_cart`. An open list: read a value you don't know as `tamr`. |
| `ordersGoToByMode` | object | May be absent. Where orders go for each way of ordering, over ordersGoTo. A way left out goes where ordersGoTo says. |
| `ordersGoToByMode.dine_in` | string | May be absent. One of `tamr`, `app_cart`. An open list: read a value you don't know as `tamr`. |
| `ordersGoToByMode.pickup` | string | May be absent. One of `tamr`, `app_cart`. An open list: read a value you don't know as `tamr`. |
| `ordersGoToByMode.delivery` | string | May be absent. One of `tamr`, `app_cart`. An open list: read a value you don't know as `tamr`. |
| `app` | object | May be absent. The restaurant's settings for the waiter in its app, between the menu's brand and the app's overrides. Every field but allowCustomise may be left out. |
| `app.look` | object | May be absent. |
| `app.shown` | object | May be absent. |
| `app.wording` | object | May be absent. |
| `app.starters` | object | May be absent. |
| `app.allowCustomise` | boolean |  |

### ConversationList

| Field | Type | Description |
| --- | --- | --- |
| `conversations` | array of object | At most 50 items. |
| `conversations[].conversationId` | string | 1 to 200 characters. |
| `conversations[].status` | string | One of `active`, `resolved`, `escalated`, `fallback`, `abandoned`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `conversations[].channel` | string | One of `qr`, `widget`, `app`, `mcp`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `conversations[].locale` | string or null | A language tag, such as `ar` or `en-GB`. |
| `conversations[].startedAt` | string (date-time) |  |
| `conversations[].updatedAt` | string (date-time) |  |
| `conversations[].title` | string or null | At most 200 characters. |

### ConversationResponse

| Field | Type | Description |
| --- | --- | --- |
| `conversationId` | string | 1 to 200 characters. |
| `status` | string | One of `active`, `resolved`, `escalated`, `fallback`, `abandoned`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `channel` | string | One of `qr`, `widget`, `app`, `mcp`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `locale` | string or null | A language tag, such as `ar` or `en-GB`. |
| `startedAt` | string (date-time) |  |
| `updatedAt` | string (date-time) |  |
| `messages` | array of object |  |
| `messages[].messageId` | string | 1 to 200 characters. |
| `messages[].role` | string | One of `diner`, `waiter`, `other`. An open list: read a value you don't know as `other`. |
| `messages[].createdAt` | string (date-time) |  |
| `messages[].text` | string or null |  |
| `messages[].cards` | array of [ChatCard](https://tamr.link/docs/api/schemas#chatcard) |  |

### ClientApiErrorData

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | One of `app_key_invalid`, `sdk_disabled`, `origin_not_allowed`, `session_expired`, `token_invalid`, `token_replayed`, `code_invalid`, `guest_not_allowed`, `unavailable`, `rate_limited`, `menu_unavailable`, `after_hours_closed`, `waiter_resting`, `test_limit_reached`, `max_turns_reached`, `message_rejected`, `nothing_heard`, `invalid_request`, `not_found`, `table_refused`, `pay_refused`, `pickup_refused`, `review_refused`, `identity_required`, `treat_refused`, `other`. An open list: read a value you don't know as `other`. |
| `requestId` | string | May be absent. At most 128 characters. |
| `retryAfter` | integer | May be absent. 0 to 9,007,199,254,740,991. |
| `refusal` | string | May be absent. One of `unknown_table`, `table_off_plan`, `no_table`, `table_cleared`, `stale`, `ordering_off`, `paused`, `closed`, `unavailable`, `test_key`, `other`. An open list: read a value you don't know as `other`. |
| `problems` | array of object | May be absent. At most 60 items. |
| `problems[].dishId` | string | 1 to 200 characters. |
| `problems[].name` | string or null | At most 200 characters. |
| `problems[].problem` | string | One of `gone`, `sold_out`, `not_served_now`, `size_required`, `size_gone`, `choices_required`, `quantity`, `other`. An open list: read a value you don't know as `other`. |
| `pausedUntil` | string (date-time) | May be absent. |
| `payRefusal` | string | May be absent. One of `not_enabled`, `paused`, `no_provider`, `provider_not_available`, `test_key`, `orders_to_app`, `invalid_amount`, `below_minimum`, `above_maximum`, `tip_too_large`, `tips_off`, `daily_cap`, `wallet_full`, `monthly_cap`, `payment_in_progress`, `already_paid`, `provider_unavailable`, `provider_error`, `table_already_paid`, `tab_not_found`, `typed_amount_off`, `tab_nothing_owed`, `tab_amount_over`, `tab_changed`, `other`. An open list: read a value you don't know as `other`. |
| `pickupRefusal` | string | May be absent. One of `ordering_off`, `no_branch`, `paused`, `closed`, `pickup_time`, `details`, `blocked`, `too_large`, `unavailable`, `catering_menu`, `test_key`, `other`. An open list: read a value you don't know as `other`. |
| `reviewRefusal` | string | May be absent. One of `order_not_found`, `order_closed`, `too_old`, `nothing_to_review`, `other`. An open list: read a value you don't know as `other`. |
| `treatRefusal` | string | May be absent. One of `withdrawn`, `expired`, `already_redeemed`, `other`. An open list: read a value you don't know as `other`. |
| `amount` | string | May be absent. An amount in minor units, as a string. |
| `paymentId` | string | May be absent. 1 to 200 characters. |
| `fallback` | object | May be absent. |
| `fallback.name` | string | At most 200 characters. |
| `fallback.phone` | string or null | At most 40 characters. |
| `fallback.message` | string | At most 500 characters. |

### ConversationEndedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"conversation.ended"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.conversationId` | string | 1 to 200 characters. |
| `data.appKeyId` | string | 1 to 200 characters. |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.branch` | string or null | An address: lower-case letters, digits and dashes. |
| `data.reason` | string | One of `resolved`, `idle`, `new_chat`, `logged_out`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `data.startedAt` | string (date-time) |  |
| `data.endedAt` | string (date-time) |  |
| `data.staffCalled` | boolean |  |
| `data.messageCount` | integer | 0 to 9,007,199,254,740,991. |

### CartProposedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"cart.proposed"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.conversationId` | string | 1 to 200 characters. |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.proposalId` | string | 1 to 200 characters. |
| `data.lines` | array of object | 1 to 50 items. |

### StaffRequestedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"staff.requested"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.conversationId` | string | 1 to 200 characters. |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.branch` | string or null | An address: lower-case letters, digits and dashes. |
| `data.table` | string or null | 1 to 40 characters. |
| `data.source` | string | One of `request`, `escalation`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `data.kind` | string | May be absent. One of `order_now`, `water`, `check`, `extra_napkins`, `refill`, `other`. An open list: read a value you don't know as `other`. |
| `data.reason` | string | May be absent. One of `diner_requested_staff`, `allergen_severe`, `off_menu_question`, `order_placement`, `complaint`, `reservation`, `payment`, `unknown_other`. An open list: read a value you don't know as `unknown_other`. |
| `data.urgency` | string | May be absent. One of `normal`, `high`, `unknown`. An open list: read a value you don't know as `unknown`. |

### BookingMadeEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"booking.made"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.conversationId` | string | 1 to 200 characters. |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.bookingId` | string | 1 to 200 characters. |
| `data.status` | string | One of `requested`, `confirmed`, `cancelled`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `data.branch` | string | An address: lower-case letters, digits and dashes. |
| `data.date` | string | Matches `^\d{4}-\d{2}-\d{2}$`. |
| `data.time` | string | Matches `^(?:[01]\d\|2[0-3]):[0-5]\d$`. |
| `data.partySize` | integer | 1 to 500. |

### BookingChangedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"booking.changed"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.conversationId` | string | 1 to 200 characters. |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.bookingId` | string | 1 to 200 characters. |
| `data.status` | string | One of `requested`, `confirmed`, `cancelled`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `data.branch` | string | An address: lower-case letters, digits and dashes. |
| `data.date` | string | Matches `^\d{4}-\d{2}-\d{2}$`. |
| `data.time` | string | Matches `^(?:[01]\d\|2[0-3]):[0-5]\d$`. |
| `data.partySize` | integer | 1 to 500. |

### OrderPlacedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"order.placed"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.conversationId` | string or null | 1 to 200 characters. |
| `data.orderId` | string | 1 to 200 characters. |
| `data.number` | integer | The short number staff call out, per branch and service day. -9,007,199,254,740,991 to 9,007,199,254,740,991. |
| `data.status` | string | One of `awaiting_payment`, `sent`, `accepted`, `served`, `declined`, `cancelled`, `expired`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `data.branch` | string | An address: lower-case letters, digits and dashes. |
| `data.table` | string or null | 1 to 40 characters. |
| `data.currency` | string | A three-letter currency code (ISO 4217). |
| `data.subtotal` | string | An amount in minor units, as a string. |
| `data.lines` | array of object | 1 to 100 items. |
| `data.fulfilment` | string | May be absent. One of `dine_in`, `pickup`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `data.pickupAt` | string (date-time) or null | May be absent. |
| `data.pickupCode` | string or null | May be absent. 1 to 12 characters. |
| `data.test` | boolean | May be absent. |

### OrderCancelledEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"order.cancelled"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.orderId` | string | 1 to 200 characters. |
| `data.status` | string | One of `awaiting_payment`, `sent`, `accepted`, `served`, `declined`, `cancelled`, `expired`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `data.by` | string | One of `restaurant`, `diner`, `time`, `unknown`. An open list: read a value you don't know as `unknown`. |

### PaymentCompletedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"payment.completed"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.externalUserId` | string or null | 1 to 200 characters. |
| `data.conversationId` | string or null | 1 to 200 characters. |
| `data.paymentId` | string | 1 to 200 characters. |
| `data.reference` | string | 1 to 40 characters. |
| `data.amount` | string | An amount in minor units, as a string. |
| `data.tip` | string | An amount in minor units, as a string. |
| `data.currency` | string | A three-letter currency code (ISO 4217). |
| `data.orderId` | string or null | 1 to 200 characters. |
| `data.branch` | string | An address: lower-case letters, digits and dashes. |
| `data.table` | string or null | 1 to 40 characters. |

### ReviewSubmittedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"review.submitted"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.reviewId` | string | 1 to 200 characters. |
| `data.externalUserId` | string | 1 to 200 characters. |
| `data.externalOrderId` | string or null | 1 to 200 characters. |
| `data.conversationId` | string or null | 1 to 200 characters. |
| `data.dishId` | string | 1 to 200 characters. |
| `data.externalId` | string or null | 1 to 200 characters. |
| `data.rating` | integer | 1 to 5. |
| `data.submittedAt` | string (date-time) |  |

### MenuChangedEvent

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"menu.changed"` |  |
| `timestamp` | string (date-time) |  |
| `livemode` | boolean |  |
| `data` | object |  |
| `data.menuId` | string | 1 to 200 characters. |
| `data.menuSlug` | string | 1 to 200 characters. |
| `data.published` | boolean |  |
| `data.modes` | array of string | At most 3 items. Each: One of `dine_in`, `pickup`, `delivery`. |
| `data.branches` | array of object | At most 500 items. |
| `data.version` | integer | 0 to 9,007,199,254,740,991. |
| `data.reason` | string | One of `content`, `external_ids`, `back_on_sale`, `other`. An open list: read a value you don't know as `other`. |
| `data.changedAt` | string (date-time) |  |
| `data.dishIds` | array of string | May be absent. At most 500 items. 1 to 200 characters. |

### ClientApiError

| Field | Type | Description |
| --- | --- | --- |
| `defined` | boolean |  |
| `code` | string |  |
| `status` | integer |  |
| `message` | string |  |
| `data` | [ClientApiErrorData](https://tamr.link/docs/api/schemas#clientapierrordata) | May be absent. |
