> ## 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.
# Profiles
> The central customer record in Omneo. Every transaction, incentive, and interaction links back to a Profile.
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](/concepts/profiles/deletions-purges-depersonalisations).
## 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](/concepts/profiles/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](/concepts/profiles/tags-and-statuses). |
### Activity tables
Records of what the customer has done:
| Table | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Transactions** | Completed purchases and returns |
| **Interactions** | [Non-purchase events](/concepts/profiles/interactions) 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](/api-reference/profile-address/overview) for addresses (full CRUD plus upsert by external ID)
* [Batch update profile tags](/api-reference/profile-tag/batch-update-profile-tags) and [batch delete profile tags](/api-reference/profile-tag/batch-delete-profile-tags) for tags
* [Batch update profile statuses](/api-reference/profile-status/batch-update-profile-statuses) and [batch delete profile statuses](/api-reference/profile-status/batch-delete-profile-statuses) for statuses
* [Profile Region endpoints](/api-reference/profile-region/browse-profile-regions) 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
1. **Created:** when a customer signs up in-store, online, or via API
2. **Enriched:** as more attributes, transactions, and interactions are recorded
3. **Merged:** if duplicate profiles are found and consolidated
4. **Deleted:** soft-deleted; removed from API responses and reporting but recoverable
5. **Purged:** fully and permanently removed from all systems; cannot be recovered
6. **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](/concepts/profiles/deletions-purges-depersonalisations) for detail on each process.
## Related
The full reference for all default profile fields.
How external system IDs link to a profile.
How labels and status types work on a profile.
Create, read, update, and delete profiles via the API.