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 Key | Description | Type |
---|---|---|
name | Name of this retargeting segment. | string |
*description | Description 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
Key | Description | Type |
---|---|---|
invertRule | Indicates if user group specified in rule should be included in or excluded from targeting. | boolean: false (include), true (exclude) |
event | Type of event by which the pool of retargeted users should be defined. Allowed values: beaconImpression, lineItemImpression, lineItemClick, advertiserImpression, advertiserClick, packageImpression, packageClick | string |
eventObjectResourceIds | ID(s) associated with the object(s)—e.g., advertisers, packages—for which event s 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
Key | Description | Type |
---|---|---|
minimum | Minimum number of times the event must occur before retargeting rule applies. | integer |
period | Number of minutes/hours/days used to define event frequency. | integer |
periodUnits | Unit of time used to define event frequency. Allowed values: minutes, hours, days | string |
velocity
DTO
Key | Description | Type |
---|---|---|
periodInDays | Number of days in which change in user interest must occur before retargeting rule applies. | integer |
change | % change in number of event s recorded for retargeted users. | float |
ruleSet
DTO
Key | Description | Type |
---|---|---|
op | Boolean operator to group rules and/or rulesets defined within this ruleset. Allowed values: and, or | string |
rules | Nested 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 |
ruleSets | Nested 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":[]}