Referrals

These two endpoints drive product-led referrals: enroll each user as a referrer, then tell TrackRev when a referred person signs up so the inviter earns their reward. Both accept a publishable (pk_) or secret (lk_) key, so they’re safe to call from the browser.

Enroll a referrer

curl -X POST "https://app.trackrev.io/api/v1/referrals/enroll" \
  -H "Authorization: Bearer <pk_ or lk_ key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "external_user_id": "USER_123",
    "tier": "paid"
  }'

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.

external_user_id

string

required

Your stable user id.

tier

string

required

free or paid — sets the reward amount.

program_id

string

Target a specific programme; defaults to your most recent one.

name

string

The user’s name.

device_id

string

A device fingerprint, used for self-referral checks.

partner_id

string

program_id

string

referral_link

string

The user’s shareable referral URL.

status

string

The enrollment status (auto-approved for referrals).

{
  "partner_id": "pa1...",
  "program_id": "p1...",
  "referral_link": "https://acme.trackrev.io/user-123",
  "status": "approved"
}

curl -X POST "https://app.trackrev.io/api/v1/referrals/report-signup" \
  -H "Authorization: Bearer <pk_ or lk_ key>" \
  -H "Content-Type: application/json" \
  -d '{
    "new_user_external_user_id": "USER_456",
    "email": "friend@example.com",
    "ref_code": "user-123"
  }'

POST /api/v1/referrals/report-signup — tell TrackRev that a referred user signed up, so the referrer earns their reward. Idempotent per new user.

new_user_external_user_id

string

required

The new user’s id.

string

The new user’s email.

device_id

string

The new user’s device fingerprint (for self-referral checks).

ref_code

string

The referrer’s link slug — the primary way to resolve who referred them.

_vid

string

A visitor id — resolves the referrer from the most recent click if no ref_code.

referrer_external_user_id

string

Name the referrer explicitly.

The referrer is resolved in order: ref_code → _vid → referrer_external_user_id. TrackRev runs self-referral checks; blocked grants are recorded as revoked and no reward webhook fires.

matched

boolean

Whether a referrer was found.

program_id

string

partner_id

string

blocked

boolean

Whether the reward was blocked as a self-referral.

block_reason

string | null

{ "matched": true, "program_id": "p1...", "partner_id": "pa1...", "blocked": false, "block_reason": null }

If no referrer matches, the response is { "matched": false } with a 200 status — a signup with no referrer isn’t an error.

API Reference

Endpoints

Events & embeds

Enroll a referrer

​Enroll a referrer

​Report a signup

Enroll a referrer

Report a signup