> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winnerr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Referrals

> Capture referrals from the public profile, record them in a per-referral ledger, and re-enter the pipeline as a new lead.

Referrals close the Reputation Studio flywheel. Where surveys and testimonials feed reputation **outward**, the `Referral` record captures the lead that comes **back in** — and ties it to the resulting deal so you can attribute revenue to the original advocate.

A `Referral` is the per-referral ledger Winnerr was missing. The legacy `Person.totalReferrals` counter is still maintained as a cache, but `Referral` is now the source of truth: who referred whom, through which channel, what reward was offered, and which `Deal` the referral eventually produced.

## Where referrals come from

| Channel           | Source                                                                        |
| ----------------- | ----------------------------------------------------------------------------- |
| `TESTIMONIAL_CTA` | The referral form on the agent's public reputation profile (testimonial CTA). |
| `WIDGET`          | The embedded reviews widget on the agent's site.                              |
| `DIRECT`          | Shared directly by the agent or captured via a direct link.                   |
| `PORTAL`          | Captured through a client portal.                                             |
| `MANUAL`          | Logged in-app by the agent.                                                   |

## Public capture endpoint

The public profile and widget post submissions to a single CORS-friendly endpoint:

```text theme={null}
POST /api/public/referral/:agentSlug
```

The endpoint:

* Resolves the org and agent server-side from the published profile slug. Anything else returns a uniform `404`.
* Creates a `Person` for the referrer with `source: REFERRAL` and `relationshipStage: ADVOCATE`.
* Creates a `Referral` row with `status: RECEIVED` and the resolved `agentUserId`.
* Emits `REFERRAL_RECEIVED`, which fires the workflow that re-enters the new lead at the top of the pipeline.
* Rate-limits the request to 20 per minute and caps the body at 32 KB; all client strings are treated as data, validated with Zod.

Example submission:

```bash theme={null}
curl -X POST https://api.winnerr.ai/api/public/referral/jane-doe-realty \
  -H "Content-Type: application/json" \
  -d '{
    "referrerName": "Pat Jones",
    "referrerEmail": "pat@example.com",
    "referredName": "Sam Lee",
    "referredContact": { "email": "sam@example.com" },
    "notes": "Sam is selling their condo this spring."
  }'
```

No auth required — the published profile slug is the capability.

## Lifecycle

| Status        | Meaning                                                                      |
| ------------- | ---------------------------------------------------------------------------- |
| `RECEIVED`    | Captured from the public endpoint or logged manually. Awaiting agent triage. |
| `CONTACTED`   | Agent has reached out to the referred person.                                |
| `QUALIFIED`   | The referred lead has been qualified.                                        |
| `CLOSED_WON`  | The referral produced a closed deal (recorded on `resultingDealId`).         |
| `CLOSED_LOST` | The referred lead did not convert.                                           |
| `DECLINED`    | Referral declined or withdrawn.                                              |

When the referral converts, set `resultingDealId` so the referral is tied to actual revenue and the original advocate shows up in attribution reports.

## What's on a Referral

| Field                                       | Purpose                                                                                   |
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `referrerPersonId`                          | The advocate who sent the referral.                                                       |
| `referredPersonId`                          | The new lead (linked once they become a `Person`).                                        |
| `referredName`, `referredContact`           | Raw captured fields, used before linking to a Person.                                     |
| `agentUserId`                               | The agent the referral was sent to.                                                       |
| `channel`                                   | Where the referral came from (`TESTIMONIAL_CTA`, `WIDGET`, `DIRECT`, `PORTAL`, `MANUAL`). |
| `resultingDealId`                           | The `Deal` that closed from this referral.                                                |
| `resultingLeadSource`                       | Defaults to `REFERRAL` on the new lead.                                                   |
| `rewardType`, `rewardStatus`, `rewardValue` | Optional reward tracking (e.g. `gift_card`, `commission_share`).                          |
| `notes`                                     | Free-form context.                                                                        |

## Managing referrals

List and create referrals via the [authenticated API](/api-reference/reputation#referrals):

```bash theme={null}
# List the calling org's referrals
curl https://api.winnerr.ai/api/reputation/referrals?status=RECEIVED \
  -H "Authorization: Bearer $TOKEN"

# Log a referral manually
curl -X POST https://api.winnerr.ai/api/reputation/referrals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referrerPersonId": "person_111",
    "agentUserId": "user_789",
    "channel": "MANUAL",
    "referredName": "Sam Lee",
    "notes": "Sam is selling their condo this spring.",
    "status": "RECEIVED"
  }'
```

## Closing the loop

When a referral is captured publicly:

1. `Referral` is created with `status: RECEIVED`.
2. `REFERRAL_RECEIVED` is emitted.
3. The downstream workflow creates or updates a `Person` for the referred lead with `LeadSource.REFERRAL`.
4. The new `Person` enters the pipeline at the lead stage like any other inbound lead — visible in [People](/crm/people) and routed through your existing automations.
5. When that lead's deal closes, set `Referral.resultingDealId` and `Referral.status = CLOSED_WON` so revenue attributes back to the advocate.

That last write — referral → resulting deal — is what turns Reputation Studio from a review tool into a revenue tool: every closed deal you can attribute to a prior `Referral` is a closing the flywheel produced.

## Referral rewards

When a referral's linked deal is won, Winnerr notifies the agent that a reward is ready to send. The agent fulfills it out of band and marks it sent from the Rewards queue, at which point the referrer is automatically thanked by email or SMS (consent-gated, per the org's reward policy).

See [Referral rewards](/reputation/rewards) for the full guide.

## Related

* [Overview](/reputation/overview) — the full reputation flywheel.
* [Public profile](/reputation/public-profile) — the surface the referral CTA lives on.
* [Referral rewards](/reputation/rewards) — reward queue and auto-thank policy.
* [Reputation API — referrals](/api-reference/reputation#referrals) — authenticated CRUD.
* [Public referral endpoint](/api-reference/reputation#public-endpoints) — token-less public capture.