Integrating Omneo Invites

By the end of this guide your website lets a signed-in profile (the referrer) enter a friend’s name and email, and Omneo Invites emails the friend (the invitee) an invitation, tracks it, and records the referral when they join. Your site owns one step: collecting the referral and submitting it. Omneo owns the email, the join, and the incentive rules. This guide covers the developer’s part. For what the service does, read Omneo Invites. For who sets up what on the Omneo side, read Configuring Invites. Every endpoint is documented in the Invites API reference.

What you build and what Omneo provides

Invites has to be called as the referrer, with a token scoped to that one profile. You mint those tokens yourself. Everything else that authenticates you comes from Omneo.

Item	Who provides it	Notes
Invites API base URL `https://api.[tenant].getomneo.com/invites/`	Omneo	Confirmed when the service is enabled for your tenant.
Omneo ID base URL `https://api.[tenant].getomneo.com/id/`	Omneo	See Using Omneo ID.
Omneo API token scoped to `read-profiles` and `read-identities`	Omneo, or created in CX Manager if you have access	Long-lived. Used only to mint ID tokens. Server-side only. See API tokens.
Identity handle for your platform’s customer IDs	Omneo	For example `shopify-[store-handle]`. Lets you mint a token from the ID you already hold.
Omneo ID token, one per referrer	You	Short-lived, minted by your backend with the API token above. This is the credential the Invites API accepts.
Machine token	Omneo	Only if your website performs the accept instead of Profile Portal. See Accepting on your own site.
Profile Portal join page `https://[portal]/join`	Omneo	Where the invitee lands and the accept is performed.
Staging equivalents of all of the above	Omneo

Health checks need no authentication: GET /invites/api/health returns 200, and GET /invites/api/version returns the service version.

Flow

The refer step

The token exchange needs your Omneo API token, so this chain runs on a server, never in the browser. Any backend you control works. On Shopify, a Shopify App Proxy is the natural home because Shopify tells you which customer is signed in. See Shopify authentication for how the Omneo Shopify extension handles the same problem.

Identify the referrer server-side

Establish which profile is signed in and what their ID is on your platform. Never trust a customer ID sent from the browser.On a Shopify App Proxy, verify the signature query parameter against your app’s shared secret before reading logged_in_customer_id, and reject the request if it is empty.

Exchange the customer ID for an Omneo ID token

Mint a profile-scoped token by external identity. With the Omneo SDK:

import { ID } from '@omneo/omneo-sdk'

const id = new ID({
  tenant: '[tenant]',
  omneoAPIToken: process.env.OMNEO_TOKEN
})

const { token, exp } = await id.auth.requestAuthToken({
  id: '7290416496812',
  id_handle: 'shopify-[store-handle]'
})

The same call as raw HTTP:

curl -X POST https://api.[tenant].getomneo.com/id/api/v1/auth/token \
  -H "Authorization: Bearer ${OMNEO_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "id": "7290416496812", "id_handle": "shopify-[store-handle]" }'

id is your platform’s customer ID as a string. Tokens are short-lived and exp is a Unix timestamp. Cache the token per referrer until shortly before it expires. Do not mint one per keystroke.A profile that was created on your platform seconds ago may not have synced to Omneo yet. In that window the create call in the next step returns 401. Treat a fresh token followed by 401 as “not synced yet” and show a try-again-shortly message instead of retrying in a loop.

Create the invite as the referrer

curl -X POST https://api.[tenant].getomneo.com/invites/api/v1/me/invites \
  -H "Authorization: Bearer ${OMNEO_ID_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_first_name": "Alex",
    "recipient_email": "alex@example.org",
    "public_message": "Join with my invite!"
  }'

Field	Rule
`recipient_first_name`	Required. The service capitalises the first letter.
`recipient_email`	Required. Must be a valid email address.
`public_message`	Optional. Rendered in the email if your template uses it.

