Servers Playground How we check Add a server Log in

ReferralHero MCP by usefulapi

Working · 761 ms

io.usefulapi/referralherov1.0.0 Domain verified

Read ReferralHero campaigns, subscribers, referrals and rewards; add subscribers and points.

Marketing & SEO

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://referralhero.usefulapi.io/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

referralhero_add_coupons

WRITE: add coupon codes to an existing coupon group. It only adds codes. POST /lists/{uuid}/coupons.

uuidstring, required

Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).

couponsarray, required

Coupon codes to add.

coupon_group_idstring, required

Coupon group id (see referralhero_list_coupon_groups).

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

ReferralHero MCP by usefulapi MCP server | mcptry

ReferralHero MCP by usefulapi

Working · 761 ms

io.usefulapi/referralherov1.0.0 Domain verified

Read ReferralHero campaigns, subscribers, referrals and rewards; add subscribers and points.

Marketing & SEO

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://referralhero.usefulapi.io/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

referralhero_add_coupons

WRITE: add coupon codes to an existing coupon group. It only adds codes. POST /lists/{uuid}/coupons.

uuidstring, required

Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).

couponsarray, required

Coupon codes to add.

coupon_group_idstring, required

Coupon group id (see referralhero_list_coupon_groups).

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Tools (28)

referralhero_add_coupons

WRITE: add coupon codes to an existing coupon group. It only adds codes. POST /lists/{uuid}/coupons.

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
coupons*	array	Coupon codes to add.
coupon_group_id*	string	Coupon group id (see referralhero_list_coupon_groups).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "coupon_group_id",
    "coupons"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "coupons": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 1000,
      "minItems": 1,
      "description": "Coupon codes to add."
    },
    "coupon_group_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Coupon group id (see referralhero_list_coupon_groups)."
    }
  }
}

referralhero_add_points

WRITE: add points to an existing subscriber (not idempotent: each call adds again). May unlock point-based rewards. The subscriber is identified by the campaign's unique identifier. POST /lists/{uuid}/subscribers/add_points.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
email	string	Subscriber email (when email is the campaign's unique identifier).
points*	integer	Points to add.
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).
phone_number	string	Subscriber phone number (when phone is the unique identifier).
crypto_wallet_address	string	Wallet address (when it is the unique identifier).
other_identifier_value	string	Custom identifier value (when a custom id is the unique identifier).

referralhero_add_subscriber

WRITE: add a subscriber (or a referred person) to a campaign. Give the campaign's unique identifier (email, phone, wallet or custom id). By default ReferralHero sends the subscriber a confirmation (double opt-in) email and any welcome automation of the campaign: set double_optin=false to suppress the confirmation email. Set referrer (a referral code or the referrer's email) to credit a referral. POST /lists/{uuid}/subscribers.

destructive

Argument	Type	Description
name	string	Subscriber name.
tags	array	Tags to assign.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
email	string	Subscriber email (when email is the campaign's unique identifier).
device	string	Device used to sign up, for analytics.
domain	string	URL used for the subscriber's referral link.
points	integer	Starting points (contest campaigns only).
source	string

referralhero_confirm_referral

WRITE: confirm a verified referral when its third conversion event happens (campaigns whose goal tracks three events; otherwise ReferralHero returns an error). Confirming can unlock the referrer's rewards and send reward emails. Identify the referral by subscriber_id, or by the campaign's unique identifier. POST /lists/{uuid}/subscribers/{id}/confirm or /subscribers/confirm.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
email	string	Subscriber email (when email is the campaign's unique identifier).
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).
phone_number	string	Subscriber phone number (when phone is the unique identifier).
subscriber_id	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).
conversion_value	number	Referral conversion value.
crypto_wallet_address	string

referralhero_create_campaign

WRITE: create a new ReferralHero campaign (list) with a name and a default referral URL. It adds a campaign and changes nothing existing. POST /lists.

Argument	Type	Description
name*	string	Campaign name.
website*	string	Default referral URL (https://...).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name",
    "website"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Campaign name."
    },
    "website": {
      "type": "string",
      "format": "uri",
      "maxLength": 2000,
      "description": "Default referral URL (https://...)."
    }
  }
}

