Profiles

A Profile in Omneo is the record representing a single known person. Most other data types (transactions, incentives, interactions, addresses, and identities) link back to a Profile via the profile ID. Profiles are not limited to customers. They can represent staff members, corporate accounts, dependants, or system-level placeholders depending on the profile type in use.

Profile types

Omneo supports several profile types to cover different use cases:

Type	Description
Active	A standard profile for a known customer. The most common type.
Deleted	The profile has been soft-deleted. It is removed from API responses and reporting views but can be recovered.
Dependant	Used for associated persons such as children or pets, linked to a primary profile.
Incomplete	A profile created as part of a workflow where full details have not yet been captured.
Pending	A profile in a pre-activation state, used for certain onboarding and workflow scenarios.
System	A profile representing a system or generic entity rather than a real person (for example, a Guest user placeholder).
Temporary	A profile created to identify a person for a service interaction, scheduled to be forgotten once the service is complete.

For the distinction between deleting, purging, and depersonalising a profile, see Deletions, purges, and depersonalisation.

What a profile contains

Profiles are rich data objects with several layers of information.

Core profile fields

Fundamental identifying information: first name, last name, email, mobile phone, date of birth, gender, currency, and join details. See Core fields for the full field reference.

Attribute tables

Extended data linked to the profile:

Attribute namespace	Description
Addresses	One or more postal addresses
Aggregations	Calculated facts like lifetime spend and average transaction value
Appearance attributes	Physical measurements, size preferences, style attributes
Comms attributes	Communication preferences and opt-in/opt-out status
Custom attributes	Brand-defined fields for any additional data
Dates attributes	Key dates associated with the profile, such as birthdays or anniversaries
Identities	External system IDs (Shopify ID, loyalty card number, etc.)
Tags	Short labels for categorisation
Statuses	Special reserved tags that identify classes of profiles and can influence incentives and other platform behaviour. See Tags and statuses.

Activity tables

Records of what the customer has done:

Table	Description
Transactions	Completed purchases and returns
Interactions	Non-purchase events such as logins, page and product views, and form submissions
Ledger	Immutable audit trail for all incentives earned or redeemed, credits, payments, and running balances
Audits	System-level change log

Incentive tables

Current incentive state:

Table	Description
Rewards	Active reward balance
Points	Point balances by definition
Benefits	Issued and claimed benefits
Tiers	Current tier assignment
Achievements	Achievement progress and levels
Redemptions	History of used incentives

Mutation semantics on POST and PUT

The Profiles API accepts several nested collections in the request body (addresses, tags, statuses, identities, custom_attributes, dates_attributes, comms_attributes, regions, organisations). These collections do not all behave the same way when included on POST /v3/profiles or PUT /v3/profiles/{profile}. The semantic falls into one of three categories.

Field	Semantic	Effect when included on PUT
`addresses`	Destructive replace	All existing addresses are soft-deleted, then the supplied list is recreated. Anything omitted from the supplied array is destroyed.
`tags`	Destructive replace	The tag set is replaced with the supplied handles. Tags not in the new list are detached. Tag definitions themselves are not deleted.
`statuses`	Destructive replace	The status set is replaced with the supplied handles. Statuses not in the new list are detached.
`regions`	Destructive replace	All existing region links are detached, then the supplied list is re-attached.
`organisations`	Destructive replace	Organisations not in the supplied list are detached. Organisations in the list are attached if not already linked.
`identities`	Upsert	Identities are matched by `id` or by (`handle`, `identifier`) and updated, or created if no match. Identities not in the supplied list are left in place.
`custom_attributes`	Upsert	Custom attributes are matched by (`namespace`, `handle`) and updated, or created if no match. Custom attributes not in the supplied list are left in place.
`dates_attributes`	Upsert	Dates are matched per record and updated, or created if no match. Dates not in the supplied list are left in place.
`comms_attributes`	Partial merge	The single comms record is updated with the supplied fields. Fields not supplied are left untouched.
`attributes.comms`	Partial merge	Same as `comms_attributes`.

Two general rules follow from this:

Omitting a key entirely from the request body never modifies that collection. If you do not want to touch addresses, do not send addresses at all.
Sending an empty array (addresses: [], tags: [], etc.) for a destructive-replace field will clear it. For an upsert field, an empty array is a no-op.

The destructive-replace fields are the most common source of accidental data loss when integrators reuse a “GET profile -> mutate -> PUT profile” pattern. If the GET response omits a sub-resource the integrator does not care about, a naive PUT can silently destroy it.For fine-grained add, update, and delete on the destructive-replace fields, prefer the dedicated sub-resource endpoints over the main profile PUT:

Profile Addresses API for addresses (full CRUD plus upsert by external ID)
Batch update profile tags and batch delete profile tags for tags
Batch update profile statuses and batch delete profile statuses for statuses
Profile Region endpoints for regions (browse, add, edit, delete, batch)

Known vs Guest customers

A Known Customer is a profile with at least a name and contact details, to which transactions and interactions can be attributed. A Guest is an anonymous shopper who has chosen not to create a profile. The value of Omneo is in the Known Customer: the ability to personalise, incentivise, and maintain a relationship with an individual over time.

Profile lifecycle

Created: when a customer signs up in-store, online, or via API
Enriched: as more attributes, transactions, and interactions are recorded
Merged: if duplicate profiles are found and consolidated
Deleted: soft-deleted; removed from API responses and reporting but recoverable
Purged: fully and permanently removed from all systems; cannot be recovered
Depersonalised: record remains for reporting but all PII is removed and replaced with unidentifiable values; often done to comply with a customer’s right to be forgotten

See Deletions, purges, and depersonalisation for detail on each process.

Core fields

The full reference for all default profile fields.

Identities

How external system IDs link to a profile.

Tags and statuses

How labels and status types work on a profile.

Profiles API

Create, read, update, and delete profiles via the API.

Platform

Commerce

Incentives

Visits

Lists

Feedback

Organisations

Extensions

Platform surfaces

Groups

Automation

Profiles

Profile types

What a profile contains

Core profile fields

Attribute tables

Activity tables

Incentive tables

Mutation semantics on POST and PUT

Known vs Guest customers

Profile lifecycle

Core fields

Identities

Tags and statuses

Profiles API

​Profile types

​What a profile contains

​Core profile fields

​Attribute tables

​Activity tables

​Incentive tables

​Mutation semantics on POST and PUT

​Known vs Guest customers

​Profile lifecycle

​Related

Core fields

Identities

Tags and statuses

Profiles API

Profile types

What a profile contains

Core profile fields

Attribute tables

Activity tables

Incentive tables

Mutation semantics on POST and PUT

Known vs Guest customers

Profile lifecycle

Related