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

# Working with Identities

> Adding, reading, and searching profile identities via the Omneo API.

Profile identities link a customer's Omneo profile to their IDs in external systems. This guide covers how to add, retrieve, and use identities in your integration.

## Adding an identity to a profile

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/profiles/{profileId}/identities \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "shopify",
    "identifier": "6432187489345"
  }'
```

## Common identity handles

| System          | Handle         |
| --------------- | -------------- |
| Shopify         | `shopify`      |
| Loyalty card    | `loyalty-card` |
| Klaviyo         | `klaviyo`      |
| Staff number    | `staff-number` |
| POS customer ID | `pos-customer` |

Use consistent handles across your implementation, they are how Omneo recognises which system each identity belongs to.

## Looking up a profile by identity

```shell theme={null}
GET /api/v3/identities/search?handle=shopify&identifier=6432187489345
```

This returns the Omneo profile ID for the given external identity. Use this at the start of any integration flow where you have a platform-specific ID but need the Omneo profile.

## Browsing identities for a profile

```shell theme={null}
GET /api/v3/profiles/{profileId}/identities
```

## Updating an identity

```shell theme={null}
PUT /api/v3/profiles/{profileId}/identities/{identityId}
```

## Deleting an identity

```shell theme={null}
DELETE /api/v3/profiles/{profileId}/identities/{identityId}
```

## Best practices

* Always check if an identity exists before adding it: duplicate identities will return an error
* Use the identity search endpoint at the start of each integration request to resolve the Omneo profile ID
* Store the Omneo profile ID alongside the external identity in your system for faster lookup
* Use identity search for real-time POS lookup flows where speed matters