Referrals

Record Referral

POST /v1/campaigns/{slug}/referrals

Records a referral event. When a new user signs up using another user’s referral code, both the referrer and referee earn configured rewards.

Authentication

Header	Required	Value
X-API-Secret	Yes	Your secret key
Content-Type	Yes	application/json

Request Body

Field	Type	Required	Description
referrerId	string	Yes	User ID of the person who shared the referral
refereeId	string	Yes	User ID of the new user who was referred
referralCode	string	Yes	The referral code used

Request Examples

cURL

curl -X POST https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals \
  -H "X-API-Secret: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "referrerId": "user_alice",
    "refereeId": "user_bob",
    "referralCode": "ALICE2025"
  }'

JavaScript

const response = await fetch(
  'https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals',
  {
    method: 'POST',
    headers: {
      'X-API-Secret': 'sk_live_your_secret_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      referrerId: 'user_alice',
      refereeId: 'user_bob',
      referralCode: 'ALICE2025',
    }),
  }
);

const data = await response.json();
console.log(`Referrer gets ${data.data.referrerReward} pts, referee gets ${data.data.refereeReward} pts`);

Python

import requests

response = requests.post(
    "https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals",
    headers={
        "X-API-Secret": "sk_live_your_secret_key",
        "Content-Type": "application/json",
    },
    json={
        "referrerId": "user_alice",
        "refereeId": "user_bob",
        "referralCode": "ALICE2025",
    },
)

data = response.json()
print(f"Referrer: {data['data']['referrerReward']} pts, Referee: {data['data']['refereeReward']} pts")

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

String body = """
    {
        "referrerId": "user_alice",
        "refereeId": "user_bob",
        "referralCode": "ALICE2025"
    }
    """;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals"))
    .header("X-API-Secret", "sk_live_your_secret_key")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Go

payload := strings.NewReader(`{
    "referrerId": "user_alice",
    "refereeId": "user_bob",
    "referralCode": "ALICE2025"
}`)

req, _ := http.NewRequest("POST", "https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals", payload)
req.Header.Set("X-API-Secret", "sk_live_your_secret_key")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

PHP

$ch = curl_init('https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Secret: sk_live_your_secret_key',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'referrerId' => 'user_alice',
        'refereeId' => 'user_bob',
        'referralCode' => 'ALICE2025',
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Referrer: {$data['data']['referrerReward']} pts, Referee: {$data['data']['refereeReward']} pts\n";

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals')
req = Net::HTTP::Post.new(uri)
req['X-API-Secret'] = 'sk_live_your_secret_key'
req['Content-Type'] = 'application/json'
req.body = {
  referrerId: 'user_alice',
  refereeId: 'user_bob',
  referralCode: 'ALICE2025'
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts "Referrer: #{data['data']['referrerReward']} pts"

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Secret", "sk_live_your_secret_key");

var content = new StringContent(
    JsonSerializer.Serialize(new {
        referrerId = "user_alice",
        refereeId = "user_bob",
        referralCode = "ALICE2025"
    }),
    Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals", content);
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Dart

import 'dart:convert';
import 'package:http/http.dart' as http;

final response = await http.post(
  Uri.parse('https://api.gamifyhost.com/v1/campaigns/summer-promo/referrals'),
  headers: {
    'X-API-Secret': 'sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'referrerId': 'user_alice',
    'refereeId': 'user_bob',
    'referralCode': 'ALICE2025',
  }),
);

final data = jsonDecode(response.body);
print('Referrer: ${data['data']['referrerReward']} pts');

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "referrerReward": 200,
    "refereeReward": 100,
    "message": "Referral recorded successfully"
  }
}

---

Get Referral Code

GET /v1/campaigns/{slug}/referral-code/{userId}

Returns a user’s unique referral code for the campaign. If the user doesn’t have one yet, it is generated automatically.

Authentication

Header	Required	Value
X-API-Secret	Yes	Your secret key

Request Examples

cURL

curl -X GET "https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/user_alice" \
  -H "X-API-Secret: sk_live_your_secret_key"

JavaScript

const userId = 'user_alice';

const response = await fetch(
  `https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/${userId}`,
  {
    headers: { 'X-API-Secret': 'sk_live_your_secret_key' },
  }
);

const data = await response.json();
console.log(`Referral code: ${data.data.referralCode}, ${data.data.referralCount} referrals`);

Python

import requests

user_id = "user_alice"

response = requests.get(
    f"https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/{user_id}",
    headers={"X-API-Secret": "sk_live_your_secret_key"},
)

data = response.json()
print(f"Code: {data['data']['referralCode']}, {data['data']['referralCount']} referrals")

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

String userId = "user_alice";

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/" + userId))
    .header("X-API-Secret", "sk_live_your_secret_key")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Go

userId := "user_alice"
url := fmt.Sprintf("https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/%s", userId)

req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("X-API-Secret", "sk_live_your_secret_key")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

PHP

$userId = 'user_alice';

$ch = curl_init("https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/{$userId}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Secret: sk_live_your_secret_key',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Code: {$data['data']['referralCode']}, {$data['data']['referralCount']} referrals\n";

Ruby

require 'net/http'
require 'json'

user_id = 'user_alice'

uri = URI("https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/#{user_id}")
req = Net::HTTP::Get.new(uri)
req['X-API-Secret'] = 'sk_live_your_secret_key'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts "Code: #{data['data']['referralCode']}, #{data['data']['referralCount']} referrals"

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Secret", "sk_live_your_secret_key");

var userId = "user_alice";
var response = await client.GetAsync(
    $"https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/{userId}");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Dart

import 'dart:convert';
import 'package:http/http.dart' as http;

const userId = 'user_alice';

final response = await http.get(
  Uri.parse('https://api.gamifyhost.com/v1/campaigns/summer-promo/referral-code/$userId'),
  headers: {'X-API-Secret': 'sk_live_your_secret_key'},
);

final data = jsonDecode(response.body);
print('Code: ${data['data']['referralCode']}, ${data['data']['referralCount']} referrals');

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "referralCode": "ALICE2025",
    "referralCount": 5,
    "totalRewardsEarned": 1000
  }
}

Errors

Code	Message
400	Self-referral not allowed
400	User has already been referred
404	Campaign or user not found