Endpoint Reference

Lists

Locations where you can find most of the required parameters:

Path Parameters	Location
api_token	ReferralHero dashboard > Account > API
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. MF078d000987

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
api_token	string	Your API Token

200

{
  "status": "ok",
  "data": {
    < List object >
  },
  "calls_left": 1000,
  "timestamp": 1487659010
}

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
api_token	string	Your API Token.
page	string	Page you want to jump to. By default 1.

200

{
  "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
}

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
api_token	string	Your API Token
count	string	Number (10-100) of subscribers returned in the leaderboard

200

{
  "status": "ok",
  "data": {
    "ranking": [
      {
        < Subscriber object >
      },
      {
        < Subscriber object >
      },
      ...
    ]
  },
  "calls_left": 1000,
  "timestamp": 1487659347
}

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
api_token	string	Your API Token

200

{
  "status": "ok",
  "data": [
    {
      < Reward object >
    },
    {
      < Reward object >
    }
  ],
  "calls_left": 1000,
  "timestamp": 1487659708
}

Subscribers

Locations where you can find most of the required parameters:

Path Parameters	Location
api_token	ReferralHero dashboard > Account > API
uuid	ReferralHero dashboard > Campaign > Installation > 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
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_2	string	The extra field 2 of the subscriber
extra_field	string	The extra field of the subscriber
name	string	The name of the subscriber
api_token	string	Your API Token
uuid	string	The list uuid
email	string	The email of the subscriber
domain	string	The URL for the referral link
status	string	Use 'custom_event_pending' to set the referral status to pending

200

