Audience API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use

Note

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

Description

AdRoll Audience API 1.0

Manage your segments with the AdRoll Audience API

Operations

GET /audience/v1/advertisers

Retrieve list of accessible advertisers

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

Responses:

200

List of Advertiser IDs

Schema as JSON:

{
  "data": [
    {
      "advertiser_id": "string"
    }
  ]
}
Schema
Type

object

data

List of Advertiser IDs

Required

True

Type

array of items

POST /audience/v1/sharing/invitation

Send a Segment Sharing invitation. With an invitation, you are granting the other party the ability to use this your Segment on their Campaigns. The other party still needs to accept the invitation.

Parameters:

Query Parameters

Name

Required

Type

Description

segment_eid

True

string

EID of the Segment to share

advertisable_eid

True

string

EID of the Advertisable to share the Segment with

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

An invitation

Returns SharingSegmentInvitationResponse

DELETE /audience/v1/sharing/invitation

Revoke an invitation. The other party will lose access to the shared Segment

Parameters:

Query Parameters

Name

Required

Type

Description

invitation_eid

True

string

EID of the invitation

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

An invitation

Returns SharingSegmentInvitationResponse

Definitions

AdvertisableAttributeCategory

a nested grouping of attribute values

Type

object

attributes
Type

AdvertisableAttributeCategoryMap

description
Type

string

order_key
Type

AdvertisableAttributeOrderKey

singular

if true, selection of enumerable member values should be exclusive

Type

boolean

values
mapping from attribute values to metadata about them. keys may be user-facing.
Type

object

AdvertisableAttributeCategoryMap

mapping from attribute category name to its contents

Type

object

AdvertisableAttributeMap
Type

object

attributes
Type

AdvertisableAttributeCategoryMap

description
Type

string

is_internal

if true, the source is managed/populated internally

Type

boolean

AdvertisableAttributeOrderKey

any value which can be sorted, representing an optional presentation ordering key

Type

object

AdvertisableAttributeSourceMap

mapping from attribute source name to its definition

Type

object

AdvertisableAttributeSourceNameList

List of attribute source names the advertisable may use

Type

array

AdvertisableAttributeValueDetail

metadata about a single attribute value

Type

object

description

user-facing extended description of the attribute

Type

string

id

unique integer or opaque string identifier of the attribute

Type

object

non_enumerable

if true, the attribute is non-enumerable (string-valued)

Type

boolean

order_key
Type

AdvertisableAttributeOrderKey

target
"name" value which should appear in targeting rules referencing this attribute
Type

string

AdvertisableAttributes
Type

object

attributes

List or detailed list of user attributes from an advertisable

Type

array of AdvertisableAttributesDetail

AdvertisableAttributesDetail
Type

object

name
Type

string

CDP-Segment-Create-Input

Parameters when sending a POST request to create a CDP Segment.

Type

object

advertisable_eid

Advertisable EID of the segment.

Required

True

Type

string

display_name

Display name of the segment.

Required

True

Type

string

event_rule

Rules defining the events belonging to the users that populate this segment.

Type

object

predictive_rule

Rules defining a predictive audience

Type

object

user_rule

Rules defining the users that populates this segment.

Type

object

CDP-Segment-Get-Email
Type

object

excluded_segment_eids

List of segment eids to not get emails from

Type

array of items

max_page_size

Total amount of emails to return per page, defaults to 20000

Type

integer

next_page_token

The last hashed email returned, used to get the starting point for pagination

Type

string

segment_eids

List of segment eids to get emails from

Required

True

Type

array of items

CDP-Segment-Get-Email-Response
Type

object

emails

List of md5 hashed emails

Required

True

Type

array of items

next_page_token

The last hashed email returned, used to get the starting point for pagination

Required

True

Type

string

CDP-Segment-Response

Response of a CDP Segment.

Type

object

advertisable_eid

Advertisable EID of the segment.

Type

string

created_at

When this segment was created.

Type

string

Format

date-time

display_name

Display name of the segment.

Type

string

eid

The EID of the CDP Segment

Type

string

event_rule

Rules defining the events belonging to the users that populate this segment.

Type

object

first_process_date

When this segment was first processed and populated.

Type

string

Format

date-time

is_active

Whether or not the segment is active.

Type

boolean

last_process_date

When this segment was last processed and populated.

Type

string

Format

date-time

predictive_rule

Rules defining a predictive audience

Type

object

segment_size

The number of users (emails) in the CDP segment within the segment’s recency window.

