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. Mxxxxxxxxxx
Create a new list
POST https://app.referralhero.com/api/v2/lists
Create a new list/campaign in your account.
Path Parameters
website
string
Default Referral URL
name
string
Your list name
api_token
string
Your API Token
{
"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
api_token
string
Your API Token.
page
string
Page you want to jump to. By default 1.
{
"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
uuid
string
Your list UUID
api_token
string
Your API Token
count
string
Number (10-100) of subscribers returned in the leaderboard
{
"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
uuid
string
Your list UUID
api_token
string
Your API Token
{
"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 Overview> Edit Campaign > Launch > Instructions
The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987
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
api_token
string
Your API Token
uuid
string
The list uuid
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
{
"status": "ok",
"data": {
"response": "subscriber_created",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487661494
} 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
api_token
string
Your API Token
uuid
string
Your list UUID
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
product_id
string
Product ID (normally used if rewards are based on specific products)
tags
array
Assign tags to subscriber
{
"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
api_token
string
Your API Token
uuid
string
Your list UUID
subscriber_id
string
The ID of the subscriber
{
"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
api_token
String
Your API Token
uuid
String
Your list UUID
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)
{
"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
api_token
string
Your API Token
uuid
string
The list UUID
name
string
The name of the subscriber
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
{
"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
api_token
string
Your API Token
uuid
string
Your list UUID
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
{
"status": "ok",
"data": {
"response": "points_added",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487661494
}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.
api_token
string
Your API Token
uuid
string
Your list UUID
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
{
"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
}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.
api_token
string
Your API Token
uuid
string
Your list UUID
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)
{
"transactions": [
{
"email": "[email protected]",
"amount": 150,
"product_id": "prod_0005",
"transaction_id": "trans_0005",
"reward_value": 15
},
{
"email": "[email protected]",
"amount": 500,
"product_id": "prod_0006",
"transaction_id": "trans_0006",
"reward_value": 50
}
]
}
Response
{
"status": "in_progress",
"message": "Transactions are being processed. It will take some time to complete."
}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
api_token
string
Your API Token
uuid
string
Your list UUID
subscriber_id
string
The ID of the subscriber
{
"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
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
{
"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
api_token
string
Your API Token
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
{
"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
api_token
string
Your API Token
uuid
string
The list UUID
subscriber_id
string
The ID of the subscriber
{
"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
api_token
string
Your API Token
uuid
string
The list UUID
string
The email of the subscriber.
{
"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
api_token
string
Your API Token
uuid
string
The list UUID
mwr
string
The referrer's referral code
{
"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
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
{
"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
GEThttps://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
api_token
string
Your API Token
uuid
string
Your list UUID
subscriber_id
string
The ID of the subscriber.
{
"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
}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
api_token
string
Your API Token
uuid
string
Your list UUID
subscriber_id
string
The ID of the subscriber.
{
"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
}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
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
{
"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
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
{
"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
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
{
"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 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
api_token
String
Your API Token
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.
{
"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": "[email protected]",
"value": 100.0,
"total": "",
"signup_type": null,
"referrals_type": "confirmed",
"recurring_count": null,
"coupon_code": null,
"coupon_group": null,
"image_url": null,
"subscriber_email": "[email protected]",
"subscriber_id": "sub_64f9c36e25de"
```
},
],
"pagination": {
"total_pages": 1,
"current_page": 1,
"per_page": 10,
"total_objects": 1
}
},
"calls_left": null,
"timestamp": 1729186260
}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
api_token
String
Your API Token
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)
{
"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": "[email protected]",
"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
api_token
string
Your API Token
uuid
string
The list UUID
subscriber_id
string
The ID of the subscriber
{
"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
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
{
"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
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
{
"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
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"]
{
"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
api_token
String
Your API Token
uuid
String
Your list UUID
{
"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
api_token
String
Your API Token
uuid
String
Your list UUID
id
String
ID of coupon group
{
"status": "ok",
"data": {
"id": "rh200",
"name": "RH200",
"active": true,
"created_at": 1686563246,
"coupons": []
},
"calls_left": null,
"timestamp": 1686563407
}Last updated
Was this helpful?