Last updated: Aug 02 2018

Area: Episerver Profile Store Applies to versions: 1.6.0 and higher

Managing segments

This topic shows how to get, filter, create, and replace segments.

In this topic

Segment

The segment request contains a fixed set of fields.

{
    "Name": "string",
    "Description": "string",
    "Scope": "string",
    "SegmentManager": "string",
    "ProfileQuery": "string"
}

Property descriptions

  • SegmentId. Required. The ID of the segment.
  • Name. The segment name.
  • Scope. Required. The segment scope; acts as a filter, which means that if a scope does not exist, the result is empty instead of producing an error.
  • SegmentManager. The segment manager.
  • ProfileQuery. Required. 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 eq, ne, gt, ge, lt, le, and, or, not. An example of ProfileQuery is:

    Name eq profile1
    • [Profile property] is case-sensitive.
    • Using string type properties with comparable operators such as gt, ge, lt, le 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 that segment. If the Scope property is defined in a segment, the matching profiles is the count based on Scope. For detailed profile information that match segments, use export segment API.  
  • AvailableForPersonalization. A boolean that indicates that this segment is available for visitor group.
  • Archived. The boolean that indicates a segment as archived since 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.

API methods

Get segment

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

Returns HTTP 200 OK with all the scopes available in the environment. Also, the default scope is added at the end of the list.

Example of response body:

{
    "SegmentId": "2259a8f6-22b4-4166-9334-96fcfb3d40d6",
    "Name": "Profile with name Admin",
    "Scope": "default",
    "SegmentManager": "user1",
    "ProfileQuery": "Name eq Admin",
    "ProfileFilter": null,
    "MatchingProfiles": 2,
    "AvailableForPersonalization": false,
    "Archived": false,
    "FavoredBy": ["user1", "user2"],
    "CreatedDate": 2018-01-01T05:34:18,
    "ModifiedDate": 2018-01-01T05:34:18
}

Note: If either ProfileQuery or ProfileFilter is null then it will not display in response. (ProfileQuery is null if the segment is created via InsightUI, ProfileFilter is also null if the segment is created via ProfileAPI).

Filter segments

Similar to TrackEvent and Profile, Segment can also have the ability to get segments based on OData query. If $skip and $top must be less than 10.000.

Create segment

Endpoint: POST api/v1.0/segments

Example of request body:

{
    "Name": "Profile with name Admin", // Required
    "Description": "Match all profile with name is 'Admin'",
    "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", "ProfileQuery": "Name eq Admin" // Required. }

Example of response body:

{
    "SegmentId": "2259a8f6-22b4-4166-9334-96fcfb3d40d6",
    "Name": "Profile with name Admin",
    "Scope": "default",
    "SegmentManager": "user1",
    "ProfileQuery": "Name eq Admin",
    "MatchingProfiles": 2,
    "AvailableForPersonalization": false,
    "Archived": false,
    "FavoredBy": ["user1", "user2"],
    "CreatedDate": 2018-01-01T05:34:18,
    "ModifiedDate": 2018-01-01T05:34:18
}

Replace segment

Endpoint: PUT api/v1.0/scopes/{id}

  • If segment ID not exists, 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": "Profile with more than 10 visits", // Required
    "Description": "Profile with more than 10 visits",
    "Scope": "3542003a-1518-4a28-99f1-303a7e74f888", // 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", "ProfileQuery": "Visits gt 10" // Required. }

Example of response body:

{
    "SegmentId": "a91e87e4-f7e6-46b4-b96c-4a3dc089f8d9",
    "Name": "Profile with more than 10 visits",
    "Scope": "3542003a-1518-4a28-99f1-303a7e74f888",
    "SegmentManager": "user1",
    "ProfileQuery": "Visits gt 10",
    "MatchingProfiles": 5,
    "AvailableForPersonalization": false,
    "Archived": false,
    "FavoredBy": [],
    "CreatedDate": 2018-01-01T04:11:45,
    "ModifiedDate": 2018-01-01T04:11:45
}

Comments