# ReferralHero MCP > ReferralHero connects your AI agent directly to your viral growth engine. Manage complex referral campaigns, track every point earned, and monitor leaderboards—all from chat. Use tools like `get_leaderboard` or `add_points` to automate everything from onboarding new subscribers to distributing rewards based on real-time activity. Stop exporting CSVs; start talking to your platform. ## Overview - **Category:** industry-titans - **Price:** Free - **Tags:** referralhero, viral-growth, referral-api, subscriber-management, leaderboards, rewards-automation, growth-marketing, mcp ## Description **ReferralHero MCP Server: Managing Points and Rewards** Listen up. This server connects your AI client directly to the engine running your viral growth campaigns. You're gonna manage complex referral programs, track every point earned, and keep an eye on leaderboards—all without ever touching a spreadsheet or leaving your chat window. It’s built for people who need action, not fluff. Forget jumping between your platform UI, your CRM, and some dusty CSV export. You talk to your agent, and the agent does the heavy lifting using specific tools like `add_points` or `get_leaderboard`. This gives you real-time control over subscriber balances, campaign performance, and conversion history. **Getting Started: Setting Up Campaigns and Users** You can start by getting a full picture of your operation. Use `list_lists` to pull names of every active referral campaign running right now. If you need the deep details on one specific program, just run `get_list`, which pulls all the metadata for that campaign ID. To figure out what kind of rewards are available, check `get_rewards`; it fetches the current rules and reward tiers set up for any given campaign. Need to bring a new person into the fold? Use `add_subscriber` to create a brand-new user record and get 'em enrolled in an active campaign list. If you need to modify someone's profile—say, they hit a new status tier or you gotta change some metadata—you use `update_subscriber`. Remember that if a participant drops out, you can clean up their account using `delete_subscriber`. **Tracking Activity and Conversions** Attribution is everything. When someone refers another user, you don't want to guess who gets credit. You use `track_conversion`; it logs the new referral event and links it straight back to an existing subscriber ID, making sure your attribution tracking is flawless. Need a headcount of current participants? Run `list_subscribers` on a campaign ID to pull a list of everyone enrolled in that specific program. For performance checks, you can check out `get_subscriber`, which pulls all the detailed data—points earned, referrals made—for one individual user. **Monitoring and Adjusting Rewards** The server gives you several ways to track what’s happening. To see who's winning right now, run `get_leaderboard`. This tool grabs a ranked list of all participants based on points, referrals, or whatever criteria the campaign demands. If someone needs an immediate boost—maybe they completed a manual task or you just wanna give out a bonus—you execute `add_points`, which adds a specific number of points directly to that subscriber's account. This is your key tool for manual reward distribution. **Data Integrity and Auditing** When it comes to data cleanup, the server lets you check out `list_transactions`. It pulls a paginated log covering every recent system activity, including all points awarded and rewards processed across the entire platform. You can also monitor current operational status by running `list_subscribers` for an overall view of who's in the campaign. Every single action is available to your AI client. You can pull a list of *all* active campaigns using `list_lists`, and you can always check out specific details on one user or one campaign setup through dedicated tools. It treats your entire referral lifecycle—from sign-up to payout—as an actionable command set for your agent. ## Tools ### add_points Adds a specified number of points directly to a subscriber's account. ### add_subscriber Adds a brand new user record and enrolls them into an active campaign list. ### delete_subscriber Removes a specific participant from their current referral campaign. ### get_leaderboard Retrieves the ranked list of participants based on points, referrals, or other criteria for a given campaign. ### get_list Pulls full details and metadata for one specific referral campaign by its ID. ### get_rewards Fetches the current rules and available reward tiers for a specified campaign. ### get_subscriber Retrieves all detailed performance data (points, referrals) for one individual user. ### list_lists Lists every active referral campaign available in your account, along with basic metadata. ### list_subscribers Pulls a list of all current participants enrolled in a specific campaign. ### list_transactions Retrieves a paginated log of recent system activity and point/reward transactions across the platform. ### track_conversion Logs a new referral event, linking it to an existing subscriber ID for accurate attribution tracking. ### update_subscriber Modifies specific metadata fields or statuses for an already existing subscriber profile. ## Prompt Examples **Prompt:** ``` List all active referral lists in my account. ``` **Response:** ``` I've retrieved your campaigns. You have 3 active lists including 'Early Access Launch' (UUID: list_123) and 'Refer-a-Friend'. Which one would you like to see the leaderboard for? ``` **Prompt:** ``` Show me the leaderboard of top referrers in my active campaign with their reward balances. ``` **Response:** ``` Top 10 referrers in "Growth Champions" campaign. #1: James Park with 47 verified referrals ($470 earned, $235 pending). #2: Lisa Wang with 34 referrals ($340 earned). #3: Alex Rivera with 28 referrals ($280 earned). #4-10: combined 89 referrals. Total campaign participants: 456. Active referrers (1+ referral): 234 (51%). Total rewards distributed: $4,560. Pending payouts: $1,230. Campaign viral coefficient: 1.4x. Average referrals per participant: 2.3. ``` **Prompt:** ``` Send a reminder email to all campaign participants who have not shared their referral link yet. ``` **Response:** ``` Reminder email sent to 222 inactive participants (those who joined but have 0 referrals). Subject: "Your referral link is waiting! Share & earn $10 per friend". Email includes their unique referral link, one-click social share buttons, and a progress bar showing how close they are to their first reward. Delivery: 218 delivered (98.2%). 4 bounced (invalid emails). Based on previous reminders, expect 15-20% to make their first share within 48 hours. ``` ## Capabilities ### Run the current campaign leaderboard The agent pulls real-time ranking data, showing who has earned the most points or referrals in any active campaign. ### Add points to a specific subscriber You tell your AI client which user needs points and how many, and it executes `add_points` instantly. This is key for manual reward distribution. ### Track new referral conversions The agent records a conversion event using `track_conversion`, ensuring the system correctly attributes the referral to a specific subscriber ID. ### List all active campaigns and users It pulls lists of every campaign available (`list_lists`) or retrieves a list of participants within a single campaign via `list_subscribers`. ### Update existing subscriber records If a user's status changes (e.g., they hit a new tier), the agent uses `update_subscriber` to ensure their profile metadata is current. ## Use Cases ### The Founder's Quarterly Audit A founder needs to know if the last month’s reward payouts matched the recorded activity. They prompt their agent: 'Check my transactions and list all active campaigns.' The agent runs `list_transactions` and then uses `list_lists`, giving them a comprehensive, single-pane view of campaign health. ### The Ops Engineer's Reward Fix An ops engineer discovers James Park is missing 50 points. Instead of logging into the platform and searching for his UUID, they prompt: 'Add 50 points to subscriber X.' The agent executes `add_points` immediately, correcting the balance without any manual intervention. ### The Growth Marketer's Campaign Check A marketer wants to see who is performing best in their 'Early Access Launch' campaign. They ask for the leaderboard. The agent runs `get_leaderboard`, giving them real-time data on top performers and current point totals. ### The Customer Success Team Member A support rep needs to check a customer's referral history before talking to them. They ask the agent for `get_subscriber` details, which instantly pulls all metadata, points, and previous activity logs into the chat. ## Benefits - **Instant Leaderboard Access:** Instead of exporting a CSV to see rankings, use `get_leaderboard` to pull the top 10 list directly into your chat. This lets you spot performance dips or stars in minutes. - **Surgical Point Management:** Need to manually adjust points? Use `add_points`. You specify the user and the count, bypassing manual UI clicks entirely. Perfect for micro-adjustments after an audit. - **Full Audit Trail:** Stop guessing where a point change came from. Run `list_transactions` to get a detailed log of every action taken on your platform—who did what and when. - **Lifecycle Control:** Need someone out of the campaign? Use `delete_subscriber`. It removes them cleanly, while `update_subscriber` lets you modify their profile status without deleting their history. ## How It Works The bottom line is, your AI client acts as a direct API wrapper. It takes natural language requests and translates them into structured function calls that update or read data in ReferralHero. 1. First, subscribe to the ReferralHero server and provide your API token in your client settings. 2. Next, prompt your AI agent with a specific goal (e.g., 'Give James Park 50 points because he hit his milestone'). 3. The agent recognizes the intent and calls the appropriate tool (`add_points`), executing the action directly against the ReferralHero platform. ## Frequently Asked Questions **How do I list all active referral campaigns using list_lists?** Just ask your agent to 'List all available campaign lists.' The agent executes `list_lists` and returns a full JSON payload detailing every UUID and name currently running in your account. **Can I use add_points if the user is not yet subscribed?** No. You must first run `add_subscriber` to create the record, then you can use `add_points`. The tool logic requires an active subscriber ID for points to stick. **Which tool should I use to check a single user's total referrals?** Use the `get_subscriber` tool. It pulls all performance metadata, including current point balances and referral counts, in one go. This is better than just listing subscribers. **How do I track a conversion event without manually entering data?** You run `track_conversion` by providing the necessary parameters (like source ID or referrer UUID). The agent logs this action, ensuring your system knows the referral happened for accurate attribution. **Is it safe to use delete_subscriber?** Yes, but be careful. `delete_subscriber` permanently removes them from a specific campaign's active list. If you just want to pause them, run `update_subscriber` instead. **How does using `list_transactions` help me audit point changes?** It provides a full record of activity. You see every transaction, including the type of action (e.g., referral, manual adjustment), which subscriber was affected, and the exact timestamp. This is essential for auditing reward payouts or tracking why points changed. **What data fields can I change using `update_subscriber`?** You must provide the existing subscriber's unique ID along with the specific attributes you want to modify. The tool validates your inputs against current campaign rules, preventing you from accidentally corrupting core user data. **How does `get_leaderboard` pull all the necessary metrics?** It fetches real-time performance data across active participants. The output aggregates total referrals, earned revenue, and pending payouts for every user listed. It gives you a single view of campaign health. **Can my AI automatically find the details and points for a specific subscriber by providing their ID?** Yes! Use the `get_subscriber` tool with the List UUID and Subscriber ID. Your agent will respond with complete metadata, including referral counts and current point balances in seconds. **How do I find my ReferralHero API Token?** Log in to your ReferralHero dashboard, navigate to **Account** > **API**, and you will find your unique secret token there.