referralhero_create_coupon_group

WRITE: create a coupon group for a campaign, optionally with its first coupon codes. It only adds a group. POST /lists/{uuid}/coupon_groups.

Argument	Type	Description
name*	string	Coupon group name.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
active	boolean	Whether the group is active (default true).
coupons	array	Coupon codes to put in the group.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Coupon group name."
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "active": {
      "type": "boolean",
      "description": "Whether the group is active (default true)."
    },
    "coupons": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 1000,
      "description": "Coupon codes to put in the group."
    }
  }
}

referralhero_delete_subscriber

WRITE, DESTRUCTIVE: permanently delete a subscriber from a campaign, with their referral standing. This cannot be undone. DELETE /lists/{uuid}/subscribers/{id}.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
confirm*	boolean	Must be true: the user has approved permanently deleting this subscriber.
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved permanently deleting this subscriber."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_get_coupon_group

One coupon group with all its coupons (code, available, sent_at). GET /lists/{uuid}/coupon_groups/{id}.

read-only

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
coupon_group_id*	string	Coupon group id (see referralhero_list_coupon_groups).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "coupon_group_id"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "coupon_group_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Coupon group id (see referralhero_list_coupon_groups)."
    }
  }
}

referralhero_get_leaderboard

The leaderboard of a campaign: its top subscribers (10 to 100) with referral counts, points and position. GET /lists/{uuid}/leaderboard.

read-only

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
count	integer	How many top subscribers, 10-100 (default 10).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "count": {
      "type": "integer",
      "maximum": 100,
      "minimum": 10,
      "description": "How many top subscribers, 10-100 (default 10)."
    }
  }
}

referralhero_get_subscriber

One subscriber by id: contact data, referral code and link, points, position, referrals by level, status, fraud risk level, tags. Only verified subscribers are found. GET /lists/{uuid}/subscribers/{id}.

read-only

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_get_subscriber_by_email

Find one subscriber of a campaign by email. Only verified subscribers are found. GET /lists/{uuid}/subscribers/retrieve_by_email.

read-only

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
email*	string	The subscriber's email.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "email"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "The subscriber's email."
    }
  }
}

referralhero_get_subscriber_by_referral_code

Find the subscriber who owns a referral code (the mwr value in a referral link). Only verified subscribers are found. GET /lists/{uuid}/subscribers/retrieve_by_mwr.

read-only

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
referral_code*	string	The referrer's referral code (the mwr parameter of a referral link).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "referral_code"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "referral_code": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The referrer's referral code (the mwr parameter of a referral link)."
    }
  }
}

referralhero_list_campaign_rewards

The rewards configured for a campaign (title, description, referrals needed to win each). This is the reward setup, not who earned what: see referralhero_list_unlocked_rewards for that. GET /lists/{uuid}/bonuses.

read-only

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    }
  }
}

referralhero_list_campaigns

List the active ReferralHero campaigns (lists) in the account: uuid, name, subscriber count and creation time. The uuid is needed by every other tool. 10 per page. GET /lists.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

referralhero_list_coupon_groups

Coupon groups of a campaign (id, name, active flag, coupons with availability), 50 per page. GET /lists/{uuid}/coupon_groups.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    }
  }
}

referralhero_list_referrals