Type

integer

segmentation_type

Type of segmentation.

Type

string

Enum

EVENT_AND_USER, USER_ONLY, EVENT_ONLY

updated_at

When this segment was last updated.

Type

string

Format

date-time

user_rule

Rules defining the users that populates this segment.

Type

object

CDP-Segment-Update-Input

Parameters when sending a POST request to update a CDP Segment.

Type

object

display_name

Display name of the segment.

Type

string

CDP-Segments-Manual-Population

Parameters when sending a POST request to create a CDP Segment.

Type

object

segments_users_pairs

List of segment -> emails profiles to be added.

Required

True

Type

array of items

CrossChannelLalValidSegments

List of valid and invalid segments to be used as CrossChanel lal Segments

Type

object

advertiser_id

ID of the advertiser to create a new segment for

Type

string

invalid_segments

Segments of valid type but that doesn’t meet audience sizes requirements

Type

array of SegmentsWithSizesResponse

prospecting_only_valid_segments

Segments of valid type and that meets audience sizes only for prospecting

Type

array of SegmentsWithSizesResponse

valid_segments

Segments of valid type and that meets audience sizes requirements

Type

array of SegmentsWithSizesResponse

DomainReferencesRequest

Options for domain references

Type

object

domains

Domains to query

Required

True

Type

array of items

entities

Entities to query

Type

array of items

verbose

Whether to include extra entity information

Type

boolean

DomainReferencesResponse
Type

object

results
Type

object

DomainReferencesResponseDomain
Type

object

companies
Type

DomainReferencesResponseVerboseEntity

playbooks
Type

DomainReferencesResponseVerboseEntity

target_accounts
Type

DomainReferencesResponseVerboseEntity

DomainReferencesResponseVerboseEntity
Type

object

eid
Type

string

name
Type

string

Duration

Number of days (1 to 540) members are valid in a segment

Type

integer

Maximum

540

Minimum

1

ICPAccountsFilter
Type

object

comparator
Type

string

Enum

exists, in, not_in

eid
Type

string

grades
Type

string

Enum

A, B, C, D, F

ICPAccountsRequest
Type

object

after
Type

string

domains
Type

object

icp_filters
Type

array of ICPAccountsFilter

size
Type

integer

ICPAccountsResponse
Type

object

page_info
Type

object

results
Type

array of items

total_count
Type

integer

Format

int32

ICPAttributeFilters
Type

array

ICPAttributes

Attributes based on the most common third-party company attributes from the accounts in the positive_domains list.

Type

object

country
Type

array of items

industry
Type

array of items

revenue
Type

array of items

size
Type

array of items

ICPDataTypeFilters
Type

array

ICPDetails
Type

object

advertisable_eid
Type

string

attributes

List or detailed list of user attributes from an advertisable

Type

array of ICPAttributes

created_at
Type

string

created_by_user_eid
Type

string

Format

nullable

deleted_at
Type

string

Format

nullable

deleted_by_user_eid
Type

string

Format

nullable

domain_filter_settings
Type

object

eid
Type

string

last_completed_model_uuid
Type

string

model_status
Type

string

model_updated_at
Type

string

model_uuid
Type

string

name
Type

string

positive_domains
Type

array of items

selected_picture_key
Type

string

updated_at
Type

string

updated_by_user_eid
Type

string

Format

nullable

ICPDetailsList
Type

object

icps
Type

array of ICPDetails

ICPFilterBlocks
Type

array

ICPScoreList
Type

object

results
Type

array of items

NumericAttributeFilter

Filter for Company Attributes numeric field

Type

object

from
Type

integer

to
Type

integer

SegmentCreate
Type

object

advertiser_id

ID of the advertiser to create a new segment for

Required

True

Type

string

conversion_value

new conversion value to be associated with the conversion segment

Type

number

Format

float

data

User records to add

Required

True

Type

array of UserRecord

duration
Required

True

Type

Duration

general_exclusion_type
Type

SegmentGeneralExclusionType

is_conversion

true if a segment is a conversion segment

Type

boolean

name

Name given to the segment upon creation

Required

True

Type

string

sfdc_company_list_id
Type

SegmentSfdcCompanyListId

type
Required

True

Type

SegmentType

SegmentGeneralExclusionResponse
Type

object

results
Type

SegmentResponse

SegmentGeneralExclusionType

Represents the general exclusion type

Type

string

Enum

customers, coworkers, competitors

