> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everybite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GuestIQ

> Real-time guest intelligence, from first touch to loyalty

**GuestIQ** is EveryBite's real-time guest intelligence platform. It identifies guests the moment they open your menu, delivers their segments and behavioral history instantly, and feeds that intelligence into your loyalty and marketing systems.

<Info>
  **The key insight:** Traditional loyalty identifies guests *after* they purchase. GuestIQ identifies them *before* they browse—enabling personalization from the very first screen.
</Info>

## What GuestIQ Does

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e40af', 'primaryTextColor': '#ffffff', 'lineColor': '#475569', 'fontFamily': 'system-ui, -apple-system, sans-serif', 'fontSize': '14px', 'clusterBkg': '#f8fafc', 'clusterBorder': '#1e40af'}}}%%
flowchart LR
    subgraph GuestIQ["⚡ GuestIQ — Real-time at session creation"]
        direction LR
        subgraph Identify["IDENTIFY"]
            direction TB
            I1["Who is this guest?"]
            I2["• Known"]
            I3["• Returning"]
            I4["• New"]
        end

        subgraph Segment["SEGMENT"]
            direction TB
            S1["What do they want?"]
            S2["• Primary"]
            S3["• Compound"]
            S4["• Cohorts"]
        end

        subgraph Activate["ACTIVATE"]
            direction TB
            A1["• Personalize menu"]
            A2["• Alert staff"]
            A3["• Feed loyalty"]
            A4["• Recommend dishes"]
        end

        Identify --> Segment --> Activate
    end

    Guest["Guest opens menu"] --> GuestIQ

    classDef guest fill:#e2e8f0,stroke:#94a3b8,color:#1e293b,stroke-width:2px
    classDef phase fill:#2563eb,stroke:#1d4ed8,color:#ffffff,stroke-width:1px
    classDef detail fill:#ffffff,stroke:#cbd5e1,color:#1e293b,stroke-width:1px

    class Guest guest
    class Identify,Segment,Activate phase
    class I1,I2,I3,I4,S1,S2,S3,S4,A1,A2,A3,A4 detail
```

## Why GuestIQ Matters

### Traditional Loyalty Flow

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e40af', 'primaryTextColor': '#ffffff', 'lineColor': '#475569', 'fontFamily': 'system-ui, -apple-system, sans-serif', 'fontSize': '14px'}}}%%
flowchart LR
    Browse["Browse"] --> Order["Order"] --> Checkout["Checkout"] --> Account["Create Account"] --> Loyalty["Join Loyalty"] --> Know["NOW we know them"]
    Know -.- TooLate["❌ Too late to personalize"]

    classDef step fill:#e2e8f0,stroke:#94a3b8,color:#1e293b,stroke-width:1px
    classDef late fill:#fecaca,stroke:#f87171,color:#991b1b,stroke-width:2px
    classDef note fill:#ffffff,stroke:#f87171,color:#991b1b,stroke-width:1px,stroke-dasharray: 5 5

    class Browse,Order,Checkout,Account,Loyalty step
    class Know late
    class TooLate note
```

### With GuestIQ

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e40af', 'primaryTextColor': '#ffffff', 'lineColor': '#475569', 'fontFamily': 'system-ui, -apple-system, sans-serif', 'fontSize': '14px'}}}%%
flowchart LR
    Session["Create Session"] --> Know["INSTANTLY know who they are"]
    Know --> Segments["+ segments"]
    Segments --> History["+ history"]
    History --> Personalize["✅ Personalize from first screen"]

    classDef session fill:#2563eb,stroke:#1d4ed8,color:#ffffff,stroke-width:2px
    classDef intel fill:#dbeafe,stroke:#3b82f6,color:#1e40af,stroke-width:1px
    classDef success fill:#bbf7d0,stroke:#22c55e,color:#166534,stroke-width:2px

    class Session session
    class Know,Segments,History intel
    class Personalize success
