Campaigns API

Campaigns let you build interactive promotions that engage your users through gamification mechanics. Each campaign is a self-contained experience with its own branding, rules, and optional public-facing microsite.

What is a Campaign?

A campaign is a time-bound promotion that combines multiple gamification mechanics:

• Points & Events — Award points when users complete actions (signup, purchase, etc.)
• Leaderboards — Rank participants by points earned
• Instant-Win Games — Spin wheel, scratch card, or card flip with configurable prize tiers
• Referrals — Unique referral codes with rewards for both referrer and referee
• Redeemable Codes — Generate batches of codes that award points when redeemed

Campaign Lifecycle

1. Create a campaign via the dashboard with name, slug, branding, dates, and budget
2. Configure mechanics — enable the mechanics you want (points, instant-win, referrals, codes)
3. Activate the campaign to make it live
4. Integrate via the API to record events, generate codes, and manage participants
5. Monitor via the dashboard or API (leaderboard, stats, code redemptions)

Authentication

All Campaign API endpoints require your API Secret Key:

Header	Required	Value
X-API-Secret	Yes	Your secret key (e.g., sk_live_... or sk_test_...)
Content-Type	Yes	application/json (for POST requests)

The environment (live vs test) is automatically determined by your key prefix.

Base URL

https://api.gamifyhost.com/v1/campaigns/{slug}

Where {slug} is your campaign’s unique slug (e.g., summer-promo-2025).

Available Endpoints

Events & Participants

Method	Endpoint	Description
POST	/{slug}/events	Record a campaign event
GET	/{slug}/participants/{userId}	Get a participant’s progress
GET	/{slug}/leaderboard	Get the campaign leaderboard

Codes

Method	Endpoint	Description
POST	/codes/generate	Generate a batch of redeemable codes
POST	/codes/verify	Check if a code is valid
GET	/codes/batches?slug={slug}	List code batches
GET	/codes/stats?slug={slug}	Get code statistics
POST	/{slug}/redeem	Redeem a code

Instant-Win

Method	Endpoint	Description
GET	/{slug}/instant-win/stats	Get instant-win statistics
POST	/{slug}/instant-win/redeem	Redeem a win code

Referrals

Method	Endpoint	Description
POST	/{slug}/referrals	Record a referral
GET	/{slug}/referral-code/{userId}	Get a user’s referral code

Campaign Mechanics

Points & Events

When you record an event, the campaign engine evaluates configured reward rules and awards points accordingly. Points accumulate on the participant’s record and count toward leaderboard ranking.

Instant-Win Games

Configure prize tiers with win probabilities, point values, and inventory limits. When a user plays, the backend randomly determines the outcome. Three game styles are available for the public microsite:

Style	Description
spin_wheel	Animated wheel with prize segments (default)
scratch_card	Canvas-based scratch overlay revealing the prize
card_flip	3D card flip — pick one of three cards

Note

Game style only affects the visual presentation on the public microsite. The API-level instant_win event type works identically regardless of game style.

Redeemable Codes

Generate batches of unique codes that you can distribute however you like (email, print, in-store, etc.). Each code has a point value and can be redeemed once. Codes are stored as SHA-256 hashes — plaintext codes are only returned at generation time.

Referrals

Each participant gets a unique referral code. When a new user signs up with that code, both the referrer and referee earn configured rewards.