Participants and enrollment

A participant is a person or a company in your product, as RefRef knows it. Every referral, Event, and Reward belongs to participants of one Project.

Name a participantCopy Anchor Link

Name each participant with its kind and your own stable ID:

{ "kind": "individual", "externalId": "user_42" }

(individual, "42") and (group, "42") are two different participants. Use the same kind and ID in every call about one customer: in Events, identifications, enrollments, and the Widget token.

Choose one level for your Programs. If your customers are companies, make the company a group participant and send the person who acted as the actor. RefRef stores no group membership, and the actor never changes attribution.

RefRef never matches participants by email and never merges them. One person under two IDs is two participants.

Create participantsCopy Anchor Link

You do not need a registration call. A trusted call that names an unknown participant creates it: an Event, an identification, an enrollment, a code, a link, or a Widget token. The Console enroll form creates one too.

Add detailsCopy Anchor Link

PUT /v1/participants sets the details of a participant, and creates it if needed:

{
  "projectId": "prj_…",
  "participant": { "kind": "individual", "externalId": "user_42" },
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "billingIds": { "stripe": "cus_…", "revenuecat": "user_42" }
}

• name and email show in the Console. null clears a value.
• billingIds gives the customer ID of the participant at each billing provider: dodo, stripe, paddle, polar, or revenuecat. RefRef needs it to deliver account credit, discounts, or plan upgrades to a participant who has not paid through that provider yet. The provider need not be connected yet. Each one is set once: another customer at a provider, or a customer that another participant has there, answers 409 CONFLICT. The answer lists every customer ID of the participant.

Change an IDCopy Anchor Link

When your ID of a customer changes, rename the participant:

POST /v1/participants/rekey
{
  "projectId": "prj_…",
  "participant": { "kind": "individual", "externalId": "old_id" },
  "newExternalId": "new_id"
}

The old ID is retired. It keeps naming the same participant in every call and in Widget tokens, and it never names another participant. The kind does not change.

Enroll in a ProgramCopy Anchor Link

A participant must be enrolled in a referral Program to refer others. A referral Program enrolls each new customer at their signup, unless you turn off "Enroll every new customer" in its settings. The Widget enrolls a customer the first time it opens for them. To enroll another participant, such as a customer who signed up before your integration, enroll from your backend:

POST /v1/enrollments
{
  "projectId": "prj_…",
  "participant": { "kind": "individual", "externalId": "user_42" },
  "programId": "prg_…"
}

Or enroll from the Console, on the Referrers page. A participant can be enrolled in several Programs at once, with one open enrollment in each Program. A repeated call returns the open enrollment.

End an enrollment with POST /v1/enrollments/{enrollmentId}/end. After that, the participant earns no new referrer Rewards from that Program, also on its earlier referrals. Its referrals stay. A participant can enroll again later and keeps its code.

A referee does not need an enrollment. Enroll a referee only when it should refer others too.

Referral codes and linksCopy Anchor Link

POST /v1/referral-codes creates the participant's code in a referral Program, or returns the existing one. A participant has one code in each referral Program, and the code stays after an enrollment ends. The referral link is https://r.refref.ai/<code>.

POST /v1/referral-links adds a vanity slug to the participant's existing code: https://r.refref.ai/<project-slug>/<slug>. When the Project has an active custom link domain, the link is also https://<your-domain>/<slug>, and the Console shows that form. A slug is unique in the Project. A slug cannot be join or health, and cannot be exactly 10 lowercase letters and digits, because a referral code has that form.

A link counts only while its owner is enrolled in the Program and the Program is active. Otherwise the visitor goes to your Project URL, and RefRef records no click.

Record a referralCopy Anchor Link

When you learn of a referral another way, for example on a sales call, record it from your backend, or with Record referral on the Referrals page of the Console:

POST /v1/referrals
{
  "projectId": "prj_…",
  "programId": "prg_…",
  "referee": { "kind": "individual", "externalId": "user_77" },
  "refCode": "k3x9m2q8ra",
  "note": "Sales call"
}

Name the referrer by its code (refCode), or by your ID ("referrer": { "kind": "individual", "externalId": "user_42" }). A partner has only a code. The referrer must be enrolled in the Program, and the API key needs the referrals:write permission. RefRef creates the referee when it does not know it.

The referral has no click or code behind it, so its touchKind is recorded. Events of the referee that RefRef receives after it count for the referrer; earlier ones do not. A referee has at most one referral: a second call for the same referee returns 409 CONFLICT.

PartnersCopy Anchor Link

A partner joins through an invitation or an application, not through these calls. Your backend cannot name a partner, because a partner has no external ID. See Partners.

DeletionCopy Anchor Link

A store privacy request through the Shopify app or the WooCommerce plugin removes the participant's external ID. The same customer then comes back as a new participant.