The people a subscriber referred, 50 per page. scope: all (pending, unconfirmed and confirmed, default), level_1_confirmed, level_2_confirmed, level_3_confirmed (confirmed only, by referral level), level_2_all or level_3_all (every status at that level). GET /lists/{uuid}/subscribers/{id}/{referred|level_N_referrals|level_N_all_referrals}.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
scope	string	Which referrals (default all).
sort_by	string	Sort order.
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "scope": {
      "enum": [
        "all",
        "level_1_confirmed",
        "level_2_confirmed",
        "level_3_confirmed",
        "level_2_all",
        "level_3_all"
      ],
      "type": "string",
      "description": "Which referrals (default all)."
    },
    "sort_by": {
      "enum": [
        "registration_desc",
        "registration_asc",
        "email_asc",
        "email_desc",
        "name_asc",
        "name_desc",
        "position_asc",
        "position_desc",
        "people_referred_asc",
        "people_referred_desc",
        "points_asc",
        "points_desc"
      ],
      "type": "string",
      "description": "Sort order."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_list_subscriber_rewards

Rewards one subscriber has unlocked, with status, value and coupon code. The reward id is what referralhero_update_reward_status needs. GET /lists/{uuid}/subscribers/{id}/rewards.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
status	string	Only rewards in this status.
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "status": {
      "enum": [
        "sent",
        "resent",
        "canceled",
        "pending",
        "flagged"
      ],
      "type": "string",
      "description": "Only rewards in this status."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_list_subscribers

List the subscribers of a campaign, 50 per page, with referral code, referral link, points, position, people referred, status and referrer. Sort and filter by the extra fields. GET /lists/{uuid}/subscribers.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
sort_by	string	Sort order.
extra_field	string	Only subscribers whose extra field has this value.
option_field	string	Only subscribers whose option field has this value.
extra_field_2	string	Only subscribers whose extra field 2 has this value.
stripe_customer_id	string	Only the subscriber linked to this Stripe customer id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "sort_by": {
      "enum": [
        "registration_desc",
        "registration_asc",
        "email_asc",
        "email_desc",
        "name_asc",
        "name_desc",
        "position_asc",
        "position_desc",
        "people_referred_asc",
        "people_referred_desc",
        "points_asc",
        "points_desc"
      ],
      "type": "string",
      "description": "Sort order."
    },
    "extra_field": {
      "type": "string",
      "maxLength": 300,
      "minLength": 1,
      "description": "Only subscribers whose extra field has this value."
    },
    "option_field": {
      "type": "string",
      "maxLength": 300,
      "minLength": 1,
      "description": "Only subscribers whose option field has this value."
    },
    "extra_field_2": {
      "type": "string",
      "maxLength": 300,
      "minLength": 1,
      "description": "Only subscribers whose extra field 2 has this value."
    },
    "stripe_customer_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Only the subscriber linked to this Stripe customer id."
    }
  }
}

referralhero_list_unlocked_rewards

Rewards unlocked by subscribers across a whole campaign: reward name, status (sent, resent, canceled, pending, flagged), value, subscriber email and id, coupon code, transaction. Filter by status to find rewards still to pay out. GET /lists/{uuid}/rewards.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
status	string	Only rewards in this status.
per_page	integer	Results per page, 1-50 (default 10).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "status": {
      "enum": [
        "sent",
        "resent",
        "canceled",
        "pending",
        "flagged"
      ],
      "type": "string",
      "description": "Only rewards in this status."
    },
    "per_page": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Results per page, 1-50 (default 10)."
    }
  }
}

referralhero_promote_subscriber

WRITE: promote a subscriber to the campaign's winners list (contests and giveaways). Only verified subscribers can be promoted; an already promoted subscriber returns an error. POST /lists/{uuid}/subscribers/{id}/promote.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_qualify_referral

WRITE: mark a referral as qualified, so it counts toward the referrer's rewards. POST /lists/{uuid}/subscribers/{id}/qualify.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_search_subscribers_by_name

Search subscribers by name across all campaigns of the account, 50 per page. GET /subscribers/search_by_name.

read-only

Argument	Type	Description
name*	string	Name to search for.
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Name to search for."
    },
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

referralhero_track_conversion_event

WRITE: report a conversion event for a referral (campaigns whose goal tracks two or three events). Updates the referral from pending to confirmed (two events) or unconfirmed (three). If the referral is unknown but a referrer is given, the referral is created. May unlock rewards. POST /lists/{uuid}/subscribers/track_referral_conversion_event.

destructive

Argument	Type	Description
tags	array	Tags to assign.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
email	string	Subscriber email (when email is the campaign's unique identifier).
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).
referrer	string	Unique identifier of the referrer (needed to create a missing referral).
product_id	string	Product id (for product-based rewards).
phone_number	string	Subscriber phone number (when phone is the unique identifier).

