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"

duration

integer

Number of days users are in the segment

90

Request Format:

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

Example Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -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",
        "duration": 90
    }' \
    "https://services.adroll.com/audience/v1/segments?apikey=MYAPIKEY"

Example Response:

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

Retrieve the segment

Request Format:

curl -H 'Authorization: Token YOUR_TOKEN' \
    "https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"

Example Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    "https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"

Example Response:

{
  "advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
  "conversion_value": null,
  "created_date": 1486523382000,
  "duration": 90,
  "expression": "category == \"Hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain",
  "is_active": true,
  "is_conversion": false,
  "name": "Your External Data Segment",
  "segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
  "source": "slargma",
  "tags": "s",
  "type": "arbitrary_data",
  "url": "cart*"
}

Update the segment

Request Arguments

You can choose to edit the name, url, or duration 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*

duration

integer

Number of days users are in the segment

90

Request Format:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -H "Content-Type: application/json" \
    -d '{
        "name": "{segment_name}",
        "url": "{url_pattern}",
        "duration": "{duration}"
    }' \
    "https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"

Example Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{
    "name": "Your Edited External Data Segment",
    "url": "buy*",
}' \
"https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"

Example Response:

{
  "result": "success",
  "segment": {
    "advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
    "conversion_value": null,
    "created_date": 1486523382000,
    "duration": 90,
    "expression": "category == \"Hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain",
    "is_active": true,
    "is_conversion": false,
    "name": "Your Edited External Data Segment",
    "segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
    "source": "slargma",
    "tags": "s",
    "type": "arbitrary_data",
    "url": "buy*"
  }
}

Delete the segment

Request Format:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -X DELETE \
    "https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"

Example Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -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 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)".