Home Login/Signup Pricing Examples

Public Methods

Add a Subscriber

POST https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers

Request Body

NameTypeDescription

email*

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

name

String

The name of the subscriber

crypto_wallet_address*

String

The crypto wallet address. Required if it is the unique identifier for the campaign.

phone_number*

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

extra_field

String

The extra field value of the subscriber

extra_field_2

String

The extra field 2 value of the subscriber

referrer

String

The referral code or email of the referrer

lifetime_spend

Number

Lifetime spend of the subscriber

subscribe_page_url

String

Subscribe Page URL of the Subscriber

landing_page_url

String

Landing Page URL of the Subscriber

is_quick_add_referral

Boolean

Send True only if you want to add the referral as Quick Add Referral otherwise False

option_field_value

String

Option field value of the subscriber

other_identifier_value*

String

The other identifier value (Required if other identifier enabled as unique identifier)

double_optin

Boolean

Send True if you want to send verification method before adding otherwise False

points

Integer

Points of the subscriber

crypto_wallet_provider

String

The crypto wallet provider

screen_size

String

The screen size of device used by subscriber when the referral link was clicked

ip_address

String

The IP address used by subscriber when the referral link was clicked

device

String

The device used by subscriber when the referral link was clicked

os_type

String

The Type of Operating system used by subscriber when the referral link was clicked

source

String

The source of the subscriber.

hosting_url

String

URL used to generate the referral link.

transaction_id

String

The unique ID of the transaction. Useful when tracking purchases.

conversion_category

String

The type of subscriber. Useful for creating reports or segmenting subscribers.

conversion_value

Number

The monetary conversion value of the subscriber

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxxxxxxxxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");


var raw = JSON.stringify({
 "email": "test24@gmail.com",
 "name": "Test User 24",
 "phone_number": "9898989896",
 "extra_field": "some extra data",
 "extra_field_2": "some more extra data",
 "referrer": "",
 "conversion_value": 0,
 "conversion_category": "",
 "transaction_id": "",
 "os_type": "Android",
 "device": "Android",
 "ip_address": "127.0.0.1",
 "screen_size": "1920.0 x 1080.0",
 "hosting_url": "https://app.referralhero.com/dashboard/lists/MF83c9616aa3/analytics/traffic",
 "crypto_wallet_address": "",
 "crypto_wallet_provider": "",
 "points": 22,
 "double_optin": false,
 "other_identifier_value": "",
 "option_field_value": "",
 "is_quick_add_referral": true,
 "landing_page_url": "",
 "subscribe_page_url": "",
 "lifetime_spend": ""
});

var requestOptions = {
 method: 'POST',
 headers: myHeaders,
 body: raw,
 redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/MF4345c63888/subscribers", requestOptions)
 .then(response => response.json())
 .then(result => console.log(result))
 .catch(error => console.log('error', error));

Update Subscriber Details

PATCH https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id

This method is used to update various user-related data like username, address, etc. Request parameters are the same as before in the Add a Subscriber API.

Required body parameters are noted below, otherwise, all other available subscriber attributes can be found above under 'Add a Subscriber'.

Request Body

NameTypeDescription

email*

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

phone_number*

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

crypto_wallet_address*

String

The crypto wallet address. Required if it is the unique identifier for the campaign.

other_identifier_value*

String

The other identifier value. Required if other identifier enabled as unique identifier.

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify({
 "email": "test102@gmail.com",
 "name": "Test name new",
 "os_type": "Ubuntu"
});

var requestOptions = {
 method: 'PATCH',
 headers: myHeaders,
 body: raw,
 redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id", requestOptions)
 .then(response => response.json())
 .then(result => console.log(result))
 .catch(error => console.log('error', error));

Get Subscriber Details

GET https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id

This method is used to get the details of a particular subscriber.

Path Parameters

NameTypeDescription

subscriber_id*

String

The ID of the subscriber.

var myHeaders = new Headers();
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "xxxxxxxxxxxxx");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/subscriber_id", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Delete Subscriber

DELETE https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id

This method is used to Delete a Subscriber.

Path Parameters

NameTypeDescription

subscriber_id*

String

The ID of the subscriber.

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
  method: 'DELETE',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Track Referral

POST https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/track_referral_conversion_event

This method is used to track the referral conversion event. It means it is used to convert Referral status from pending to unconfirmed/confirmed.

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.

Note:

1. Your campaign must be set up as a custom event or a multi-step event 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 referer 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.

Request Body

NameTypeDescription

email*

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

crypto_wallet_address*

String

The crypto wallet address. Required if crypto wallet address is the unique identifier for the campaign.

phone_number*

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value. Required if other identifier value is the unique identifier for the campaign.

  • uniqueIdentifier is a placeholder.

  • When tracking referrals on your App you should ALWAYS send the ACTUAL unique identifier (email, phone number, crypto wallet address, or other ID) of the user in referralParams class Object

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "xxxxxxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");