referralhero_track_transaction

WRITE: record a purchase/transaction for a subscriber (amount required) so revenue-based rewards and reports count it (not idempotent unless a transaction_id is reused). The subscriber is identified by the campaign's unique identifier. POST /lists/{uuid}/subscribers/add_transactions.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
email	string	Subscriber email (when email is the campaign's unique identifier).
amount*	number	Amount of the transaction.
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).
product_id	string	Product id (for product-based rewards).
phone_number	string	Subscriber phone number (when phone is the unique identifier).
reward_value	number	A reward value to attach to the transaction.

referralhero_unlock_promoted_reward

WRITE: unlock a promoted-winner or one-off reward for a subscriber. This delivers the reward and may email the subscriber and use coupon codes. POST /lists/{uuid}/subscribers/{id}/unlock_promoted_reward.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
confirm*	boolean	Must be true: the user has approved delivering this reward to the subscriber now.
reward_id*	string	Id of the promotion reward (see referralhero_list_campaign_rewards).
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id",
    "reward_id",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved delivering this reward to the subscriber now."
    },
    "reward_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Id of the promotion reward (see referralhero_list_campaign_rewards)."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_unqualify_referral

WRITE: mark a referral as unqualified (for example fraud or a refund), so it no longer counts toward the referrer's rewards. POST /lists/{uuid}/subscribers/{id}/unqualify.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).
subscriber_id*	string	Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    }
  }
}

referralhero_update_reward_status

WRITE: set the status of an unlocked reward to sent, resent or canceled. Marking sent/resent can trigger the reward delivery email to the subscriber. Get the reward_id from referralhero_list_subscriber_rewards or referralhero_list_unlocked_rewards. POST /lists/{uuid}/subscribers/update_reward_status.

destructive

Argument	Type	Description
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
status*	string	New status.
confirm*	boolean	Must be true: the user has approved this reward status change (sent/resent can email the reward; canceled withdraws it).
reward_id*	string	Id of the unlocked reward.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "reward_id",
    "status",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "status": {
      "enum": [
        "sent",
        "resent",
        "canceled"
      ],
      "type": "string",
      "description": "New status."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this reward status change (sent/resent can email the reward; canceled withdraws it)."
    },
    "reward_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Id of the unlocked reward."
    }
  }
}

referralhero_update_subscriber

WRITE: change fields of a subscriber (overwrites the given fields): name, contact identifiers, extra fields, points (contest campaigns), tags, address, referral status (qualified/unqualified). Only fields you pass change. Only verified subscribers can be updated. POST /lists/{uuid}/subscribers/{id}.

destructive

