API Endpoints

Server-side referral tracking endpoints

On this page

Referral API Endpoints

If you prefer server-side referral tracking (or need it for backend-only integrations), you can call these endpoints directly instead of using the JavaScript tracking script.

All referral endpoints support CORS and do not require API key authentication.

Validate Referral Code

GET/api/referral/validate-code
No authentication required

Check if a referral code is valid and retrieve information about the referrer.

Query Parameters

codestring required

The referral code to validate

contestIdstring required

The contest identifier

Request

curl -X GET "https://blitzrocket.com/api/referral/validate-code?code=REF-XYZ789&contestId=clx1abc123"

const params = new URLSearchParams({
  code: "REF-XYZ789",
  contestId: "clx1abc123",
});

const response = await fetch(
  `https://blitzrocket.com/api/referral/validate-code?${params}`
);

const data = await response.json();
if (data.valid) {
  console.log(`Referred by: ${data.referrerName || data.referrerEmail}`);
}

import requests

response = requests.get(
    "https://blitzrocket.com/api/referral/validate-code",
    params={
        "code": "REF-XYZ789",
        "contestId": "clx1abc123"
    }
)

data = response.json()
if data.get("valid"):
    print(f"Referred by: {data.get('referrerName') or data.get('referrerEmail')}")

Response

{
  "valid": true,
  "referrerEmail": "[email protected]",
  "referrerName": "Jane Doe",
  "contestId": "clx1abc123"
}

Track Visit

POST/api/referral/track-visit
No authentication required

Record that someone visited your site through a referral link.

Request Body

referralCodestring required

The referral code from the URL

contestIdstring required

The contest identifier

urlstring

The page URL that was visited (optional)

Request

curl -X POST https://blitzrocket.com/api/referral/track-visit \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "REF-XYZ789",
    "contestId": "clx1abc123",
    "url": "https://yoursite.com/landing-page"
  }'

await fetch("https://blitzrocket.com/api/referral/track-visit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    referralCode: "REF-XYZ789",
    contestId: "clx1abc123",
    url: window.location.href,
  }),
});

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-visit",
    json={
        "referralCode": "REF-XYZ789",
        "contestId": "clx1abc123",
        "url": "https://yoursite.com/landing-page"
    }
)

Response

{
  "success": true
}

Track Signup

POST/api/referral/track-signup
No authentication required

Record that a referred visitor has signed up.

Request Body

emailstring required

Email address of the new signup

contestIdstring required

The contest identifier

referralCodestring required

The referral code of the person who referred them

namestring

Name of the new signup (optional)

Request

curl -X POST https://blitzrocket.com/api/referral/track-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "contestId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "name": "New User"
  }'

await fetch("https://blitzrocket.com/api/referral/track-signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    contestId: "clx1abc123",
    referralCode: "REF-XYZ789",
    name: "New User",
  }),
});

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-signup",
    json={
        "email": "[email protected]",
        "contestId": "clx1abc123",
        "referralCode": "REF-XYZ789",
        "name": "New User"
    }
)

Response

{
  "success": true,
  "data": {
    "entryId": "entry_new789",
    "isReferred": true,
    "pointsAwarded": {
      "advocate": 10,
      "friend": 5
    }
  }
}

Track Purchase

POST/api/referral/track-purchase
No authentication required

Record that a referred user has made a purchase.

Request Body

emailstring required

Email address of the purchaser

contestIdstring required

The contest identifier

orderIdstring required

Unique order identifier

amountnumber required

Purchase amount

currencystring

Currency code (default: 'USD')

referralCodestring

The referral code (optional if stored in cookie)

Request

curl -X POST https://blitzrocket.com/api/referral/track-purchase \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "contestId": "clx1abc123",
    "orderId": "order-12345",
    "amount": 99.99,
    "currency": "USD",
    "referralCode": "REF-XYZ789"
  }'

await fetch("https://blitzrocket.com/api/referral/track-purchase", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    contestId: "clx1abc123",
    orderId: "order-12345",
    amount: 99.99,
    currency: "USD",
    referralCode: "REF-XYZ789",
  }),
});

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-purchase",
    json={
        "email": "[email protected]",
        "contestId": "clx1abc123",
        "orderId": "order-12345",
        "amount": 99.99,
        "currency": "USD",
        "referralCode": "REF-XYZ789"
    }
)

Response

{
  "success": true,
  "data": {
    "purchaseId": "purchase_xyz789",
    "entryId": "entry_abc123",
    "pointsAwarded": 100,
    "message": "Purchase recorded successfully"
  }
}

Complete Server-Side Example

Here's a complete example of implementing referral tracking on your server:

const express = require("express");
const app = express();

const BLITZROCKET_BASE = "https://blitzrocket.com/api/referral";
const CONTEST_ID = process.env.CONTEST_ID;

app.post("/api/signup", async (req, res) => {
  const { email, name, referralCode } = req.body;

  // 1. Create user in your system
  const user = await createUser({ email, name });

  // 2. Track the referred signup in Blitz Rocket
  if (referralCode) {
    await fetch(`${BLITZROCKET_BASE}/track-signup`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        email,
        name,
        contestId: CONTEST_ID,
        referralCode,
      }),
    });
  }

  res.json({ success: true, user });
});

app.post("/api/purchase", async (req, res) => {
  const { email, orderId, amount, currency } = req.body;

  // 1. Process the purchase in your system
  const order = await processOrder({ email, orderId, amount });

  // 2. Track the purchase in Blitz Rocket
  await fetch(`${BLITZROCKET_BASE}/track-purchase`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email,
      contestId: CONTEST_ID,
      orderId,
      amount,
      currency,
    }),
  });

  res.json({ success: true, order });
});

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

BLITZROCKET_BASE = "https://blitzrocket.com/api/referral"
CONTEST_ID = os.environ["CONTEST_ID"]

@app.route("/api/signup", methods=["POST"])
def signup():
    data = request.get_json()
    email = data["email"]
    name = data.get("name")
    referral_code = data.get("referralCode")

    # 1. Create user in your system
    user = create_user(email=email, name=name)

    # 2. Track the referred signup in Blitz Rocket
    if referral_code:
        requests.post(
            f"{BLITZROCKET_BASE}/track-signup",
            json={
                "email": email,
                "name": name,
                "contestId": CONTEST_ID,
                "referralCode": referral_code
            }
        )

    return jsonify({"success": True, "user": user})

@app.route("/api/purchase", methods=["POST"])
def purchase():
    data = request.get_json()

    # 1. Process the purchase
    order = process_order(data)

    # 2. Track in Blitz Rocket
    requests.post(
        f"{BLITZROCKET_BASE}/track-purchase",
        json={
            "email": data["email"],
            "contestId": CONTEST_ID,
            "orderId": data["orderId"],
            "amount": data["amount"],
            "currency": data.get("currency", "USD")
        }
    )

    return jsonify({"success": True, "order": order})