{
  "data": {
    "id": "9c1c6f3e-5d5a-4a1e-9d6a-2c2f4b1a8e10",
    "source_omneo_id": "01H8Z...",
    "recipient_email": "alex@example.org",
    "status": "PENDING",
    "should_communicate": null,
    "send_count": 0,
    "invited_at": "2026-08-28 14:03:21",
    "expires_at": "2026-09-27 23:59:59",
    "accepted_at": null,
    "declined_at": null,
    "revoked_at": null,
    "definition": "refer-a-friend",
    "meta": null
  }
}

On 200 Omneo has already sent the email. You send nothing. The response does not echo recipient_first_name or public_message.

Handle the response

Status	Body	What to do
`400`	`{"data":{"error":"Refusing to create invitation as the eligibility check failed (not enough invites remaining or definition not in range)"}}`	The referrer has used their quota or the campaign is not running. Show “You’ve used all your invites”. Check remaining invites first to avoid this.
`403`	`{"data":{"error":"This action is forbidden."}}`	The address, or its domain, has opted out. Show a neutral “We can’t send an invite to that address”.
`422`	`{"message":"The given data was invalid.","errors":{"recipient_email":["..."]}}`	Validation. Surface the field messages.
`401`	Empty message	The ID token is invalid or expired, or the profile has not synced yet. Mint a fresh token and retry once.
`429`	Throttled	60 requests per minute per token. Back off.

Log the returned invite id against your customer ID. Omneo support can look up any invite by ID when a referrer reports that a friend did not receive the email.

Showing invites remaining

curl https://api.[tenant].getomneo.com/invites/api/v1/me/invites \
  -H "Authorization: Bearer ${OMNEO_ID_TOKEN}"

{
  "data": [ { "id": "...", "status": "ACCEPTED", "...": "..." } ],
  "meta": {
    "remaining": 3,
    "override_count": null,
    "profile_statuses": ["member"],
    "eligible_definition": {
      "id": 1,
      "handle": "refer-a-friend",
      "in_range": true,
      "starts_at": null,
      "ends_at": null,
      "max_invites": 5
    }
  }
}

meta.remaining is how many invites the referrer can still send. null means unlimited.
meta.eligible_definition.in_range is false when the campaign window is closed. Creating an invite will return 400.
“Friends who joined” are the entries in data with status equal to ACCEPTED.
data is ordered oldest first by invited_at.

The same token can also fetch one invite, resend it, or revoke it. None of these are needed for a basic integration. See Endpoints.

Lighter alternative: send referrers to Profile Portal

If you would rather not run a backend, link your “Refer a friend” button to https://[portal]/refer. The referrer signs in to Profile Portal and sends invites from there. Quota, email, and success messaging are built in. You lose the on-site experience but write no code. Link to /refer without query parameters.

The invitee’s journey

Omneo owns this part. It is described here so you can design around it.

Omneo emails the invitee using your brand’s template. The call to action links to https://[portal]/join?invite_id={inviteId}&email={recipientEmail}. The join page pre-fills email, and also first_name, last_name, and mobile_phone if present in the query string.
The invitee completes the join form. Profile Portal creates their profile and, server-side, tells Invites the invitation was accepted. Invites checks the email matches, writes the custom attribute invites.invited_by (the referrer’s profile ID) to the new profile, and marks the invite ACCEPTED.
Other pending invites to that same address, from other referrers, are marked DECLINED. First accept wins.
Your Reactions fire on the referral. See Referral incentives.

If the accept fails because the invite has expired, was already used, or the email was changed on the form, the invitee’s profile is still created. Only the referral credit is lost, and the invitee sees no error. If referral credit is business-critical, ask Omneo about monitoring pending invites whose invitee has since joined.

Accepting on your own site

If invitees create their account on your website rather than in Profile Portal, your backend performs the accept using a machine token Omneo issues for server-to-server calls.

# Optional: check the invite before showing the sign-up form
curl -X POST https://api.[tenant].getomneo.com/invites/api/v1/invites/{inviteId}/validate \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "recipient_email": "alex@example.org" }'
# 200 with an empty body means it is safe to proceed

