Platform Concepts
The mental model you need before reading a single line of API docs. Understand how Komo's pieces fit together, what the terminology means, and how data flows through the system.
Data Hierarchy
Everything in Komo lives inside a strict hierarchy. Understanding this structure is the key to knowing where data lives and how permissions work.
Workspace (org-level container)
├── Site / Hub (branded web destination)
│ ├── Pages (layout sections within the hub)
│ │ └── Cards (interactive content units)
│ ├── Theme & Branding (colors, logos, fonts)
│ └── URL (e.g., brand.komo.site or custom domain)
├── Contacts (user profiles built from engagement)
├── Competitions (prize pools, draws, instant wins)
└── Workflows (event-driven automations)Workspaces
A Workspace is the top-level organizational unit. It represents an account — typically one per client or one per business unit. All Sites, Contacts, Competitions, and Workflows belong to a Workspace. Team members are invited at the Workspace level and can be assigned roles to control access.
Sites (Hubs)
A Site — also called a Hub — is a branded web destination where engagement happens. Think of it as a microsite purpose-built for interactive content.
What a Site has
- A URL (subdomain on komo.site or custom domain)
- Pages — layout containers that hold cards
- Theme — colors, fonts, logos, background images
- Cards — the interactive content units
- Navigation and footer configuration
How Sites are used
- Standalone engagement destinations (linked from email, social, QR codes)
- Embedded into existing websites or apps via the Embed SDK
- Event-specific microsites with sponsor branding
- Always-on loyalty or community hubs
Cards
Cards are the building blocks of engagement in Komo. Each card is a self-contained interactive content unit with its own gameplay, data capture, and visual presentation. There are 55+ card types.
Card Type Examples
Gamification
- Trivia
- Spin-to-Win
- Scratch Cards
- Instant Win
- Memory Match
Data Capture
- Polls & Surveys
- Quizzes
- Personality Tests
- Pick & Compare
- Swipe Cards
Engagement
- Scavenger Hunts
- Countdown Timers
- Video Players
- Content Reveals
- Photo Galleries
Each card can include a data capture form (pre or post gameplay) that collects contact details, preferences, and custom fields. Cards can also be linked to Competitions for prize management.
Contacts
A Contact is a user profile automatically built from engagement. When someone fills out a form on a card, their data is captured and stored as a Contact within the Workspace.
What a Contact contains
- Identity — email, name, phone, custom fields
- Engagement history — which cards they interacted with, scores, answers
- Zero-party data — preferences, opinions, and selections willingly given
- Tags & segments — applied manually, by workflows, or by card configuration
- Competition entries — prize draws they're eligible for, prizes won
This is zero-party data — data users voluntarily provide in exchange for the value of the experience. No cookies, no tracking pixels, no third-party inference.
Competitions
Competitions manage everything related to prizes and winning. They're a separate entity from Cards — a card can be linked to a Competition, but the prize logic lives independently.
Competition features
- Prize pool definition (multiple prizes, quantities)
- Draw logic (random, leaderboard, first-come)
- Instant win configuration
- Scheduled draws with automated winner selection
- Leaderboard tracking with point systems
Coupon distribution
- Upload coupon pools (CSV of unique codes)
- Auto-distribute on win or form submission
- Track redemption status
- Limit per-user distribution
Workflows
Workflows are event-driven automation flows. They follow a Trigger → Action pattern: when something happens in Komo, the workflow executes a sequence of actions.
Triggers (events)
- Gameplay.DataCaptured
- Gameplay.Ended
- Prize.Won
- Form.Submitted
- Contact.Created
- Receipt validation events
Actions
- HTTP Request (call any API)
- Send Email / SMS
- Update Contact properties
- Salesforce Get/Update/Create
- Mailchimp Upsert/Tag
- Braze Track User
Workflows also support conditional logic (Decision nodes), delays (Wait nodes), and data mapping to transform payloads between steps.
Embedding
Komo content doesn't have to live on komo.site. The Embed SDK lets you place cards or full hubs into any website or mobile app.
Embedding capabilities
- Full Hub embed — render the entire Site as an iframe in your page
- Card Cover embed — show a card's promotional image/button that opens the card modal
- Card Trigger embed — attach card-open behavior to any HTML element
- SSO via JWT — pass auth tokens so users don't re-authenticate
- Form prefilling — pre-populate form fields from your existing user data
- Event listening — receive events (gameplay, form, prize) in your parent page
- Extension data — pass custom key-value data that flows through to webhooks/workflows
How Data Flows
This is the core loop. Every Komo deployment follows this same pattern — only the specifics of the cards, data fields, and downstream systems change.
┌─────────────────────────────────────────────────────────────────┐
│ DATA FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ User visits Hub ──► Engages with Card ──► Data Captured │
│ (web / embed) (trivia, poll, (form fields, │
│ spin-to-win...) answers, scores) │
│ │ │
│ ▼ │
│ Contact Enriched │
│ (profile updated, │
│ tags applied) │
│ │ │
│ ▼ │
│ Workflow Triggered │
│ (automation fires) │
│ │ │
│ ┌───────────────────┼──────────┐ │
│ ▼ ▼ ▼ │
│ HTTP Request CRM Updated Email │
│ (your API) (Salesforce, Sent │
│ Mailchimp, │
│ ▼ Braze) │
│ Webhook Event │
│ (real-time POST │
│ to your endpoint) │
│ │
└─────────────────────────────────────────────────────────────────┘Engagement Layer
Cards capture attention and data. Users interact willingly because the experience is fun, rewarding, or interesting.
Data Layer
Contacts, form entries, gameplay results, and competition entries are all stored and queryable within Komo.
Integration Layer
Workflows, webhooks, and the API push data outward to the systems that need it — CRMs, CDPs, analytics, and custom backends.
Ready to get hands-on? Embed your first Komo card in 30 minutes.