Installation

Let's imagine we have a web application called "AwesomeApp" and we want to implement a referral program using Referral-API.

Step 1: Integrating the Referral-API with your backend

This step is entirely optional. You don't need to integrate referral-api with your backend to utilize its functionalities effectively. The Referral-API provides comprehensive client-side script and package that empower you to perform all necessary actions directly from your client-side code.

Assuming we have a Python backend for our application, we would require the requests package to make calls to the Referral-API’s API.

Before we can start using Referral-API’s API, we need to obtain an API key. This key will be used for authentication in our API requests. To obtain the API-Key we would first need to sign up for Referral-API. You can read more about obtaining API Key here.

import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://api.referralapi.com'

Step 2: Creating a Referral Campaign

Campaigns in the context of Referral-API are like themed events or promotions within your referral program. For example, you could run a "Summer Referral Bonanza" campaign offering $10 off for each successful signup referral during the summer season as well as $20 for every successful purchase made by the referred user. By creating campaigns, you can tailor your referral program to suit different marketing objectives and engage users in a more personalized way.

A campaign is defined by a URL and an internal name. Every referral link generated within a campaign will direct users to the URL used to create a campaign. We can create campaign using API as well as from the dashboard. Using dashboard:

1. Go to the dashboard
2. Click on the Create New Campaign Button
3. Enter the internal name of the campaign and the URL for it, and create campaign using Submit Button.

Using API:

def create_campaign(name, reward):
    url = f'{BASE_URL}/campaign'
    headers = {'api-key': API_KEY}
    payload = {'name': ‘Summer Referral Bonanza’ , 'url': “www.awesomeapp.com”}
    response = requests.post(url, headers=headers, json=payload)
    campaign_id = response.json()['id']
    return campaign_id

We can always get this campaign_id from the dashboard under the installation section. Great, now that we have a campaign in place for our awesomeapp, let us checkout how users can create and share referral links.

Step 3: Creating Referral Links

You can skip this step if you wish to create referral links on client side directly using our script/package. This step provides you with the option to create referral links using either the API directly or through the dashboard interface.

Now that we have the “Summer Referral Bonanza” up and running, it's time to rally our existing users and showcase the fantastic rewards awaiting them through our referral program. We envision a dedicated section on our awesomeapp website, prominently displaying alluring details about the campaign. With a compelling call-to-action, users can effortlessly generate their unique referral links and start sharing the excitement with friends and family.

When the user clicks on the button to generate their referral-link, we would make a call to our Referral-API’s API, to generate a unique referral link for them. While generating this link, we have the option to include an unique id i.e. referrer_id of the user as an attribute, this could be any arbitary string. Leveraging this field not only streamlines the process but also eliminates the need to manually track and associate each referral link with its respective owner. Referral-API allows an referrer_id to be linked with multiple referral links within a campaign.

def generate_referral_link(campaign_id, referrer_id):
    url = f'{BASE_URL}/referral_link'
    headers={'api-key': API_KEY}
    payload = {'referrer_id': referrer_id, 'campaign_id' : campaign_id}
    response = requests.post(url, headers=headers, json=payload)
    referral_link = response.json()['referral_link']
    return referral_link

We can also create referral links from the dashboard by following the following steps:

1. From the dashboard, navigate to the campaign of choice
2. Click on the create Referral Link button
3. It will prompt you to associate a link it with a user providing a user id, you can add one or skip, it is totally optional.
4. Finally click on create Referral Link to create a referral link

Next Steps

Depending on which platform you are using, you can integrate our API into your application in a few different ways.

• Web Script
• NPM Package
• API

To comprehensively capture website visits via referral links, record conversions, and track diverse user actions, leverage our versatile tools such as Web Script/NPM Package tailored to your specific tech stack. Additionally, for scenarios where certain actions, like subscription processing, require backend tracking due to their sensitive nature, seamlessly integrate our Action API to initiate calls from the server-side.