---
name: Trophy
description: Use when building gamification features (achievements, streaks, points, leaderboards), tracking user metrics and events, configuring gamified workflows, integrating webhooks, or managing user engagement through gamified experiences in web or mobile applications.
metadata:
    mintlify-proj: trophy
    version: "1.0"
---

# Trophy Skill

## Product summary

Trophy is a developer-friendly gamification platform that provides APIs and a dashboard for building engagement features like achievements, streaks, points systems, and leaderboards. Agents use Trophy to track user interactions through metrics and events, configure gamification rules, and deliver personalized engagement experiences. The platform includes two main APIs: the Application API (`https://api.trophy.so/v1`) for user-facing gamification, and the Admin API (`https://admin.trophy.so/v1`) for administrative workflows. Authentication uses API keys passed in the `X-API-KEY` header. SDKs are available in most major languages. Primary documentation: https://docs.trophy.so

## When to use

Reach for Trophy when:
- Building achievement systems that unlock based on user milestones or actions
- Implementing streak mechanics to encourage daily/weekly/monthly habits
- Creating points or XP systems with configurable triggers and levels
- Setting up leaderboards to drive competition and engagement
- Tracking user interactions through metrics and events
- Configuring automated emails or push notifications tied to gamification events
- Running A/B tests on gamification features
- Managing multi-tenant gamification for multiple customer organizations
- Integrating gamification data into external systems via webhooks
- Personalizing gamification features per user or user cohort

## Quick reference

### Core Concepts

| Concept | Purpose | Key Detail |
|---------|---------|-----------|
| **Metrics** | Model user interactions (tasks, posts, miles, etc.) | Server-side only; drive all gamification features |
| **Events** | Track individual user interactions against metrics | Include user ID, metric key, value, optional attributes |
| **Users** | Individual people using the app | Require `id`; optional: `name`, `email`, `tz`, custom attributes |
| **Achievements** | Rewards for milestones or actions | Types: metric, API, streak, composite |
| **Streaks** | Consecutive periods (daily/weekly/monthly) of activity | Auto-calculated; support freezes and personalization |
| **Points** | Counters rewarding interactions (XP, energy, gems) | Multiple systems per account; support levels and boosts |
| **Leaderboards** | Ranked competition between users | Auto-calculated from metrics |

### API Authentication

```bash
# All requests require X-API-KEY header with both prefix and body
curl https://api.trophy.so/v1/users/{id}/metrics/{key} \
  -H "X-API-KEY: {prefix}.{body}"
```

- Create up to 3 API keys per account from Integration Page
- Prefix (8 chars) is readable; body is secret (shown once)
- Rotate or revoke keys anytime; both prefix and body change on rotation

### Rate Limits

| Tier | Limit |
|------|-------|
| Tier 1 | 10 req/s |
| Tier 2 | 100 req/s |

Exceeding limits returns `429 Too Many Requests`. Contact support for higher limits.

### Essential Endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST /metrics/{key}/event` | Track user interaction; returns achievements, streaks, points |
| `POST /users/identify` | Explicitly identify a user (inline identification happens automatically) |
| `GET /users/{id}/achievements` | Fetch user's completed achievements |
| `GET /users/{id}/streak` | Fetch user's current streak with history |
| `GET /users/{id}/points/{key}` | Fetch user's points total, level, recent awards |
| `GET /leaderboards/{key}` | Fetch leaderboard rankings |
| `POST /achievements/{key}/complete` | Mark API achievement as completed |

### Dashboard Configuration

- **Metrics**: Define at https://app.trophy.so/metrics
- **Achievements**: Create at https://app.trophy.so/achievements (inactive by default)
- **Streaks**: Configure at https://app.trophy.so/streaks
- **Points**: Set up systems and triggers at https://app.trophy.so/points
- **Leaderboards**: Create at https://app.trophy.so/leaderboards
- **Webhooks**: Register at https://app.trophy.so/integration/webhooks (Pro plan)
- **API Keys**: Manage at https://app.trophy.so/integration

## Decision guidance

### When to use inline vs. explicit user identification

| Scenario | Use Inline | Use Explicit |
|----------|-----------|--------------|
| Users auto-created on first metric event | ✓ | |
| Need to identify before any metric interaction | | ✓ |
| Syncing user properties on every metric call | ✓ | |
| Complete control over when Trophy learns about users | | ✓ |
| Minimal code required | ✓ | |
| Tracking many metrics; avoid repetition | | ✓ |

**Recommendation**: Start with inline identification (pass user details in metric event API). Switch to explicit if you need more control.

### When to use achievement types

| Type | Use When | Trigger |
|------|----------|---------|
| **Metric** | Rewarding repeated actions (1000 tasks, 5000 miles) | Auto on metric threshold |
| **Streak** | Rewarding consistency (7-day, 30-day streaks) | Auto on streak length |
| **API** | Rewarding one-time actions (profile complete, share) | Manual API call |
| **Composite** | Creating tiered/mastery rewards | Auto when all prerequisites complete |

### When to use points triggers

| Trigger Type | Use When |
|--------------|----------|
| **Metric** | Award points for every N interactions (10 points per 3 tasks) |
| **Streak** | Reward streak milestones (50 points per 7-day streak) |
| **Achievement** | Bonus points for unlocking achievements |
| **Time-based** | Recurring rewards (10 points every 3 hours) |
| **User Identification** | Initial signup bonus |

### Webhook vs. polling for events

