User Lists API Reference¶

Note

If you use the APIs provided here, you are subject to the API Terms of Use, and Service Privacy Notice

Note

We’ve introduced API keys, please read Migrating to API Keys

Description¶

AdRoll User List API 1.0

Access your user list data with Adroll User List API

List of Operations¶

GET /user-lists/api/v1/userlists/ad
GET /user-lists/api/v1/userlists/adgroup
GET /user-lists/api/v1/userlists/advertisable
GET /user-lists/api/v1/userlists/audience_preview
GET /user-lists/api/v1/userlists/segment
POST /user-lists/api/v1/userlists/segment
GET /user-lists/api/v1/userlists/segment/cdp_plus
GET /user-lists/api/v1/userlists/segment/exact

Operations¶

GET /user-lists/api/v1/userlists/ad¶

Provides user list sizes broken down by ad and date

Parameters:

Query Parameters¶
Name	Required	Type	Description
`ad_eids`	True	string	Comma-separated list of ad EIDs
`end_date`	False	string	End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)
`breakdowns`	True	string	Comma-separated list of breakdowns. Must be at least one of entity, date, summary
`advertisable_eid`	True	string	A single advertisable EID
`use_uhura`	False	boolean	Explicitly ask the API to use the Uhura Backend for hll calculations
`durations`	True	string	Comma-separated list of ad durations. Must be the same length as ad_eids
`past_days`	False	integer	Equivalent to setting `end_date` to today (exclusive) and `start_date` to (today - `past_days`). Takes precedence over `start_date` and `end_date`
`start_date`	False	string	Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Successful operation

Returns UserList-Metrics-Response

GET /user-lists/api/v1/userlists/adgroup¶

Provides user list sizes broken down by AdGroup and date

Parameters:

Query Parameters¶
Name	Required	Type	Description
`end_date`	False	string	End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)
`breakdowns`	True	string	Comma-separated list of breakdowns. Must be at least one of entity, date, summary
`advertisable_eid`	True	string	A single advertisable EID
`use_uhura`	False	boolean	Explicitly ask the API to use the Uhura Backend for hll calculations
`adgroup_eids`	True	string	No description
`durations`	True	string	Comma-separated list of ad durations. Must be the same length as ad_eids
`past_days`	False	integer	Equivalent to setting `end_date` to today (exclusive) and `start_date` to (today - `past_days`). Takes precedence over `start_date` and `end_date`
`start_date`	False	string	Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Successful operation

Returns UserList-Metrics-Response

GET /user-lists/api/v1/userlists/advertisable¶

Provides user list sizes broken down by advertisable and date

Parameters:

Query Parameters¶
Name	Required	Type	Description
`end_date`	False	string	End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)
`breakdowns`	True	string	Comma-separated list of breakdowns. Must be at least one of entity, date, summary
`advertisable_eid`	True	string	A single advertisable EID
`use_uhura`	False	boolean	Explicitly ask the API to use the Uhura Backend for hll calculations
`past_days`	False	integer	Equivalent to setting `end_date` to today (exclusive) and `start_date` to (today - `past_days`). Takes precedence over `start_date` and `end_date`
`start_date`	False	string	Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)
`duration`	True	string	No description
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Successful operation

Returns UserList-Metrics-Response

GET /user-lists/api/v1/userlists/audience_preview¶

Estimates the size of composite segments based on their components

Parameters:

Query Parameters¶
Name	Required	Type	Description
`advertisable_eid`	True	string	A single advertisable EID
`segment_eids`	True	string	Comma-separated list of segment EIDs
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Successful operation

Returns Audience-Preview-Response

GET /user-lists/api/v1/userlists/segment¶

Provides user list sizes broken down by segment and date, as well as a summary for counts across all specified segments. If a particular segment has multiple durations associated with it, then the summary section will be computed with the segment’s largest duration. This endpoint also allows the specification of excluded segments, which are segments to not consider in generating the user list sizes. The excluded segments and their durations are combined together across the entire specified date range when they are being applied against the summary and entity breakdowns, but they are applied on a corresponding day-by-day basis when applied to the date breakdown.

Parameters:

Query Parameters¶
Name	Required	Type	Description
`email`	False	boolean	Ask the API to retrieve the segment email hll counts instead of segment hll counts.
`end_date`	False	string	End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)
`breakdowns`	True	string	Comma-separated list of breakdowns. Must be at least one of entity, date, summary
`advertisable_eid`	True	string	A single advertisable EID
`use_uhura`	False	boolean	Explicitly ask the API to use the Uhura Backend for hll calculations
`excluded_segment_eids`	False	string	Comma-separated list of segment EIDs to exclude from the count
`durations`	True	string	Comma-separated list of ad durations. Must be the same length as ad_eids
`excluded_durations`	False	string	Comma-separated list of durations corresponding to the segments to exclude from the count. Must be the same length as excluded_segment_eids. Each excluded segment must have exactly one duration associated with it.
`past_days`	False	integer	Equivalent to setting `end_date` to today (exclusive) and `start_date` to (today - `past_days`). Takes precedence over `start_date` and `end_date`
`start_date`	False	string	Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)
`segment_eids`	True	string	Comma-separated list of segment EIDs
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Successful operation

