Referral Link API

This is the main API to interact with referral links.

Referral Link Object

Name
id
Type
int
Description
The unique referral link id.
Name
created_at
Type
string
Description
Date of creation of referral link, in the format "Year-Month-Day_Hour-Minute-Seconds".
Name
referral_code
Type
string
Description
Unique code associated with referral link.
Name
campaign_id
Type
string
Description
The ID of the camapaign associated with the referral link.
Name
referrer_id
Type
string or none
Description
ID of the user to which the referral link belongs to, if any.
Name
referral_link
Type
string or none
Description
The Link of the referral, comprised of Campaign URL and Referral Code.
Name
total_clicks
Type
int
Description
Total actions associated with the referral link.
Name
total_referrals
Type
int
Description
Total referred users associated with the referral link.

Referral Link Object Example

  {
    "id": 1,
    "created_at": "2023-09-11_03-33-06",
    "referral_code": "ABC623KC",
    "campaign_id": "3a6a4dd0-1055-4c3c-a531-7036793e10ee",
    "referrer_id": "user@gmail.com",
    "total_clicks" : 0,
    "total_referrals": 0,
    "referral_link": "https://example.com?rfa=ABC623KC"
  }

POST/api/v1/referral_link

Create a Referral Link

Required attributes

Name
campaign_id
Type
string
Description
The Referral Link you create has to be associated with a campaign. Use the UUID from your Campaign creation API or from your dashboard.

Optional attributes

Name
referrer_id
Type
string
Description
You can associate the Referral link with any arbitary value based on your internal representation, that uniquely identifies user of your website. Within a camapaign, a referrer_id, could be associated with multiple referral links.

Response

The response is a Referral Link object as shown in the response. The full URL of your referral link is the url from your Campaign and the referral_code from our API.

Request

POST

/api/v1/signup

curl --request POST \
  --url https://api.referralapi.com/api/v1/referral_link \
  --header 'Content-Type: application/json' \
  --header 'api-key: 1968aa57ccd72d208dbac95d6679e6389ecfd60e59f31163506474a9c766fb6d' \
  --data '{
    "campaign_id": "3a6a4dd0-1055-4c3c-a531-7036793e10ee",
    "referrer_id": "user@gmail.com"
  }'

Link Response Example

{
  "id": 1,
  "created_at": "2023-09-11_03-33-06",
  "referral_code": "ABC623KC",
  "campaign_id": "3a6a4dd0-1055-4c3c-a531-7036793e10ee",
  "referrer_id": "user@gmail.com",
  "total_clicks" : 0,
  "total_referrals": 0,
  "referral_link": "https://example.com?rfa=ABC623KC"
}

GET/api/v1/referral_link

Get a Referral Link

Optional attributes

Name
id
Type
string
Description
The ID of the referral link as returned by ReferralAPI originally
Name
referral_code
Type
string
Description
The referral code of the referral link as returned by ReferralAPI originally

Response

The response is a link object, as shown in the response.

Request

GET

/api/v1/referral_link

curl --request GET \
  --url https://api.referralapi.com/api/v1/referral_link?id=12\
  --header 'Content-Type: application/json' \
  --header 'api-key: 1968aa57ccd72d208dbac95d6679e6389ecfd60e59f31163506474a9c766fb6d'

Link Response Example

{
  "id": 1,
  "created_at": "2023-09-11_03-33-06",
  "referral_code": "ABC623KC",
  "campaign_id": "3a6a4dd0-1055-4c3c-a531-7036793e10ee",
  "referrer_id": "user@gmail.com",
  "total_clicks" : 0,
  "total_referrals": 0,
  "referral_link": "https://example.com?rfa=ABC623KC"
}

GET/api/v1/campaign_referral_links/<campaign_id>

Get all Referral Links from a Campaign

Required attributes

Name
campaign_id
Type
string
Description
The ID of the campaign as returned by ReferralAPI originally

Response

The response is an array of referral link objects that are part of that particular campaign.

Request

GET

/api/v1/campaign_referral_links/<campaign_id>

curl --request GET \
  --url https://api.referralapi.com/api/v1/campaign_referral_links/3a6a4dd0-1055-4c3c-a531-7036793e10ee\
  --header 'Content-Type: application/json' \
  --header 'api-key: 1968aa57ccd72d208dbac95d6679e6389ecfd60e59f31163506474a9c766fb6d'

Link Response Example

[
  {
    "id": 1,
    "created_at": "2023-09-11_03-33-06",
    "referral_code": "ABC623KC",
    "campaign_id": "3a6a4dd0-1055-4c3c-a531-7036793e10ee",
    "referrer_id": "user@gmail.com",
    "total_clicks" : 4,
    "total_referrals": 0,
    "referral_link": "https://example.com?rfa=ABC623KC"
  },
  {
    "id": 2,
    "created_at": "2023-09-12_03-33-06",
    "referral_code": "JDE872399",
    "campaign_id": "3a6a4dd0-1055-4c3c-a531-7036793e10ee",
    "referrer_id": "",
    "total_clicks" : 3,
    "total_referrals": 3,
    "referral_link": "https://example.com?rfa=JDE872399C"
  }
]

GET/api/v1/referral_link/<campaign_id>/<referrer_id>

Get all Referral Links for a campaign corresponding to an referrer_id

Required attributes

Name
campaign_id
Type
string
Description
The ID of the campaign as returned by the ReferralAPI API originally
Name
referrer_id
Type
string
Description
The referrer_id of the user whose referral link(s) are required to be fetched

Response

The response is a list of referral link object(s), as shown in the response.

Request

GET

/api/v1/referral_link/<campaign_id>/<referrer_id>

curl --request GET \
  --url https://api.referralapi.com/api/v1/referral_link/3a6a4dd0-1055-4c3c-a531-7036793e10ee/user@gmail.com\
  --header 'Content-Type: application/json' \
  --header 'api-key: 1968aa57ccd72d208dbac95d6679e6389ecfd60e59f31163506474a9c766fb6d'

Link Response Example

[{
  "id": 1,
  "created_at": "2023-09-11_03-33-06",
  "referral_code": "ABC623KC",
  "campaign_id": "3a6a4dd0-1055-4c3c-a531-7036793e10ee",
  "referrer_id": "user@gmail.com",
  "total_clicks" : 3,
  "total_referrals": 3,
  "referral_link": "https://example.com?rfa=ABC623KC"
}]