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

{% tabs %}
{% tab title="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. |
| {% endtab %}    |             |                                                                      |

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Attributes" %}

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

{% tab title="Example" %}

```yaml
{
    "id": "sub_2bad325a25d7",
    "name": "John Doe",
    "email": "john.doe@gmail.com",
    "phone_number": "+1228374652",
    "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": "test123@gmail.com",
        "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
}
```

{% endtab %}
{% endtabs %}

## Reward

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

{% tabs %}
{% tab title="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 |
| {% endtab %}    |           |                                                   |

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}