> ## Documentation Index
> Fetch the complete documentation index at: https://doc.trackrev.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Referrals
> Enroll a user as a referrer and report referred signups — the API behind product-led referral programmes.
These two endpoints drive [product-led referrals](/affiliate/referral-widget): 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
```bash cURL theme={null}
curl -X POST "https://app.trackrev.io/api/v1/referrals/enroll" \
-H "Authorization: Bearer " \
-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)`.
The user's email.
Your stable user id.
`free` or `paid` — sets the reward amount.
Target a specific programme; defaults to your most recent one.
The user's name.
A device fingerprint, used for self-referral checks.
The user's shareable referral URL.
The enrollment status (auto-approved for referrals).
```json Response theme={null}
{
"partner_id": "pa1...",
"program_id": "p1...",
"referral_link": "https://acme.trackrev.io/user-123",
"status": "approved"
}
```
## Report a signup
```bash cURL theme={null}
curl -X POST "https://app.trackrev.io/api/v1/referrals/report-signup" \
-H "Authorization: Bearer " \
-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.
The new user's id.
The new user's email.
The new user's device fingerprint (for self-referral checks).
The referrer's link slug — the primary way to resolve who referred them.
A visitor id — resolves the referrer from the most recent click if no `ref_code`.
Name the referrer explicitly.
The referrer is resolved in order: `ref_code` → `_vid` → `referrer_external_user_id`. TrackRev runs
[self-referral checks](/affiliate/fraud-detection); blocked grants are recorded as revoked and no
reward webhook fires.
Whether a referrer was found.
Whether the reward was blocked as a self-referral.
```json Response theme={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.