Creating Audiences

Learn more about AdRoll Audiences on the Help Center.

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 --user apihelp@adroll.com:password \
    -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 should conform to the RFC 5322 standard.

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 AdRoll cookies using 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": "crm",
  "data": [
    {
      "id": "MY_USER_ID_1"
    },
    {
      "id": "MY_USER_ID_2"
    }
  ]
}

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.

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
  • = — Attribute value must exactly match
  • != — Attribute does not exactly match

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" :  "=",
        },
        {
           "name" : "domain",
           "values" : ["example.com"],
           "comparator" :  "=",
        }
    ]
}

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",
  "created_by_user_eid": "MY_USER_EID",
  "components": [
    {
      "component_segment_eid": "MY_SEGMENT_EID_1"
    },
    {
      "component_segment_eid": "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.