Creating Audiences¶

Audience Types

URL
CRM
Partner
External Data
Attribute
Composite
CrossChannel Lookalike

URL ¶

Type: url

To create a URL Audience, you’ll need to create a rule on the Pixel. To create a rule on a Pixel, you call POST /api/v1/rule/create with the following parameters:

pixel

Pixel EID to create the rule on. You can retrieve the Pixel EID by calling GET /api/v1/advertisable/get_pixel.

type

The type of the rule being created. You can’t change this later. One of:

c — Conversion
b — Visited their cart
l — Viewed a list of products
u — Viewed a single product
s — Segment. Use this if a one of the previous doesn’t fit your situation

match_method

Set to url_match when creating a URL Audience

pattern

Pattern expression that matches your URL. You can specify wildcards in the pattern. Max length of 255.

name

Name for this rule. This must be unique within each Pixel. Max 128 characters. Alphanumeric with -, _, (, ), [, ], <, >.

display_name (Optional)

Display name for reporting. Names cannot contain <, >, ', or ". Max 128 characters.

order

Priority order in which this rule needs to be applied among the others. Must be unique in the Pixel. The lower the number, the higher the priority. Highest priority is 0.

For example, to create an audience of people who have visited a a cart page:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -F pixel=MY_PIXEL_EID \
    -F type=b \
    -F match_method=url_match \
    -F pattern='*/cart/'  \
    -F name=shopping_cart \
    -F order=3 \
    https://services.adroll.com/api/v1/rule/create?apikey=MYAPIKEY

CRM ¶

Type: crm

Target your users by email address by creating a CRM Audience.

To create a CRM Audience, call POST /audience/v1/segments with the following body:

{
  "advertiser_id": "MY_ADVERTISALE_EID",
  "name": "Newsletter subscribers",
  "type": "crm",
  "data": [
    {
      "email": "test1@example.com"
    },
    {
      "email": "test2@example.com"
    }
  ]
}

Emails need to be either: - RFC 5322 emails, e.g. test1@example.com - MD5 hashes of RFC 5322 emails, e.g. aa99b351245441b8ca95d54a52d2998c (MD5 hash of “test1@example.com”)

You can optionally specify a timestamp, ts, to indicate when a user entered a Audience (the default timestamp is now). Timestamps can be up to 540 days old or up to 7 days in the future. Timestamps are specified as seconds since epoch.

Partner ¶

Type: custom

Target people using your custom user identifiers. These identifiers must have been previously matched to cookies using a cookie-match.

To create a Partner Audience, call POST /audience/v1/segments with the following body:

{
  "advertiser_id": "MY_ADVERTISABLE_EID",
  "name": "Downloaded whitepaper",
  "type": "custom",
  "duration": 30,
  "data": [
    {
      "id": "MY_USER_ID_1"
    },
    {
      "id": "MY_USER_ID_2"
    }
  ]
}

The duration parameter, controls the number of days that a user will remain in the defined segment. After that period, the identifiers in the segment should be refreshed in order to repopulate the segment with up-to-date profiles. We recommend a duration of 90 days. Longer durations expose the same ads to the same audience for an extended period of time and can lead to ad fatigue.

You can optionally specify a timestamp, ts, to indicate when a user entered a segment (the default timestamp is now). Timestamps can be up to 540 days old or up to 7 days in the future. Timestamps are specified as seconds since epoch.

There are not limits on the number of identifiers that can be added to a segment. However, our APIs limits the size of the body request up to 20MB. If you require to append identifiers to an existing segment you should call POST /audience/v1/segments/(segment_id) with the following body:

{
  "name": "Downloaded whitepaper",
  "type": "custom",
  "data": [
    {
      "id": "MY_USER_ID_3"
    },
    {
      "id": "MY_USER_ID_4"
    }
  ]
}

External Data ¶

Type: arbitrary_data

See Manage External Data Segments.

Attribute ¶

Type: user_attributes

Attribute Audiences target users based on data from third party sources.

Note

Access to Attribute Audiences is not available to everyone. Contact your Account Manager if you’re interested in Attribute Audiences.

To create an Attribute Audience, you specify one or more attributes. You can retrieve a list of available attribute names and values for your Advertisable by calling GET /audience/v1/user_attribute_names/(advertisable_eid).

type: Set to user_attributes to create an Attribute Audience
attributes: Array of attributes that define the Audience
use_first_party_data (Optional): If true, use first-party data sources. Defaults to true.
use_third_party_data (Optional): If true, use third-party data sources. Defaults to true.

Each object in the attributes array consists of:

name

Name of the attribute

values

Array of target values for the named attribute. Case sensitive.

comparator

Operator to use when comparing a user to an attribute value. Possible values include:

in — Attribute matches any value in the list
not_in — Attribute does not match any value in the list

Note

If values is null then comparator must also be null and that means that membership to the audience is defined as the existence of name.

For example, to create an Attribute Audience that targets managers at example.com, call POST /audience/v1/segments with the following body:

{
    "advertiser_id": "MY_ADVERTISABLE_EID",
    "name": "Management at example.com",
    "type": "user_attributes",
    "attributes": [
        {
           "name" : "ccm_seniority",
           "values" : ["Management"],
           "comparator" :  "in",
        },
        {
           "name" : "domain",
           "values" : ["example.com"],
           "comparator" :  "in",
        }
    ]
}

Composite ¶

Type: composite

Composite Audiences apply a set union relationship between two or more Audiences. A composite audience can narrow down Audiences to a more precise target audience. E.g. usage can be all audiences who viewed pages at least 5 times and are interested in snowboarding.

To create a Composite Audience, call POST /audience/v1/segments with the following body:

{
  "advertiser_id": "MY_ADVERTISABLE_EID",
  "name": "Managers at example.com who have downloaded a whitepaper",
  "type": "composite",
  "duration": 30,
  "components": [
    "MY_SEGMENT_EID_1",
    "MY_SEGMENT_EID_2"
  ]
}

components is a list of two or more audiences specified by their Segment EID. All components must be valid existing audiences and must not be another composite audience. You cannot have multiple Attribute Audiences in a Composite Audience.

CrossChannel Lookalike ¶

Type: crosschannel_lal

CrossChannel Lookalike Audiences gives you the ability to run campaigns seamlessly across inventory sources (Facebook Lookalike campaigns and Web Prospecting campaigns).

To create a CrossChannel Lookalike audience, call POST /audience/v1/segments with the following body:

{
  "advertiser_id": "MY_ADVERTISABLE_EID",
  "name": "Test CrossChannel Lookalike audience",
  "type": "crosschannel_lal",
  "source_segment_eid": "SOURCESEGMENT_EID",
  "duration": 30,
  "size": 6,
  "countries": [
    {
        "country_code": "CL",
        "include": "True"
    }
  ],
  "allow_international_seeds": "True"
}

countries (Optional)

List of countries to target the audience. The actual limit is just 1 country.

source_segment_eid

Source segment eid to created the audience. The current restrictions for the source segment are:

The source segment must be of type CRM, pages viewed or arbitrary data.
The source segment size must be of at least 100 total visitors AND 1100 for facebook visitors.

size

A choice between broadness and narrowness on a 1-10 scale.

allow_international_seeds

Boolean indicating if allow or not international seeds.

Creating Audiences¶

URL¶

CRM¶

Partner¶

External Data¶

Attribute¶

Composite¶

CrossChannel Lookalike¶