--- title: "ReferralHero Integration" description: "Run referral and waitlist campaigns with ReferralHero, adding subscribers and attributing referrals. Agents keep reward eligibility tied to confirmed conversions." url: https://flowrunner.ai/integrations/referralhero date_modified: 2026-08-07T17:20:23-07:00 --- # ReferralHero [Loyalty & Referral](https://flowrunner.ai/integrations/category/loyalty-referral) Run referral and waitlist campaigns with ReferralHero, adding subscribers and attributing referrals. Agents keep reward eligibility tied to confirmed conversions. [Verified](https://flowrunner.ai/integrations/verified "What does verified mean?") · 17 actions · API key · available [ReferralHero website](https://referralhero.com/) · [Platform Documentation](https://support.referralhero.com/integrate/rest-api) · Capability data verified 2026-08-12 1. A refund posts in Stripe for a customer who originally arrived through a referral 2. Agent resolves the customer with Find Subscriber By Email and reads who referred them 3. Agent calls List Rewards to see whether the referrer's reward has already been marked sent 4. Agent confirms the refund is a full cancellation rather than a partial adjustment 5. Agent posts the referral chain, the reward state and the refund amount to the growth channel 6. The programme owner decides whether to withdraw the credit, and only then does the agent call Unqualify Subscriber and update the reward status ## What This Integration Enables ReferralHero is built for teams that treat a referral as a claim rather than a fact. Most referral tools count a signup and move on. ReferralHero gives you an explicit state machine on top of the signup: a subscriber can be confirmed, qualified, and then unqualified again if the reason you rewarded them stops being true. Agents work that state machine from the systems where the truth actually lives, which is your billing platform, your product, and your CRM, not the referral widget. The connector covers the whole lifecycle. An agent can add a subscriber, attribute them to an advocate's referral code, and return their share link and waitlist position. It can confirm double opt-in on behalf of a system that already verified the address, record purchases so revenue-based rewards stay accurate, and keep the reward ledger honest after a gift card goes out. It can also reverse all of it. That reversal path is the reason a programme owner can trust the numbers. ### Without FlowRunner **Referrals treated as final**: A signup counts the moment it lands, before anyone knows if it sticks **Rewards reconciled by hand**: Someone exports the reward list and compares it against gift cards actually sent **Refunds never reach the programme**: Billing knows the customer churned, the referral ledger does not ### With FlowRunner **Referrals stay provisional**: Credit is released on qualification, not on signup **Reward ledger matches reality**: Every dispatched gift card is written back with Update Reward Status **Billing events reach the programme**: A refund opens a reviewed clawback instead of quietly leaving the ledger wrong ## Use Case Scenarios ### Reward clawback after a refund A referred customer refunds their first order three weeks in. The agent picks the refund up from [Stripe](https://flowrunner.ai/integrations/stripe), calls Find Subscriber By Email to resolve the person in ReferralHero, and reads who introduced them. It then checks List Rewards to see whether the advocate's reward has already been marked sent. The evidence goes to the growth channel as one message: who referred whom, what was paid out, and what the refund was worth. The programme owner decides. If they choose to withdraw, the agent calls Unqualify Subscriber and sets the reward status to canceled. If they choose to honour the reward because the advocate did nothing wrong, the agent records that decision and leaves the ledger alone. ### Waitlist enrolment that returns a real position A signup arrives through a [Typeform](https://flowrunner.ai/integrations/typeform) form. The agent calls Add Subscriber against the campaign, passing the referrer's code from the URL so the introduction is credited, and gets back the new subscriber's referral code, share link and waitlist position. It sends that link and position straight back in the confirmation email. Later, when the person finishes onboarding in the product, the agent calls Qualify Subscriber so the advocate who brought them in becomes eligible. The advocate never has to ask where their reward went. ### Revenue-weighted advocate reporting Every purchase a referred customer makes goes into ReferralHero with Add Transaction, using a stable transaction ID so retries do not double count. On a weekly schedule the agent pulls Get Leaderboard for raw referral volume and cross-references the transaction history so the report shows which advocates brought in customers who actually spend, not just which ones shared the most. The summary lands in [Slack](https://flowrunner.ai/integrations/slack) with the top advocates and the revenue attached to each. ## Human-in-Loop Highlight The clawback is where this connector needs a person. Unqualify Subscriber withdraws referral credit from someone who has already been told they earned it, and if the reward was a gift card that has been redeemed, the money is gone regardless. Delete Subscriber goes further and permanently removes the person along with their entire referral history, with no undo. So the agent never runs either on its own judgment. When a refund, chargeback or fraud signal lands, it assembles the case first: the referred customer, the advocate, every other person that advocate brought in from List Referred Subscribers, and the current reward state. It posts that to the programme owner and asks one question. "Customer refunded in full 19 days after signup. Their referrer has three other referrals, all still active. Withdraw this credit, or honour it?" A person answers, and the agent executes the answer. Reward reversals are the [automation exceptions](https://flowrunner.ai/concepts/automation-exceptions) of a referral programme, and treating them as a [human-in-the-loop](https://flowrunner.ai/concepts/human-in-the-loop) decision is how you keep a programme that advocates still trust. Agent processes routinely Detects exception requiring judgment Clear match Continues automatically Ambiguous Routes to human via preferred channel Human decides Agent resumes with decision ## Agent Capabilities 17 actions ### Campaigns and Leaderboards 2 - **List Campaigns** Lists the referral campaigns on the account with their UUIDs, names and subscriber counts, ten per page. Used as the resolution step, because every other action needs a campaign UUID. - **Get Leaderboard** Retrieves a campaign's leaderboard ranking subscribers by referral count, between 10 and 100 entries. Used to surface top advocates in a report or to build a shortlist for a giveaway draw. ### Subscribers 7 - **List Subscribers** Lists campaign subscribers fifty per page with referral codes, share links, referral counts and waitlist positions, in the order you choose. Used for exports and for locating a subscriber ID. - **Get Subscriber** Retrieves one subscriber by their ReferralHero ID, returning referral code, share link, referral counts, points, waitlist position and who referred them. Used to check an individual's progress before acting on it. - **Find Subscriber By Email** Looks up the same full profile by email address instead of ID. Used whenever the upstream system knows the person only by email, which is most of the time. - **Add Subscriber** Adds a subscriber to a campaign and returns their referral code and share link, optionally attributing them to an advocate's referral code so the introduction is credited. Used at the moment someone joins the waitlist or programme. - **Update Subscriber** Updates an existing subscriber's name, email, phone or points balance, changing only the fields supplied. Used to keep the referral record in step with the CRM record. - **Delete Subscriber** Permanently removes a subscriber and their referral history. This cannot be undone. Used to honour an erasure request or clear test entries, and always behind a human decision. - **List Referred Subscribers** Lists the people a given subscriber has referred, with the state of each referral, paginated and orderable. Used to inspect an advocate's full referral tree when a fraud pattern is suspected. ### Qualification and Conversion 6 - **Confirm Subscriber** Marks a subscriber confirmed, completing double opt-in on their behalf so their referral counts toward the advocate who introduced them. Used when your own system has already verified the email address. - **Qualify Subscriber** Marks a subscriber as having met the campaign's success criteria, so the referral reward can be released. Used once a referred person finishes onboarding or places a first order. - **Unqualify Subscriber** Reverses a qualification, withdrawing referral credit. Used after a refund, a cancellation or a confirmed fraud finding, and always after a person has decided. - **Track Conversion** Records a referral conversion event with an optional value and referrer code, closing the loop between a referral and a real outcome. Used to make the campaign report reflect revenue instead of signups. - **Add Transaction** Records a purchase against a subscriber so revenue-based rewards and lifetime spend stay accurate, with a transaction ID that makes retries safe. Used on every order from a referred customer. - **Add Points** Awards points to a subscriber identified by email or phone, adding to their existing balance. Used to reward actions outside the referral itself, such as completing a profile or sharing on social. ### Rewards 2 - **List Rewards** Lists rewards issued in a campaign with the earning subscriber and any coupon code, filterable by fulfilment status. Used to reconcile which rewards still need dispatching. - **Update Reward Status** Marks a reward sent, resent or canceled once it has been fulfilled or withdrawn outside ReferralHero. Used to write the outcome of a real gift card dispatch back into the ledger. ## Frequently Asked Questions ### What can FlowRunner do with ReferralHero? FlowRunner agents can run List Campaigns, Get Leaderboard, and List Rewards in ReferralHero, plus 14 more actions. ### Does connecting ReferralHero to FlowRunner require OAuth? No. ReferralHero connects to FlowRunner with an API key, no OAuth flow required. ### Can ReferralHero trigger a FlowRunner workflow automatically? ReferralHero doesn't currently expose triggers in FlowRunner. It connects as an action step inside workflows started by another trigger. **Work at ReferralHero?** This integration exposes ReferralHero to AI agents on every FlowRunner plan, including through MCP, at no cost to you. [See what FlowRunner offers integration partners](https://flowrunner.ai/integrations/partners), including how to keep this page current. --- Markdown version of https://flowrunner.ai/integrations/referralhero. Site index: https://flowrunner.ai/llms.txt