# After the customer account exists
curl -X POST https://api.[tenant].getomneo.com/invites/api/v1/invites/{inviteId}/accept \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "alex@example.org",
    "recipient_external_id": "7290416496913",
    "first_name": "Alex",
    "last_name": "Smith"
  }'
# 200 {"profile_id": "01H9A...", "statuses": ["member"]}

Read invite_id from your sign-up page URL, keep it through the form, and call accept only after the customer account exists. recipient_email must equal the invited address exactly. recipient_external_id is the new customer’s ID on your platform. Invites finds or creates the Omneo profile by that ID first, then by email, so it converges with your platform-to-Omneo sync either way.

Decide this with Omneo before go-live. The identity handle that Invites links recipient_external_id under is a tenant-wide setting and cannot be changed once invites are in flight. It has one value when Profile Portal performs the accept and a different one when your website does. Mixing both accept paths in one tenant is not recommended.

State errors from validate and accept are listed in Error responses.

Things not to do

Do not call POST /api/v1/invites (without /me/). It exists for a legacy integration and does not send the email, enforce the referrer’s quota, or honour opt-outs. Use /api/v1/me/invites.
Do not put the Omneo API token, the machine token, or an ID token in browser JavaScript. All three stay on your server.
Do not add query parameters to /refer links. Link to the portal refer page as-is.

Security checklist

The Omneo API token and machine token live only in server configuration or a secret manager.
Every request to your handler is authenticated server-side before a customer ID is trusted. On Shopify, verify the App Proxy signature before reading logged_in_customer_id.
ID tokens are minted only for the profile proven to be signed in. Never accept a customer ID from the request body.
Nothing on your site links to /refer with query parameters.
Your own email and marketing tooling does not pre-fetch links in Omneo’s invitation emails. The opt-out link is a plain GET with no confirmation step.
The referral form is rate-limited per profile. The API’s 60 requests per minute is a backstop, not a UX limit.
Each returned invite id is logged with your customer ID so support can trace it.

Go-live checklist

Before you start, Omneo confirms: the Invites service is live for your tenant (GET /invites/api/health returns 200), your Omneo API token is issued, a test profile exists on your platform and in Omneo, and you have a staging host and a disposable inbox for the invitee.

Sign in as the test profile on your website and submit the referral form with the disposable inbox address.
Expect 200 and an invite id. GET /api/v1/me/invites shows it as PENDING with meta.remaining decremented, or null if unlimited.
The disposable inbox receives the email. Its call to action links to https://[portal]/join?invite_id=...&email=....
Complete the join form. GET /api/v1/me/invites as the referrer now shows the invite as ACCEPTED.
Omneo confirms the new profile carries invites.invited_by equal to the referrer’s source_omneo_id, and that the referral Reaction fired.
Negative checks: submit the same address again and expect a second PENDING invite, or your own de-duplication. Submit an address Omneo has blocked for the test and expect 403. Exhaust the quota on a definition with a small maximum and expect 400.

Concern	Owner
Referral form, backend handler, token exchange, create call, on-site messaging	You
Tenant configuration, email template and copy, portal join and accept, Invite Definitions and quotas, Reactions, opt-out management	Omneo
Portal refer page copy, if you use the lighter alternative	Your brand, through Omneo

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

Discovery search

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Integrating Omneo Invites

What you build and what Omneo provides

Flow

The refer step

Showing invites remaining

Lighter alternative: send referrers to Profile Portal

The invitee’s journey

Accepting on your own site

Things not to do

Security checklist

Go-live checklist

​What you build and what Omneo provides

​Flow

​The refer step

​Showing invites remaining

​Lighter alternative: send referrers to Profile Portal

​The invitee’s journey

​Accepting on your own site

​Things not to do

​Security checklist

​Go-live checklist

What you build and what Omneo provides

Flow

The refer step

Showing invites remaining

Lighter alternative: send referrers to Profile Portal

The invitee’s journey

Accepting on your own site

Things not to do

Security checklist

Go-live checklist