New Retargeting Segment

POST {{campaign_url}}/advertisers/:advertiserId/retargetingSegments

Create a new retargeting segment

You can create a new retargeting segment by sending this POST request. To define the segment's retargeting rules, open the body tab and edit the JSON object.

For DTO fields rule and ruleSet, see the corresponding DTO tables below for guidance on entering values.

Request Body (Definitions)

*Optional element

JSON Object KeyDescriptionType
nameName of this retargeting segment.string
*descriptionDescription of targeted user group(s).string
rule (DTO)Information on a single user group to retarget. Define if targeting only one user group (e.g., A).

Cannot be defined when ruleSet is defined, required otherwise.
DTO
ruleSet (DTO)Rules and/or nested rulesets bound by a boolean operator. Define if targeting more than one user group (e.g., A OR B).

Cannot be defined when rule is defined, required otherwise.
DTO

rule DTO

KeyDescriptionType
invertRuleIndicates if user group specified in rule should be included in or excluded from targeting.boolean: false (include), true (exclude)
eventType of event by which the pool of retargeted users should be defined.

Allowed values: beaconImpression, lineItemImpression, lineItemClick, advertiserImpression, advertiserClick, packageImpression, packageClick
string
eventObjectResourceIdsID(s) associated with the object(s)—e.g., advertisers, packages—for which events are tracked.comma-separated array of strings
frequency (DTO)event frequency of retargeted users.

Cannot be defined when velocity is defined.
DTO
velocity (DTO)event velocity (i.e., increase/decrease in interest) displayed by retargeted users.

Cannot be defined when frequency is defined.
DTO

frequency DTO

KeyDescriptionType
minimumMinimum number of times the event must occur before retargeting rule applies.integer
periodNumber of minutes/hours/days used to define event frequency.integer
periodUnitsUnit of time used to define event frequency.

Allowed values: minutes, hours, days
string

velocity DTO

KeyDescriptionType
periodInDaysNumber of days in which change in user interest must occur before retargeting rule applies.integer
change% change in number of events recorded for retargeted users.float

ruleSet DTO

KeyDescriptionType
opBoolean operator to group rules and/or rulesets defined within this ruleset.

Allowed values: and, or
string
rulesNested list of rules grouped together in this ruleset.

Example ruleSet containing two rules: include (A AND B).
comma-separated array containing one or more rule DTOs
ruleSetsNested list of rulesets.

Example ruleSet containing two nested ruleSets: include ((A OR B) AND (C OR D))
comma-separated array containing one or more ruleSet DTOs

Request Body

{"name"=>"irene test - include (A OR B) & (C OR D)", "description"=>"retarget users that fall in any of the following group combos: AC, BC, AD, BD; A = served 2+ impressions from specified advertiser within last 8 hours, B = clicked specified package's ads at least once within last 20 hours, C = caused 2+ pixel fires in last 8 hours, D = pixel fires increased by 50% in 2 days", "ruleSet"=>{"op"=>"and", "ruleSets"=>[{"op"=>"or", "rules"=>[{"invertRule"=>false, "event"=>"advertiserImpression", "eventObjectResourceIds"=>["{{advertiserId}}"], "frequency"=>{"minimum"=>2, "period"=>8, "periodUnits"=>"hours"}}, {"invertRule"=>false, "event"=>"packageClick", "eventObjectResourceIds"=>["{{packageId}}"], "frequency"=>{"minimum"=>1, "period"=>20, "periodUnits"=>"hours"}}]}, {"op"=>"or", "rules"=>[{"invertRule"=>false, "event"=>"beaconImpression", "eventObjectResourceIds"=>["{{beaconId}}"], "frequency"=>{"minimum"=>2, "period"=>8, "periodUnits"=>"hours"}}, {"invertRule"=>false, "event"=>"beaconImpression", "eventObjectResourceIds"=>["{{beaconId}}"], "velocity"=>{"periodInDays"=>2, "change"=>50}}]}]}}

RESPONSES

status: Created

{"data":[{"id":"2210947588","marketId":"1","resourceType":"retargetingSegment","name":"irene test - include (A OR B) \u0026 (C OR D)","description":"retarget users that fall in any of the following group combos: AC, BC, AD, BD; A = served 2+ impressions from specified advertiser within last 8 hours, B = clicked specified package's ads at least once within last 20 hours, C = caused 2+ pixel fires in last 8 hours, D = pixel fires increased by 50% in 2 days","ruleSet":{"op":"and","ruleSets":[{"op":"or","rules":[{"invertRule":false,"event":"advertiserImpression","eventObjectResourceIds":["1608775066"],"frequency":{"minimum":2,"period":8,"periodUnits":"hours"}},{"invertRule":false,"event":"packageClick","eventObjectResourceIds":["1608784938"],"frequency":{"minimum":1,"period":20,"periodUnits":"hours"}}]},{"op":"or","rules":[{"invertRule":false,"event":"beaconImpression","eventObjectResourceIds":["1608785239"],"frequency":{"minimum":2,"period":8,"periodUnits":"hours"}},{"invertRule":false,"event":"beaconImpression","eventObjectResourceIds":["1608785239"],"velocity":{"periodInDays":2,"change":50}}]}]},"advertiserId":"1608792487","createdAt":"2022-08-30T02:49:56Z","updatedAt":"2022-08-30T02:49:56Z"}],"errors":[]}