pk_) or secret (lk_) key, so they’re safe to call from the
browser.
Enroll a referrer
POST /api/v1/referrals/enroll — enroll a user as a referrer and mint their referral link.
Idempotent on (workspace, external_user_id).
string
required
The user’s email.
string
required
Your stable user id.
string
required
free or paid — sets the reward amount.string
Target a specific programme; defaults to your most recent one.
string
The user’s name.
string
A device fingerprint, used for self-referral checks.
string
string
string
The user’s shareable referral URL.
string
The enrollment status (auto-approved for referrals).
Report a signup
POST /api/v1/referrals/report-signup — tell TrackRev that a referred user signed up, so the
referrer earns their reward. Idempotent per new user.
string
required
The new user’s id.
string
The new user’s email.
string
The new user’s device fingerprint (for self-referral checks).
string
The referrer’s link slug — the primary way to resolve who referred them.
string
A visitor id — resolves the referrer from the most recent click if no
ref_code.string
Name the referrer explicitly.
ref_code → _vid → referrer_external_user_id. TrackRev runs
self-referral checks; blocked grants are recorded as revoked and no
reward webhook fires.
boolean
Whether a referrer was found.
string
string
boolean
Whether the reward was blocked as a self-referral.
string | null
If no referrer matches, the response is
{ "matched": false } with a 200 status — a signup with
no referrer isn’t an error.Get referral stats
GET /api/v1/referrals/stats — a user’s referral link, windowed stats, lifetime rewards and a
daily series. This is the endpoint behind the dashboard embed.
Auto-enrolls the user if they aren’t a referrer yet (idempotent — same as
enroll).
string
required
The user’s id in your system.
string
The user’s email. Recommended — used as the partner identity.
string
default:"free"
free or paid — decides which credit amount applies.number
default:"30"
The stats window in days,
7–90.string
string
string
The enrollment status (auto-approved for referrals).
string
The user’s shareable referral URL.
number
The window the
stats and series cover.object
clicks, signups, purchases and conversion_rate over the selected window.object
All-time rewards:
cash (currency, pending, paid, total, in major currency units —
e.g. dollars) and credits
(per kind: earned, delivered, pending).array
One entry per day in the window:
day, clicks, signups, purchases.string
How this user is currently rewarded:
referrer (credits) or affiliate (cash commissions).
See Set the reward mode.object
Affiliate-mode details:
allowed (whether the program offers the upgrade), min_payout
(major currency units, same as lifetime.cash), payout_method ({ method, paypal_email } or null),
recent_commissions (date, type, amount, earnings, status) and payouts
(date, amount, status).Errors use the standard envelope — e.g.
401 unauthorized for a missing
or invalid key, 400 bad_request for invalid parameters such as a missing external_user_id.Set the reward mode
POST /api/v1/referrals/reward-mode — switch a user between referrer mode (earn credits)
and affiliate mode (earn cash commissions at the program’s commission rate). Powers the
toggle in the dashboard embed. The switch
affects future conversions only — credits already earned are kept — and is reversible.
string
required
The user’s id in your system.
string
required
referrer or affiliate.string
string
string
The mode now in effect.
Errors use the standard envelope —
403 forbidden when the program
doesn’t allow the affiliate upgrade, 400 bad_request for an invalid mode or missing
external_user_id.Set the payout method
POST /api/v1/referrals/payout-method — save where an affiliate-mode user gets paid. Only
accepted while the enrollment is in affiliate mode (403 forbidden otherwise).
string
required
The user’s id in your system.
string
required
The payout method, e.g.
paypal.string
The PayPal address to pay, when
method is paypal.string
string
string