Argument	Type	Description
city	string	City.
name	string	New name.
tags	array	Tags to assign.
uuid*	string	Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns).
email	string	Subscriber email (when email is the campaign's unique identifier).
points	integer	New points total (contest campaigns only).
address	string	Address.
confirm*	boolean	Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations).

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "points",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "Subscriber email (when email is the campaign's unique identifier)."
    },
    "points": {
      "type": "integer",
      "maximum": 1000000000,
      "minimum": 1,
      "description": "Points to add."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "phone_number": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "Subscriber phone number (when phone is the unique identifier)."
    },
    "crypto_wallet_address": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Wallet address (when it is the unique identifier)."
    },
    "other_identifier_value": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Custom identifier value (when a custom id is the unique identifier)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "confirm"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Subscriber name."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 50,
      "description": "Tags to assign."
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "Subscriber email (when email is the campaign's unique identifier)."
    },
    "device": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Device used to sign up, for analytics."
    },
    "domain": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "URL used for the subscriber's referral link."
    },
    "points": {
      "type": "integer",
      "maximum": 1000000000,
      "minimum": 0,
      "description": "Starting points (contest campaigns only)."
    },
    "source": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Source, for analytics."
    },
    "status": {
      "enum": [
        "custom_event_pending"
      ],
      "type": "string",
      "description": "custom_event_pending = set the referral status to pending (multi-step goals)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "referrer": {
      "type": "string",
      "maxLength": 320,
      "minLength": 1,
      "description": "Referral code or email of the referrer to credit."
    },
    "extra_field": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Extra field value."
    },
    "double_optin": {
      "type": "boolean",
      "description": "false = do not send the confirmation email. Default: the campaign's setting (usually sends it)."
    },
    "phone_number": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "Subscriber phone number (when phone is the unique identifier)."
    },
    "advocate_name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Name of the advocate."
    },
    "extra_field_2": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Extra field 2 value."
    },
    "transaction_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Unique id of the purchase this referral came from."
    },
    "conversion_value": {
      "type": "number",
      "maximum": 1000000000000,
      "minimum": 0,
      "description": "Monetary value of the referral."
    },
    "stripe_customer_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Stripe customer id to link."
    },
    "conversion_category": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Subscriber type for reports and segments."
    },
    "self_reported_source": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Where the subscriber says they heard about the campaign."
    },
    "crypto_wallet_address": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Wallet address (when it is the unique identifier)."
    },
    "other_identifier_value": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Custom identifier value (when a custom id is the unique identifier)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "confirm"
  ],
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 50,
      "description": "Tags to assign."
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "Subscriber email (when email is the campaign's unique identifier)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "referrer": {
      "type": "string",
      "maxLength": 320,
      "minLength": 1,
      "description": "Unique identifier of the referrer (needed to create a missing referral)."
    },
    "product_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Product id (for product-based rewards)."
    },
    "phone_number": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "Subscriber phone number (when phone is the unique identifier)."
    },
    "transaction_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Transaction id for the event."
    },
    "conversion_value": {
      "type": "number",
      "maximum": 1000000000000,
      "minimum": 0,
      "description": "Referral conversion value."
    },
    "stripe_customer_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Stripe customer id."
    },
    "crypto_wallet_address": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Wallet address (when it is the unique identifier)."
    },
    "other_identifier_value": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Custom identifier value (when a custom id is the unique identifier)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "amount",
    "confirm"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "Subscriber email (when email is the campaign's unique identifier)."
    },
    "amount": {
      "type": "number",
      "maximum": 1000000000000,
      "minimum": 0,
      "description": "Amount of the transaction."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "product_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Product id (for product-based rewards)."
    },
    "phone_number": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "Subscriber phone number (when phone is the unique identifier)."
    },
    "reward_value": {
      "type": "number",
      "maximum": 1000000000000,
      "minimum": 0,
      "description": "A reward value to attach to the transaction."
    },
    "lifetime_spend": {
      "type": "number",
      "maximum": 1000000000000,
      "minimum": 0,
      "description": "The subscriber's total lifetime spend."
    },
    "transaction_id": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Your unique transaction id."
    },
    "crypto_wallet_address": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Wallet address (when it is the unique identifier)."
    },
    "other_identifier_value": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Custom identifier value (when a custom id is the unique identifier)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "uuid",
    "subscriber_id",
    "confirm"
  ],
  "properties": {
    "city": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "City."
    },
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "New name."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 50,
      "description": "Tags to assign."
    },
    "uuid": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "Subscriber email (when email is the campaign's unique identifier)."
    },
    "points": {
      "type": "integer",
      "maximum": 1000000000,
      "minimum": 0,
      "description": "New points total (contest campaigns only)."
    },
    "address": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Address."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user has approved this change. It can unlock rewards and make ReferralHero email or text the subscriber or referrer (automations)."
    },
    "country": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Country."
    },
    "extra_field": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "New extra field value."
    },
    "phone_number": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "Subscriber phone number (when phone is the unique identifier)."
    },
    "extra_field_2": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "New extra field 2 value."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    },
    "referral_status": {
      "enum": [
        "qualified",
        "unqualified"
      ],
      "type": "string",
      "description": "Mark the referral qualified or unqualified."
    },
    "stripe_customer_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Stripe customer id."
    },
    "crypto_wallet_address": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Wallet address (when it is the unique identifier)."
    },
    "other_identifier_value": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Custom identifier value (when a custom id is the unique identifier)."
    }
  }
}