ReferralHero MCP by usefulapi

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.

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

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

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

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.

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

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.

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

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.

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

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}.

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

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

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

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.

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

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

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

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}.

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

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.

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

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.

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

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

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

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

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

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.

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

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}.

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

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

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

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.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "description": "Subscriber email (when email is the campaign's unique identifier).",
      "type": "string",
      "minLength": 3,
      "maxLength": 320
    },
    "phone_number": {
      "description": "Subscriber phone number (when phone is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "crypto_wallet_address": {
      "description": "Wallet address (when it is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "other_identifier_value": {
      "description": "Custom identifier value (when a custom id is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "points": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000000,
      "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)."
    }
  },
  "required": [
    "uuid",
    "points",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "description": "Subscriber email (when email is the campaign's unique identifier).",
      "type": "string",
      "minLength": 3,
      "maxLength": 320
    },
    "phone_number": {
      "description": "Subscriber phone number (when phone is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "crypto_wallet_address": {
      "description": "Wallet address (when it is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "other_identifier_value": {
      "description": "Custom identifier value (when a custom id is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "Amount of the transaction."
    },
    "transaction_id": {
      "description": "Your unique transaction id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "product_id": {
      "description": "Product id (for product-based rewards).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "lifetime_spend": {
      "description": "The subscriber's total lifetime spend.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "reward_value": {
      "description": "A reward value to attach to the transaction.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "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)."
    }
  },
  "required": [
    "uuid",
    "amount",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "subscriber_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Subscriber id, e.g. sub_2bad325a25d7 (the id field of a subscriber)."
    },
    "email": {
      "description": "Subscriber email (when email is the campaign's unique identifier).",
      "type": "string",
      "minLength": 3,
      "maxLength": 320
    },
    "phone_number": {
      "description": "Subscriber phone number (when phone is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "crypto_wallet_address": {
      "description": "Wallet address (when it is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "other_identifier_value": {
      "description": "Custom identifier value (when a custom id is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "conversion_value": {
      "description": "Referral conversion value.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "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)."
    }
  },
  "required": [
    "uuid",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "email": {
      "description": "Subscriber email (when email is the campaign's unique identifier).",
      "type": "string",
      "minLength": 3,
      "maxLength": 320
    },
    "phone_number": {
      "description": "Subscriber phone number (when phone is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "crypto_wallet_address": {
      "description": "Wallet address (when it is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "other_identifier_value": {
      "description": "Custom identifier value (when a custom id is the unique identifier).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "referrer": {
      "description": "Unique identifier of the referrer (needed to create a missing referral).",
      "type": "string",
      "minLength": 1,
      "maxLength": 320
    },
    "conversion_value": {
      "description": "Referral conversion value.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "stripe_customer_id": {
      "description": "Stripe customer id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "transaction_id": {
      "description": "Transaction id for the event.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "product_id": {
      "description": "Product id (for product-based rewards).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "tags": {
      "description": "Tags to assign.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      }
    },
    "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)."
    }
  },
  "required": [
    "uuid",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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

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

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.

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

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.

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

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.

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

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.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Campaign (list) uuid, the 12-character id starting with MF (see referralhero_list_campaigns)."
    },
    "reward_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Id of the unlocked reward."
    },
    "status": {
      "type": "string",
      "enum": [
        "sent",
        "resent",
        "canceled"
      ],
      "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)."
    }
  },
  "required": [
    "uuid",
    "reward_id",
    "status",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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

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

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

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