Referrals

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:

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:

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:

# 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:

Referral is created with status: RECEIVED.
REFERRAL_RECEIVED is emitted.
The downstream workflow creates or updates a Person for the referred lead with LeadSource.REFERRAL.
The new Person enters the pipeline at the lead stage like any other inbound lead — visible in People and routed through your existing automations.
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 for the full guide.

Overview — the full reputation flywheel.
Public profile — the surface the referral CTA lives on.
Referral rewards — reward queue and auto-thank policy.
Reputation API — referrals — authenticated CRUD.
Public referral endpoint — token-less public capture.

Getting Started

Dashboard

Collaboration

CRM

Properties

Calendar & Tasks

Communication

AI

Marketing

Reputation Studio

Document OS

Analytics

Automation & Tools

Settings

Organization (Admins)

Developers

API Reference

Architecture

Integrations

Where referrals come from

Public capture endpoint

Lifecycle

What’s on a Referral

Managing referrals

Closing the loop

Referral rewards

​Where referrals come from

​Public capture endpoint

​Lifecycle

​What’s on a Referral

​Managing referrals

​Closing the loop

​Referral rewards

​Related

Where referrals come from

Public capture endpoint

Lifecycle

What’s on a Referral

Managing referrals

Closing the loop

Referral rewards

Related