Omneo ID
What is Omneo ID?
Omneo ID is a proxy service that allows developers to proxy requests on behalf of a unique customer.
Using Omneo ID involves the following:
- Request a Token (Profile specific, or anonymous)
- Request the '/profiles/me' endpoint, using the
id
specified in the proxy
or - Request the '/profiles' endpoint to quickly create or update a profile.
Request a Token
- Request a token for use with Omneo ID
provide the Omneo profileid
in the payload.
(Optional) omit theid
from the payload, to create a token for use only with the/profiles
endpoint
to quickly create or modify a profile. Tokens without an ID will be unable to make requests to 'profiles/me'
Once a valid token is obtained, this can be used to authenticate further requests to the '/profiles/me' or '/profiles' endpoints
A token request payload could look like the below:
//Authorization: Bearer {Omneo API token obtained from CX manager}
//POST https://api.{tenant}.getomneo.com/id/api/v1/auth/token
{
"id": "..." // The Omneo profile ID (or identity)
"id_handle": "..." // The identity handle. Remove this key if you want to just use the profile ID.
}
Specify an id_handle
to search for a specific identity value instead of an Omneo ID
For example
// Request by Identity
//This payload, will search for a profile by identities, where the identifier = "1004993MH", and the handle = "magento_id"
{
"id" : "1004993MH",
"id_handle" : "magento_id"
}
//OR
// Request by Omneo ID
{
"id" : "93770831-e18d-467c-b213-0087218ae9dd",
}
Searching for a profile.
Searching for a profile can be done with a token without an
id
The ID service provides the ability to quickly create a profile, or modify comms preferences in a limited capacity. This works by providing an email
or mobile_phone
to check against the Omneo database.
If any matching details are found within the Omneo database, the matching profiles attributes.comms
preferences will be updated according to the provided payload.
If no profile is found, a new profile is created using the payload provided.
When updating a profile
When updating an existing profile, only the
attributes.comms
attribute is included in the payload. This is to prevent unauthorised editing of personal details without being properly authenticated.
Other profile fields such asfirst_name
orlast_name
are unable to be edited this way.
To modify a profile, use the "/profiles/me" endpoint. (an auth token with anid
is required)
There is no differentiation between responses between when a creation or update action is taken. The response will always be 200, unless any payload validation errors occur within the request.
To Find, Search or Update a profile, you can use the following:
Attribute | Description |
---|---|
emailSTRING REQUIRED | Used to search a profile by email address |
mobile_phoneSTRING | Used to search a profile by mobile |
Any Profile Attributes | Any objects can be used as part of this Add Profile endpoint. If no matching profile is found, this payload will be redirected to create a new profile |
first_name
andlast_name
are defaulted to "unknown" if not provided
attributes.comms.email_promo
is defaulted totrue
if not provided
attributes.comms.email_optout
is defaulted tofalse
if not provided
An example payload to this endpoint could be:
//Authorization: Bearer {Omneo API token obtained from CX manager}
//POST https://api.{tenant}.getomneo.com/id/api/v1/profiles
{
"email" : "[email protected]",
"first_name" : "test",
"last_name" : "user",
"gender" : "male",
"region_id" : 1,
"tags" : ["tag1","tag2","tag3"],
"addresses":[
{
"address_line_1":"asd333",
"address_line_2":null,
"address_line_3":null,
"company":"Test Company",
"latitude":null,
"longitude":null,
"city":"Melbourne",
"postcode":"3002",
"state":"Victoria",
"country":"Australia",
"notes":null
}],
"attributes" : {
"comms" : {
"email_promo" : true,
"email_optout" : true
}
}
}
Using the ID Proxy "/profiles/me"
the
/profiles/me
endpoint requires a token with anid
specified.
Tokens without a profileid
will result in a 404 response
The profiles 'me' endpoint proxies requests to Omneo, prepending an omneo ID as part of the request.
This is to ensure front end applications obtain limited access in context to the specified profile only.
To use this endpoint, ensure you generate a token with an id
, to proxy requests on behalf of the id specified in the token.
Because the '/profiles/me' endpoint acts as a proxy to omneo, any profile endpoint can be accessed.
for example, a request of /profiles/me/lists/wishlist
will actually request /profiles/{profile_id}/lists/wishlist
with the profile_id
being the id
specified in your JWT
This endpoint is proxied to Profiles. Further documentation about these endpoints can be found in the accompanying API documentation.
The ID Proxy provides a GET only endpoint to access locations.
request this endpoint by sending a GET request to /locations
All query parameters are supported in this request.
A good example of query parameters, is filtering locations to only opened stores.
(this means is_permanently_closed
is false and is_published
is true
this could be achieved using: /locations?filter[is_published]=1&filter[is_permanently_closed]=0
Specific locations can be requested by using locations/{id}
This endpoint is proxied to Read Location and Browse Locations. Further API information can be found in their accompanying documentation
Updated about 3 years ago