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 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
| 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 events 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":[]}