SegmentResponse
Type

object

conversion_value

conversion value associated with the conversion segment else null

Type

number

Format

float

duration
Type

Duration

emails

Number of emails appended to a crm segment

Type

integer

Format

int64

general_exclusion_type
Type

SegmentGeneralExclusionType

ids

Number of users appended to a custom segment

Type

integer

Format

int64

is_conversion

true if a segment is a conversion segment else false

Type

boolean

name

Name given to the segment upon creation

Required

True

Type

string

segment_id

Identifier used to represent this segment

Required

True

Type

string

sfdc_company_list_id
Type

SegmentSfdcCompanyListId

type
Required

True

Type

SegmentType

SegmentSfdcCompanyListId

Represents the salesforce company list id that this segment references

Type

string

SegmentTalReferences

A TAL segment reference

Type

object

advertisable_eid
Type

string

cdp_rule_eid
Type

string

created_date
Type

string

Format

date-time

eid
Type

string

last_modified_date
Type

string

Format

date-time

name
Type

string

rule_last_modified_date
Type

string

Format

date-time

tal_eid
Type

string

tal_tier_eid
Type

string

type
Type

string

SegmentTalReferencesResponse

All TAL references of a segment

Type

object

results

An array of TAL references

Type

array of SegmentTalReferences

SegmentType

Represents the segment type

Type

string

Enum

crm, custom, impression, user_events, user_attributes, crosschannel_lal

SegmentUpdate
Type

object

conversion_value

new conversion value to be associated with the existing conversion segment

Type

number

Format

float

data

User records to add

Required

True

Type

array of UserRecord

duration
Type

Duration

general_exclusion_type
Type

SegmentGeneralExclusionType

name

Name shown on client’s dashboard

Required

True

Type

string

sfdc_company_list_id
Type

SegmentSfdcCompanyListId

SegmentsWithSizesResponse

Represents a segment with their audience sizes (facebook and audiences)

Type

object

facebook_visitors

Number of facebook visitors

Type

integer

Format

int64

total_visitors

Number of total visitors

Type

integer

Format

int64

SharingSegmentBulkSegmentCreateResponse

Represents the results of a bulk creation

Type

object

created_segments

Successful creations count

Type

integer

failed_creations

failed creations count, usually due to invitation already being accepted

Type

integer

SharingSegmentInvitationListResponse
Type

array

SharingSegmentInvitationResponse

Represents a Segment Invitation

Type

object

accepted

Has the invitation been accepted?

Type

boolean

created_at

When this invitation was sent.

Type

string

Format

date-time

is_active

Whether or not the invitation is still active.

Type

boolean

segment_source
Type

string

source_advertisable_eid

The Advertisable sharing the Segment.

Type

string

source_segment_eid

The EID of the Segment that wants to be shared.

Type

string

source_user_eid

The user than sent the invitation.

Type

string

target_advertisable_eid

The Advertisable receiving the Segment Share invitation.

Type

string

updated_at

When this invitation was updated (accepted/deleted).

Type

string

Format

date-time

SharingSegmentMirrorSegmentResponse

Represents a Mirror Segment

Type

object

advertisable_eid

The Advertisable owning the Segment.

Type

string

eid

The eid of the segment

Type

string

name

The name of the segment

Type

string

segment_source

Where the source segment is stored.

Type

string

source_segment_eid

The EID of the Segment that was shared.

Type

string

TargetAccountItemsFilter

Filter Target Accounts Items

Type

object

grades

Filter only items that are in the given grades

Type

array of items

is_scored

Filter only items that are scored

Type

boolean

score
Type

NumericAttributeFilter

TargetAccountsItems

Target Accounts Item

Type

object

domain
Type

string

score
Type

number

sfdc_synced_at

The last timestamp of the Salesforce synchronization

Type

string

Format

date-time

source
Type

string

Enum

user_uploaded, discover_accounts, suggestion, sfdc_synced, notification

updated_at
Type

string

Format

date-time

TargetAccountsItemsAllResponse

All Target Accounts Items response

Type

object

results

An array of Target Accounts Items

Type

array of TargetAccountsItemsReport

total_items
Type

integer

TargetAccountsItemsListDelete

A list of Target Accounts domains to delete

Type

object

domains
Type

array of items

filters
Type

TargetAccountItemsFilter

force

Force the deletion even though there are audiences associated with this item

Type

boolean

inverted

Tells if domains is the oposite selection in the current TAL/TAG

Type

boolean