Returns UserList-Metrics-Response

POST /user-lists/api/v1/userlists/segment¶

This is identical to the GET endpoint, but is presented as a POST endpoint in order to submit large input sets. The POST body is a JSON-encoded string whose format follows from the GET endpoint’s query parameters.

Parameters:

Query Parameters¶
Name	Required	Type	Description
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Schema for request body:

{
  "advertisable_eid": "string",
  "breakdowns": "string",
  "durations": "string",
  "email": true,
  "end_date": "string",
  "excluded_durations": "string",
  "excluded_segment_eids": "string",
  "past_days": 0,
  "segment_eids": "string",
  "start_date": "string",
  "use_uhura": true
}

Schema

Parameters when sending a POST request to the segment user list endpoint

Type: object

email

Ask the API to retrieve the segment email hll counts instead of segment hll counts.

Type: boolean

end_date

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

Type: string

breakdowns

Comma-separated list of breakdowns. Must be at least one of entity, date, summary

Required: True
Type: string

advertisable_eid

A single advertisable EID

Required: True
Type: string

use_uhura

Explicitly ask the API to use the Uhura Backend for hll calculations

Type: boolean

excluded_segment_eids

Comma-separated list of segment EIDs to exclude from the count

Type: string

durations

Comma-separated list of ad durations. Must be the same length as ad_eids

Type: string

excluded_durations

Comma-separated list of durations corresponding to the segments to exclude from the count. Must be the same length as excluded_segment_eids. Each excluded segment must have exactly one duration associated with it.

Type: string

past_days

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

Type: integer
Format: int32

start_date

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

Type: string

segment_eids

Comma-separated list of segment EIDs

Required: True
Type: string

Responses:

200

Successful operation

Returns UserList-Metrics-Response

GET /user-lists/api/v1/userlists/segment/cdp_plus¶

Provides user list sizes broken down by segment and date

Provides user list sizes broken down by segment and date, as well as a summary for counts across all specified segments. If a particular segment has multiple durations associated with it, then the summary section will be computed with the segment’s largest duration. This endpoint also allows the specification of excluded segments, which are segments to not consider in generating the user list sizes. The excluded segments and their durations are combined together across the entire specified date range when they are being applied against the summary and entity breakdowns, but they are applied on a corresponding day-by-day basis when applied to the date breakdown.

Parameters:

Query Parameters¶
Name	Required	Type	Description
`metrics`	True	string	Comma-separated list of metrics to retrieve (at least one item needs to be provided), can be any of (`email`, `phone`)
`end_date`	False	string	End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)
`breakdowns`	True	string	Comma-separated list of breakdowns. Must be at least one of entity, date, summary
`advertisable_eid`	True	string	A single advertisable EID
`use_hll`	True	boolean	No description
`metric`	True	string	Metric to retrieve , can be any of (`email`, `phone`)
`start_date`	False	string	Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)
`segment_eids`	True	string	Comma-separated list of segment EIDs
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Successful operation

Returns UserList-Metrics-Response

GET /user-lists/api/v1/userlists/segment/exact¶

Provides exact user counts by date and metric

Provides exact counts for the amount of users that exist in a segment on a daily basis, this membership is historic and will not change after the day has ended

Parameters:

Query Parameters¶
Name	Required	Type	Description
`metrics`	True	string	Comma-separated list of metrics to retrieve (at least one item needs to be provided), can be any of (`email`, `phone`)
`end_date`	False	string	End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)
`advertisable_eid`	True	string	A single advertisable EID
`start_date`	False	string	Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)
`segment_eids`	True	string	Comma-separated list of segment EIDs
`apikey`	False	string	Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Successful operation

Returns Exact-Metrics-Response

Definitions¶

Audience-Preview-Response¶

Responds to requests regarding estimating composite segment sizes

Type: object

count

Count of total unique membership size of given segments

Type: integer

Exact-Metrics-Response¶

An object for responding to requests with UserList metrics

Type: object

results

Type: Exact-Metrics

Exact-Metrics¶

An object for the different ways UserList metrics are broken down and exposed

Type: object

segment_eid

Type: object

Exact-Date-Metrics-Response¶

A JSON encoded wrapper for UserList Metrics broken down by each day

Type: object

date

Type: string
Format: date-time

size

Count of total membership size of segment on a particular day

Type: integer
Format: int64

UserList-Metrics-Response¶

An object for responding to requests with UserList metrics

Type: object

results

Type: UserList-Metrics

UserList-Metrics¶

An object for the different ways UserList metrics are broken down and exposed

Type: object

summary

Type: UserList-Summary-Metrics-Response

entity

Type: array of User-List-Entity-Metrics-Response

date

Type: array of UserList-Date-Metrics-Response

UserList-Summary-Metrics-Response¶

A JSON encoded wrapper for UserList Metrics

Type: object

new_visitors