```

GuestIQ moves identity resolution upstream—before the transaction, not after. This unlocks personalization at every step of the guest journey.

***

## Core Capabilities

<CardGroup cols={2}>
  <Card title="Instant Identity" icon="fingerprint">
    Recognize guests at session start using device fingerprint, email, phone, or loyalty ID. Even returning guests without accounts can be identified.
  </Card>

  <Card title="Real-Time Segments" icon="layer-group">
    Primary segments (wheat-free, high-protein) and compound segments (wheat-free + high-protein) computed and delivered in milliseconds.
  </Card>

  <Card title="Behavioral Intelligence" icon="brain">
    Past orders, favorite dishes, customization patterns, visit frequency—delivered at session creation so you can act on it immediately.
  </Card>

  <Card title="Loyalty Integration" icon="arrows-turn-to-dots">
    Feed rich behavioral data into your existing loyalty system via webhooks. Every signal enriches the guest profile.
  </Card>
</CardGroup>

***

## How It Works

When you call `startSession`, GuestIQ returns intelligence alongside the session:

```graphql theme={null}
mutation StartSession {
  startSession(input: {
    chainId: "honeygrow"
    guestId: "loyalty_12345"
    platform: IOS
  }) {
    sessionId

    # GuestIQ Intelligence
    guestiq {
      identity {
        guestId
        identifiedVia
        confidence
        isReturning
      }
      segments {
        primary
        compound
      }
      cohorts
      history {
        lastVisit
        visitCount
        favoriteDishes
        avgOrderValue
        customizationRate
      }
      recommendations {
        type
        dishId
        reason
      }
    }
  }
}
```

<Accordion title="Example Response">
  ```json theme={null}
  {
    "data": {
      "startSession": {
        "sessionId": "sess_7f3a9c2e-8b1d-4e5f-a6c0-9d2e8f1a3b5c",
        "guestiq": {
          "identity": {
            "guestId": "guest_abc123",
            "identifiedVia": "LOYALTY_ID",
            "confidence": 0.98,
            "isReturning": true
          },
          "segments": {
            "primary": ["wheat-free", "high-protein", "frequent-visitor"],
            "compound": [
              "wheat-free+high-protein",
              "wheat-free+frequent-visitor",
              "high-protein+frequent-visitor"
            ]
          },
          "cohorts": [
            "health-conscious-regulars",
            "weekday-lunch-crowd",
            "customizers"
          ],
          "history": {
            "lastVisit": "2026-01-20T12:30:00Z",
            "visitCount": 12,
            "favoriteDishes": ["dish_stir_fry", "dish_power_bowl"],
            "avgOrderValue": 18.50,
            "customizationRate": 0.73
          },
          "recommendations": [
            {
              "type": "HIGHLIGHT",
              "dishId": "dish_new_bowl",
              "reason": "Matches wheat-free + high-protein preferences"
            },
            {
              "type": "UPSELL",
              "dishId": "dish_protein_add",
              "reason": "Frequently adds extra protein"
            }
          ]
        }
      }
    }
  }
  ```
</Accordion>

***

## Segments

GuestIQ computes two types of segments:

### Primary Segments

Single-attribute segments based on dietary needs, behavior, or value:

| Category       | Examples                                                    |
| -------------- | ----------------------------------------------------------- |
| **Dietary**    | `wheat-free`, `dairy-free`, `vegan`, `keto`, `halal`        |
| **Allergens**  | `peanut-free`, `shellfish-free`, `tree-nut-free`            |
| **Behavioral** | `customizer`, `saver`, `browser`, `quick-orderer`           |
| **Preference** | `spicy-lover`, `high-protein`, `low-carb`, `low-sodium`     |
| **Value**      | `high-frequency`, `high-aov`, `loyalty-member`, `new-guest` |

### Compound Segments

Combinations of primaries that create targetable micro-audiences:

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e40af', 'primaryTextColor': '#ffffff', 'lineColor': '#475569', 'fontFamily': 'system-ui, -apple-system, sans-serif', 'fontSize': '14px'}}}%%
flowchart LR
    subgraph Primary["Primary Segments"]
        P1["wheat-free"]
        P2["high-protein"]
        P3["dairy-free"]
        P4["customizer"]
        P5["vegan"]
        P6["spicy-lover"]
    end

    subgraph Compound["Compound Segments"]
        C1["wheat-free + high-protein"]
        C2["dairy-free + customizer"]
        C3["vegan + spicy-lover"]
    end

    P1 --> C1
    P2 --> C1
    P3 --> C2
    P4 --> C2
    P5 --> C3
    P6 --> C3

    classDef primary fill:#e2e8f0,stroke:#94a3b8,color:#1e293b,stroke-width:1px
    classDef compound fill:#2563eb,stroke:#1d4ed8,color:#ffffff,stroke-width:1px

    class P1,P2,P3,P4,P5,P6 primary
    class C1,C2,C3 compound
```

