# Endpoints Reference ## Authentication All API requests must be authenticated using an API token. **Preferred (**Recommended) **:** Authorization: `Bearer YOUR_API_TOKEN` **Alternative :** X-API-Key: `YOUR_API_TOKEN` > Use X-API-Key only if your client cannot send the Authorization header. **Headers** | Name | Value | Description | | ------------- | ----------------------- | ------------------ | | Authorization | Bearer `YOUR_API_TOKEN` | (Preferred) | | X-API-Key | `YOUR_API_TOKEN` | Alternative option | {% hint style="info" %} You can find your api token by navigating to **ReferralHero dashboard > Account > API** {% endhint %} ## Lists Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | *ReferralHero dashboard > Campaign name* | | uuid |

ReferralHero dashboard > Campaign > Installation > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. Mxxxxxxxxxx

| ### Create a new list `POST` `https://app.referralhero.com/api/v2/lists` Create a new list/campaign in your account. #### Path Parameters | Name | Type | Description | | ------- | ------ | -------------------- | | website | string | Default Referral URL | | name | string | Your list name | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { < List object > }, "calls_left": 1000, "timestamp": 1487659010 } ``` {% endtab %} {% endtabs %} ### Retrieve all lists `GET` `https://app.referralhero.com/api/v2/lists` Get all the lists/campaigns in your account. Results are paginated (10 results per page).\ Only active lists will be retrieved. #### Path Parameters | Name | Type | Description | | ---- | ------ | --------------------------------------- | | page | string | Page you want to jump to. By default 1. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "lists_retrieved", "lists": [ { < List object > }, { < List object > }, ... ], "pagination": { "total_pages": 7, "current_page": 1, "per_page": 10, "total_objects": 67 } }, "calls_left": 1000, "timestamp": 1487658324 } ``` {% endtab %} {% endtabs %} ### Get List Leaderboard `GET` `https://app.referralhero.com/api/v2/lists/:uuid/leaderboard` Retrieve leaderboard of the top 10-100 subscribers in a list. #### Path Parameters | Name | Type | Description | | ----- | ------ | ---------------------------------------------------------- | | uuid | string | Your list UUID | | count | string | Number (10-100) of subscribers returned in the leaderboard | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "ranking": [ { < Subscriber object > }, { < Subscriber object > }, ... ] }, "calls_left": 1000, "timestamp": 1487659347 } ``` {% endtab %} {% endtabs %} ### Get list rewards `GET` `https://app.referralhero.com/api/v2/lists/:uuid/bonuses` Retrieve list of rewards from a list. #### Path Parameters | Name | Type | Description | | ---- | ------ | -------------- | | uuid | string | Your list UUID | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": [ { < Reward object > }, { < Reward object > } ], "calls_left": 1000, "timestamp": 1487659708 } ``` {% endtab %} {% endtabs %} ## Subscribers Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | uuid |

ReferralHero dashboard > Campaign Overview> Edit Campaign > Launch > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987

