Retrieve all lists
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
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
}
Create a new list
https://app.referralhero.com/api/v2/lists
Create a new list/campaign in your account.
{
"status": "ok",
"data": {
< List object >
},
"calls_left": 1000,
"timestamp": 1487659010
}
Get List Leaderboard
https://app.referralhero.com/api/v2/lists/:uuid/leaderboard
Retrieve leaderboard of the top 10 subscribers in a list.
{
"status": "ok",
"data": {
"ranking": [
{
< Subscriber object >
},
{
< Subscriber object >
},
...
]
},
"calls_left": 1000,
"timestamp": 1487659347
}
Get list rewards
https://app.referralhero.com/api/v2/lists/:uuid/bonuses
Retrieve list of rewards from a list.
{
"status": "ok",
"data": [
{
< Reward object >
},
{
< Reward object >
}
],
"calls_left": 1000,
"timestamp": 1487659708
}
Retrieve all subscribers from a list
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
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 you want to jump to. By default 1.
{
"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
}
Create a new subscribers
https://app.referralhero.com/api/v2/lists/:uuid/subscribers
Path Parameters
The unique ID of the transaction. Useful when tracking referrals for purchases.
conversion_category
optional
The type of referral. Useful for creating reports.
The monetary value of the referral.
The device used by the subscriber to sign up. Used for analytics.
The source of the subscriber. Used for analytics.
If set to false
the subscriber will not received a confirmation email.
The number of points for the subscriber. It only works for "contest" campaigns.
Set a referrer for the subscriber by providing the referrer's referral code or email.
The extra field 2 of the subscriber
The extra field of the subscriber
The name of the subscriber
The email of the subscriber
The URL for the referral link
{
"status": "ok",
"data": {
"response": "subscriber_created",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487661494
}
Retrieve subscriber by ID
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.
{
"status": "ok",
"data": {
"response": "subscriber_retrieved",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487676070
}
Retrieve subscriber by email
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
The email of the subscriber.
{
"status": "ok",
"data": {
"response": "subscriber_retrieved",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487676070
}
Update a subscriber
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
The number of points of the subscriber. It only works for "contest" campaigns.
The email of the subscriber
The extra field 2 of the subscriber
The extra field of the subscriber
The name of the subscriber
{
"status": "ok",
"data": {
"response": "subscriber_updated",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487661494
}
Confirm referral
https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/confirm
Confirm a referral. Useful when your campaign has enabled the "Manual confirmation" option and you want to confirm referrals when a specific event occur (e.g: upgrade to a paid plan, end of trial, etc)
Note: only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a subscriber_not_found
error.
{
"status": "ok",
"data": {
"response": "subscriber_confirmed",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487661494
}
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.
{
"status": "ok",
"data": {
"response": "subscriber_promoted",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487661494
}
Retrieve all referrals of a subscriber
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
The ID of the subscriber.
Page you want to jump to. By default is 1.
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
}
Delete a subscriber
https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id
Delete a single subscriber.
{
"status": "ok",
"data": {
"response": "subscriber_deleted",
< Subscriber object >
},
"calls_left": 1000,
"timestamp": 1487661494
}