Getting started

Introduction

Flyhalf is a headless gamification engine. You send events; it runs the flows you design and delivers the engagement — points, badges, rewards, leaderboard moves and messages — then webhooks the results back to you.

The shape of an integration

Three moving parts, and the middle one is where the product lives:

  1. Events in. One POST from your store, app or POS — any JSON payload. Orders, check-ins, referrals, reviews.
  2. Flows run. You design flows on a visual canvas: triggers, conditions, actions and delays. They award points and badges, grant rewards, move leaderboards and send messages.
  3. Results out. Delivered by WhatsApp, email or push, and webhooked back to your systems with signed, replayable payloads.
A first event bash 
curl -X POST https://api.flyhalf.run/v1/events \
  -H "Authorization: Bearer fh_live_…" \
  -H "Idempotency-Key: order-5512-completed" \
  -d '{
    "event_type": "order.completed",
    "participant": { "external_id": "cus_84h2" },
    "payload": { "total": 349.00, "items": 3 }
  }'

→ 202 accepted

Core concepts

Participants

Everything gamified hangs off a participant, matched by your external_id. You never pre-create them — the first event that references an external_id upserts the participant and enriches their email, phone and name if you send them.

Live and sandbox

Every key is either live (fh_live_) or sandbox (fh_test_). Sandbox events, participants and messages are flagged and isolated — flows run and messages render, but nothing reaches a real customer. See Sandbox mode.

Observability is a feature, not an afterthought

Every event, flow run, message and webhook delivery is logged and replayable from the dashboard. When something doesn't fire, the trace tells you exactly why.

Where to next

Run the Quickstart to fire a signed event and watch it award a badge, or browse the full API reference.