Skip to main content
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

ChannelSource
PUBLIC_PROFILEThe referral form on the agent’s public reputation profile.
WIDGETThe embedded reviews widget on the agent’s site.
MANUALLogged in-app by the agent.
IMPORTBulk-imported from a prior system.

​
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.
  • Records the referrer as a Person (creating one if it doesn’t exist).
  • 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 with LeadSource.REFERRAL and RelationshipStage.ADVOCATE.
  • Rate-limits the request 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",
    "referredEmail": "sam@example.com",
    "notes": "Sam is selling their condo this spring."
  }'
No auth required — the published profile slug is the capability.

​
Lifecycle

StatusMeaning
RECEIVEDCaptured from the public endpoint or logged manually. Awaiting agent triage.
CONTACTEDAgent has reached out to the referred person.
QUALIFIEDThe referred lead has been qualified.
CONVERTEDThe referral produced a real Deal (recorded on resultingDealId).
LOSTDid not convert.
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

FieldPurpose
referrerPersonIdThe advocate who sent the referral.
referredPersonIdThe new lead (linked once they become a Person).
referredName, referredContactRaw captured fields, used before linking to a Person.
agentUserIdThe agent the referral was sent to.
channelWhere the referral came from (PUBLIC_PROFILE, WIDGET, MANUAL, IMPORT).
resultingDealIdThe Deal that closed from this referral.
resultingLeadSourceDefaults to REFERRAL on the new lead.
rewardType, rewardStatus, rewardValueOptional reward tracking (e.g. gift_card, commission_share).
notesFree-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."
  }'

​
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 and routed through your existing automations.
  5. When that lead’s deal closes, set Referral.resultingDealId and Referral.status = CONVERTED 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.