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:

1. Request a Token (Profile specific, or anonymous)
2. Request the '/profiles/me' endpoint, using the id specified in the proxy
   or
3. Request the '/profiles' endpoint to quickly create or update a profile.

Request a Token

1. Request a token for use with Omneo ID
   provide the Omneo profile id in the payload.
   (Optional) omit the id 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 as first_name or last_name are unable to be edited this way.
To modify a profile, use the "/profiles/me" endpoint. (an auth token with an id 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:

🚧

first_name and last_name are defaulted to "unknown" if not provided
attributes.comms.email_promo is defaulted to true if not provided
attributes.comms.email_optout is defaulted to false 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 an id specified.
Tokens without a profile id 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