Manage External Data Segments

The guide shows you how to create and manage external data segments using the Audience API.

Create the segment

Request Arguments

Key Data Type Description Example
advertiser_id string ID of the advertiser to create a new segment for MOCQ3OFYHRA4PGY6VCZYRT
type string Type of the segment, in this case arbitrary_data arbitrary_data
name string Name of the segment Entertainment Segment
url string The URL pattern you want to apply your external data filter against /checkout/cart*
expression string The external data expression - see External Data Expressions category == "entertainment"

Request Format:

curl --user api@example.com:password \
    -H "Content-Type: application/json" \
    -d '{
        "name": "{segment_name}",
        "advertiser_id": "{advertiser_id}",
        "type": "arbitrary_data",
        "url": "{url_pattern}",
        "expression": "{external_data_expression}"
    }' \
    "https://services.adroll.com/audience/v1/segments?apikey=MYAPIKEY"

Example Request:

curl --user api@example.com:password \
    -H "Content-Type: application/json"
    -d '{
        "name": "Your External Data Segment",
        "advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
        "type": "arbitrary_data",
        "url": "cart*",
        "expression": "category == \"hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain"
    }' \
    "https://services.adroll.com/audience/v1/segments?apikey=MYAPIKEY"

Example Response:

{
  "result": "success",
  "segment": {
    "advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
    "segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
    "name": "Your External Data Segment",
    "url": "cart*",
    "expression": "category == \"Hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain",
    "type": "arbitrary_data",
    "source": "slargma",
    "tags": "s",
    "created_date": 1486523382000
  }
}

Retrieve the segment

Request Format:

curl --user api@example.com:password \
    "https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"

Example Request:

curl --user api@example.com:password \
    "https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"

Example Response:

{
  "advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
  "segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
  "name": "Your External Data Segment",
  "url": "cart*",
  "expression": "category == \"hotels\" && [\"Hilton\", \"Westin\", \"Sheraton\"] contains refererDomain",
  "type": "arbitrary_data",
  "source": "slargma",
  "tags": "s",
  "created_date": 1486523382000
}

Update the segment

Request Arguments

You can choose to edit the name, url, and expression of the segment.

Key Data Type Description Example
name string Name of the segment Fashion Segment
url string The URL pattern you want to apply your external data filter against /women/shoes*
expression string The external data expression - see External Data Expressions category == "fashion"

Request Format:

curl --user api@example.com:password \
    -H "Content-Type: application/json" \
    -d '{
        "name": "{segment_name}",
        "url": "{url_pattern}",
        "expression": "{expression}"
    }' \
    "https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"

Example Request:

curl --user api@example.com:password \
-H "Content-Type: application/json" \
-d '{
    "name": "Your Edited External Data Segment",
    "url": "buy*",
    "expression": "category == \"contractors\" && vertical contains \"construction\""
}' \
"https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"

Example Response:

{
  "result": "success",
  "segment": {
    "advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
    "segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
    "name": "Your Edited External Data Segment",
    "url": "buy*",
    "expression": "category == \"contractors\" && vertical contains \"construction\"",
    "type": "arbitrary_data",
    "source": "slargma",
    "tags": "s",
    "created_date": 1486523382000
  }
}

Delete the segment

Request Format:

curl --user api@example.com:password \
    -X DELETE \
    "https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"

Example Request:

curl --user api@example.com:password \
    -X DELETE \
    "https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"

Example Response:

{
  "result": "success",
  "segment_id": "IIEBKZ5R7BAADIF3BVVY7T"
}

External Data Expressions

You may use the expressions to target your Segment audiences based on data passed in through the AdRoll pixel.

It supports the following operators

Operator Description Example
== equals (case sensitive) category == "entertainment"
> greater than age > 21
< less than age < 21
>= greater than or equal to age >= 21
<= less than or equal to age <= 21
&& and category == "contractors" && vertical contains "construction"
|| or category == "contractors" || vertical contains "construction"
contains string or array contains value category contains "contractors" || [94102, 94115] contains zipcode
~= regex match category ~= ".*education.*"

Additional Notes

  • You can use single quotes ' for strings instead of double quotes ("). For example: category == 'foobar'.
  • You can use brackets to specify order of operations. For example, "a > 1 && (b > 2 || c < 3)".