var raw = JSON.stringify({
  "email": "test17@gmail.com",
  "name": "Test name updated",
  "phone_number": "3289408393",
  "Crypto_wallet_address": ""
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/track_referral_conversion_event", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Capture Share

POST https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id/click_capture

This method is used with parameters like 'copy', 'sms', 'facebook', 'twitter', etc. to capture a Share Event.

Request Body

NameTypeDescription

social

facebook

To capture a 'facebook' share event.

social

twitter

To capture a 'twitter' share event.

social

linkedin

To capture a 'linkedin' share event.

social

email

To capture a 'email' share event.

social

telegram

To capture a 'telegram' share event.

social

sms

To capture a 'sms' share event.

social

copy

To capture a 'copy' share event.

social

reddit

To capture a 'reddit' share event.

social

facebook messenger

To capture a 'facebook messenger' share event.

social

whatsapp

To capture a 'whatsapp' share event.

social

line

To capture a 'line' share event.

social

pinterest

To capture a 'pinterest' share event.

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "social": "facebook"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id/click_capture", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Get My Referrals

GET https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber-id/referrals_data

This method is used for retrieving all referrals of the specific subscriber.

Path Parameters

NameTypeDescription

uuid*

String

List UUID for the campaign

subscriber-id*

String

Subscriber ID

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id/referrals_data", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Get Leaderboard

GET https://dev.referralhero.com/api/sdk/v1/lists/:uuid/leaderboard

This method is used for retrieving the campaign leaderboard.

Path Parameters

NameTypeDescription

uuid*

String

List UUID for the campaign

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
  method: 'GET',
  headers: myHeaders
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/MFb1f0135c55/leaderboard", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Pending Referral

POST https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/pending_referral

This method is used for creating the Referral with the Pending Status.

The Unique Identifier is the only required body parameter, otherwise, all other available subscriber attributes can be found above under 'Add a Subscriber'.

Request Body

NameTypeDescription

email

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

phone_number

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

crypto_wallet_address

String

The crypto wallet address of the subscriber. Required if crypto wallet address is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value of the subscriber. Required if other identifier value is the unique identifier for the campaign.

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Authorization", "xxxxxxxxxxxxxxxxxx");

var raw = JSON.stringify({
  "name": "Pending Referral",
  "os_type": "IOS",
  "ip_address": "123.456.789.0123",
  "screen_size": "64*32",
  "device": "IOS",
  "email": "testpending1@email.com",
  "Phone_nubmer": "",
  "Cryoto_wallet_address": "",
  "referrer": "8f01d5db",
  "hosting_url": "https://app.referralhero.com"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/pending_referral", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Organic Track Referral

POST https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/organic_track_referral

If you would like to track referrals or add organic subscribers on the conversion page to your referral campaign, you can use this method.

If the Referrer code and uniqueidentifier are present, a Referral is created with the status unconfirmed/confirmed referral on the basis of the ‘Review Referral’ feature enabled/disabled.

If the Referrer code is not present but uniqueidentifier is present, an Organic Subscriber is created.

If the Referrer code is not present but a uniqueidentifier is present and a Referral already exists with the same uniqueidentifier in the campaign with pending status, the Referral Status will convert from pending to unconfirmed/confirmed on the basis of the ‘Review Referral’ feature enabled/disabled.

The Unique Identifier is the only required body parameter, otherwise, all other available subscriber attributes can be found above under 'Add a Subscriber'.

Request Body

NameTypeDescription

email

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

phone_number

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

crypto_wallet_address

String

The crypto wallet address of the subscriber. Required if crypto wallet address is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value of the subscriber. Required if other identifier value is the unique identifier for the campaign.

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Authorization", "xxxxxxxxxxxx");

var raw = JSON.stringify({
  "email": "testorganic1@gmail.com",
  "name": "Test organic User1",
  "hosting_url": "https://app.referralhero.com/dashboard/lists/:uuid/analytics/traffic",
  "referrer": "2c2dbefb"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/organic_track_referral", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Confirm Referral

POST https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id/confirm

Confirm a referral. Useful when your campaign has enabled the "Manual Review & Confirm" feature and you want to confirm referrals when a specific event occurs.

Note: only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a subscriber_not_found error.

Request Body

NameTypeDescription

email

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value of the subscriber. Required if other identifier value is the unique identifier for the campaign.

crypto_wallet_address

String

The crypto wallet address of the subscriber. Required if crypto wallet address is the unique identifier for the campaign.

phone_number

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Authorization", "xxxxxxxxxxxxx");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id/confirm", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Get Referrer

GET https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/referrer

Use this method to get Referrer data.

Path Parameters

NameTypeDescription

uuid*

String

List UUID for the campaign

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxxxxx");
myHeaders.append("Accept", "application/vnd.referralhero.v1");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "os_type": "ios",
  "devise": "device",
  "ip_address": "192.168.0.1",
  "screen_size": "1200x1800"
});


var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/referrer", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Get Rewards

GET https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/:subscriber_id/rewards

Use this method to Get Rewards unlocked by a specific subscriber.

Path Parameters

NameTypeDescription

uuid*

String

List UUID for the campaign

subscriber-id*

String

Subscriber ID

var myHeaders = new Headers();
myHeaders.append("Authorization", "xxxxxxxxxxxxxxxx");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/vnd.referralhero.v1");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://dev.referralhero.com/api/sdk/v1/lists/:uuid/subscribers/sub_bfdc2b6e2f7e/rewards", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
PreviousGetting Started

Last updated