| | email | The email of the subscriber | | domain | *ReferralHero dashboard > Campaign > Options > Default Referral Link* | | subscriber\_id | *ReferralHero dashboard > Campaign > Subscribers* | ### Add a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` #### Path Parameters | Name | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------- | | uuid | string | The list uuid | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | name | string | The name of the subscriber | | status | string | Use 'custom\_event\_pending' to set the referral status to pending | | transaction\_id | string | The unique ID of the transaction. Useful when tracking referrals for purchases. | | conversion\_category | string | The type of subscriber. Useful for creating reports or segmenting subscribers. | | conversion\_value | number | The monetary value of the referral. | | device | string | The device used by the subscriber to sign up. Used for analytics. | | source | string | The source of the subscriber. Used for analytics. | | double\_optin | boolean | If set to `false` the subscriber will not received a confirmation email. | | points | integer | The number of points for the subscriber. It only works for "contest" campaigns. | | referrer | string | Set a referrer for the subscriber by providing the referrer's referral code or email. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | domain | string | The URL for the referral link | | stripe\_customer\_id | string | Stripe Customer ID | | advocate\_name | string | Name of the advocate | | tags | array | Assign tags to subscribers | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_created", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Note for Web Integrations:** When deciding between using our Javascript Web API or REST API to interact with ReferralHero, it is generally advisable to '[add a subscriber](https://support.referralhero.com/integrate/javascript-web-api/adding-a-subscriber-manually)' using the Javascript Web API as you will take advantage of our powerful global tracking script and cookie. Once a subscriber is added to our database, you can manage that subscriber and campaign more freely using either the Javascript Web API or REST API. {% endhint %} ### Track referral conversion event `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/track_referral_conversion_event` Use when your Campaign Goal is set to track two or three conversion events. **If the referrer is present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, we will create the referral and set the referral status. **If the referrer is not present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, the referral will not be created. **The Referral Status Is Set To:** Confirmed (if tracking two conversion events) Unconfirmed (if tracking three conversion events) \ **Note**: 1\. Your campaign Goal must be set up to track two or three conversion events otherwise, an error will return. 2\. If the referral is present in ReferralHero with pending status, a successful response `custom_event_completed` will return. 3\. If the referral unique identifier is not present in the ReferralHero, but the referrer unique identifier is present, a successful response `custom_event_completed` with the data of the new confirmed referral will return. 4\. If a referral exists but the referral status is not pending, the error `custom event is already completed` will return. 5\. If the referral unique identifier is not present in ReferralHero and the referrer is also not provided in the API, the error `referrer is invalid or not present` will return. 6\. If the referral status is unconfirmed or confirmed, the error `custom event is already completed` will return. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The identifier value of subscriber (if unique identifier) | | referrer | string | The unique identifier of the referrer | | conversion\_value | string | Referral conversion value | | stripe\_customer\_id | string | Stripe Customer ID | | transaction\_id | string | Assign a transaction id to the conversion event | | product\_id | string | Product ID (normally used if rewards are based on specific products) | | tags | array | Assign tags to subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "custom_event_completed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Confirm referral by Subscriber ID `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Confirm referral by Unique Identifier `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | String | Your list UUID | | email | String | The email of subscriber (if unique identifier) | | crypto\_wallet\_address | String | The wallet address of subscriber (if unique identifier) | | phone\_number | String | The phone number of subscriber (if unique identifier) | | other\_identifier\_value | String | The other identifier value of subscriber (if unique identifier) | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Update a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Update a single subscriber.\ Note: only verified subscribers can be updated. Trying to update a non-verified subscriber will return a subscriber\_not\_found error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | ------------------------------------------------------------------------------ | | uuid | string | The list UUID | | name | string | The name of the subscriber | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | points | string | The number of points of the subscriber. It only works for "contest" campaigns. | | subscriber\_id | string | The ID of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | | tags | array | Assign tags to subscribers | | address | string | The address of the subscriber | | city | string | The city of the subscriber | | country | string | The country of the subscriber | | referral\_status | string | unqualified / qualified | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_updated", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Add points to a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_points` Add points to an existing subscriber for any reason.\ **Note**: Trying to add points to a non-existing subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | points | string | The number or points to add | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "points_added", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Track Transactions (Single Transaction) `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_transactions` This allows you to pass transaction data to ReferralHero. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Response** {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "id": 592, "transaction_id": "MFa19e08789720240219142611", "transaction_time": "2024-02-19T14:26:11.000Z", "amount": 56665, "product_id": "12345", "response": "transaction_added" }, "calls_left": null, "timestamp": 1708352775 } ``` {% endtab %} {% endtabs %} ### Track Bulk Transactions `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_bulk_transactions` This allows you to pass multiple transaction data to ReferralHero in bulk. Once processing is complete, the results will be emailed to the admin with a CSV file containing the transaction status. You can pass up to **500 transactions** at a time. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the Transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Request Body (JSON Format)** {% tabs %} {% tab title="JSON" %} ```json { "transactions": [ { "email": "refloading@hi.com", "amount": 150, "product_id": "prod_0005", "transaction_id": "trans_0005", "reward_value": 15 }, { "email": "tremendousref3@hi.com", "amount": 500, "product_id": "prod_0006", "transaction_id": "trans_0006", "reward_value": 50 } ] } ``` {% endtab %} {% endtabs %} **Response** {% tabs %} {% tab title="200" %} ```json { "status": "in_progress", "message": "Transactions are being processed. It will take some time to complete." } ``` {% endtab %} {% endtabs %} ### Promote a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/promote` Promote a single subscriber. Read this article about what "promoting" means.\ **Note**: only verified subscribers can be promoted. Trying to promote a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_promoted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Trigger manual rewards `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/unlock_promoted_reward` Used to trigger the Rewards for Promoted Winners #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------------ | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | reward\_id | String | The ID of the promotion reward | {% tabs %} {% tab title="200: OK " %} ```json { "response": "reward_unlocked", "reward": { "id": 203, "title": "Winner 2", "header": null, "description": "", "referrals": null, "image": "/missing.png", "label": "Winner Reward", "points": null, "category": "promoted_winners" } } ``` {% endtab %} {% endtabs %} ### Retrieve all subscribers from a list `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` Get all the subscribers in a list. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | uuid | string | Your list UUID | | sort\_by | string | Sort subscribers by one attribute. Possible options are: `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 | string | Page you want to jump to. By default 1. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | option\_field | string | The option field of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by ID `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by email `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_email` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ----- | ------ | ---------------------------- | | uuid | string | The list UUID | | email | string | The email of the subscriber. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by MWR `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_mwr` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------------- | | uuid | string | The list UUID | | mwr | string | The referrer's referral code | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": null, "timestamp": 1725032082 } ``` {% endtab %} {% endtabs %} ### Retrieve all referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/referred` Retrieve all referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: 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
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_all_referrals` Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------- | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134345", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} ### Retrieve all Level 3 referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_all_referrals` **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------- | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134ss4", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 1 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_1_referrals` Retrieve all level 1 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: 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
{% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 2 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_referrals` Retrieve all level 2 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: 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
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 3 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_referrals` Retrieve all level 3 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: 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
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all rewards for all subscribers `GET` `https://app.referralhero.com/api/v2/lists/:uuid/rewards` Retrieve a list of all rewards across all subscribers in a specified campaign. Results are paginated (maximum 50 results per page). #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | uuid | String | Your list UUID | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | | page | String | Page you want to jump to. By default is 1. | | per\_page | String | Number of results you want per page. By default is 10. | {% tabs %} {% tab title="200 " %} ````json { "status": "ok", "data": { "response": "rewards_retrieved", "rewards": [ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created_at": 1729166882, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "nishchay@referralhero.com", "value": 100.0, "total": "", "signup_type": null, "referrals_type": "confirmed", "recurring_count": null, "transaction_id": "pi_3SV7RlJb999K2d", "product_id": "price_1RBZEsJb999K2d", "coupon_code": null, "coupon_group": null, "image_url": null, "subscriber_email": "johndoe@gmail.com", "subscriber_id": "sub_64f9c36e25de" ``` }, ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 10, "total_objects": 1 } }, "calls_left": null, "timestamp": 1729186260 } ```` {% endtab %} {% endtabs %} ### Retrieve all rewards unlocked by a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/rewards` Get all rewards unlocked by the subscriber. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "rewards_retrieved", "rewards": [ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "nishchay@referralhero.com", "value": 100.0, "total": "", "signup_type": null, "referrals_type": "confirmed", "recurring_count": null, "transaction_id": "pi_3SV7RlJb999K2d", "product_id": "price_1RBZEsJb999K2d", "coupon_code": null, "coupon_group": null, "image_url": null }, ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 10, "total_objects": 1 } }, "calls_left": null, "timestamp": 1729186260 } ``` {% endtab %} {% endtabs %} ### Delete a subscriber `DELETE` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Delete a single subscriber. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_deleted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Update reward status by reward\_id `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/update_reward_status` Update status of an unlocked reward of a subscriber by reward\_id #### Path Parameters | Name | Type | Description | | ---------- | ------ | --------------------------------------------------------------------- | | uuid | String | Your list UUID | | reward\_id | String | ID of reward provided in GET all rewards unlocked by a subscriber API | | status | String | sent/resent/canceled | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": 794765, "name": "referral signup", "status": "confirmed", "referrals": null, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "", "value": null, "total": "", "signup_type": "referral", "referrals_type": null, "recurring_count": null, "coupon_code": "cdwtmnKz8P", "coupon_group": "10-off-new-355bed2b-d645-4b2f-88ed-40a813940243", "image_url": null }, "calls_left": null, "timestamp": 1753514108 } ``` {% endtab %} {% endtabs %} ### Create coupon group `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Add new coupon group #### Path Parameters | Name | Type | Description | | ------- | ------ | --------------------------------------- | | uuid | String | Your list UUID | | name | String | Coupon group name | | coupons | String | Array, e.g. \["ab23fg, fghg45, gh78wl"] | | active | String | True or false | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [], "response": "coupon_group_created" }, "calls_left": null, "timestamp": 1686563261 } ``` {% endtab %} {% endtabs %} ### Create coupons `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupons` Add coupon(s) to a coupon group #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ------------------------------------------ | | uuid | String | Your list UUID | | coupon\_group\_id | String | ID of coupon group | | coupons | String | Array, e.g. \["ab23fg", fghg45”, “gh78wl"] | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "tvt4g45v", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "RFGH677", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "KMLFG767", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, "calls_left": null, "timestamp": 1686676359 } ``` {% endtab %} {% endtabs %} ### Retrieve all coupon groups `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Get all coupon groups of a campaign #### Path Parameters | Name | Type | Description | | ---- | ------ | -------------- | | uuid | String | Your list UUID | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "coupon_groups_retrieved", "coupon_groups": [ { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [] } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 2 } }, "calls_left": null, "timestamp": 1686563777 } ``` {% endtab %} {% endtabs %} ### Retrieve coupons `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups/:id` Get all coupons within a coupon group #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------ | | uuid | String | Your list UUID | | id | String | ID of coupon group | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [] }, "calls_left": null, "timestamp": 1686563407 } ``` {% endtab %} {% endtabs %} ### Mark Referral as Unqualified `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/unqualify` Mark a referral as Unqualified #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | String | The list UUID | | subscriber\_id | String | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```ara { "status": "ok", "data": { "response": "subscriber_unqualified" < Subscriber object > }, "calls_left": null, "timestamp": 1775833694 } ``` {% endtab %} {% endtabs %} ### Mark Referral as Qualified `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/qualify` Mark a referral as Qualified #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | String | The list UUID | | subscriber\_id | String | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```ara { "status": "ok", "data": { "response": "subscriber_qualified" < Subscriber object > }, "calls_left": null, "timestamp": 1775833694 } ``` {% endtab %} {% endtabs %}