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

List of Operations¶

GET /audience/v1/advertisers
POST /audience/v1/sharing/invitation
DELETE /audience/v1/sharing/invitation

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