Count of unique new visitors who visited the entities between the specified date range. DEPRECATED.

Type: integer
Format: int64

total_visitors

Total number of unique visitors between the specified start_date (inclusive) and end_date (exclusive) ignoring duration i.e. [START_DATE, END_DATE)

Type: integer
Format: int64

current_visitors

Total number of unique visitors within the duration of the entity i.e. [$TODAY - $DURATION, $TODAY)

Type: integer
Format: int64

current_visitors_in_date_range

Total number of unique visitors within the duration of the entity with the specified date range i.e. [$END_DATE - $DURATION, $END_DATE)

Type: integer
Format: int64

excluded_total_visitors

Count of total visitors who did not visit entities because of a exclusion segment.

Type: integer
Format: int64

excluded_current_visitors

Count of current visitors at the time of query who did not visit entities because of a exclusion segment.

Type: integer
Format: int64

excluded_current_visitors_in_date_range

Count of current visitors during the end_date who did not visit entities because of a exclusion segment.

Type: integer
Format: int64

User-List-Entity-Metrics-Response¶

Response of userlist metrics broken down by a specified entity type

Type: object

entity

The EID of a specified entity type that belongs to the advertisable

Type: string

XX_days

Type: User-List-Entity-Duration-Metrics-Response

User-List-Entity-Duration-Metrics-Response¶

Type: object

new_visitors

Count of unique new visitors who visited the entities between the specified date range. DEPRECATED.

Type: integer
Format: int64

total_visitors

Total number of unique visitors between the specified start_date (inclusive) and end_date (exclusive) ignoring duration i.e. [START_DATE, END_DATE)

Type: integer
Format: int64

current_visitors

Total number of unique visitors within the duration of the entity i.e. [$TODAY - $DURATION, $TODAY)

Type: integer
Format: int64

current_visitors_in_date_range

Total number of unique visitors within the duration of the entity with the specified date range i.e. [$END_DATE - $DURATION, $END_DATE)

Type: integer
Format: int64

UserList-Date-Metrics-Response¶

A JSON encoded wrapper for UserList Metrics broken down by each day

Type: object

date

Type: string
Format: date-time

new_visitors

Count of unique new visitors who visited the entities between the specified date range. DEPRECATED.

Type: integer
Format: int64

total_visitors

Total number of unique visitors between the specified start_date (inclusive) and end_date (exclusive) ignoring duration i.e. [START_DATE, END_DATE)

Type: integer
Format: int64

excluded_total_visitors

Count of total visitors who did not visit entities because of a exclusion segment.

Type: integer
Format: int64

Segment-UserList-Post-Input¶

Parameters when sending a POST request to the segment user list endpoint

Type: object

breakdowns

List of breakdowns. Must be at least one of entity, date, summary

Required: True
Type: array of items

advertisable_eid

A single advertisable EID

Required: True
Type: string

segment_eids

List of segment eids

Required: True
Type: array of items

durations

List of segment durations. Must be the same length as segment_eids

Type: array of items

excluded_segment_eids

List of segment eids to exclude from the count

Type: array of items

excluded_durations

List of durations corresponding to the segments to exclude from the count. Must be the same length as excluded_segment_eids. Each excluded segment must have exactly one duration associated with it.

Type: array of items

start_date

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

Type: string

end_date

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

Type: string

past_days

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

Type: integer
Format: int32

Bulk-UserList-Post-Input¶

Parameters when sending a POST request to the bulk user list endpoint

Type: object

entities

Required: True
Type: Bulk-Entity-Input

start_date

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

Type: string

end_date

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

Type: string

past_days

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

Type: integer
Format: int32

Bulk-Entity-Input¶

Type: object

advertisable_eid

A single advertisable EID

Required: True
Type: string

segment_eids

List of segment eids

Type: array of items

adgroup_eids

List of adgroup eids

Type: array of items

ad_eids

List of ad eids

Type: array of items

durations

List of segment durations. Must be the same length as segment_eids

Type: array of items

Query-Response¶

An object for responding to requests with the metadata for reporting audience insights cookie attribute distribution by segment

Type: object

id

ID of the query metadata

Type: integer

advertisable_eid

A single advertisable EID

Type: string

attribute_name

Name of the attribute selected

Type: string

top_number

Number of attribute values to display

Type: integer

last_modified_date

Last time this set of metadata was modified, currently equates to creation date

Type: string

Results-Line¶

A single result line from the query

Type: object

id

ID of the query metadata

Type: integer

segment_eid

A single segment EID

Type: string

attribute_category

Value of the attribute selected

Type: string

date_analyzed

Date that this data pertains to

Type: string

cookies_matched

Number of cookies with a matched attribute value for this attribute

Type: integer

segment_size

Number of cookies in this segment

Type: integer

unique_cookies

Number of cookies with this attribute value

Type: integer

last_modified_date

Creation date of result data

Type: string

Results-Response¶

Type: object

results

List of result lines

Type: array of Results-Line

Results-Empty-Dates-Response¶

Type: object

results

List of dates ISO format

Type: array of items