Referrals.com

API Reference

Complete documentation for the Referrals.com REST API v1.

Base URL & Authentication

All API endpoints are available under two base URLs:

https://referrals.com/api/v1
https://api.referrals.com/v1

Both are identical — use whichever you prefer. Authenticate by including your API key in the X-API-Key header, or pass a JWT Bearer token from POST /v1/auth/token.

curl https://api.referrals.com/v1/members/profile \
  -H "X-API-Key: ref_your_api_key_here"

Widget Embed

Add a referral widget to any website with a single script tag. Replace 123 with your campaign ID.

<div id="referrals-widget"></div>
<script src="https://referrals.com/widget.js?campaign=123" async></script>

Or embed directly via iframe:

<iframe src="https://referrals.com/widget/123/embed"
  width="100%" height="560" style="border:0"
  allow="clipboard-write"></iframe>

The widget supports three modes — embed (inline), popup (button + modal), and floating(corner bubble) — configured in your campaign's widget settings.

Referral Tracker (whole domain)

Track referrals across an entire site with one script — no per-link edits. Add the tag to any page and set data-domain to the brand domain that should earn the credit (defaults to the current hostname).

<script src="https://www.referrals.com/referral.js"
  data-domain="garagechannel.com" async></script>

On load it appends ?ref=<data-domain> to every outbound link so the destination brand attributes the referral. On each outbound click it beacons /api/click, which logs the click against that domain's own referral campaign — so clicks and signups both show on its dashboard. Links go straight to the destination brand; no redirect hop.

Prefer to build the link yourself? Link straight to the brand and pass the referrer as ref (attributes the signup, but won't log the click):

https://www.handyman.com/?ref=garagechannel.com

Authentication

POST/api/v1/auth/token

Exchange email and password for a JWT token.

Request Body

{ "email": "user@example.com", "password": "secret" }

Response

{ "success": true, "data": { "token": "eyJ...", "member": { "id": 1, "email": "...", "name": "..." } } }

Members

POST/api/v1/members

Register a new member (public).

Request Body

{ "email": "new@example.com", "name": "Jane Doe", "password": "securepass" }

Response

{ "success": true, "data": { "id": 42, "email": "...", "name": "...", "date_signedup": "..." } }
GET/api/v1/members/profileAuth Required

Get authenticated member profile.

Response

{ "success": true, "data": { "id": 1, "email": "...", "name": "...", "plan_id": 2, ... } }
POST/api/v1/members/api-keyAuth Required

Generate a new API key.

Response

{ "success": true, "data": { "api_key": "ref_abc123...", "date_generated": "..." } }
GET/api/v1/members/api-keyAuth Required

Get current API key.

Response

{ "success": true, "data": { "api_key": "ref_abc123...", "date_generated": "..." } }

Brands

GET/api/v1/brandsAuth Required

List all brands. Supports ?page=1&limit=20.

Response

{ "success": true, "data": { "brands": [...], "pagination": { ... } } }
POST/api/v1/brandsAuth Required

Create a new brand.

Request Body

{ "url": "https://mybrand.com", "description": "My Brand" }

Response

{ "success": true, "data": { "id": 5, "url": "...", "domain": "...", ... } }
GET/api/v1/brands/:brandIdAuth Required

Get a single brand by ID.

PUT/api/v1/brands/:brandIdAuth Required

Update a brand.

Request Body

{ "description": "Updated description", "logo_url": "https://..." }
DELETE/api/v1/brands/:brandIdAuth Required

Delete a brand.

GET/api/v1/brands/:brandId/statsAuth Required

Get brand analytics (campaigns, participants, shares, clicks, impressions).

Campaigns

GET/api/v1/campaignsAuth Required

List campaigns. Filter with ?brand_id=5. Supports pagination.

POST/api/v1/campaignsAuth Required

Create a new campaign.

Request Body

{ "name": "Summer Promo", "url_id": 5, "type_id": 1, "reward_type": 1 }
GET/api/v1/campaigns/:campaignIdAuth Required

Get campaign details including widget, reward, and contest info.

PUT/api/v1/campaigns/:campaignIdAuth Required

Update a campaign.

Request Body

{ "name": "Updated Name", "publish": "public" }
DELETE/api/v1/campaigns/:campaignIdAuth Required

Delete a campaign and related records.

GET/api/v1/campaigns/:campaignId/statsAuth Required

Get campaign stats (participants, shares, clicks, impressions, daily signups).

Participants

GET/api/v1/participantsAuth Required

List participants across your campaigns. Filter with ?campaign_id=10.

GET/api/v1/participants/:participantIdAuth Required

Get participant detail with shares, rewards, and invited emails.

POST/api/v1/signupsAuth Required

Register a participant signup externally.

Request Body

{ "campaign_id": 10, "email": "participant@example.com", "name": "John" }

Webhooks

GET/api/v1/webhooksAuth Required

List registered webhooks.

POST/api/v1/webhooksAuth Required

Register a new webhook URL.

Request Body

{ "link": "https://hooks.zapier.com/...", "campaign_id": 10 }
PUT/api/v1/webhooks/:webhookIdAuth Required

Update a webhook.

DELETE/api/v1/webhooks/:webhookIdAuth Required

Delete a webhook.

Zapier Integration

POST/api/v1/zapier/authAuth Required

Validate API key for Zapier authentication test.

GET/api/v1/zapier/contactsAuth Required

Get participants for Zapier polling trigger. Filter with ?campaign_id=10.

Lander

GET/api/v1/lander?campaign_id=123Auth Required

Get lander page configuration for a campaign. Returns template, header/footer text, background settings, brand info, and social URLs.

Response

{ "success": true, "data": { "lander": { "template": "default", "header_text": "...", ... }, "brand": { "domain": "...", "logo_url": "..." }, "social_urls": [...] } }

Referral Signups

POST/api/v1/signups/referralAuth Required

Process a referral signup with a base64-encoded referral code. Tracks who referred whom and automatically processes rewards (coupon, cash, or custom message).

Request Body

{ "referral_code": "base64_encoded_string", "email": "newuser@example.com", "name": "New User" }

Response

{ "success": true, "data": { "participant": { "id": 55, ... }, "reward": { "type": "coupon", "value": "SAVE20" } } }

Referral Tracking API

GET/api/click?from=garagechannel.com&to=handyman.com

Log a whole-domain referral click (used by referral.js, also POST via sendBeacon with a JSON body or query params). Resolves `from` to its own referral campaign and increments that campaign's click count. Public, rate-limited, and fails open so it never blocks navigation.

Response

{ "ok": true, "campaignId": 16046, "participantId": 13720, "to": "handyman.com" }

Billing

GET/api/v1/billing/plans

List all available subscription plans (public endpoint).