User Journeys API

The User Journeys API lets you track your end-users across all gamification touchpoints, automatically segment them by lifecycle stage and engagement tier, and receive campaign recommendations tailored to each user.

How It Works

1. Identify users — Send user profiles with POST /v1/user-journeys/users
2. Track events — Log user actions with POST /v1/user-journeys/events or batch with POST /v1/user-journeys/track
3. Query profiles — Retrieve enriched user profiles with auto-computed segments via GET /v1/user-journeys/users/{externalId}
4. View timelines — Get a user’s full event history with GET /v1/user-journeys/users/{externalId}/timeline

Tip

Game plays and campaign events are automatically tracked when you use the Game Play API or Campaigns API. Use the User Journeys API for custom events and user enrichment.

Auto-Segmentation

Users are automatically classified into lifecycle stages and engagement tiers based on their activity. Segments are recomputed periodically.

Lifecycle Stages

Stage	Criteria
new	First seen within 7 days, 3 or fewer events
active	Seen within last 7 days, more than 3 events
engaged	10+ plays in 30 days, joined at least 1 campaign
power_user	30+ plays in 30 days, engagement score 70+
at_risk	Last seen 14–30 days ago
churned	Last seen more than 30 days ago

Engagement Tiers

Tier	Criteria
casual	Fewer than 5 plays in 30 days
regular	5–15 plays in 30 days
power_user	15–50 plays in 30 days
whale	More than 50 plays in 30 days

Engagement Score (0–100)

The engagement score is a weighted composite:

Factor	Weight	Calculation
Recency	30%	Based on days since last seen
Frequency	30%	Based on plays in last 30 days
Monetary	20%	Based on points earned in last 30 days
Breadth	20%	Based on campaigns joined

Authentication

All User Journeys API endpoints require your API Public Key:

Header	Required	Value
X-API-Key	Yes	Your public key (e.g., pk_live_... or pk_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/user-journeys

Available Endpoints

Method	Endpoint	Description
POST	/users	Track/enrich a user profile
POST	/events	Track a single event
POST	/track	Batch track events
GET	/users/{externalId}	Get user profile + recommendations
GET	/users/{externalId}/timeline	Get user event timeline

Event Categories

When tracking events, use one of these categories:

Category	Description
GAME_PLAY	User played a game (auto-tracked by Game Play API)
CAMPAIGN	User interacted with a campaign (auto-tracked by Campaigns API)
POINTS	Points were awarded or deducted
PAGE_VIEW	User viewed a page (for SDK auto-tracking)
SESSION	Session start/end events (for SDK auto-tracking)
CUSTOM	Any custom event you define

Campaign Recommendations

When you retrieve a user profile, the API returns personalized campaign recommendations based on the user’s lifecycle stage and engagement tier. Each recommendation includes:

Field	Description
type	Campaign type (e.g., spin_to_win, referral, daily_streak)
name	Human-readable campaign name
reason	Why this campaign is recommended for this user
priority	high, medium, or low

Recommendation Matrix

User Segment	Recommended Campaigns
New users	Welcome bonus spin, first action reward
Active users	Daily streak challenge, daily spin
Engaged users	Referral program, weekly leaderboard
Power users	Ambassador program, VIP exclusive rewards
At-risk users	Re-engagement streak, win-back instant prize
Churned users	Win-back reward, fresh start bonus