TargetAccountsItemsListUpdate

A list of Target Accounts Items to update

Type

object

items
Type

array of TargetAccountsItemsUpdate

TargetAccountsItemsReport
TargetAccountsItemsSearch

Search Target Accounts List items

Type

object

domains
Type

array of items

filters
Type

TargetAccountItemsFilter

inverted

Tells if domains is the oposite selection in the current TAL/TAG

Type

boolean

TargetAccountsItemsUpdate

Target Accounts Item

Type

object

domain
Type

string

score
Type

number

sfdc_synced_at

The last timestamp of the Salesforce synchronization

Type

string

Format

date-time

source
Type

string

Enum

user_uploaded, discover_accounts, suggestion, sfdc_synced, notification

TargetAccountsList

The Target Accounts Lists (TAL)

Type

object

advertisable_eid

The advertisable EID that owns this TAL

Type

string

eid

The Target Accounts List EID

Type

string

items_count

The number of items in the Target Accounts List

Type

integer

name

The Target Accounts List name

Type

string

scoring_at

The timestamp of when the scoring process was started

Type

string

Format

date-time

scoring_auc

The raw number for the score AUC (Area Under the Curve)

Type

number

scoring_by_user_eid

The user that started the scoring process

Type

string

scoring_filename

The filename that generated the scoring model

Type

string

scoring_grades
Type

TargetAccountsScoringGrades

scoring_holdout1_model_id

The holdout 1 scoring model ID

Type

string

scoring_holdout1_retries

The number of retries for the holdout 1 scoring model

Type

integer

scoring_holdout1_status

The current status of the holdout 1 scoring process

Type

string

scoring_holdout2_model_id

The holdout 2 scoring model ID

Type

string

scoring_holdout2_retries

The number of retries for the holdout 2 scoring model

Type

integer

scoring_holdout2_status

The current status of the holdout 2 scoring process

Type

string

scoring_holdout3_model_id

The holdout 3 scoring model ID

Type

string

scoring_holdout3_retries

The number of retries for the holdout 3 scoring model

Type

integer

scoring_holdout3_status

The current status of the holdout 3 scoring process

Type

string

scoring_holdout4_model_id

The holdout 4 scoring model ID

Type

string

scoring_holdout4_retries

The number of retries for the holdout 4 scoring model

Type

integer

scoring_holdout4_status

The current status of the holdout 4 scoring process

Type

string

scoring_holdout5_model_id

The holdout 5 scoring model ID

Type

string

scoring_holdout5_retries

The number of retries for the holdout 5 scoring model

Type

integer

scoring_holdout5_status

The current status of the holdout 5 scoring process

Type

string

scoring_items_count

The number of items used for the scoring process

Type

integer

scoring_items_pending

Flag that signals that there are pending items to be scored

Type

boolean

scoring_model_id

The production scoring model ID

Type

string

scoring_production_model_id

The production scoring model ID

Type

string

scoring_production_retries

The number of retries for the production scoring model

Type

integer

scoring_production_status

The current status of the production scoring process

Type

string

scoring_status

The current status of the entire scoring process

Type

string

sfdc_company_list_name

The Salesforce Company List name that syncs with this TAL

Type

string

sfdc_company_list_object_id

The Salesforce Company List ID that syncs with this TAL

Type

string

sfdc_scoring_company_list_name

The Salesforce Company List name used for scoring model

Type

string

sfdc_scoring_company_list_object_id

The Salesforce Company List ID used for scoring model

Type

string

sfdc_sync_state

The configuration for the Salesforce synchronization

Type

string

Enum

none, push, bidirectional

sfdc_synced_at

The last timestamp of the Salesforce synchronization

Type

string

Format

date-time

suggestions_count

(Deprecated) The number of suggestions in the Target Accounts List

Type

integer

tiers

An array of Target Accounts Tier

Type

array of TargetAccountsTier

updated_at

The last timestamp of when this TAL was updated

Type

string

Format

date-time

updated_by_user_at

The last timestamp of when this TAL was updated by some user

Type

string

Format

date-time

updated_by_user_eid

The last user that updated this TAL

Type

string

TargetAccountsListAllResponse

All Target Accounts Lists response

Type

object

results

An array of Target Accounts Lists

Type

array of TargetAccountsList

TargetAccountsListCreate
TargetAccountsListCreateBase

Create a Target Accounts List

Type

object

advertisable_eid
Required

True

Type

string

domains
Type

array of items

name
Required

True

