Skip to main content
Users
Developers
CloudPortalLogin
  • Powered byPowered by
Introduction to the Sitecore Send API
Getting started with the Sitecore Send API
API reference
  • Sitecore Send API documentation
  • API reference
  • Segments
  • Create a segment with criteria

Create a segment with criteria

POST /lists/{MailingListID}/segments/create.{Format}

Creates a new segment with criteria in a specific email list. You must specify how many subscribers are returned based on the criteria that you defined to segment your list.

Request

Parameter

In

Type

Required

Description

Accept

header

string

true

Determines the expected format and data type to retrieve the response data.

Value: application/json

MailingListID

path

string

true

The ID of the email list where the segment is created.

Format

path

string

true

The supported file format for getting a response.

Possible values: json and xml.

apikey

query

string

true

The API key of your account.

Name

body

string

true

The name of the segment.

MatchType

body

string

false

Specifies how subscribers are returned by your segment based on matching criteria:

  • All (Default) - returns subscribers that match all the given criteria.

  • Any - returns subscribers that match any of the given criteria.

FetchType

body

string

false

Specifies how many criteria-matching subscribers are contained in your segment:

  • All - returns all criteria matching subscribers.

  • Top - returns only a maximum number of subscribers defined in FetchValue.

  • TopPercent - returns only a percentage of subscribers defined in FetchValue.

FetchValue

body

integer

false

Specifies the maximum number for FetchType:Top or percentage for FetchType:TopPercent of members to be contained in the created segment. If not specified, 0 is assumed.

Criteria

body

array

true

An array containing the criteria parameters used to filter the email list:

  • Field - the criterion used to filter the email list. See Field values.

  • Comparer - the operator that defines how to compare a Field with its Value. See Comparer values.

  • Value - the search term used to filter the specified Field.

  • LastXMinutes - constrains the results by the time that has elapsed.

  • DateFrom to DateTo - constrains the results by a date span.

  • Date Function - the value used with custom fields of dateTime data type. See DateFunction values.

Field values

Select one of the following Field values to filter the email list:

  • DateAdded - filters subscribers by the date they were added to the email list.

  • DateUpdated - filters subscribers by the date they were last updated in the email list.

  • RecipientName - filters subscribers by name.

  • RecipientEmail - filters subscribers by their email address.

  • SubscribeMethod - filters subscribers by their subscription method.

  • CustomField - filters subscribers by the value of a custom field.

  • MailingListIncluded - filters subscribers by checking if they belong to another mailing list.

  • CampaignsOpened - filters subscribers by the number of campaigns they have opened within the past 60 days.

  • LinksClicked - filters subscribers by the number of links they have clicked from the campaigns sent to them within the past 60 days.

  • CampaignName - filters subscribers by the name of the campaign they have opened.

  • LinkURL - filters subscribers by the URL of the link they have clicked.

  • CampaignSent - filters subscribers by the campaign they have received or not received.

  • Platform - filters subscribers by the platform they use.

  • OperatingSystems - filters subscribers by the operating system they use.

  • EmailClient - filters subscribers by the email client they use.

  • WebBrowser - filters subscribers by the web browser they use.

  • MobileBrowser - filters subscribers by the mobile browser they use.

  • AddedAnythingToCart - filters subscribers by their cart history in a tracked website.

  • ViewedProduct - filters subscribers by their browsing history in a tracked website.

  • PurchasedProduct - filters subscribers by their purchase history in a tracked website.

  • ViewedProductCategory - filters recipients based on their browsing history in a tracked website.

  • PurchasedProductCategory - filters recipients based on their purchase history in a tracked website.

  • ViewedProductBrand - filters recipients based on their browsing history in a tracked website.

  • PurchasedProductBrand - filters recipients based on their purchase history in a tracked website.

  • Preference - filters subscribers by their preferences.

Comparer values

Select one of the following Comparer operators to compare a criterion field with its value:

  • Is - finds subscribers where the Field is exactly equal to the specified Value.

  • IsNot - finds subscribers where the Field is not equal to the specified Value

  • Contains - finds subscribers where the Field contains the specified Value.

  • DoesNotContain - finds subscribers where the Field does not contain the specified Value.

  • StartsWith - finds subscribers where the Field starts with the specified Value.

  • DoesNotStartWith - finds subscribers where the Field does not start with the specified Value.

  • EndsWith - finds subscribers where the Field ends with the specified Value.

  • DoesNotEndWith - finds subscribers where the Field does not end with the specified Value.

  • IsGreaterThan - finds subscribers where the Field is greater than the specified Value.

  • IsGreaterThanOrEqualTo - finds subscribers where the Field is greater than or equal to the specified Value.

  • IsLessThan - finds subscribers where the Field is less than the specified Value.

  • IsLessThanOrEqualTo - finds subscribers where the Field is less than or equal to the specified Value.

  • IsBefore - finds subscribers where the Field is before the specified Value.

  • IsAfter - finds subscribers where the Field is after the specified Value.

  • IsEmpty - finds subscribers where the Field has no Value.

  • IsNotEmpty - finds subscribers where the Field contains a Value.

  • IsTrue - finds subscribers where the condition defined by the Field is true.

  • IsFalse - finds subscribers where the condition defined by the Field is false.

DateFunction values

Select one of the following to use with fields of DateTime data type.

  • Year - the four-digit year part of the date.

  • Month - the month part of the date from 1 to 12.

  • Day - the day part of the date from 1 to 31.

  • WeekDay - the day of the week from 1 to 7. For example, 1 for Sunday, 2 for Monday, and so on.

  • DaysPassed - the number of days that have passed until now.

  • HoursPassed - the number of hours that have passed until now.

  • MinutesPassed - the number of minutes that have passed until now.

RequestResponse
POST https://{hostname}/v3/lists/{MailingListID}/segments/create.{Format}?apikey=

Request body:
{
    "Name": "Engaged and Verified",
    "MatchType": "All",
    "FetchType": "All",
    "Criteria": [
       {
            "Field": "VerifiedForDoubleOptIn",
            "Comparer": "IsTrue"
        },
        {
            "Field": "LinksClicked",
            "Comparer": "Is",
            "Value": "2",
            "LastXMinutes": 43200
        },
        {
            "Field": "Age",
            "Comparer": "Is",
            "Value": "25"
        }
    ]
}

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

RequestResponse
{
  "Code": 0,
  "Error": null,
  "Context": 10199
}

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the segment created.

Do you have some feedback for us?

If you have suggestions for improving this article,

Privacy policySitecore Trust CenterCopyright © 1999-2025 Sitecore