action, a channel, and a signal to one of the two interaction routes. Which route you use depends on how much you know about the customer at the moment the event happens. For what an interaction is and when one is the right record to create, see Interactions.
Choosing a route
There are two ways to create an interaction. Both write the same record; they differ in how the owning profile is determined.
As a rule, use the profile-scoped route for customer-facing experiences (loyalty apps, member portals, clienteling screens) and the global route for server-side integrations and bulk recording. See Global vs profile-scoped endpoints for the wider pattern.
On the profile-scoped route, creating and editing require the
update-profiles scope, and browsing and reading require read-profiles. The global route uses interaction-specific scopes: create-interactions to add, read-interactions to browse and read, update-interactions to edit, and delete-interactions to delete.
Required fields
Every interaction, on either route, requires five fields.
Omneo stores
namespace in handle format: spaces become hyphens, letters are lowercased, and characters other than letters, digits, _, . and - are removed. Sending Web Engagement stores web-engagement, so filter and build reactions against the stored form.
Create an interaction for a known profile
Use the profile-scoped route when you already hold the profile, such as inside a logged-in app session. The profile comes from the URL, so you never sendprofile_id, and an identifier in the body is rejected.
Create an interaction from a server-side integration
Use the global route when you are recording activity from a backend system. If you hold the Omneoprofile_id, send it directly.
Identify the customer by an external identity
Often a server-side integration does not hold the Omneoprofile_id. It knows the customer only by an ID from another system, such as a Shopify customer ID or a loyalty card number. In that case, send an identifier instead of profile_id. The two are mutually exclusive; send one or the other, not both.
An identifier has two parts: a handle naming the identity type, and an id holding the value. The handle must match the handle the identity is stored under on the profile. Omneo matches against identities only, not against the profile’s own email or mobile fields, so an email address identifies a customer here only when your tenant stores email as an identity.
handle and value, then attributes the interaction to the profile that identity belongs to. Swap the handle for shopify, loyalty-card, or any identity type your tenant uses.
If you frequently need the Omneo
profile_id for other calls, resolve it once with the identity search endpoint and reuse it. See Looking up a profile by identity.Link an interaction to other records
An interaction can connect to other objects, which is what makes it useful for attribution and reporting. Add any of these alongside the required fields.
A location can be identified by Omneo’s
location_id or by your own location_external_id or location_external_code, whichever you hold. Omneo tries them in that order and uses the first one that has a value. A location identifier that matches no active location is rejected with a validation error rather than ignored.
To link to an object that does not have a dedicated field, use the polymorphic pair interacted_type and interacted_id. Set interacted_type to the object type and interacted_id to its ID. Supported types include transaction, order, appointment, questionnaire_submission, rating, reward, and benefit, among others.
Browse and read interactions
Read across all profiles with the global route, or scope to one profile.Correct or remove an interaction
Treat interactions as append-only event records: in normal use you create them and move on. The API does expose edit and delete for correcting a mistake or honouring a deletion request, so use them for that, not as part of routine recording./api/v3/profiles/{profileId}/interactions/{interactionId}.
Drive incentives from interactions
Each interaction you create fires aninteraction.created event. That event is available as a Reaction trigger, so you can act on tracked activity: award points for a product review, issue a benefit on a first app login, or progress an achievement. Filter on fields such as action, channel, signal, or namespace to target the exact activity you want to reward.
When the interaction has a profile, the event also carries that profile’s name, contact details, statuses and communication preferences, so a reaction can check who the customer is and what they have consented to before it issues anything of value.