{
  "status": "ok",
  "data": {
    "response": "subscriber_created",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
} 

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

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
api_token	string	Your API Token
uuid	string	Your list UUID
email	string	The email of subscriber (if unique identifier)
referrer	string	The unique identifier of the referrer
phone_number	string	The phone number of subscriber (if unique identifier)
crypto_wallet_address	string	The crypto wallet address of subscriber (if unique identifier)

200

{
  "status": "ok",
  "data": {
    "response": "custom_event_completed",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

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
api_token	string	Your API Token
uuid	string	Your list UUID
subscriber_id	string	The ID of the subscriber

200

{
  "status": "ok",
  "data": {
    "response": "subscriber_confirmed",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

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
api_token	String	Your API Token
uuid	String	Your list UUID
email	String	If email is the Unique Identifier
crypto_wallet_address	String	If crypto_wallet_address is the Unique Identifier
phone_number	String	if phone_number is the Unique Identifier

200: OK

{
  "status": "ok",
  "data": {
    "response": "subscriber_confirmed",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

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
points	string	The number of points of the subscriber. It only works for "contest" campaigns.
email	string	The email of the subscriber
extra_field_2	string	The extra field 2 of the subscriber
extra_field	string	The extra field of the subscriber
name	string	The name of the subscriber
api_token	string	Your API Token
uuid	string	The list UUID
subscriber_id	string	The ID of the subscriber

200

{
  "status": "ok",
  "data": {
    "response": "subscriber_updated",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

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
api_token	string	Your API Token
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)
points	string	The number or points to add

200

{
  "status": "ok",
  "data": {
    "response": "points_added",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

Track Transactions

POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_transactions

This allows you to pass transaction data to ReferralHero.

Name	Type	Description
api_token	string	Your API Token
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)
amount (required)	string	Amount of the Transaction
transaction_id	string	Transaction ID
product_id	string	Product ID
lifetime_spend	string	Total lifetime spend

Response

200

{
    "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
}

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
api_token	string	Your API Token
uuid	string	Your list UUID
subscriber_id	string	The ID of the subscriber

200

{
  "status": "ok",
  "data": {
    "response": "subscriber_promoted",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

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
api_token	String	Your API Token
uuid	String	Your list UUID
subscriber_id	String	The ID of the subscriber
reward_id	String	The ID of the promotion reward

200: OK

{
    "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"
    }
}

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
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.
uuid	string	Your list UUID
api_token	string	Your API Token
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

200

{
  "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
}

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
Your API Token	string	Your API Token
uuid	string	The list UUID
subscriber_id	string	The ID of the subscriber

200

{
  "status": "ok",
  "data": {
    "response": "subscriber_retrieved",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487676070
}

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
api_token	string	Your API Token
uuid	string	The list UUID
email	string	The email of the subscriber.

200

{
  "status": "ok",
  "data": {
    "response": "subscriber_retrieved",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487676070
}

Retrieve all referrals of a subscriber

GET https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/referred

Retrieve all referrals of a single subscriber. Results are paginated (max 50 results per page).

Path Parameters

Name	Type	Description
api_token	string	Your API Token
uuid	string	Your list UUID
subscriber_id	string	The ID of the subscriber.
page	string	Page you want to jump to. By default is 1.
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

200

{
  "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
}

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
api_token	String	Your API Token
uuid	String	Your list UUID
subscriber_id	String	The ID of the subscriber

200: OK

{
  "status": "ok",
  "data": {
    "response": "rewards_retrieved",
    "rewards": [
      {
        "id": 1795,
        "name": "A free Premium account for 1 year",
        "status": "confirmed",
        "referrals": null,
        "created_at": 1686397951,
        "signup_type": "organic subscriber",
        "referrals_type": null,
        "recurring_count": null,
        "coupon_code": 'AD45RF',
        "coupon_group": 'rh123'
      }
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 10,
      "total_objects": 1
    }
  },
  "calls_left": null,
  "timestamp": 1686561391
}

Delete a subscriber

DELETE https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id

Delete a single subscriber.

Path Parameters

Name	Type	Description
api_token	string	Your API Token
uuid	string	The list UUID
subscriber_id	string	The ID of the subscriber

200

{
  "status": "ok",
  "data": {
    "response": "subscriber_deleted",
    < Subscriber object >
  },
  "calls_left": 1000,
  "timestamp": 1487661494
}

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
api_token	String	Your API Token
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

200: OK

{
  "status": "ok",
  "data": {
    "id": 1795,
    "name": "A free Premium account for 1 year",
    "status": "confirmed",
    "referrals": null,
    "created_at": 1686397951,
    "signup_type": "organic subscriber",
    "referrals_type": null,
    "recurring_count": null
  },
  "calls_left": null,
  "timestamp": 1686561403
}

Create coupon group

POST https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups

Add new coupon group

Path Parameters

Name	Type	Description
api_token	String	Your API Token
uuid	String	Your list UUID
name	String	Coupon group name
coupons	String	Array, e.g. ["ab23fg, fghg45, gh78wl"]
active	String	True or false

200: OK

{
  "status": "ok",
  "data": {
    "id": "rh400",
    "name": "RH400",
    "active": true,
    "created_at": 1686563261,
    "coupons": [],
    "response": "coupon_group_created"
  },
  "calls_left": null,
  "timestamp": 1686563261
}

Create coupons

POST https://app.referralhero.com/api/v2/lists/:uuid/coupons

Add coupon(s) to a coupon group

Path Parameters

Name	Type	Description
api_token	String	Your API Token
uuid	String	Your list UUID
coupon_group_id	String	ID of coupon group
coupons	String	Array, e.g. ["ab23fg", fghg45”, “gh78wl"]

200: OK

{
  "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
}

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
api_token	String	Your API Token
uuid	String	Your list UUID

200: OK

{
  "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
}

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
api_token	String	Your API Token
uuid	String	Your list UUID
id	String	ID of coupon group

200: OK

{
  "status": "ok",
  "data": {
    "id": "rh200",
    "name": "RH200",
    "active": true,
    "created_at": 1686563246,
    "coupons": []
  },
  "calls_left": null,
  "timestamp": 1686563407
}