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

# Omneo Invites

> Omneo Invites is a refer-a-friend service. A profile invites friends by email, and Omneo records the referral on the new profile so Reactions can issue incentives.

**Omneo Invites** is a refer-a-friend service. A profile in your incentive program (the **referrer**) enters a friend's first name and email address. Omneo emails the friend (the **invitee**) a branded invitation. When the invitee joins, Omneo records who referred them on the new profile, and your [Reactions](/concepts/automation/reactions) issue incentives to the referrer, the invitee, or both.

<Info>
  Omneo Invites is different from [Corporate Invites](/dev-guides/extensions/corporate-invites), which is a white-label sign-up portal for B2B and group enrolment. This page covers the refer-a-friend service only.
</Info>

## What Invites does

1. **Create.** The referrer submits a friend's name and email, from Profile Portal or from your own website. Omneo checks the referrer's remaining quota and creates an invite in the `PENDING` state.
2. **Email.** Omneo sends the invitation through your SendGrid account using your dynamic template. The email carries the referrer's first name, an optional personal message, the expiry date, and links to join, decline, or opt out.
3. **Join.** The invitee follows the link to your join page. The page pre-fills their email address from the link.
4. **Accept.** When the invitee registers, Omneo checks that the email matches the invitation, finds or creates the invitee's profile, writes the referral to the profile as the custom attribute `invites.invited_by` (the referrer's profile ID), applies any default statuses, and marks the invite `ACCEPTED`.
5. **Reward.** Your Reactions run on the new profile. Typical rules issue a Reward to the referrer when the invitee joins or completes a first Transaction.

Invites owns steps 1 to 4. Step 5 is standard Omneo automation, configured the same way as any other Reaction.

## Where referrers send invites

| Surface          | How it works                                                                                                                                | Availability                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Profile Portal   | A refer page, an invite block on the loyalty page, and an optional home block let a signed-in profile send invites and see how many remain. | Available in Profile Portal v3 when Omneo enables invites in your portal configuration. If you run a newer Profile Portal version, confirm availability with your Omneo account manager. |
| Your own website | Your backend creates invites on the referrer's behalf using an Omneo ID token. Quota, email delivery, and the join flow stay with Omneo.    | Available to any tenant with Invites enabled. See [Integrating Omneo Invites](/dev-guides/frontend/invites-plugin).                                                                      |

Both surfaces can run side by side. A referrer's quota is shared across them.

## What the invitee experiences

* The invitation comes from your brand's sender address, in your template, and includes the referrer's first name and any personal message they wrote.
* The join link opens your join page with the invitee's email pre-filled. The invitee completes registration as normal.
* If the invitee has pending invites from more than one referrer, the first invite accepted wins. Omneo marks the others `DECLINED` so only one referrer is credited.
* If the invitee registers with a different email address, the referral is not credited. The profile is still created.
* The email also carries a decline link and an opt-out link. Declining marks that one invite `DECLINED`. Opting out blocks all future invitations to that address and declines any pending ones.

## Invite statuses

| Status     | Meaning                                                                                               |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| `PENDING`  | Created and awaiting a response. The invitation email has been sent unless the address has opted out. |
| `ACCEPTED` | The invitee joined and the referral was recorded on their profile.                                    |
| `REVOKED`  | The referrer cancelled the invite before it was accepted.                                             |
| `DECLINED` | The invitee declined or opted out, or accepted a different referrer's invite.                         |
| `EXPIRED`  | The invite passed its expiry date without being accepted.                                             |

Expiry is enforced when an invitee tries to accept. An invite past its `expires_at` date is refused even while its `status` still reads `PENDING`. See [Status lifecycle](/dev-guides/frontend/invites-api#status-lifecycle) for how to handle this in your own UI.

## Quotas and campaigns

Every invite belongs to an **Invite Definition**, which Omneo configures for your tenant. A definition sets:

| Setting          | Effect                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------ |
| Period           | Days until an invite expires. No period means invites never expire.                        |
| Maximum invites  | How many invites each referrer can send under this definition. No maximum means unlimited. |
| Campaign window  | Optional start and end dates. Outside the window, referrers cannot create invites.         |
| Default statuses | Statuses applied to the invitee's profile when they join, for example a `member` status.   |

You can run a single definition for every profile, or map profile statuses to different definitions so that, for example, higher tiers receive more invites. Omneo can also set a per-profile override to raise or remove one referrer's limit.

Quota counts `PENDING`, `ACCEPTED`, `DECLINED`, and `EXPIRED` invites. Revoked invites do not count, so a referrer who cancels a stale invite gets that slot back.

## Privacy and opt-out

Invites is designed so that a referrer cannot use it to discover whether an email address already belongs to your program. If the address has already accepted an invitation, the referrer still sees a normal pending invite in their list and no email is sent.

Opt-out is permanent for that address. Later invites to it are refused, and Omneo can lift the block on request. Omneo can also block whole email domains for your tenant.

## Referral incentives

Invites writes one fact to the invitee's profile: the custom attribute `invites.invited_by`, whose value is the referrer's profile ID. Everything else is standard Omneo automation:

* A [Trigger](/concepts/automation/triggers) on profile creation or first Transaction, conditioned on `invites.invited_by` being set, issues a [Reward](/concepts/incentives/rewards) to the referrer. The action also writes `invites.invited_by_name` to the invitee's profile for use in communications.
* The referrer's profile carries a `total_referred` [aggregation](/concepts/profiles/aggregations), the number of distinct profiles that name them in `invites.invited_by`. Use it for milestone incentives such as "refer five friends".
* Welcome incentives for the invitee use the same Triggers as any other join.

<Note>
  Omneo also supports referral relationships modelled as [Connections](/concepts/profiles/connections). Invites does not create a Connection. If you run both, decide with your Omneo account manager which one your Reactions key off.
</Note>

See [Program objectives](/business-guides/incentive-design/program-objectives) for where referral programs fit in an acquisition strategy, and [Custom attributes](/concepts/profiles/custom-attributes) for how the referral is stored.

## Administration

Omneo manages Invite Definitions, quota overrides, the opt-out list, and invite metrics on your behalf. Omneo support can look up any invite by its ID, which is why the integration guide recommends logging invite IDs against your own customer records.

See [Configuring Invites](/experiences/invites/configuration) for who sets up each part, [Integrating Omneo Invites](/dev-guides/frontend/invites-plugin) for the developer guide, and the [Invites API reference](/dev-guides/frontend/invites-api) for every endpoint.