Lists
Locations where you can find most of the required parameters:
Create a new list
POST https://app.referralhero.com/api/v2/lists
Create a new list/campaign in your account.
Path Parameters
200
Copy {
"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
200
Copy {
"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
200
Copy {
"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
200
Copy {
"status" : "ok" ,
"data" : [
{
< Reward object >
} ,
{
< Reward object >
}
] ,
"calls_left" : 1000 ,
"timestamp" : 1487659708
} Subscribers
Locations where you can find most of the required parameters:
Add a subscriber
POST https://app.referralhero.com/api/v2/lists/:uuid/subscribers
Path Parameters
200
Copy {
"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
200
Copy {
"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
200
Copy {
"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
200: OK
Copy {
"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
200
Copy {
"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
200
Copy {
"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.
Response
200
Copy {
"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
200
Copy {
"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
200: OK
Copy {
"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
200
Copy {
"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
200
Copy {
"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
200
Copy {
"status" : "ok" ,
"data" : {
"response" : "subscriber_retrieved" ,
< Subscriber object >
} ,
"calls_left" : 1000 ,
"timestamp" : 1487676070
} 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
200
Copy {
"status": "ok",
"data": {
"response": "subscriber_retrieved",
< Subscriber object >
},
"calls_left": null,
"timestamp": 1725032082
} 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
200
Copy {
"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 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
200
Copy {
"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.sagicor.bank/refer",
"source": null,
"device": null,
"referral_link": "https://www.sagicor.bank/refer?mwr=eb134b6d",
"created_at": 1723452705,
"last_updated_at": 1723452705,
"referral_status": "confirmed",
"referral_status_at": 1723452705,
"universal_link": "https://app.referralhero.com//MF0b793ba17d/universal_link?mwr=eb134b6d"
}
],
"pagination": {
"total_pages": 1,
"current_page": 1,
"per_page": 50,
"total_objects": 1
}
},
"calls_left": null,
"timestamp": 1723457099
} 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
200
Copy {
"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.sagicor.bank/refer",
"source": null,
"device": null,
"referral_link": "https://www.sagicor.bank/refer?mwr=eb134b6d",
"created_at": 1723452705,
"last_updated_at": 1723452705,
"referral_status": "confirmed",
"referral_status_at": 1723452705,
"universal_link": "https://app.referralhero.com//MF0b793ba17d/universal_link?mwr=eb134b6d"
}
],
"pagination": {
"total_pages": 1,
"current_page": 1,
"per_page": 50,
"total_objects": 1
}
},
"calls_left": null,
"timestamp": 1723457099
} 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
200
Copy {
"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 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
200
Copy {
"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 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
200
Copy {
"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
200: OK
Copy {
"status": "ok",
"data": {
"response": "rewards_retrieved",
"rewards": [
{
"id": 214,
"name": "10% commission",
"status": "sent",
"referrals": 1,
"created_at": 1729166882,
"unlocked_date": "2024-10-17",
"sent_date": "2024-10-17",
"referral": "nishchay@referralhero.com",
"value": 100.0,
"total": "",
"signup_type": null,
"referrals_type": "confirmed",
"recurring_count": null,
"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
} Delete a subscriber
DELETE https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id
Delete a single subscriber.
Path Parameters
200
Copy {
"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
200: OK
Copy {
"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
200: OK
Copy {
"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
200: OK
Copy {
"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
200: OK
Copy {
"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