Type

string

source
Type

string

Enum

user_uploaded, discover_accounts, suggestion, sfdc_synced, notification

TargetAccountsListUpdate

Update a Target Accounts List

Type

object

eid

The Target Accounts List EID

Required

True

Type

string

name

The Target Accounts List name

Type

string

scoring_auc
Type

number

scoring_grades
Type

TargetAccountsScoringGradesUpdate

scoring_holdout1_status
Type

string

scoring_holdout2_status
Type

string

scoring_holdout3_status
Type

string

scoring_holdout4_status
Type

string

scoring_holdout5_status
Type

string

scoring_items_pending
Type

boolean

scoring_production_status
Type

string

scoring_status
Type

string

sfdc_sync_state

The configuration for the Salesforce synchronization

Type

string

Enum

none, push, bidirectional

sfdc_synced_at

The last timestamp of the Salesforce synchronization

Type

string

Format

date-time

TargetAccountsScoringGrade

The Target Accounts List grade definition

Type

object

items_count

The number of scored items in this grade

Type

integer

min_item

The Target Accounts List grade minimum item in this grade

Type

object

threshold
Type

integer

TargetAccountsScoringGradeUpdate

The Target Accounts List grade definition

Type

object

threshold
Type

integer

TargetAccountsScoringGrades

The Target Accounts List grades scoring configuration

Type

object

A
Type

TargetAccountsScoringGrade

B
Type

TargetAccountsScoringGrade

C
Type

TargetAccountsScoringGrade

D
Type

TargetAccountsScoringGrade

F
Type

TargetAccountsScoringGrade

scored_count

The number of scored items in the Target Accounts List

Type

integer

unscored_count

The number of unscored items in the Target Accounts List

Type

integer

TargetAccountsScoringGradesUpdate

The Target Accounts List grades scoring configuration

Type

object

A
Type

TargetAccountsScoringGradeUpdate

B
Type

TargetAccountsScoringGradeUpdate

C
Type

TargetAccountsScoringGradeUpdate

D
Type

TargetAccountsScoringGradeUpdate

F
Type

TargetAccountsScoringGradeUpdate

TargetAccountsTier

The Target Accounts Tier

Type

object

created_at

The creation timestamp of the tier

Type

string

Format

date-time

eid

The EID of the tier or one of the calculated tiers: all and untiered

Type

string

items_count

The number of items in this tier

Type

integer

name

The name of the tier

Type

string

tal_eid

The Target Accounts List EID this tier belongs to

Type

string

TargetAccountsTierCreate
TargetAccountsTierUpdate

The Target Accounts Tier updatable fields

Type

object

eid

The tier EID

Required

True

Type

string

name

The name of the tier

Required

True

Type

string

TargetAccountsTiersAllResponse

All Target Accounts Tiers response

Type

object

results

An array of Target Accounts Tier

Type

array of TargetAccountsTier

TargetAccountsTiersCreateBase

The Target Accounts Tier

Type

object

domains
Required

True

Type

array of items

name

The name of the tier

Required

True

Type

string

UserAttributeCountsRequest
Type

object

attributes
Type

UserAttributeCountsRequestAttributes

UserAttributeCountsRequestAttributes
Type

object

UserAttributeCountsRequestResult
Type

object

UserAttributeCountsResponse
Type

object

results
Type

UserAttributeCountsRequestResult

UserAttributeSegmentResponse

Represents a user attribute segment

Type

object

comparator
Type

string

display_name
Type

string

name
Type

string

source
Type

string

values
Type

array of items

UserAttributesSegmentResponse

Represents many user attributes

Type

object

attributes
Type

array of UserAttributeSegmentResponse

attributes_source
Type

string

cdp_rule_eid
Type

string

tal_eid
Type

string

tal_tier_eid
Type

string

use_first_party_data
Type

boolean

use_third_party_data
Type

boolean

UserRecord
Type

object

email

Email RFC 5322 standard. Used with crm segments.

Type

string

id

Unique user identifier synced to AdRoll via Cookie Match. Used with custom segments.

Type

string

WarehouseResponse
Type

object

advertiser_id
Type

string

comments
Type

string

created_date
Type

integer

db_host
Type

string

db_name
Type

string

db_password
Type

string

Format

binary

db_port
Type

integer

db_schema
Type

string

db_type
Type

string

db_username
Type

string

email_opt_in
Type

boolean

id
Type

integer

is_active
Type

boolean

warehouse_eid
Type

string