> ## 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.

# Identities

> Profile Identities link a customer's Omneo profile to their IDs in external systems, enabling a true single view of the customer across every platform.

**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.

## Uniqueness

Each handle and identifier combination is unique across all profiles. A given `shopify` 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 the `klaviyo` 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

<Info>
  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](/api-reference/identity) for full endpoint reference.
</Info>

## Mutation semantics on the main Profile endpoints

<Info>
  Unlike addresses, tags, and statuses, including `identities` on `POST /v3/profiles` or `PUT /v3/profiles/{profile}` is an **upsert**, not a destructive replace. Each entry is matched by `id` or by (`handle`, `identifier`) and updated, or created if no match. Identities not in the supplied list are left in place.

  See [Mutation semantics on POST and PUT](/concepts/profiles/overview#mutation-semantics-on-post-and-put) for the full table of behaviours across profile collections, and the dedicated [Profile Identities endpoints](/api-reference/profile-identity/overview) for explicit delete operations.
</Info>

## Related

* [Profiles](/concepts/profiles/overview)
* [Extensions](/concepts/extensions/overview)
* [Identities API](/api-reference/identity)