Loading...
Area: Episerver Profile Store
Applies to versions: REST API v2
Other versions:

Segments

This topic shows how to get, filter, create, and replace segments using the Episerver Profile Store API Version 2. A segment is a dynamic collection of profiles matching conditions based on filter or query, such as visitors that previously responded to a campaign.

In this topic

How it works

Profile Store has three types of segments:

  • Segments created from the Profile Store API with segment filters (Available on Version 2).
  • Segments created from the Profile Store API with OData query to profile properties.
  • Segments created from the Episerver Insight user interface.

    Note: Segments created from Insight cannot be modified from the Profile Store API. You can use all types as visitor group criteria, and can export al types to generate a profile reports.

Caching

A segment created from event filters is not real-time because it caches profiles and refreshes the profile list every day.

  • The following functions are affected by the cache:
    • Verifies list profile Id and returns profiles that match the segment.
    • Verifies list profile email and returns profiles that match the segment.
  • The following function is not affected by the cache; you get the latest profiles.
    • Execute a segment draft for previewing.

Segment properties

The segment request contains the following property fields.

  • SegmentId. Required. The ID of the segment.
  • Name. The segment name.
  • Scope.  Required. The segment scope does not have to be a registered scope; it can be any non-empty string value.
  • SegmentManager. The segment manager.
  • ProfileQuery. The query in OData $filter format; used in a segment created by Profile API.

    OData $filter format has the following form: [Profile property] [OData logical operator] [value].

    OData logical operators include eqnegtgeltleandornot. An example of ProfileQuery is:

    Name eq profile1
    • [Profile property] is case-sensitive.
    • Using string type properties with comparable operators such as gtgeltle may yield the wrong result.
    • When filtering an array, no additional brackets are needed. For example:
      FavoredBy eq "user1", "user2" (OR logic) or FavoredBy eq "user1" AND FavoredBy eq "user2"
  • ProfileFilter. The object specifies a profile filter; used in a segment created by Insight API.
  • MatchingProfiles. The number of profiles matching the segment at the moment when the segment was created or updated last time. This value is also recalculated, and the current number of matching profiles is included in the result when loading specific segment by ID using Profile Store API.

    Note: This value is not re-evaluated, and it is not updated when listing segments.

  • AvailableForPersonalization. A boolean that indicates that this segment is available for using in visitor group.
  • Archived. The boolean that indicates a segment as archived (because a segment cannot be deleted).
  • FavoredBy. The list of users that mark this segment as their favorite segment.
  • CreatedDate. The created date.
  • ModifiedDate. The modified date.
  • Filters. The segment filter collection object contains a list of filters that contain FilterDefinition to query profiles. Filters are stored in the Items property.
    Currently only one filter is supported in the filters list. Filters could be combined with ProfileQuery to create segment from both profile properties and track event properties. A Filter contains the following properties:
    • Type. The type of the filter; either Events or Profiles.
    • Query. The FilterDefinition name to match profiles from track event or profiles properties. You create FilterDefinition from FilterDefinition endpoint before creating the segment. See Filter Definition.
    • Parameters. The list of parameters and its value in a dictionary. Parameters are defined in FilterDefinition which lets several segments share the same query with different values in parameters. See Filter DefinitionAll parameters are mandatory. 

Example

{
  "Name"           : "string",
  "Description"    : "string",
  "Scope"          : "string",
  "SegmentManager" : "string",
  "Filters"        : {
                       "Items" : [{
                                    "Type"       : "Events",
                                    "Query"      : "string",
                                    "Parameters" : {
                                                     "IntParameter"      : int,
                                                     "LongParameter"     : long,
                                                     "StringParameter"   : "string",
                                                     "DateTimeParameter" : "datetime",
                                                     "DoubleParameter"   : double,
                                                     "BoolParameter"     : bool,
                                                     "TimeSpanParameter" : "timespan"
                                                   }
                                 }]
                     }
}

Segment methods

Get segment

Endpoint: GET api/v2.0/segments/{id}

Returns HTTP 200 OK with the segment specified by {id}.

Example of response body:

{
  "SegmentId"                   : "2259a8f6-22b4-4166-9334-96fcfb3d40d6",
  "Name"                        : "Profiles ordered most products",
  "Scope"                       : "default",
  "SegmentManager"              : "user1",
  "ProfileQuery"                : "",
	                          "Filters" : {
		                                "Items" : [{
				                             "Type"       : "Events",
				                             "Query"      : "fd_topOrders",
				                             "Parameters" : {
					                                      "takeTop" : 10					
				                                            }
			                                  }]
	                                      },
  "ProfileFilter"               : null,
  "MatchingProfiles"            : 2,
  "AvailableForPersonalization" : false,
  "Archived"                    : false,
  "FavoredBy"                   : ["user1", "user2"],
  "CreatedDate"                 : 2018-01-01T05:34:18,
  "ModifiedDate"                : 2018-01-01T05:34:18
}

Note: ProfileQuery and Filters is null if the segment is created via InsightUI. ProfileFilter is also null if the segment is created via ProfileAPI.

Query segments

Endpoint: GET api/v2.0/segments

