Identities are the external IDs that link an Omneo Profile to a customer’s record in every other system that creates or interacts with customer data. Every platform has its own native ID for a customer: Shopify has a customer ID, your POS has a customer number, Klaviyo has a subscriber ID. Identities are how Omneo maps all of those back to a single Profile, creating a true single view of the customer regardless of which system they interact with. Without identities, each system would see a different slice of the customer. With them, Omneo can unify transactions, interactions, and incentive data from every touchpoint into one coherent record.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.
Uniqueness
Each handle and identifier combination is unique across all profiles. A givenshopify identity value can only exist on one profile at a time. Omneo enforces this at write time: if an incoming identity already exists on another profile, Omneo uses it to automatically route the data to the correct profile rather than create a duplicate. This is the mechanism behind automatic data merging across systems.
Identity fields
| Field | Description |
|---|---|
handle | The system name for this identity type (e.g., shopify, loyalty-card, klaviyo) |
identifier | The actual ID value on that platform |
profile_id | The Omneo profile this identity belongs to |
Examples
| Identity handle | Example value |
|---|---|
shopify | 6432187489345 |
staff-number | EMP-00421 |
loyalty-card | LY-8831227 |
klaviyo | 01HXYZ... |
apns | APNS device token |
instagram | @meganjones |
pos | CID-9923 |
Reserved handles
Omneo Extensions claim specific identity handles as part of their integration. The Klaviyo Extension expects to write to theklaviyo handle; the Shopify Extension uses shopify. Using a handle name that conflicts with an Extension will cause that Extension to behave incorrectly.
Handle names should be agreed and documented during solution design, before any integration is built. Treat handle names as part of your data model: they are not easy to change after data has been written against them.
How identities power integrations
When a customer interacts with a connected system, that system presents its native ID to Omneo. Omneo looks up the matching identity and returns the full profile, complete with incentive balances, transaction history, and attributes. The connected system never needs to know the Omneo profile ID. Identities are also used for:- Automatic data routing: if an incoming record carries an identity that already exists on a profile, the data is attributed to that profile automatically
- Authentication: integrations such as the Shopify proxy use an identity to issue a delegated token without requiring the customer to re-authenticate
- Reactions: identity data is available in event contexts and can be used as filter conditions
The Profile Identities API supports browse, add, read, edit, and delete operations. You can look up a profile by identity value using the
/identities/search endpoint. See the Identities API for full endpoint reference.