Every viable combination is pre-computed and targetable. This enables hyper-specific personalization and campaign targeting.

***

## Cohorts

Pre-built audience groups based on behavioral patterns:

| Cohort                      | Description                                       |
| --------------------------- | ------------------------------------------------- |
| `health-conscious-regulars` | Frequent visitors who filter by dietary/nutrition |
| `weekday-lunch-crowd`       | Visits primarily Mon-Fri 11am-2pm                 |
| `weekend-explorers`         | Tries new dishes, visits Sat-Sun                  |
| `customizers`               | High rate of BYO/modification usage               |
| `value-seekers`             | Responds to promotions, uses discounts            |
| `high-value-loyalists`      | High AOV + high frequency + loyalty member        |

***

## Identity Resolution

GuestIQ identifies guests through multiple signals:

| Method               | Confidence | Description                                  |
| -------------------- | ---------- | -------------------------------------------- |
| `LOYALTY_ID`         | Highest    | Guest's loyalty program ID passed in session |
| `PASSPORT_ID`        | Highest    | EveryBite Passport authentication            |
| `EMAIL`              | High       | Email match from previous sessions           |
| `PHONE`              | High       | Phone number match                           |
| `DEVICE_FINGERPRINT` | Medium     | Browser/device characteristics               |
| `BEHAVIORAL_MATCH`   | Lower      | Pattern matching against known profiles      |

Even without explicit authentication, GuestIQ can identify returning guests and surface their preferences.

***

## Use Cases

<AccordionGroup>
  <Accordion title="Menu Personalization">
    Use segments to highlight dishes that match guest preferences. A `wheat-free + high-protein` guest sees gluten-free protein bowls prominently displayed.
  </Accordion>

  <Accordion title="Staff Alerts">
    Alert front-of-house when a high-value guest or someone with specific dietary needs arrives. "VIP guest, dairy allergy, prefers booth seating."
  </Accordion>

  <Accordion title="Campaign Targeting">
    Target email/push campaigns to compound segments. Send your new vegan dessert promotion only to `vegan + dessert-lover + opted-in` guests.
  </Accordion>

  <Accordion title="Predictive Ordering">
    Use `recommendations` to pre-populate suggested items. Returning guests see their favorites and personalized suggestions immediately.
  </Accordion>

  <Accordion title="Loyalty Enrichment">
    Feed behavioral signals to your loyalty platform. Your CRM now knows not just what they bought, but what they browsed, customized, and saved.
  </Accordion>
</AccordionGroup>

***

## Getting Started

1. **Enable GuestIQ** — Contact your EveryBite account manager to enable the GuestIQ module
2. **Update Session Calls** — Request `guestiq` fields in your `startSession` mutation
3. **Act on Intelligence** — Use segments, history, and recommendations to personalize the experience

<Card title="Session Endpoint" icon="play" href="/api/smartmenu/endpoints/session">
  GuestIQ data is returned in the startSession response
</Card>

***

## Roadmap

<Note>
  GuestIQ intelligence is available **read-only** via the `startSession` response. The following management APIs are planned for future releases.
</Note>

| Feature                 | Description                                                             | Status  |
| ----------------------- | ----------------------------------------------------------------------- | ------- |
| **Identity Management** | Merge guest profiles, link identifiers across systems                   | Planned |
| **Segment Analytics**   | Query segment metrics, trends, and overlap analysis                     | Planned |
| **Signal Tracking**     | Track behavioral events to enrich guest profiles                        | Planned |
| **Integrations**        | Webhooks, batch exports, and direct connections to Punchh, Thanx, Braze | Planned |

Interested in early access? Contact your EveryBite account manager.