| Approach | Use When |
|----------|----------|
| **Webhooks** | Need real-time reactions (send email, update CRM, trigger workflow) |
| **Polling APIs** | Building dashboards, periodic syncs, or on-demand queries |

Webhooks require Pro plan and signature validation.

## Workflow

### 1. Set up Trophy account and API key
- Create account at https://app.trophy.so/sign-up
- Complete onboarding to generate first API key
- Store API key in environment variable (e.g., `TROPHY_API_KEY`)
- Install SDK for your language or use HTTP client

### 2. Define metrics
- Go to https://app.trophy.so/metrics
- Click "New Metric" for each user interaction you want to track
- Name the metric (e.g., "flashcards-flipped", "miles-run")
- Optionally set units (arbitrary numbers, currency)
- Copy the metric key for API integration

### 3. Integrate metric tracking
- In your backend, call the metric event API whenever a user performs the tracked action
- Pass user ID, email, timezone, and any custom attributes
- Capture the response (includes achievements unlocked, streaks, points changes)
- Use response data to trigger transactional UI (pop-ups, sounds)

### 4. Configure gamification features
- **Achievements**: Create at dashboard; set trigger type (metric, API, streak, composite); set thresholds; activate
- **Streaks**: Enable on streaks page; set frequency (daily/weekly/monthly); define metric conditions; configure freezes
- **Points**: Create system; add triggers (metric, streak, achievement, time, identification); set point values; create levels
- **Leaderboards**: Create leaderboard; select metric to rank by; set frequency (daily/weekly/monthly)

### 5. Display gamification data
- Fetch achievements: `GET /users/{id}/achievements` (optionally include incomplete)
- Fetch streaks: `GET /users/{id}/streak` with `historyPeriods` query param
- Fetch points: `GET /users/{id}/points/{key}` for total, level, recent awards
- Fetch leaderboards: `GET /leaderboards/{key}` for rankings
- Bind UI to API responses; update on metric event responses

### 6. Set up webhooks (optional, Pro plan)
- Go to https://app.trophy.so/integration/webhooks
- Create webhook with URL and select event types
- Copy webhook secret
- Build HTTP endpoint that validates signature and processes events
- Test with Hookdeck Console or similar tool
- Deploy to production with new webhook URL and secret

### 7. Test and iterate
- Use dashboard analytics to monitor feature adoption
- Check metric analytics for achievement completion rates
- Review points distribution and level progression
- A/B test gamification changes using experimentation feature
- Adjust triggers, thresholds, and messaging based on retention impact

## Common gotchas

- **Forgetting to activate achievements**: Achievements are created as inactive by default. They won't unlock until you activate them on the achievements page.
- **Not passing both API key parts**: API keys have two parts separated by a period. Both must be included in the `X-API-KEY` header or requests fail with 401.
- **Inline identification overwrites on every metric event**: If you pass different user properties (name, email) in successive metric events, Trophy updates the user record. Ensure consistency or use explicit identification.
- **Timezone matters for streaks**: Streaks reset at midnight in the user's timezone. If `tz` is not provided, Trophy uses UTC. Users changing timezones may see streak behavior changes.
- **Metric achievements don't trigger on backdating**: When you activate an achievement, Trophy automatically completes it for users who already meet the threshold, but no notifications are sent. This prevents spam.
- **Points boosts stack multiplicatively**: If a user qualifies for 2X and 1.5X boosts, they get 3X total (2 × 1.5), not 3.5X. Plan boost values accordingly.
- **Custom user attributes must be created first**: You can't set arbitrary attributes in API calls. Create them in the dashboard first at https://app.trophy.so/users/attributes, or requests fail.
- **Webhook signatures use SHA256**: Validate using `HMAC-SHA256` with your webhook secret. Reject requests with invalid signatures immediately with 4XX status.
- **Rate limits are org-level**: All API keys in your account share the same rate limit bucket. Monitor usage to avoid 429 responses.
- **Leaderboards require metric events**: Leaderboards are auto-calculated from metrics. If no events are tracked, leaderboard is empty.

## Verification checklist

Before submitting work with Trophy:

- [ ] API key is stored securely in environment variables, not hardcoded
- [ ] All metric keys match those created in the Trophy dashboard
- [ ] User identification includes required `id` field and optional `tz` for timezone-aware features
- [ ] Achievements are activated in the dashboard before testing
- [ ] Metric event responses are captured and used to trigger UI updates
- [ ] Custom user attributes are created in dashboard before setting them in API calls
- [ ] Webhook signatures are validated using SHA256 HMAC before processing events
- [ ] Rate limits are monitored; no 429 errors in logs
- [ ] Streaks configured with correct frequency (daily/weekly/monthly) and metric conditions
- [ ] Points triggers are set to inactive initially, then activated after testing
- [ ] Leaderboard metric is actively receiving events
- [ ] User timezone (`tz`) is set for streak and email accuracy
- [ ] Webhook secret is stored securely and not committed to source control
- [ ] All gamification features tested in staging before production deployment

## Resources

**Comprehensive navigation**: https://docs.trophy.so/llms.txt

**Critical documentation pages**:
1. [Getting Started Quickstart](https://docs.trophy.so/getting-started/quickstart) — 10-minute integration walkthrough
2. [API Reference Introduction](https://docs.trophy.so/api-reference/introduction) — Authentication, rate limits, SDKs
3. [Features Overview](https://docs.trophy.so/features/overview) — Core concepts (metrics, events, users, achievements, streaks, points, leaderboards)

---

> For additional documentation and navigation, see: https://docs.trophy.so/llms.txt