Objects

List

Your ReferralHero list, also known as your campaign, is where you store and manage all of your subscribers. Your subscribers will always be added to one list and can't be transferred to another list.

Attributes

Attributes
uuid	string	The unique identifier of the campaign
name	string	The campaign name
subscribers	integer	The total subscribers count
created_at	timestamp	Unix timestamp (expressed in UTC) of when the list has been created.

Example

{
  "uuid": "MFxxxxxxxxx",
  "name": "My amazing sweepstake",
  "created_at": 1487347070,
  "subscribers": 0
}

Subscriber

A subscriber is a person who is added to one of your lists. Subscribers belong to precisely one list and can't be transferred.

Attributes

Attributes
id	integer	The unique identifier of the subscriber
name	string	The name of the subscriber
email	string	The email of the subscriber
extra_field	string	The extra field value of the subscriber
extra_field_2	string	The extra field 2 value of the subscriber
code	string	The referral code of the subscriber
position	string	The position of the subscriber in the list (if applicable)
referred	boolean	True if the subscriber has been referred, false if not.
referral_value	integer	The monetay value of the referral.
referral_category	string	The type of subscriber. Useful for creating reports or segmenting subscribers.
transaction_id	string	The unique ID of the transaction. Useful when tracking referrals for purchases.
referred_by	object	An object containing the subscriber's referrer information.
people_referred	integer	The total number of referrals of the subscriber.
level_2_confirmed_referrals	integer	The total number of level 2 confirmed referrals of the subscriber.
level_3_confirmed_referrals	integer	The total number of level 3 confirmed referrals of the subscriber.
promoted	boolean	True is the subscriber is in the "winners" list, false if not.
promoted_at	timestamp	Unix timestamp (expressed in UTC) of when the subscriber has been promoted.
verified	boolean	True if the subscriber has verified their email address, false if not.
verified_at	timestamp	Unix timestamp (expressed in UTC) of when the subscriber has verified their email address.
risk_level	integer	Subscriber's fraudulence level expressed as an integer from 0 (none) to 5 (extremely likely)
points	integer	The number of points of the subscriber
host	string	Url used to generate the referral link.
source	string	The source of the subscriber.
device	string	The decide used by the subscriber to sign up.
created_at	timestamp	The date the participant was added to the campaign (UTC milliseconds)
updated_at	timestamp	Unix timestamp (expressed in UTC) of the last time the subscriber has been updated.
phone_number	string	If phone_number is the Unique Identifier
crypto_wallet_address	string	If crypto_wallet_address is the Unique Identifier
other_identifier_value	string	If custom ID is the Unique Identifier
extra_field_3	string	The extra field 3 value of the subscriber
extra_field_4	string	The extra field 4 value of the subscriber
option_field	string	The option field of the subscriber
conversion_amount	integer	The conversion amount generated by the subscriber
visitors	integer	The number of visitors referred by the subscriber
pending_referrals	integer	The number of pending referrals for the subscriber
unconfirmed_referrals	integer	The number of unconfirmed referrals for the subscriber
referral_link	string	The unique referral link of the subscriber
referral_status	string	The current status of the subscriber, if referred
universal_link	string	The universal referral link of the subscriber
stripe_customer_id	string	The Stripe Customer ID linked to the subscriber
tags	array	Assign tags to subscribers

Example

{
    "id": "sub_2bad325a25d7",
    "name": "John Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]",
    "crypto_wallet_address": "tb1qxyzxy",
    "crypto_wallet_provider": "Coinbase",
    "other_identifier_value": "",
    "extra_field": "Signup",
    "extra_field_2": "USA",
    "extra_field_3": "Item3",
    "extra_field_4": "Item4",
    "option_field": "Are you invited?",
    "conversion_amount": 1.0,
    "code": "c4fb914e",
    "position": 174,
    "referred": true,
    "referred_by": {
        "id": "sub_8a5b8df578c6",
        "name": "Nishchay",
        "email": "[e-mail]",
        "code": "1b52f1e0",
        "people_referred": 2,
        "points": 1
    },
    "visitors": 8,
    "pending_referrals": 3,
    "unconfirmed_referrals": 2,
    "people_referred": 2,
    "level_2_confirmed_referrals": 2,
    "level_3_confirmed_referrals": 2,
    "promoted": false,
    "promoted_at": null,
    "verified": true,
    "verified_at": 1738954543,
    "points": 1,
    "risk_level": 3,
    "host": "https://app.referralhero.com/MFxxxxxxxxxx/signup",
    "source": "Admin",
    "device": "Mobile",
    "referral_link": "https://app.referralhero.com/MFxxxxxxxxx/signup?mwr=c4fb914e",
    "referral_status": "Payment Pending",
    "referral_status_at": 1738954543,
    "universal_link": "https://app.referralhero.com/MFxxxxxxxxxxx/universal_link?mwr=c4fb914e",
    "stripe_customer_id": "cus_TEST123456789",
    "tags": ["tag1", "tag2"],
    "created_at": 1738954543,
    "last_updated_at": 1738954701
}

Reward

The Reward Object contains detailed reward information about a single reward that was set up for a campaign.

Attributes

Attributes
title	string	The name of the reward
description	string	The description of the reward
referrals	integer	The number of referrals needed to win this reward

Example

{
  "title": "30% discount on our Pro Plan",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "referrals": 2
}