Skip to main content
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

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

SystemHandle
Shopifyshopify
Loyalty cardloyalty-card
Klaviyoklaviyo
Staff numberstaff-number
POS customer IDpos-customer
Use consistent handles across your implementation, they are how Omneo recognises which system each identity belongs to.

​
Looking up a profile by identity

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

GET /api/v3/profiles/{profileId}/identities

​
Updating an identity

PUT /api/v3/profiles/{profileId}/identities/{identityId}

​
Deleting an identity

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