Similar to TrackEvent and Profile, Segment can also get segments based on OData query. The result window size is limited and must fit the top 10000 records, so the sum of $skip and $top values must be less than 10000.

NoteMatchingProfiles value is not re-evaluated, and it is not updated when listing segments.

Create segment

Endpoint: POST api/v2.0/segments

Example of request body:

{
  "Name"           : "Profiles ordered most products", // Required
  "Description"    : "Match top 10 profiles who ordered most products",
  "Scope"          : "default", // Required, Scope just act as a filter, 
                                // which means if a scope is not exist, the result will be empty instead of giving error
  "SegmentManager" : "user1",
  "Filters"        : {
		       "Items": [{
				   "Type"       : "Events",
				   "Query"      : "fd_topOrders",
				   "Parameters" : {
				 	            "takeTop" : 10					
				                  }
			        }]
                     }
}

Example of response body:

{
  "SegmentId"                   : "2259a8f6-22b4-4166-9334-96fcfb3d40d6",
  "Name"                        : "Profiles ordered most products",
  "Description"                 : "Match top 10 profiles who ordered most products",
  "Scope"                       : "default",
  "SegmentManager"              : "user1",
	                          "Filters" : {
		                                "Items" : [{
				                             "Type"       : "Events",
				                             "Query"      : "fd_topOrders",
				                             "Parameters" : {
					                                      "takeTop" : 10					
				                                            }
			                                  }]
	                                      }
  "MatchingProfiles"            : 10,
  "AvailableForPersonalization" : false,
  "Archived"                    : false,
  "CreatedDate"                 : 2018-01-01T05:34:18,
  "ModifiedDate"                : 2018-01-01T05:34:18
}

NoteMatchingProfiles value is not re-evaluated, and it is not updated when listing segments. Set Filters.Items[0].Query to the FilterDefinition name. FilterDefinition executes KQL/OData query to match profiles from track events or profiles. Create the filter definition from the FilterDefinition endpoint before using it in event segment.

Replace segment

Endpoint: PUT api/v2.0/segments/{id}

  • If segment ID does not exist, the API creates a new segment;  otherwise, it is replaced.
  • If the segment is created by InsightUI, you cannot update that segment with the profile API.

Example of request body:

{
  "Name"           : "Top 20 profiles ordered most products", // Required
  "Description"    : "Match top 20 profiles who ordered most products",
  "Scope"          : "default", // Required, Scope just act as a filter, 
                                // which means if a scope is not exist, the result will be empty instead of giving error
  "SegmentManager" : "user1",
  "Filters"        : {
		       "Items" : [{
				    "Type"       : "Events",
				    "Query"      : "fd_topOrders",
				    "Parameters" : {
					             "takeTop" : 20					
				                   }
			         }]
	             }
}

Example of response body:

{
  "SegmentId"                   : "2259a8f6-22b4-4166-9334-96fcfb3d40d6",
  "Name"                        : "Top 20 profiles ordered most products",
  "Description"                 : "Match top 20 profiles who ordered most products",
  "Scope"                       : "default",
  "SegmentManager"              : "user1",
	                          "Filters" : {
		                                "Items" : [{
				                             "Type"       : "Events",
				                             "Query"      : "fd_topOrders",
				                             "Parameters" : {
					                                      "takeTop" : 20					
				                                            }
			                                  }]
	                                      }
  "MatchingProfiles"            : 20,
  "AvailableForPersonalization" : false,
  "Archived"                    : false,
  "CreatedDate"                 : 2018-01-01T05:34:18,
  "ModifiedDate"                : 2018-01-01T05:34:18
}

Execute segment

Endpoint: POST api/v2.0/segments/execute

The result window size Take is limited and must fit 1000 records.

Example of request body:

{
  "Scope"      : "default", // Required, Scope just act as a filter, 
	  	            // which means if a scope is not exist, the result will be empty instead of giving error
  "Filters"    : {
                   "Items": [{
			       "Type"       : "Events",
			       "Query"      : "fd_topOrders",
		   	       "Parameters" : {
		   		                "takeTop" : 20
		   	                      }
		            }]
	         },
  "Take"       : 100,
  "Skip"       : 0,
  "SortOption" : [{
                    "SortField"  : "UpdateTime",
                    "SortOrder"  : "asc"
	         }]
}

Example of response body:

{
  "items" : [
              {
                "ProfileId"          : "4a188e8c-8b73-418b-ac37-bcd26cc64a44",
                "Name"               : "admin",
                "ProfileManager"     : null,
                "FirstSeen"          : "2001-01-01T00:00:00Z",
                "LastSeen"           : "2001-01-01T11:12:13Z",
                "Visits"             : 1,
                "UpdateTime"         : "2001-01-01T11:12:13Z",
                "Info"               : {
                                         "Email" : "admin@episerver.com"
                                       },
                "ContactInformation" : [
                                         "Mailable",
                                         "Known"
                                       ],
                "DeviceIds"          : [
                                         "0187bca0-4bf3-4ce2-b35f-d843488eb8e0"
                                       ],
                "Scope"              : "default",
                "VisitorGroups"      : [],
                "Payload"            : null
              }
            ],
  "total" : 20,
  "count" : 1
}

Related topic

Last updated: Nov 08, 2019