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)".