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

Operations

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

Provides user list sizes broken down by ad and date

Provides user list sizes broken down by ad and date

Parameters:

Query Parameters

Name

Required

Type

Description

start_date

False

string

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

advertisable_eid

True

string

A single advertisable EID

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)

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

use_uhura

False

boolean

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

breakdowns

True

string

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

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

Provides user list sizes broken down by AdGroup and date

Parameters:

Query Parameters

Name

Required

Type

Description

start_date

False

string

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

adgroup_eids

True

string

No description

advertisable_eid

True

string

A single advertisable EID

end_date

False

string

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

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

use_uhura

False

boolean

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

breakdowns

True

string

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

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

Provides user list sizes broken down by advertisable and date

Parameters:

Query Parameters

Name

Required

Type

Description

start_date

False

string

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

advertisable_eid

True

string

A single advertisable EID

end_date

False

string

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

duration

True

string

No description

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

use_uhura

False

boolean

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

breakdowns

True

string

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

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

Estimates the size of composite segments based on their components

Parameters:

Query Parameters

Name

Required

Type

Description

segment_eids

True

string

Comma-separated list of segment EIDs

advertisable_eid

True

string

A single advertisable EID

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.

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

excluded_segment_eids

False

string

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

start_date

False

string

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

advertisable_eid

True

string

A single advertisable EID

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.

end_date

False

string

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

segment_eids

True

string

Comma-separated list of segment EIDs

email

False

boolean

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

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

use_uhura

False

boolean

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

breakdowns

True

string

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

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.

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

excluded_segment_eids

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

Type

string

start_date

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

Type

string

advertisable_eid

A single advertisable EID

Required

True

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

end_date

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

Type

string

segment_eids

Comma-separated list of segment EIDs

Required

True

Type

string

email

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

Type

boolean

durations

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

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

use_uhura

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

Type

boolean

breakdowns

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

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

start_date

False

string

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

advertisable_eid

True

string

A single advertisable EID

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)

segment_eids

True

string

Comma-separated list of segment EIDs

metric

True

string

Metric to retrieve , can be any of (email, phone)

use_hll

True

boolean

No description

breakdowns

True

string

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

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

start_date

False

string

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

advertisable_eid

True

string

A single advertisable EID

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)

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