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
List of Operations¶
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
-
description
- Type
string
-
order_key
-
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
-
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
-
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
-
playbooks
-
target_accounts
-
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
-
general_exclusion_type
-
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
- Required
True
- Type
-
SegmentGeneralExclusionResponse
¶ - Type
object
-
results
- Type
-
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
-
emails
Number of emails appended to a crm segment
- Type
integer
- Format
int64
-
general_exclusion_type
-
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
- Required
True
- Type
-
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
-
general_exclusion_type
-
name
Name shown on client’s dashboard
- Required
True
- Type
string
-
sfdc_company_list_id
-
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
-
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
-
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
-
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
-
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
-
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
-
B
-
C
-
D
-
F
-
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
-
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
anduntiered
- 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
-
UserAttributeCountsRequestAttributes
¶ - Type
object
-
UserAttributeCountsRequestResult
¶ - Type
object
-
UserAttributeCountsResponse
¶ - Type
object
-
results
-
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