Create Segment
POST {{baseUrl}}/directories/:directoryId/segments
Create a segment.
This API call is only available to XM Directory users.
Rate Limits
This API allows you to make 60 calls per minute.
The size of the JSON body accepted by this API call is 10 kB.
Formulating a multi-category and deeply nested sample criteria allows one to describe a search with high precision, but it also comes with the pitfall of inadvertently including criteria that are contradictory or impossible to satisfy. We recommend that you keep your sample criteria flat and concise.
The JSON object represented by the criteria key allows one to specify a single criterion or group and nest criteria.
Suppose you have criteria W, X, Y and Z.
A correctly constructed criteria key will allow you to specify any of the following and more:
- Retrieve contacts which satisfy   W.
- Retrieve contacts which satisfy   X.
- Retrieve contacts which satisfy   Y.
- Retrieve contacts which satisfy   Z.
- Retrieve contacts which satisfy   (W or X).
- Retrieve contacts which satisfy   (W and X).
- Retrieve contacts which satisfy   (W or Y).
- Retrieve contacts which satisfy   (W or Z).
- Retrieve contacts which satisfy   (X or Y).
- Retrieve contacts which satisfy   (X and Y).
- Retrieve contacts which satisfy   (X or Z).
- Retrieve contacts which satisfy   (W or (X and Y)).
- Retrieve contacts which satisfy   (W or (X and Z)).
- Retrieve contacts which satisfy   (W or (X and (Y or Z))).
- Retrieve contacts which satisfy   (X and (Y or (Z and W))).
- Retrieve contacts which satisfy   (X and Y) or (Z and W).
- and so on...
Constructing the simpleFilter JSON object
At its core, the JSON object is formed by parameters describing the evaluation of a single criterion or is formed by criteria that are grouped together with a conjunction (and, or), thereby creating a filterGroup.
Simple Filter Criterion
Below are the supported filter criteria and their associated JSON syntax. Read beyond the table to understand the mechanics of grouping and nesting criteria via the filterGroup described below.
Criterion | JSON Syntax | As simpleFilter |
---|---|---|
{filterType: comparison: stringComparison, value: plainString} | simpleFilter: { filterType: comparison: startsWith, value: pritty} | |
first name | {filterType: firstName, comparison: stringComparison, value: plainString} | simpleFilter: { filterType: firstName, comparison: eq, value: Iain} |
last name | {filterType: lastName, comparison: stringComparison, value: plainString} | simpleFilter: { filterType: lastName, comparison: neq, value: reezy} |
external data reference | {filterType: extRef, comparison: stringComparison, value: plainString} | simpleFilter: { filterType: extRef, comparison: contains, value: beryl} |
any field (Notes) | {filterType: anyField, comparison: stringComparison, value: plainString} | simpleFilter: { filterType: anyField, comparison: doesNotContain, value: math} |
subscribed | {filterType: subscribed, comparison: booleanComparison} | simpleFilter: { filterType: subscribed, comparison: true} |
embedded data (Notes) | {filterType: embeddedData, comparison: embeddedDataComparison, field: plainString, value: plainString} | simpleFilter: { filterType: embeddedData, comparison: eq, field: citizenship ,value :switzerland"} |
embedded data (Notes) | simpleFilter: { filterType: embeddedData, comparison: gte, field: age, value: 23} | |
transaction data (Notes) | {filterType: transactionData, comparison: transactionDataComparison, field: plainString, value: plainString} | simpleFilter: { filterType: transactionData, comparison: eq, field: citizenship, value: switzerland} |
transaction date (Notes) | {filterType: transactionData, comparison: transactionDateComparison, field: Q_TransactionDateTime, value: dateOrUTCDateTime} | simpleFilter: { filterType: transactionData, comparison: gt, field: Q_TransactionDateTime, value: 2016-12-04 15:41:34,} |
info field state | {filterType: infoFieldState, comparison: emptyComparison, field: infoField} | simpleFilter: { filterType: infoFieldState, comparison: empty, field: |
embedded data field state (Notes) | {filterType: embeddedDataFieldState, comparison: emptyComparison, field: plainString} | simpleFilter: { filterType: embeddedDataFieldState, comparison: notEmpty, field: edf11} |
in list | {filterType: inList, comparison: booleanComparison, mailingListId: listId} | simpleFilter: { filterType: inList, comparison: true, mailingListId: CG_0CgJ5dUewtIvxIN} |
in sample | {filterType: inSample, comparison: booleanComparison, sampleId: sampleId} | simpleFilter: { filterType: inSample, comparison: false, sampleId: CG_77fAbR6TjhDxOKh} |
created | {filterType: created, comparison: numericComparison, value: dateOrUTCDateTime} | simpleFilter: { filterType: created, comparison: eq, value: 2017-03-01 23:18:12} |
created | simpleFilter: { filterType: created, comparison: neq, value: 2017-03-08} | |
unsubscribe date | {filterType: unsubscribeDate, comparison: numericComparison, value: dateOrUTCDateTime} | simpleFilter: { filterType: unsubscribeDate, comparison: eq, value: 2017-01-20 21:00:11} |
last modified date | {filterType: lastModified, comparison: numericComparison, value: dateOrUTCDateTime} | simpleFilter: { filterType: lastModified, comparison: gt, value: 2013-10-31 23:48:59} |
last email date | {filterType: lastEmail, comparison: numericComparison, value: dateOrUTCDateTime} | simpleFilter: { filterType: lastEmail, comparison: lt, value: 2015-11-30 08:00:00} |
last invite date | {filterType: lastInvite, comparison: numericComparison, value: dateOrUTCDateTime} | simpleFilter: filterType: lastInvite, comparison: gte, value: 2016-10-04} |
last response date | {filterType: lastResponse, comparison: numericComparison, value: dateOrUTCDateTime} | simpleFilter: { filterType: lastResponse, comparison: lte, value: 2015-05-20} |
total emails | {filterType: totalEmails, comparison: numericComparison, value: nonNegativeInt} | simpleFilter: { filterType: totalEmails, comparison: lte, value: 2} |
total invites | {filterType: totalInvites, comparison: numericComparison, value: nonNegativeInt} | simpleFilter: { filterType: totalInvites, comparison: gte, value: 5} |
total responses | {filterType: totalResponses, comparison: numericComparison, value: nonNegativeInt} | simpleFilter: { filterType: totalResponses, comparison: neq, value: 7} |
response rate (Notes) | {filterType: responseRate, comparison: numericComparison, value: nonNegativeInt} | simpleFilter: { filterType: responseRate, comparison: gt, value: 49} |
average response time (Notes) | {filterType: averageResponseTime, comparison: numericComparison, value: nonNegativeInt} | simpleFilter: { filterType: averageResponseTime, comparison: gt, value: 2} |
points | {filterType: points, comparison: numericComparison, value: nonNegativeInt} | simpleFilter: { filterType: points, comparison: lt, value: 27} |
Leading and trailing spaces
String values associated with JSON keys that are not filterType or comparison will have any leading and trailing spaces trimmed off.
The JSON keys filterType and comparison have strict values enumerated herein. Any deviation from those values will result in an error being returned in the API response.
Filter Group
The filter group allows one to create complex and nested criteria.
The filter group is equivalent to taking several simple criterion (X, Y, Z), inserting a common boolean operator between them, and surrounding the criteria in parentheses, e.g. (X and Y and Z) or (X or Y or Z).
Filter groups can be nested within other filter groups, allowing you to produce statements like (X and (Y or Z)).
simpleFilterGroup JSON Syntax | As simpleFilter |
---|---|
{conjunction: conjunction, filters: simpleFilters](../../../sampleDefinitions.json/paths/~1directories~1{directoryId}~1samples~1definitions#simplefilters)} | simpleFilter: { conjunction: or, filters: [{ comparison: eq, filterType: lastName, value: test},{ comparison: gte, filterType: totalEmails, value: 7}]} |
simpleFilter: { conjunction: or, filters: [{ comparison: eq, filterType: lastName, value: test},{ comparison: gte, filterType: totalEmails, value: 7},{ conjunction: and, filters: [{ comparison: lte, filterType: embeddedData, field: experience, value: 13},{ comparison: true, filterType: subscribed}]},]} |
Valid associations between filter, filterGroup and filters
simpleFilter => simpleFilterGroup <===> simpleFilters
One cannot mix and match between these associations.
booleanComparison
JSON data type: boolean Valid values are: - true - false
embeddedDataComparison
JSON data type: string Valid values are: - contains - doesNotContain - eq - neq - gt - lt - gte - lte
Embedded data comparison is not case sensitive for the values it is inspecting. EdVAlue is equivalent to edvalue, EDVALUE, eDvaLUE and so on...
transactionDataComparison
JSON data type: string Valid values are: - eq
Transaction data comparison is not case sensitive for the values it is inspecting. TdVAlue is equivalent to tdvalue, TDVALUE, tDvaLUE and so on...
**Important: transactionDataComparison <!-- Commented out due a a defect making the comparisons below not work.
transactionDateComparison
JSON data type: dateOrUTCDateTime Valid values are: - gt - gte - le - lte
Note: on date can be implemented by AND-ing a gte day-before with lte day-after -->
emptyComparison
JSON data type: string Valid values are: - empty - notEmpty
numericComparison
JSON data type: string Valid values are: - eq - neq - gt - lt - gte - lte
stringComparison
JSON data type: string Valid values are: - startsWith - eq - neq - contains - doesNotContain
String comparison is not case sensitive for the values it is inspecting. sEArcH is equivalent to search, SEARCH, SeaRCh and so on...
conjunction
JSON data type: string Valid values are: - and - or
date
JSON data type: string Value represents a date. The value must match the format yyyy-MM-dd.
dateOrUTCDateTime
JSON data type: string Value represents a UTC date time. The value must match the format yyyy-MM-ddThh:mm:ssZ.
simpleFilters
JSON data type: array Must have a minimum of two items in the array; there is no maximum.
The JSON array can contain any combination of simpleFilterGroup(s) and simple filter criterion.
For example you could have:
[
<simpleFilterGroup1>,
<simpleFilterGroup2>,
<firstName criterion>
]
or
[
<inList criterion>,
<subscribed criterion>,
<extRef criterion>
]
and so on...
infoField
JSON data type: string Valid values are: - email - firstName - lastName - extRef
listId
JSON data type: string Value must match the regex, CG_[0-9a-zA-Z]{11,15}$
When specifying a mailingListId or a sampleId for the filterTypes, inList or inSample, take care to not associate the value with an incompatible filterType.
An invalid id value may affect resultant samples.
nonNegativeInt
JSON data type: number Value is treated as an integer and must be greater than or equal to 0.
plainString
JSON data type: string There is no minimum or maximum length.
sampleId
JSON data type: string Value must match the regex, CG_[0-9a-zA-Z]{11,15}$
When specifying a mailingListId or a sampleId for the filterTypes, inList or inSample, take care to not associate the value with an incompatible filterType.
An invalid id value may affect resultant samples.
surveyId
JSON data type: string Value must match the regex, SV_[0-9a-zA-Z]{11,15}$
Any Field
anyField is a superset of email, firstName, lastName and extRef. It does not mean a fuzzy-search like filter on any piece of data belonging to a contact.
Embedded Data
Currently only a total of 5 embedded data related filterTypes can be included in the filter. The filterTypes associated with this restriction are embeddedData and embeddedDataFieldState.
The field that one provides for the embeddedData or embeddedDataFieldState filters are case-sensitive. For example, edFIEld is different from EDFIELD or edfield.
Response Rate
The value for the responseRate filterType should be treated as a percentage out of 100, i.e. a value of 50 is 50% and a value of 7 is 7%.
Average Response Time
The value for the averageResponseTime filterType should be treated as the hours it takes for a recipient to respond.
The precision of average response time is limited to hours.
Request Body
{"criteria"=>{"simpleFilter"=>{"filterType"=>"anyField", "comparison"=>"doesNotContain", "value"=>"<string>", "mailingListId"=>"<string>"}}, "name"=>"<string>", "description"=>"<string>"}
HEADERS
Key | Datatype | Required | Description |
---|---|---|---|
Content-Type | string | ||
Accept | string |
RESPONSES
status: OK
{"result":{"segmentId":"\u003cstring\u003e"},"meta":{"httpStatus":"\u003cstring\u003e","requestId":"\u003cstring\u003e","notice":"\u003cstring\u003e"}}