Create Sample Definition

POST {{baseUrl}}/directories/:directoryId/samples/definitions

Create a sample definition <!--From Readme--> <!-- theme: warning -->

This API call is only available to XM Directory users.

The size of the JSON body accepted by this API call is 10kB.

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 sampleCriteria 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 sampleCriteria 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.

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)).

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

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 date or a UTC date time. The value must match the format yyyy-MM-dd HH:mm:ss or yyyy-MM-dd.

If the string value provided is of the form yyyy-MM-dd, then the HH:mm:ss will default to 00:00:00.

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: [ &ltsimpleFilterGroup1&gt, &ltsimpleFilterGroup2&gt, &ltfirstName criterion&gt ]

or

[
  &ltinList criterion&gt,
  &ltsubscribed criterion&gt,
  &ltextRef criterion&gt
]

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

{"sampleCriteria"=>{"simpleFilter"=>{"filterType"=>"email", "comparison"=>"contains", "value"=>"consectetur aute"}}, "maxSampleSize"=>0, "samplePercentage"=>29}

HEADERS

RESPONSES

status: OK

{"result":{"sampleDefinitionId":"SAMD_012345678901234"},"meta":{"httpStatus":"pa","requestId":"minim commodo ad consequat","notice":"non enim aliquip aliqu"}}