CRUD 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 CRUD API v1 by AdRoll

Manage AdRoll with the AdRoll CRUD API

External documentation

Operations by Tag

Ad

• POST /api/v1/ad/clone

• POST /api/v1/ad/create

• POST /api/v1/ad/create_templated_web_ads

• PUT /api/v1/ad/edit

• GET /api/v1/ad/get

Adgroup

• POST /api/v1/adgroup/add_segments

• POST /api/v1/adgroup/create

• POST /api/v1/adgroup/deselect_ads

• POST /api/v1/adgroup/edit

• GET /api/v1/adgroup/get

• GET /api/v1/adgroup/get_ads

• POST /api/v1/adgroup/pause

• POST /api/v1/adgroup/pause_ad

• POST /api/v1/adgroup/pause_ads

• POST /api/v1/adgroup/remove_segments

• POST /api/v1/adgroup/select_ads

• POST /api/v1/adgroup/unpause

• POST /api/v1/adgroup/unpause_ad

• POST /api/v1/adgroup/unpause_ads

Advertisable

• POST /api/v1/advertisable/create

• POST /api/v1/advertisable/edit

• POST /api/v1/advertisable/enable_rollcrawl

• GET /api/v1/advertisable/get

• GET /api/v1/advertisable/get_adgroups

• GET /api/v1/advertisable/get_adgroups_fast

• GET /api/v1/advertisable/get_ads

• GET /api/v1/advertisable/get_ads_fast

• GET /api/v1/advertisable/get_campaigns

• GET /api/v1/advertisable/get_campaigns_fast

• GET /api/v1/advertisable/get_pixel

• GET /api/v1/advertisable/get_segments

• GET /api/v1/advertisable/get_suggested_country

Advertisable Logo

• POST /api/v1/advertisable_logo/create

Campaign

• POST /api/v1/campaign/create

• POST /api/v1/campaign/edit

• GET /api/v1/campaign/get

• GET /api/v1/campaign/get_adgroups

• PUT /api/v1/campaign/pause

• PUT /api/v1/campaign/pause_ads

• PUT /api/v1/campaign/unpause

• PUT /api/v1/campaign/unpause_ads

Consent Banner

• GET /api/v1/consent_banner/get

• GET /api/v1/consent_banner/retrieve

• POST /api/v1/consent_banner/update

Dynamic Configuration

• PUT /api/v1/dynamic_configuration/edit

• POST /api/v1/dynamic_configuration/enable

• GET /api/v1/dynamic_configuration/get

Dynamic Template

• GET /api/v1/dynamic_template/get_all_for_advertisable

Dynamic Template Capability Description

• GET /api/v1/dynamic_template_capability_description/get_all

Feed

• POST /api/v1/feed/autoconfigure

Invoice

• GET /api/v1/invoice/get

Marketplace

• POST /api/v1/marketplace/create

• GET /api/v1/marketplace/get

Organization

• GET /api/v1/organization/get

• GET /api/v1/organization/get_accounts

• GET /api/v1/organization/get_advertisables

• GET /api/v1/organization/get_advertisables_paginated

• GET /api/v1/organization/get_billing_methods

• GET /api/v1/organization/get_users

Pixel

• GET /api/v1/pixel/get

• GET /api/v1/pixel/get_rules

• GET /api/v1/pixel/get_segments

Policy

• POST /api/v1/policy/send_email

Product Feeds

• PUT /api/v1/product_feeds/add_feed_config

• POST /api/v1/product_feeds/autoconfigure

• GET /api/v1/product_feeds/delete_feed_config

• GET /api/v1/product_feeds/delete_parser_config

• PUT /api/v1/product_feeds/edit_feed_config

• GET /api/v1/product_feeds/feed_downloadable

• GET /api/v1/product_feeds/feed_status

• GET /api/v1/product_feeds/get_feed_config

• GET /api/v1/product_feeds/get_parser_config

• GET /api/v1/product_feeds/get_products

• GET /api/v1/product_feeds/get_troubled_products

• GET /api/v1/product_feeds/match_rate

• GET /api/v1/product_feeds/parse_preview

• GET /api/v1/product_feeds/set_parser_config

• POST /api/v1/product_feeds/set_parser_configs

Report

• GET /api/v1/report/ad

• GET /api/v1/report/advertisable

• GET /api/v1/report/campaign

Rule

• POST /api/v1/rule/create

• GET /api/v1/rule/get

• GET /api/v1/rule/get_segments

Segment

• POST /api/v1/segment/edit

• GET /api/v1/segment/get

User

• POST /api/v1/user/edit

• GET /api/v1/user/get

• POST /api/v1/user/grant

Xdevice Opt In

• GET /api/v1/xdevice_opt_in/retrieve

• POST /api/v1/xdevice_opt_in/update

Operations

POST /api/v1/ad/clone

Clones an ad. Any parameters given will override the corresponding field in the original ad. The fields below may be overridden.

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

Form Parameters

Name	Required	Type	Description
destination_url	False	string	The URL that the browser will navigate to when the ad is clicked (Optional; default: None)
name	False	string	The name of the ad (Optional; default: None)
headline	False	string	The headline text of the Facebook ad (Optional, only for Facebook ads; default: ‘’)
body	False	string	The body text of the Facebook ad (Optional, only for Facebook ads; default: ‘’)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The new ad’s “get” representation

Type

object

POST /api/v1/ad/create

Creates a new ad.

Ad will only be created as active if both the name and destination_url parameters are provided.

The following ad formats are supported:

Format ID	Name	Description
1	Full Banner	468 wide x 60 high
3	Leaderboard	728 wide x 90 high
4	Small Rectangle	180 wide x 150 high
5	Medium Rectangle	300 wide x 250 high
6	Large Rectangle	336 wide x 280 high
7	Wide Skyscraper	160 wide x 600 high
8	Skyscraper	120 wide x 600 high
9	Vertical Banner	120 wide x 240 high
10	Square Button	125 wide x 125 high
11	Rectangular Button	180 wide x 60 high
12	Square	250 wide x 250 high
13	Tiny Rectangle	120 wide x 60 high
14	Mid Square	200 wide x 200 high
16	3:1 Rectangle	300 wide x 100 high
20	Half Page	300 wide x 600 high
21	Mobile Leaderboard	320 wide x 50 high
17	Facebook Banner	645 wide x 60 high
24	Facebook Page Post Link Ad	600 wide x 315 high
25	Facebook App Install Mobile News Feed Ad	1200 wide x 627 high
26	Facebook Instagram Ad	600 wide x 600 high
31	Instagram Carousel Base	0 wide x 1 high
27	Billboard	970 wide x 250 high
28	Facebook Instagram Ad	1200 wide x 1200 high
29	Facebook Carousel Child	460 wide x 460 high
30	Facebook Carousel Base	0 wide x 0 high
32	Facebook Page Post Link Ad	1200 wide x 628 high
33	Native Ad Wide	600 wide x 315 high
34	Native Ad Square	600 wide x 600 high
35	Native Ad Taboola Min	600 wide x 500 high

Files can be uploaded via either a base64 encoded string, or a multipart HTTP request.

For Facebook ads, call_to_action is one of:

• NO_BUTTON

• BOOK_TRAVEL

• BUY_NOW

• DONATE_NOW

• DOWNLOAD

• GET_QUOTE

• INSTALL_APP

• INSTALL_MOBILE_APP

• LEARN_MORE

• LISTEN_MUSIC

• MESSAGE_PAGE

• OPEN_LINK

• PLAY_GAME

• SHOP_NOW

• SIGN_UP

• SUBSCRIBE

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable to which this ad will belong
file	True	string	The actual contents of the ad creative. Pass this in as a base64-encoded string or use a multi-part form request.
destination_url	False	string	The URL that the browser will navigate to when the ad is clicked (Optional; default: ‘’)
name	False	string	The name of the ad (Optional; default: ‘’)
headline	False	string	The headline text of the Facebook ad (Optional, only for Facebook ads and limited to 25 characters; default: ‘’)
body	False	string	The body text of the Facebook ad (Optional, only for Facebook ads and limited to 90 characters; default: ‘’)
message	False	string	The message text of the Facebook ad (Optional, only for Facebook newsfeed ads and limited to 500 characters; default: ‘’)
product	False	string	The SWF data of the product animation loop (Optional, only for liquid ads; default: ‘’)
logo	False	string	The data of the logo image (Optional, only for liquid ads; default: ‘’)
headline_dynamic	False	string	The headline text of the Facebook ad (Optional; default: ‘’)
body_dynamic	False	string	The body text of the Facebook ad (Optional; default: ‘’)
message_dynamic	False	string	The message text of the Facebook ad (Optional; default: ‘’)
is_fb_dynamic	False	string	True to indicate that this is a dynamic Facebook ad (Optional; default: ‘’)
multiple_products	False	integer	Number of products the Facebook ad should show. One of: 0, 3, 4, 5 (Optional; default: 0)
call_to_action	False	string	Facebook call to action to use (Optional; default: ‘’)
lead_gen_form_id	False	string	ID of the Facebook lead form for Lead Ads (Optional; default: ‘’)
multi_share_optimized	False	string	True if Facebook should automatically select and order images for Carousel Ads (Optional; default: ‘’)
child_ads	False	string	Comma separated list of child ads for Facebook Carousel Ads (Optional; default: ‘’)
app_id	False	string	ID of application for Facebook App Ads (Optional; default: ‘’)
dynamic_template_id	False	string	Dynamic Creative template to use (Optional; default: ‘’)
background	False	string	Background color (hex value or name) or URL to an image for the Dynamic Creative ad (Optional; default: ‘white’)
ad_format	False	string	Ad format ID. (Optional; default: ‘’)
prefix	False	string	Product URLs will be prefixed with this when Dynamic Creative is clicked, used for redirect-style click trackers (Optional; default: ‘’)
tracking	False	string	URL query parameters to add to product URLs when Dynamic Creative is clicked (Optional; default: ‘’)
display_url_override	False	string	When the destination URL uses a redirect or click trackers, this value is required and should be equal to the final destination URL of the redirect. Some of our partner networks do not follow redirects when approving ads so this value must be provided to mitigate against ad disapprovals. (Optional; default: ‘’)
type	False	string	Ad type (Optional; default: ‘image’)
brand_name	False	string	The brand name for native ads (Optional for non-native ads; default: ‘’)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The new ad’s “get” representation

Type

object

POST /api/v1/ad/create_templated_web_ads

Creates a set of ads from a template.

Assumes that you’ve already called the `advertisable_logo/create` api to upload a logo for the provided advertisable.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable to which these ads will belong
name	True	string	The name of the ad set. Appends to the following default naming convention as such ‘Dynamic_[ad size]_[date]_[ad set name]’. Properties such as theme name are recommended (limited to 30 characters)
theme_color	True	string	Hexadecimal color code for the color of the CTA box, e.g. #FFFF00
text_cta	True	string	The call to action text shown on the cta box. Since the available space depends on the specific template you’re using, this field doesn’t have a limit.
dynamic_template_id	True	integer	The ID of the template to be created
text_promo	False	string	The call to action text shown on the cta box (Optional; default: ‘’)
sale_price_option	False	integer	How price should be seen inside the Ad. 0 - don’t show the price, 1 - show the price normalized, 2 - show sale price, 3 - show original price with strikethrough, sale price, and discount percentage. (Optional; default: ‘’)
prefix	False	string	Product URLs will be prefixed with this when Dynamic Creative is clicked, used for redirect-style click trackers (Optional; default: ‘’)
tracking	False	string	URL query parameters to add to product URLs when Dynamic Creative is clicked (Optional; default: ‘’)
countdown_end	False	string	The end date a countdown timer ticks down to in ISO 8601 timestamp format. Append with ‘Z’ for UTC time. (Optional; default: ‘’)
product_group	False	string	A product group defined on a feed to be included in the recommendations endpoint call (Optional; default: ‘’)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

A list of the new ad’s “get” representation

Type

object

PUT /api/v1/ad/edit

Edits an ad. If a major data point is edited (i.e. destination_url), it will create a new ad and put it in an admin approval state. A new ad is created to allow your old ad to continue to run until the edited ad is approved. If innocuous data is entered, or the ad is not part of a campaign, it will just be edited in place.

Parameters:

Query Parameters

Name	Required	Type	Description
ad	True	string	EID of the ad to edit
destination_url	False	string	The new destination_url for the ad (Optional; default: None)
name	False	string	The new name of the ad (Optional; default: None)
headline	False	string	The headline text of the Facebook ad (Optional, only for Facebook ads; default: ‘’)
body	False	string	The body text of the Facebook ad (Optional, only for Facebook ads; default: ‘’)
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

Schema as JSON:

{
  "edit_mode": "string",
  "original": {},
  "replacement": {}
}

Schema

Type

object

edit_mode

Either ‘edit’, if edits were made in place, or ‘clone’, if the edits necessitated the creation of a new ad

Type

string

original

The original ad’s “get” representation

Type

object

replacement

The new ad’s “get” representation, if the edits necessitated the creation of a new ad

Type

object

GET /api/v1/ad/get

Fetches an ad by its EID.

Parameters:

Query Parameters

Name	Required	Type	Description
ad	True	string	The EID of the ad to fetch
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

Schema as JSON:

{
  "ad_format": "string",
  "ad_format_id": 0,
  "ad_format_name": "string",
  "adgroups": [],
  "advertisable": "string",
  "body": "string",
  "created_date": "string",
  "destination_url": "string",
  "display_url_override": "string",
  "eid": "string",
  "has_edits": true,
  "has_future_campaigns": true,
  "has_pending_edits": true,
  "headline": "string",
  "height": 0,
  "is_active": true,
  "is_outlined": true,
  "message": "string",
  "name": "string",
  "original_ad": "string",
  "outline_color": "string",
  "src": "string",
  "status": "string",
  "type": "string",
  "updated_date": "string",
  "valid_clicktag": true,
  "width": 0
}

Schema

Type

object

eid

EID of the ad.

Type

string

ad_format_id

The id of the corresponding ad format in the AdRoll system

Type

integer

ad_format

Format string. i.e. ‘300 wide x 250 high’

Type

string

ad_format_name

Format string. i.e. ‘300x250’

Type

string

advertisable

The EID of the advertisable to which this ad belongs

Type

string

adgroups

The list of adgroup EIDs that this ad belongs to

Type

array of items

has_future_campaigns

Whether or not this ad has the possibility of serving based on the adgroups and campaigns in which it inhabits

Type

boolean

destination_url

The URL that the browser will navigate to when this ad is clicked

Type

string

headline

For Facebook ads, the text to be displayed as the ad’s headline

Type

string

body

For Facebook ads, the text to be displayed as the ad’s body

Type

string

message

For Facebook Newsfeed ads, the text to be displayed as the ad’s message

Type

string

is_active

Whether or not this ad is currently active

Type

boolean

name

The name of this ad

Type

string

src

This ad’s creative’s source URL

Type

string

status

One of ‘approved’, ‘admin_review’, ‘paused’

Type

string

type

The ad type: ‘image’ or ‘ad_network’

Type

string

height

The height in pixels of this ad’s creative

Type

integer

width

The width in pixels of this ad’s creative

Type

integer

created_date

The date this ad was created

Type

string

updated_date

The date this ad was last updated

Type

string

has_edits

Whether or not this ad has been edited such that another ad has it’s original ad parameter set to this ad’s EID

Type

boolean

has_pending_edits

Whether or not this ad has edits that must be reviewed by an AdRoll administrator

Type

boolean

original_ad

The EID of the ad that was edited to create this ad

Type

string

is_outlined

Whether or not an outline has been applied to the ad to satisfy network compliancy

Type

boolean

outline_color

Hexadecimal color code corresponding to the outline of an ad

Type

string

valid_clicktag

If the ad is in flash format, this is the flag showing whether or not the clickTAG is compliant

Type

boolean

display_url_override

When the destination URL uses a redirect, this value is used as the destination URL by our partner networks during ad reviews.

Type

string

POST /api/v1/adgroup/add_segments

Adds (associates) segments to an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup to add the segments to
segments	True	string	A comma-separated string of the EIDs of the segments to add to this adgroup
is_negative	False	boolean	Whether or not this segment is negatively targeted (Optional; default: False)

Responses:

200

Schema as JSON:

{
  "results": true
}

Schema

Type

object

results

Whether or not the segments were added

Type

boolean

POST /api/v1/adgroup/create

Creates a new adgroup on a campaign.

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

Form Parameters

Name	Required	Type	Description
campaign	True	string	EID of campaign to attach the adgroup to
name	False	string	The name of the new adgroup (Optional; default: None)
status	False	string	The status of the adgroup. One of [‘approved’, ‘draft’] (Optional; default: ‘approved’)
ads	False	string	A comma-separated string of Ad EIDs to attach to the adgroup (Optional; default: None)
positive_segments	False	string	A comma-separated string of Segment EIDs to attach to the adgroup as positive segments (Optional; default: None)
negative_segments	False	string	A comma-separated string of Segment EIDs to attach to the adgroup as negative segments (Optional; default: None)
product_set	False	string	The Product Set to attach to this adgroup (Optional; default: None) - DEPRECATED it will be discarded from the incoming payload
geo_targets	False	string	JSON string of desired geo targets for the adgroup The parsed JSON should be an array of objects, each object should be like: {“country_id”:19, “eid”:”YD2QNVI2GVH4DP4TIO8GEO”, “is_negative”:false} The first ID should be one of: - “country_id” - “region_id” - “metro_id” - “city_id” - “postal_code_id” - “postal_code” “is_negative” is a boolean, defaulting to False. When is_negative is true, that means the geolocation is excluded. “eid” is the true identifier obtained from magellan about this geo_target. Example of JSON string: ‘[{“country_id”:19,”eid”:”YD2QNVI2GVH4DP4TIO8GEO”,”is_negative”:false}, {“region_id”:”USCA”,”eid”:”FPDT2YVTEZG3LNMQ5Q8GEO”,”is_negative”:false}]’ All existing geo targets will be removed before adding the new ones. If omitted, the adgroup will get the same geo targets as other adgroups in the same campaign.(Optional; default: None)
placement_targets	True	array	A JSON list of placements targets for Facebook ads - DEPRECATED it will not be returned anymore

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The new adgroup’s “get” representation

Type

object

POST /api/v1/adgroup/deselect_ads

Detaches ads from an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup whose ads are to be detached
ads	True	array	A list of the EIDs of the ads to detach from this adgroup

Responses:

200

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list of compliancy dictionaries in the following format: {ad: ad_eid, sites: [DEPRECATED], errors: [DEPRECATED]}.

Type

array of items

POST /api/v1/adgroup/edit

Edits an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	EID of the adgroup to edit
name	False	string	The name of the adgroup (Optional; default: None)
status	False	string	The status of the adgroup. One of [‘approved’, ‘paused’] (Optional; default: None)
ads	False	string	A comma-separated string of Ad EIDs to attach to the adgroup (Optional; default: None)
positive_segments	False	string	A comma-separated string of Segment EIDs to attach to the adgroup as positive segments. Will take the place of existing positive segments. (Optional; default: None)
negative_segments	False	string	A comma-separated string of Segment EIDs to attach to the adgroup as negative segments. Will take the place of existing negative segments. (Optional; default: None)
product_set	False	string	The Product Set to attach to this adgroup (Optional; default: None) - DEPRECATED it will be discarded from the incoming payload
geo_targets	False	string	JSON string of desired geo targets for the adgroup The parsed JSON should be an array of objects, each object should be like: {“country_id”:19, “eid”:”YD2QNVI2GVH4DP4TIO8GEO”, “is_negative”:false} The first ID should be one of: - “country_id” - “region_id” - “metro_id” - “city_id” - “postal_code_id” - “postal_code” “is_negative” is a boolean, defaulting to False. When is_negative is true, that means the geolocation is excluded. “eid” is the true identifier obtained from magellan about this geo_target. Example of JSON string: ‘[{“country_id”:19,”eid”:”YD2QNVI2GVH4DP4TIO8GEO”,”is_negative”:false}, {“region_id”:”USCA”,”eid”:”FPDT2YVTEZG3LNMQ5Q8GEO”,”is_negative”:false}]’ All existing geo targets will be removed before adding the new ones. (Optional; default: None)
geo_target_worldwide	True	boolean	If passed, all geo targets of the adgroup will be removed. (Optional)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The adgroup’s “get” representation after being edited

Type

object

GET /api/v1/adgroup/get

Fetches an adgroup by its EID.

Parameters:

Query Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup to fetch
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

Schema as JSON:

{
  "ad_optimization": "string",
  "ads": [],
  "campaign": "string",
  "created_date": "string",
  "eid": "string",
  "flight_timezone": "string",
  "geo_targets": [],
  "name": "string",
  "placement_targets": [],
  "platform_targets": [],
  "product_set": {},
  "segments": [],
  "site_exclusions": [],
  "status": "string",
  "updated_date": "string"
}

Schema

Type

object

ad_optimization

The strategy used to optimize ads when multiple ads fit a single ad space

Type

string

campaign

The EID of the campaign that this adgroup is associated with

Type

string

eid

The EID of the adgroup

Type

string

name

The name of this adgroup

Type

string

status

This adgroup’s current status

Type

string

created_date

The date this adgroup was created

Type

string

updated_date

The date this adgroup was last updated

Type

string

geo_targets

Deprecated. See geo_targets field on AdGroups.

Type

array of items

ads

A list of dictionaries for the ads attached to the adgroup. Each entry has two fields: ‘id’, which is the EID of the Ad; and ‘status’, which is the status of the ad within this adgroup.

Type

array of items

segments

A list of dictionaries for the segments attached to the adgroup. Each entry has ‘id’ and ‘is_negative’ fields. Each entry has two fields: ‘id’, which is the EID of the segment; and ‘is_negative’, which defines whether the segment is excluded (`is_negative` == True) or included (`is_negative` == False) within this adgroup.

Type

array of items

site_exclusions

The list of excluded domains for the adgroup, with ad format information, if any

Type

array of items

platform_targets

A list of dictionaries for the adgroup’s platform targets. - DEPRECATED it will return an emptry list

Type

array of items

placement_targets

A list of strings for an adgroup’s placement targets. Each entry can have a value of ‘all’, ‘newsfeed’, or ‘rightcolumn’

Type

array of items

flight_timezone

The timezone preference of all flights of this adgroup

Type

string

product_set

The product_set object, if exists. - DEPRECATED it will not be returned anymore

Type

object

GET /api/v1/adgroup/get_ads

Fetches the ads associated with this adgroup, based on the specified filter parameters. If a filter argument is not specified for a field, and the field does not have a default value, then no filtering will be done on that field.

Parameters:

Query Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the advertisable whose ads are to be fetched
is_active	False	boolean	If True, only active ads will be returned, and vice versa (Optional; default: True)
statuses	False	array	Only ads that match one of these statuses will be returned (Optional; default: None)
types	False	array	Only ads that match one of these types will be returned (Optional; default: None)
width	False	integer	Only ads having one of the specified widths will be returned (Optional; default: None)
height	False	integer	Only ads having one of the specified heights will be returned (Optional; default: None)
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each ad’s “get” representation

Type

array of items

POST /api/v1/adgroup/pause

Pauses an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	EID of the adgroup to pause

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

results.status is the adgroup’s new status

Type

object

POST /api/v1/adgroup/pause_ad

Pauses a running ad.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup on which to pause the ad
ad	True	string	The EID of the ad to pause on the given adgroup

Responses:

200

Schema as JSON:

{
  "status": "string"
}

Schema

Type

object

status

The new status of the paused ad

Type

string

POST /api/v1/adgroup/pause_ads

Pauses a list of running ads in an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup on which to pause the ad
ads	True	string	The EIDs of the ads to pause on the given adgroup

Responses:

200

Schema as JSON:

{
  "status": "string"
}

Schema

Type

object

status

The new status of the paused ad(s)

Type

string

POST /api/v1/adgroup/remove_segments

Removes (dissociates) segments from an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup from which to remove the segments
segments	True	string	A comma-separated string of the EIDs of the segments to remove from this adgroup

Responses:

200

Schema as JSON:

{
  "results": true
}

Schema

Type

object

results

Whether or not the segments were removed

Type

boolean

POST /api/v1/adgroup/select_ads

Attach ads to an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup to attach the ads to
ads	True	array	A list of the EIDs of the ads to attach to the adgroup

Responses:

200

Schema as JSON:

{
  "comps": []
}

Schema

Type

object

comps

A list of compliancy dictionaries in the following format: {ad: ad_eid, sites: [DEPRECATED], errors: [DEPRECATED]}.

Type

array of items

POST /api/v1/adgroup/unpause

Unpauses an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	EID of the adgroup to unpause

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

results.status is the adgroup’s new status

Type

object

POST /api/v1/adgroup/unpause_ad

Unpauses a paused ad.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup on which to unpause the ad
ad	True	string	The EID of the ad to unpause on the given adgroup

Responses:

200

Schema as JSON:

{
  "advertiser_status": "string"
}

Schema

Type

object

advertiser_status

The new status of the unpaused ad

Type

string

POST /api/v1/adgroup/unpause_ads

Unpauses a list of running ads in an adgroup.

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

Form Parameters

Name	Required	Type	Description
adgroup	True	string	The EID of the adgroup on which to pause the ad
ads	True	string	The EIDs of the ads to pause on the given adgroup

Responses:

200

Schema as JSON:

{
  "statuses": []
}

Schema

Type

object

statuses

A list of dicts for each ad given, containing the ad’s EID and its new status.

Type

array of items

POST /api/v1/advertisable/create

Creates a new advertisable.

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

Form Parameters

Name	Required	Type	Description
name	True	string	The name of the advertisable.
organization	True	string	The EID of the organization who will own this advertisable. You need to own this organization.
set_as_default	False	boolean	Whether or not the created advertisable should be your new default advertisable. (Optional; default: False)
url	False	string	The advertisable’s URL. (Optional; default: None)
product_name	False	string	The advertisable’s specified product or brand. (Optional; default: None)
country_code	False	string	The ISO‌-3166 2-Letter country code the company is based in. This field is used to handle data collection policies in different countries. If left blank, we will apply our most conservative rules. (Optional; default: None)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The new advertisable’s “get” representation.

Type

object

POST /api/v1/advertisable/edit

Edits an advertisable.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the advertisable to edit
click_through_conversion_window	False	integer	Size of this advertisables’ click through conversion window in days (Optional; default: None)
name	False	string	The name of the advertisable (Optional; default: None)
path_name	False	string	A unique string used in all URLs referring to this advertisable (Optional; default: None)
url	False	string	The advertisable’s URL (Optional; default: None)
product_name	False	string	The advertisable’s specified product or brand (Optional; default: None)
view_through_conversion_window	False	integer	Size of this advertisables’ view through conversion window in days (Optional; default: None)
is_twitter_syncing	False	boolean	Whether this advertisable is actively syncing its cookie data to Twitter (Optional; default: None)
twitter_handle	False	string	Twitter handle used by the advertisable (Optional; default: None)
country_code	False	string	The ISO-3166 2-Letter country code the advertisable is registered in. (Optional; default: None)
is_coop_approved	False	boolean	True if the advertisable should be opted-into prospecting (Optional; default: False)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The advertisable’s “get” representation after being edited

Type

object

POST /api/v1/advertisable/enable_rollcrawl

Enable RollCrawl on an advertisable and set the feed URL. This is an advanced feature that first must be enabled by AdRoll admins before use.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable.
url	True	string	The URL of the product feed. Must point to an XML, JSON or CSV resource or a zipped or gzipped version of such a resource.
crawl_interval_seconds	False	integer	The interval to run the crawl. Must be between 720 and 43200. (Optional; default: 2880)

Responses:

200

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/advertisable/get

Fetches an advertisable by its EID.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable to fetch
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

Schema as JSON:

{
  "approval_state": "string",
  "attached_users": [],
  "blacklisted_sites": [],
  "business_unit": "string",
  "click_through_conversion_window": 0,
  "company_phone": "string",
  "created_date": "string",
  "ecomm_platform_plan": "string",
  "eid": "string",
  "enable_customer_multi_dur_segs": true,
  "has_approved_consent_solution": true,
  "has_privacy_policy": true,
  "iab1_category_id": 0,
  "iab1_category_name": 0,
  "iab2_category_id": 0,
  "iab2_category_name": 0,
  "iab_content_id": 0,
  "is_active": true,
  "is_coop_approved": true,
  "is_publisher": true,
  "liquidads": "string",
  "name": "string",
  "ops": "string",
  "optimizer": "string",
  "organization": "string",
  "product_name": "string",
  "saleser": "string",
  "status": "string",
  "updated_date": "string",
  "url": "string",
  "view_through_conversion_window": 0,
  "zvelo_category_id": 0,
  "zvelo_category_name": "string"
}

Schema

Type

object

eid

The EID of the advertisable

Type

string

is_active

Whether or not the advertisable is currently active

Type

boolean

name

The name of the advertisable

Type

string

organization

The EID of this advertisable’s organization

Type

string

status

The status of the advertisable. One of [‘admin_review’, ‘approved’, ‘rejected’].

Type

string

url

The advertisable’s URL

Type

string

product_name

The advertisable’s specified product or brand

Type

string

click_through_conversion_window

Duration of this advertisable’s click through conversion window in days

Type

integer

view_through_conversion_window

Duration of this advertisable’s view through conversion window in days

Type

integer

created_date

The date this advertisable was created (UTC).

Type

string

updated_date

The date this advertisable was last updated (UTC).

Type

string

attached_users

The IDs of additional users allowed to access the advertisable

Type

array of items

blacklisted_sites

The list of blacklisted domains for the advertisable

Type

array of items

enable_customer_multi_dur_segs

Whether or not the advertisable is allowed to create multiple duration segments

Type

boolean

is_coop_approved

Whether or not the advertisable has approved the data co-op terms of use

Type

boolean

is_publisher

Whether or not this advertisable is a publisher

Type

boolean

iab1_category_id

IAB1 Category

Type

integer

iab1_category_name

IAB1 Category Name

Type

integer

iab2_category_id

IAB2 Category

Type

integer

iab2_category_name

IAB2 Category Name

Type

integer

iab_content_id

IAB Content Category

Type

integer

zvelo_category_id

3rd party service we use to categorize sites for auto whitelisting

Type

integer

zvelo_category_name

3rd party service category name

Type

string

approval_state

Auto approval state derived from /zvelo service and/or manually overridden

Type

string

has_privacy_policy

site has privacy policy

Type

boolean

ops

The EID of this advertisable’s ops

Type

string

optimizer

The EID of this advertisable’s optimizer

Type

string

saleser

The EID of this advertisable’s saleser

Type

string

liquidads

The EID of this advertisable’s liquidads

Type

string

has_approved_consent_solution

Whether or not advertisable has an approved Consent Banner solution

Type

boolean

business_unit

The Business Unit of the advertisable.

Type

string

company_phone

The Phone Number of the advertisable’s company.

Type

string

ecomm_platform_plan

The advertisable’s ecommerce platform plan –if applicable and known.

Type

string

GET /api/v1/advertisable/get_adgroups

Fetches the adgroups associated with an advertisable based on the given filters. There are two sets of filters, one for choosing which campaigns to select, and one for choosing which adgroups to select from those campaigns.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable whose adgroups are to be fetched
camp_active	False	boolean	If True, only active campaigns will be returned, and vice versa (Optional; default: True)
camp_statuses	False	array	Only campaigns that match one of these statuses will be returned (Optional; default: None)
camp_blacklist_statuses	False	array	Only campaigns whose status is not one of these will be returned (Optional; default: None)
camp_types	False	array	Only campaigns that match one of these types will be returned (Optional; default: None)
statuses	False	array	Only adgroups that match one of these statuses will be returned (Optional; default: [‘approved’, ‘admin_review’, ‘paused’, ‘admin_paused’])
blacklist_statuses	False	array	Only adgroups whose status is not one of these will be returned (Optional; default: None)
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each adgroup’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_adgroups_fast

Fetches the adgroups associated with an advertisable based on the given filters. There are two sets of filters, one for choosing which campaigns to select, and one for choosing which adgroups to select from those campaigns.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable whose adgroups are to be fetched
camp_active	False	boolean	If True, only active campaigns will be returned, and vice versa (Optional; default: True)
camp_eids	False	array	Only campaigns that match one of these EIDs will be returned (Optional; default: None)
camp_statuses	False	array	Only campaigns that match one of these statuses will be returned (Optional; default: None)
camp_blacklist_statuses	False	array	Only campaigns whose status is not one of these will be returned (Optional; default: None)
camp_types	False	array	Only campaigns that match one of these types will be returned (Optional; default: None)
statuses	False	array	Only adgroups that match one of these statuses will be returned (Optional; default: [‘approved’, ‘admin_review’, ‘paused’, ‘admin_paused’])
blacklist_statuses	False	array	Only adgroups whose status is not one of these will be returned (Optional; default: None)
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each adgroup’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_ads

Fetches the ads associated with an advertisable based on the given filters. If a filter argument is not specified for a field, and the field does not have a default value, then no filtering will be done on that field.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable whose ads are to be fetched
is_active	False	boolean	If True, only active ads will be returned, and vice versa (Optional; default: True)
statuses	False	array	Only ads that match one of these statuses will be returned (Optional; default: None)
types	False	array	Only ads that match one of these types will be returned (Optional; default: None)
width	False	integer	Only ads having the specified width will be returned (Optional; default: None)
height	False	integer	Only ads having the specified height will be returned (Optional; default: None)
include_fb	False	boolean	If True, Facebook ads will be included; if False, Facebook ads will be excluded (Optional; default: True)
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each ad’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_ads_fast

Fetches the ads associated with an advertisable based on the given filters. If a filter argument is not specified for a field, and the field does not have a default value, then no filtering will be done on that field.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable whose ads are to be fetched
is_active	False	boolean	If True, only active ads will be returned, and vice versa (Optional; default: True)
statuses	False	array	Only ads that match one of these statuses will be returned (Optional; default: None)
types	False	array	Only ads that match one of these types will be returned (Optional; default: None)
width	False	integer	Only ads having the specified width will be returned (Optional; default: None)
height	False	integer	Only ads having the specified height will be returned (Optional; default: None)
include_fb	False	boolean	If True, ads with Facebook ad formats will be included (Optional; default: True)
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each ad’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_campaigns

Fetches the campaigns associated with an advertisable based on the given filters. If a filter argument is not specified for a field, and the field does not have a default value, then no filtering will be done on that field.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable whose campaigns are to be fetched
is_active	False	boolean	If True, only active campaigns will be returned, and vice versa (Optional; default: True)
statuses	False	array	Only campaigns that match one of these statuses will be returned (Optional; default: None)
blacklist_statuses	False	array	Only campaigns whose status is not one of these will be returned (Optional; default: None)
types	False	array	Only campaigns that match one of these types will be returned (Optional; default: None)
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each campaign’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_campaigns_fast

Fetches the campaigns associated with an advertisable based on the given filters. If a filter argument is not specified for a field, and the field does not have a default value, then no filtering will be done on that field.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable whose campaigns are to be fetched
is_active	False	boolean	If True, only active campaigns will be returned, and vice versa (Optional; default: True)
statuses	False	array	Only campaigns that match one of these statuses will be returned (Optional; default: None)
blacklist_statuses	False	array	Only campaigns whose status is not one of these will be returned (Optional; default: None)
types	False	array	Only campaigns that match one of these types will be returned (Optional; default: None)
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each campaign’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_pixel

Fetches the active pixel for a given advertisable

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the advertisable. :number pixel_version: pixel version requested, default to 2
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The pixel’s “get” representation

Type

object

GET /api/v1/advertisable/get_segments

Fetches the segments from the active pixel for a given advertisable

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the advertisable. :number page: Current page, defaults to 0. :number per_page: Number of results in each page, do not fill if you don’t want pagination.
sort	True	string	Column to sort the data (rules.created_date, rules.duration_sec).
type	True	string	Filter by the type. :number duration: Filter by the duration in days.
created_start	True	string	Filter by segments created before this date.
created_end	True	string	Filter by segments created after this date.
include_migration_data	True	boolean	Wether to include CDP+ migration related data in the response.
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

Schema as JSON:

{
  "pagination": {},
  "results": []
}

Schema

Type

object

results

The list of segments in their “get” representation

Type

array of items

pagination

Pagination data with `count` and `pages`

Type

object

GET /api/v1/advertisable/get_suggested_country

Recommends a country for an advertiser based on other known data

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

Schema as JSON:

{}

Schema

Type

object

POST /api/v1/advertisable_logo/create

Upload a logo for an advertisable.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable to which this logo will belong
logo_file	True	string	The image file to be used as the advertisables logo. Pass this in as a base64-encoded string. Aspect ratio: Square or close to square is best. Very narrow images will not display properly. (Supported formats: jpeg, png; Max size limited to 10MB)

Responses:

200

Schema as JSON:

{
  "height": 0,
  "id": "string",
  "s3_logo_path": "string",
  "width": 0
}

Schema

Type

object

id

The ID of the advertisable that uses this logo

Type

string

s3_logo_path

Path to the file

Type

string

width

Width of the logo file in pixels

Type

integer

height

Height of the logo file in pixels

Type

integer

POST /api/v1/campaign/create

Creates a new campaign

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the advertisable to which this campaign will belong
budget	True	number	The WEEKLY budget for the campaign
ui_budget_daily	False	boolean	Whether or not this campaign should show a daily budget in the UI. (Optional; default: true)
is_retargeting	False	boolean	Is this a retargeting campaign? Otherwise, false == geo campaign. (Optional; default: false)
is_fbx_newsfeed	False	boolean	Is this a Facebook newsfeed campaign? Otherwise, false (Optional; default: false)
adgroups	False	array	List of EIDs of adgroups to attach to this campaign (Optional; default: None)
cpc	False	number	The CPC goal for the campaign (Optional; default: None)
cpm	False	number	The CPM limit of the campaign, used in pricing model (Optional; default: None)
start_date	False	string	The day the campaign will start (Optional; default: tomorrow)
end_date	False	string	The day the campaign will end, exclusive. If None, then will run without end. (Optional; default: None)
name	False	string	The name of the campaign (Optional; default: None)
status	False	string	The status of the campaign. One of [‘admin_review’, ‘draft’] (Optional; default: admin_review)
max_cpm	False	number	The CPM limit for the networks, used in bidding (Optional; default: None)
networks	False	string	A string of letters representing which networks to set up initially. Currently only supports ‘f’ (Facebook). (Optional; default: None)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The new campaign’s “get” representation

Type

object

POST /api/v1/campaign/edit

Edits an existing campaign.

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

Form Parameters

Name	Required	Type	Description
campaign	True	string	The EID of the campaign to edit
budget	False	number	The new WEEKLY budget for the campaign (Optional; default: None)
ui_budget_daily	True	boolean	Whether or not this campaign is configured with a daily budget in the UI
cpc	False	number	The new CPC goal for the campaign (Optional; default: None)
cpm	False	number	The new CPM limit of the campaign, to be used in bidding (Optional; default: None)
end_date	False	string	The new end date of the campaign, exclusive (Optional; default: None)
is_retargeting	False	boolean	Whether or not the campaign is a retargeting campaign (Optional; default: None)
name	False	string	The new name of the campaign (Optional; default: None)
start_date	False	string	The new start date of the campaign (Optional; default: None)

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The campaign’s “get” representation after being edited

Type

object

GET /api/v1/campaign/get

Fetches a campaign by its EID.

Parameters:

Query Parameters

Name	Required	Type	Description
campaign	True	string	The EID of the campaign to fetch
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

Schema as JSON:

{
  "adgroups": [],
  "advertisable": "string",
  "bid_strategy": "string",
  "bid_strategy_target": "string",
  "billing_auth_status": "string",
  "budget": 0.0,
  "cpc": 0.0,
  "cpm": 0.0,
  "created_date": "string",
  "eid": "string",
  "end_date": "string",
  "is_active": true,
  "is_apple": true,
  "is_contextual": true,
  "is_coop": true,
  "is_ctv": true,
  "is_demo_interest": true,
  "is_facebook": true,
  "is_fb_wca": true,
  "is_fbx_newsfeed": true,
  "is_lookalike": true,
  "is_pubgraph": true,
  "is_retargeting": true,
  "max_cpm": 0.0,
  "name": "string",
  "pricing_strategies": [],
  "spend_limit_until": "string",
  "start_date": "string",
  "status": "string",
  "ui_budget_daily": true,
  "updated_date": "string"
}

Schema

Type

object

adgroups

List of EIDs of the adgroups attached to this campaign

Type

array of items

advertisable

EID of the advertisable to which this campaign belongs

Type

string

budget

The WEEKLY budget of the campaign

Type

number

ui_budget_daily

Whether or not this campaign is configured with a daily budget in the UI

Type

boolean

created_date

The date this campaign was created (UTC).

Type

string

cpc

The CPC for this campaign

Type

number

cpm

The CPM for this campaign

Type

number

eid

EID of the campaign

Type

string

end_date

The date the campaign will end, exclusive (UTC).

Type

string

is_active

Whether or not this campaign is currently active

Type

boolean

is_facebook

Whether or not this campaign is configured for the Facebook network

Type

boolean

is_fbx_newsfeed

Whether or not this campaign is configured for the Facebook Newsfeed

Type

boolean

is_retargeting

Whether or not this campaign is a retargeting campaign

Type

boolean

is_fb_wca

Whether or not this campaign is a Facebook WCA campaign

Type

boolean

is_apple

Whether or not this campaign is an Apple iAd campaign

Type

boolean

is_ctv

Whether or not this campaign is a Connected TV campaign

Type

boolean

is_demo_interest

Whether this campaign is a Demographic&Interest campaign

Type

boolean

is_lookalike

Whether or not this campaign is a Lookalike campaign

Type

boolean

is_contextual

Whether or not this campaign is a Contextual campaign

Type

boolean

max_cpm

The maximum CPM for this campaign

Type

number

name

The name of this campaign

Type

string

pricing_strategies

DEPRECATED Information about pricing strategies for each of this campaign’s active networks.

Type

array of items

start_date

The date the campaign will start (UTC).

Type

string

status

The status of the campaign. One of [“admin_review”, “approved”, “rejected”, “cancelled”, “completed”].

Type

string

billing_auth_status

billing status of the campaign. It can be null or one of [“launched”, “failed”]

Type

string

updated_date

The date this campaign was last updated (UTC).

Type

string

is_coop

Whether or not this is a coop (data sharing) campaign.

Type

boolean

is_pubgraph

Whether or not this is a publisher graph campaign.

Type

boolean

spend_limit_until

The date the campaign can resume spending after being limited by spendtracker (UTC). Can spend if none.

Type

string

bid_strategy

The Bid Strategy of the campaign.

Type

string

bid_strategy_target

The Bid Strategy target of the campaign.

Type

string

GET /api/v1/campaign/get_adgroups

Fetches the adgroups associated with a campaign.

Parameters:

Query Parameters

Name	Required	Type	Description
campaign	True	string	The EID of the campaign whose adgroups are to be fetched
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list containing each adgroup’s “get” representation

Type

array of items

PUT /api/v1/campaign/pause

Pauses a campaign.

Parameters:

Query Parameters

Name	Required	Type	Description
campaign	True	string	The EID of the campaign to pause
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

Schema as JSON:

{
  "results": "string"
}

Schema

Type

object

results

The status of the campaign after being paused

Type

string

PUT /api/v1/campaign/pause_ads

Pauses a list of ads in a campaign.

Parameters:

Query Parameters

Name	Required	Type	Description
campaign	True	string	The EID of the campaign
ads	True	string	The EIDs of the ads to pause
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The statuses of the ads after being paused

Type

array of items

PUT /api/v1/campaign/unpause

Unpauses a campaign.

Parameters:

Query Parameters

Name	Required	Type	Description
campaign	True	string	The EID of the campaign to unpause
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

Schema as JSON:

{
  "results": "string"
}

Schema

Type

object

results

The status of the campaign after being unpaused

Type

string

PUT /api/v1/campaign/unpause_ads

Unpauses a list of ads in a campaign.

Parameters:

Query Parameters

Name	Required	Type	Description
campaign	True	string	The EID of the campaign
ads	True	string	The EIDs of the ads to unpause
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The statuses of the ads after being unpaused

Type

array of items

GET /api/v1/consent_banner/get

DEPRECATED Fetch the consent banner configuration by Advertisable EID.

consent_banner_state will be one of:

• adroll: advertisable has selected AdRoll’s consent banner solution

• custom_pending: advertisable has opted to use their own consent solution and it is pending AdRoll approval

• custom_approved: advertisable’s own consent solution has been approved by AdRoll admins

• custom_rejected: advertisable’s own consent solution was rejected by AdRoll admins

• banner_declined: advertisable has selected not to use a consent solution and AdRoll will not track/serve ads to users in GDPR countries (available only to advertisables in countries not covered by GDPR)

• null: no selection has been made by the advertisable

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of advertisable
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

Schema as JSON:

{
  "config_state_change_date": "string",
  "consent_banner_state": "string"
}

Schema

Type

object

consent_banner_state

Current banner configuration state. One of ‘adroll’, ‘custom_pending’, ‘custom_approved’, ‘custom_pending’, ‘banner_declined’ or null

Type

string

config_state_change_date

Time current configuration was set.

Type

string

GET /api/v1/consent_banner/retrieve

Fetch the consent banner configuration by Advertisable EID.

consent_banner_state will be one of:

• adroll: advertisable has selected AdRoll’s consent banner solution

• custom_pending: advertisable has opted to use their own consent solution and it is pending AdRoll approval

• custom_approved: advertisable’s own consent solution has been approved by AdRoll admins

• custom_rejected: advertisable’s own consent solution was rejected by AdRoll admins

• banner_declined: advertisable has selected not to use a consent solution and AdRoll will not track/serve ads to users in GDPR countries (available only to advertisables in countries not covered by GDPR)

• null: no selection has been made by the advertisable

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of advertisable
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

Schema as JSON:

{
  "config_state_change_date": "string",
  "consent_banner_state": "string"
}

Schema

Type

object

consent_banner_state

Current banner configuration state. One of ‘adroll’, ‘custom_pending’, ‘custom_approved’, ‘custom_pending’, ‘banner_declined’ or null

Type

string

config_state_change_date

Time current configuration was set.

Type

string

POST /api/v1/consent_banner/update

Update or create banner configuration for given advertisable

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	EID of advertisable
state	True	string	new state for banner config. One of ‘adroll’, ‘custom_pending’, ‘banner_declined’
feedback	True	string	(optional) some context about a resubmission update (custom_rejected -> custom_pending transition only).

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The consent banner config’s “get” representation

Type

object

PUT /api/v1/dynamic_configuration/edit

Edit the Dynamic configuration.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the advertisable.
key	True	string	Name of property being edited
value	True	string	Value of property to set
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The Dynamic configuration’s “get” representation

Type

object

POST /api/v1/dynamic_configuration/enable

Enable feed parsing on an advertisable and create a feed configuration.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	The EID of the advertisable.
url	True	string	The URL of the product feed. Must point to an XML, JSON or CSV resource or a zipped or gzipped version of such a resource.

Responses:

200

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/dynamic_configuration/get

Get the Dynamic configuration.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the advertisable.
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The Dynamic configuration’s “get” representation

Type

object

GET /api/v1/dynamic_template/get_all_for_advertisable

Retrieve a list of all the available *dynamic_templates* for an *advertisable*.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the *advertisable*
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The list of Dynamic Templates allowed_methods = [GET]

Type

array of items

GET /api/v1/dynamic_template_capability_description/get_all

Retrieve a list of all the available template capabilities

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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The list of Dynamic template capabilities

Type

array of items

POST /api/v1/feed/autoconfigure

Automatically configure a product feed for an Advertisable. This feature must be enabled for your account before you can use it.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the Advertisable
url	True	string	URL of the product feed. Must point to an XML, JSON or CSV resource. The resource can be compressed using zip or gzip.

Responses:

200

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/invoice/get

Fetch an invoice by ID

Parameters:

Query Parameters

Name	Required	Type	Description
invoice	True	string	The ID of the invoice.
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

Schema as JSON:

{
  "amount": 0,
  "end_date": "string",
  "id": "string",
  "organization": "string",
  "start_date": "string",
  "transactions": []
}

Schema

Type

object

id

The invoice ID

Type

string

start_date

The start date of the requested invoice(s)

Type

string

end_date

The end date of the requested invoice(s)

Type

string

organization

The organization of the requested invoice(s)

Type

string

amount

The amount (in U.S. cents) billed by the requested invoice(s)

Type

integer

transactions

The list of account transactions associated with the invoice.

Type

array of items

POST /api/v1/marketplace/create

Create a marketplace mapping. Once setup, all Pixel views with a ``adroll_shop_id`` parameter that match ``shop_id`` will be attributed to ``dest_advertisable_id`` instead of ``source_advertisable_id``.

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

Form Parameters

Name	Required	Type	Description
source_advertisable	True	string	EID of the *marketplace* (parent) Advertisable
dest_advertisable	True	string	EID of the *merchant* (child) Advertisable
shop_id	True	string	Unique identifier for the *merchant* within the *marketplace*
external_shop_id	False	string	An identifier for the merchant that is used by the merchant. Must be unique within entries with the same source_advertisable (Optional; default: None)

Responses:

200

Schema as JSON:

{
  "dest_advertisable_id": "string",
  "id": "string",
  "shop_id": "string",
  "source_advertisable_id": "string"
}

Schema

Type

object

id

ID of the marketplace mapping

Type

string

source_advertisable_id

ID of the *marketplace* (parent) Advertisable

Type

string

dest_advertisable_id

ID of the *merchant* (child) Advertisable

Type

string

shop_id

Unique identifier for the *merchant* within the *marketplace*

Type

string

GET /api/v1/marketplace/get

Retrieve a list of marketplace mappings for a *marketplace* and *merchant*.

Parameters:

Query Parameters

Name	Required	Type	Description
source_advertisable	True	string	EID of the *marketplace* (parent) Advertisable
dest_advertisable	True	string	EID of the *merchant* (child) Advertisable
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The list of marketplace mappings containing feature id, source_advertisable_eid, source_advertisable_id, dest_advertisable_eid, dest_advertisable_id, external_shop_id and shop_id.

Type

array of items

GET /api/v1/organization/get

Fetch the details about a given organization.

Parameters:

Query Parameters

Name	Required	Type	Description
organization	False	string	The EID of the organization to retrieve (optional; default: your organization).
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

Schema as JSON:

{
  "created_date": "string",
  "eid": "string",
  "name": "string"
}

Schema

Type

object

eid

EID of the organization

Type

string

name

The name of this organization

Type

string

created_date

The date this organization was created

Type

string

GET /api/v1/organization/get_accounts

Fetch the accounts associated with an organization.

Parameters:

Query Parameters

Name	Required	Type	Description
organization	False	string	The EID of the organization (optional; default: your organization).
exclude_statuses	False	string	Comma-separated account statuses to exclude (optional; default: no statuses excluded).
include_balances	False	boolean	Whether to include balance information for the accounts (optional; default: True).
include_advertisables	False	boolean	Whether to include a list of advertisables associated to each account (optional; default: False).
include_advertisables_count	False	boolean	Whether to include a count of advertisables associated to each account (optional; default: False).
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The get responses for each of the organization accounts.

Type

array of items

GET /api/v1/organization/get_advertisables

Fetch the advertisables associated with an organization.

Parameters:

Query Parameters

Name	Required	Type	Description
organization	False	string	The EID of the organization (optional; default: your organization).
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The get responses for each of your advertisables.

Type

array of items

GET /api/v1/organization/get_advertisables_paginated

Fetch the advertisables associated with an organization.

Parameters:

Query Parameters

Name	Required	Type	Description
organization	False	string	The EID of the organization (optional; default: your organization). :number page: Current page (optional; default: 1)
per_page	False	integer	How many advertisables to return (optional; default: 10)
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

Schema as JSON:

{
  "meta": {},
  "results": []
}

Schema

Type

object

results

The get responses for each of your advertisables.

Type

array of items

meta

The current page and per_page attributes.

Type

object

GET /api/v1/organization/get_billing_methods

Fetch the billing methods associated with an organization.

Parameters:

Query Parameters

Name	Required	Type	Description
organization	False	string	The EID of the organization (optional; default: your organization).
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list of your billing methods.

Type

array of items

GET /api/v1/organization/get_users

Fetch the users associated with an organization, their role within the organization and their associated advertisables.

Parameters:

Query Parameters

Name	Required	Type	Description
organization	True	string	The EID of the organization (optional; default: your organization). :number page: Current page, defaults to 0. :number per_page: Number of results in each page, do not fill if you don’t want pagination.
email	True	string	Filter by email.
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The viewable users for your organization, represented according to the get response

Type

array of items

GET /api/v1/pixel/get

Fetch the pixel by EID.

Parameters:

Query Parameters

Name	Required	Type	Description
pixel	True	string	EID of the pixel
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

Schema as JSON:

{
  "code": "string",
  "dropped_code_date": "string",
  "eid": "string",
  "is_consistent": true,
  "placed_code_date": "string",
  "status": "string"
}

Schema

Type

object

eid

EID of the pixel.

Type

string

status

The status of the pixel.

Type

string

code

The HTML/Javascript snippet an advertiser should place on their site.

Type

string

is_consistent

Whether or not the pixel is consistent.

Type

boolean

placed_code_date

Time the pixel was last placed.

Type

string

dropped_code_date

Time the pixel was last dropped. :number pixel_version: Version of the pixel code.

Type

string

GET /api/v1/pixel/get_rules

Fetch all the rules associated with a pixel.

Parameters:

Query Parameters

Name	Required	Type	Description
pixel	True	string	The EID of the pixel in question.
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

A list of the pixel’s rules in their “get” representation

Type

array of items

GET /api/v1/pixel/get_segments

Fetch all the segments associated with a pixel.

Parameters:

Query Parameters

Name	Required	Type	Description
pixel	True	string	The EID of the pixel in question. :number page: Current page, defaults to 0. :number per_page: Number of results in each page, do not fill if you don’t want pagination.
sort	True	string	Column to sort the data (rules.created_date, rules.duration_sec).
type	True	string	Filter by the type. :number duration: Filter by the duration in days.
created_start	True	string	Filter by segments created before this date.
created_end	True	string	Filter by segments created after this date.
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

Schema as JSON:

{
  "pagination": {},
  "results": []
}

Schema

Type

object

results

A list of the pixel’s segments in their “get” representation

Type

array of items

pagination

Pagination data with `count` and `pages`

Type

object

POST /api/v1/policy/send_email

Send email using SendWithUs with optional template version support.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the advertisable
template_name	True	string	Name of the email template to use
email_data	True	object	Data to be used in the email template
template_version	True	string	Version of the template to use (Optional)

Responses:

200

Schema as JSON:

{}

Schema

Type

object

PUT /api/v1/product_feeds/add_feed_config

Add a new feed configuration by registering a new product feed.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the Advertisable that the feed belongs to
feed_url	True	string	URL of the feed
feedtype	True	string	Data format used in the feed: auto, csv, xml, json
skipfirstrow	True	boolean	True if the CSV contains a header row that should be skipped
delimiter	True	string	Field delimiter used for CSV feeds
escapechar	True	string	Escape character used for CSV feeds
quotechar	True	string	Quote character used for CSV feeds
skipinitialspace	True	boolean	True if the parser should ignore whitespace after the delimiter character in CSV feeds
encoding	True	string	File encoding used by the feed
tag_name	True	string	XML element containing product info
locale	True	string	Cultural locale of the data defaults to en_US
prices_in_locale_format	True	boolean	True if the price field contains a locale character (i.e. $)
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The feed configuration’s “get” representation

Type

object

POST /api/v1/product_feeds/autoconfigure

Automatically configure a product feed for an Advertisable. This feature must be enabled for your account before you can use it.

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the Advertisable
url	True	string	URL of the product feed. Must point to an XML, JSON or CSV resource. The resource can be compressed using zip or gzip.

Responses:

200

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/product_feeds/delete_feed_config

Delete a feed configuration

Parameters:

Query Parameters

Name	Required	Type	Description
feed_config	True	string	EID of the feed configuration to delete
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

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/product_feeds/delete_parser_config

Delete a parser configuration.

Parameters:

Query Parameters

Name	Required	Type	Description
feed_config	True	string	EID of the parent feed configuration
key	True	string	Name of the field configuration to remove
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

Schema as JSON:

{
  "results": true
}

Schema

Type

object

results

Whether the delete operation succeeded

Type

boolean

PUT /api/v1/product_feeds/edit_feed_config

Edit a feed configuration

Parameters:

Query Parameters

Name	Required	Type	Description
feed_config	True	string	EID of the feed configuration to edit
key	True	string	Name of property being edited
value	True	string	Value of property to set
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The feed configuration’s “get” representation

Type

object

GET /api/v1/product_feeds/feed_downloadable

Verify whether the config at the given feed is downloadable or not

Parameters:

Query Parameters

Name	Required	Type	Description
feed_url	True	string	URL to verify
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

Schema as JSON:

{
  "downloadable": true,
  "errorCode": 0,
  "errorMessage": "string",
  "results": {}
}

Schema

Type

object

results

with the following fields

Type

object

downloadable

Whether or not feed is downloadable

Type

boolean

errorCode

Error code in case of failure

Type

integer

errorMessage

Error message

Type

string

GET /api/v1/product_feeds/feed_status

Get the parse status for the active feed configurations for the specified advertisable.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	Advertisable EID to check the parse status for
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

Schema as JSON:

{
  "errors": 0,
  "feed_config_eid": "string",
  "items": 0,
  "removed_items": 0,
  "results": [],
  "skips": 0,
  "state": "string",
  "timestamp": "string",
  "total_products": 0
}

Schema

Type

object

results

List of objects representing the parse status for each active feed They have the following attributes:

Type

array of items

feed_config_eid

EID of the feed configuration

Type

string

errors

Number of parse errors

Type

integer

items

Number of parsed items

Type

integer

skips

Number of skipped items

Type

integer

removed_items

Number of items removed

Type

integer

total_products

Total number of products in feed

Type

integer

timestamp

Time when parse task ran

Type

string

state

State of parse task

Type

string

GET /api/v1/product_feeds/get_feed_config

Fetch the feed configuration that matches the specified EID

Parameters:

Query Parameters

Name	Required	Type	Description
feed_config	True	string	EID of the feed configuration
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The feed configuration’s “get” representation

Type

object

GET /api/v1/product_feeds/get_parser_config

Get all parser configurations for the given feed configuration.

Parameters:

Query Parameters

Name	Required	Type	Description
feed_config	True	string	EID of the feed configuration to retrieve
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

Contains all parser configurations.

Type

object

GET /api/v1/product_feeds/get_products

Get the parsed products for any or all of the feeds for an advertisable

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the Advertisable
query	True	string	search string
size	True	integer	number of records to fetch
page	True	integer	chunk position by size
feed_selected	True	string	EID of feed to fetch products from
any_word	True	string	search for any word of query
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The products fetched

Type

array of items

GET /api/v1/product_feeds/get_troubled_products

Get the top 5 troubled products for an advertisable

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the Advertisable
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

Schema as JSON:

{
  "results": []
}

Schema

Type

object

results

The 5 troubled products

Type

array of items

GET /api/v1/product_feeds/match_rate

Get the all time match rate statistics for the given Advertisable. If a date is specified, get the match rate for that date as well. Note that statistics are maintained for a rolling window of the past six months.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	Advertisable EID to get match rate statistics for
date	False	string	If specified, match rate for this date (PST) will also be retrieved. Recommended format `YYYY-MM-DD`. (Optional; default: None)
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

Schema as JSON:

{
  "high_match_rate": 0,
  "high_match_rate_date": "string",
  "low_match_rate": 0,
  "low_match_rate_date": "string",
  "match_rate": 0,
  "results": {}
}

Schema

Type

object

results

Contains the following attributes:

Type

object

high_match_rate

All time high match rate

Type

integer

high_match_rate_date

Date on which the all time high match rate happened

Type

string

low_match_rate

All time low match rate

Type

integer

low_match_rate_date

Date on which the all time low match rate happened

Type

string

match_rate

If a date was specified, the match rate for that date

Type

integer

GET /api/v1/product_feeds/parse_preview

Provides a preview of the given raw product data parsed using the given parse configuration.

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of the Advertisable
parse_prices_in_locale_format	True	boolean	Whether to parse prices based on the locale
language_tag	True	string	Language tag
parser_configs	True	string	Stringified JSON object defining configuration for each field
product_data	True	string	Raw product data to be parsed as string
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

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

Parse preview output

Type

object

GET /api/v1/product_feeds/set_parser_config

Set parser configuration for the specified key.

Parameters:

Query Parameters

Name	Required	Type	Description
feed_config	True	string	EID of the feed configuration
key	True	string	Name of the field The following parameters set the parser configuration attributes:
is_required	True	boolean	True if this field is required for the parsed product to be valid
path	True	string	Column number (CSV), field name (JSON), or tag name (XML) for the field
attribute	True	string	Attribute on the tag to use (i.e. text)
type	True	string	Field type (either text, image, price)
regular_expression	True	string	Regular expression to search the field
regular_expression_replace	True	string	Replacement string to apply to the field
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

Schema as JSON:

{
  "results": true
}

Schema

Type

object

results

Whether the set operation succeeded

Type

boolean

POST /api/v1/product_feeds/set_parser_configs

Set parser configs. You’ll need to specify a Parser Configuration for each field. Since we require a minimum number of fields, you’ll have at least four Parser Configurations. Any additional fields will depend on the Dynamic Creative template you’re using.

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

Form Parameters

Name	Required	Type	Description
feed_config	True	string	EID of the feed configuration
parser_configs	True	string	Stringified JSON object defining configuration for each field The parser_configs parameter consists of an object of fields names as keys and field specification objects consisting of the following attributes:
is_required	True	boolean	True if this field is required for the parsed product to be valid
path	True	string	Column number (CSV), field name (JSON), or tag name (XML) for the field
attribute	True	string	Attribute on the tag to use (i.e. text)
regular_expression	True	string	Regular expression to search the field
regular_expression_replace	True	string	Replacement string to apply to the field
type	True	string	Field type (either text, image, price) Example parser_configs object: :: { “id”: { “path”: “id”, “type”: “text”, “attribute”: “text”, “is_required”: “true” }, “title”: { “path”: “title”, “type”: “text”, “attribute”: “text”, “is_required”: “true” }, “image”: { “path”: “image”, “type”: “image”, “attribute”: “text”, “is_required”: “true” }, “url”: { “path”: “url”, “type”: “text”, “attribute”: “text”, “is_required”: “true” }, “price”: { “path”: “price”, “type”: “price”, “attribute”: “text”, “is_required”: “true” } }

Responses:

200

Schema as JSON:

{
  "results": true
}

Schema

Type

object

results

Whether the set operation succeeded

Type

boolean

GET /api/v1/report/ad

Pull reports for your ads. The entity data_format returns:

{
    results: [{
        ad:           'My Ad',
        eid:          'CYTQSJ3EIVDDRAG3MPDLEU',
        status:       'approved',
        ad_size:      '300x250',
        created_date: '2010-02-23',
        cpc:          1.0,
        ctr:          0.234,
        cpm:          2.34,
        cost:         500.00,
        impressions:  213675,
        clicks:       500,
        prospects:      6983
    }]
}

Parameters:

Query Parameters

Name	Required	Type	Description
campaigns	False	array	List of campaign EIDs (optional; default: None)
adgroups	False	array	List of ad group EIDs (optional; default: None)
ads	False	array	List of ad EIDs (optional; default: None)
advertisables	False	array	List of advertisable EIDs (optional; default: None)
data_format	True	string	‘summary’, ‘date’, or ‘entity’ (required)
currency	False	string	the currency code to use for the report (optional; default: ‘USD’)
past_days	False	integer	Run the report for the last n days (optional; default: None)
start_date	False	string	start date of report (optional; default: None)
end_date	False	string	end date of report (optional; default: None)
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

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/report/advertisable

Pull reports for one or more advertisables. The entity data_format returns an object in the following format, for each advertisable EID given:

{
    results: [{
        advertisable: 'My Advertisable',
        eid:          'CYTQSJ3EIVDDRAG3MPDLEU',
        status:       'approved',
        created_date: '2010-02-23',
        cpc:          1.0,
        ctr:          0.234,
        cpm:          2.34,
        cost:         500.00,
        impressions:  213675,
        clicks:       500,
        prospects:    6983
    }]
}

Parameters:

Query Parameters

Name	Required	Type	Description
campaigns	True	array	List of campaign EIDs (optional; default: None). If campaign EIDs are passed, only data from these campaigns will be returned.
adgroups	True	array	List of ad group EIDs (optional; default: None). If adgroup EIDs are passed, only data from these adgroups will be returned.
ads	True	array	List of ad EIDs (optional; default: None). If ad EIDs are passed, only data from these ads will be returned.
advertisables	True	array	List of advertisable EIDs (at least one is required)
data_format	True	string	‘summary’, ‘date’, or ‘entity’ (required)
currency	False	string	the currency code to use for the report (optional; default: ‘USD’)
past_days	False	integer	Run the report for the last n days (optional; default: None)
start_date	False	string	start date of report (optional; default: None)
end_date	False	string	end date of report (optional; default: None)
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

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/report/campaign

Pull reports for campaigns.

Note: Prospecting and new-style Facebook campaigns are not available in this endpoint. We recommend using the GraphQL Reporting API if you need to retrieve data for all campaign types.

The entity data_format returns:

{
    results: [{
        campaign:     'My campaign 1',
        eid:          'CYTQSJ3EIVDDRAG3MPDLEU',
        advertiser:   'My Advertisable',
        type:         'Retargeting',
        status:       'approved',
        created_date: '2010-02-23',
        start_date:   '2010-02-23',
        end_date:     null,
        budget:       3234.0,
        cpc:          1.0,
        ctr:          0.234,
        cpm:          2.34,
        cost:         500.00,
        impressions:  213675,
        clicks:       500,
        prospects:      6983
    }]
}

Parameters:

Query Parameters

Name	Required	Type	Description
campaigns	False	array	List of campaign EIDs (optional; default: None)
adgroups	False	array	List of ad group EIDs (optional; default: None)
ads	False	array	List of ad EIDs (optional; default: None)
advertisables	False	array	List of advertisable EIDs (optional; default: None)
data_format	True	string	‘summary’, ‘date’, or ‘entity’ (required)
currency	False	string	the currency code to use for the report (optional; default: ‘USD’)
past_days	False	integer	Run the report for the last n days (optional; default: None)
start_date	False	string	start date of report (optional; default: None)
end_date	False	string	end date of report (optional; default: None)
attributions	False	boolean	include attribution data (optional; default: False)
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

Schema as JSON:

{}

Schema

Type

object

POST /api/v1/rule/create

Create a new rule on a given pixel.

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

Form Parameters

Name	Required	Type	Description
pixel	True	string	The EID of the pixel in which we want to create a new rule
type	True	string	The type of the rule being created. One of [c, s, p, b] (c=Conversion, s=Segment, p=Prospect, b=Cart). You can’t change this later.
order	True	integer	The priority order in which this rule needs to be applied among the others. Must be unique in the Pixel. The lower the number, the higher the priority.
name	False	string	The arbitrary name of the rule (Optional; default: None).
display_name	False	string	The display name of the rule (Optional; default: None).
pattern	True	string	The regexp-like expression that matches a URL, if creating a URL rule.
duration	True	integer	The duration of inactivity that can elapse before a user is dropped from this rule.
source	True	string	one of [c, d, m] (c=cookie, d=crm_data, m=mobile)
csv_file	True	string	A CSV file with the emails to generate the rule from, if creating a CRM rule. Use a multi-part form request. Must contain at least 100 emails.

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The new rule’s “get” representation

Type

object

GET /api/v1/rule/get

Fetch a rule object by EID.

Parameters:

Query Parameters

Name	Required	Type	Description
rule	True	string	The EID of the rule.
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

Schema as JSON:

{
  "display_name": "string",
  "eid": "string",
  "name": "string",
  "order": 0,
  "pattern": "string",
  "segments": [],
  "source": "string",
  "type": "string"
}

Schema

Type

object

eid

The rule’s EID

Type

string

name

The rule’s name

Type

string

display_name

The rule’s display name

Type

string

pattern

The rule’s url pattern to match

Type

string

type

Type of the rule. One of [c, s, p, b] (c=Conversion, s=Segment, p=Prospect, b=Cart).

Type

string

source

The source of users (js pixel, mobile, crm_data)

Type

string

order

The priority order in which this rule needs to be applied among the others. The lower the number, the higher the priority.

Type

integer

segments

A list of segments objects attached to this rule in the segment’s “get” representation

Type

array of items

GET /api/v1/rule/get_segments

Fetch the segments on a specific rule.

Parameters:

Query Parameters

Name	Required	Type	Description
rule	True	string	The EID of the rule.
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

Schema as JSON:

{
  "segments": []
}

Schema

Type

object

segments

A list of segments objects attached to this rule in the segment’s “get” representation

Type

array of items

POST /api/v1/segment/edit

Edit an existing segment.

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

Form Parameters

Name	Required	Type	Description
conversion_value	True	number	The value of a conversion from this segment (in USD).
duration	True	integer	The duration of inactivity that can elapse before a user is dropped from this segment.

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The edited segment’s “get” representation

Type

object

GET /api/v1/segment/get

Get an existing segment by its EID.

Parameters:

Query Parameters

Name	Required	Type	Description
segment	True	string	The EID of the segment.
include_int_id	True	boolean	whether the response should include segment integer id or not.
include_lookalike	True	boolean	Whether to include lookalike data.
include_migration_data	True	boolean	Wether to include CDP+ migration related data in the response. :LookalikeSegment lookalike_parent: (Optional) The preloaded LookalikeSegment for the segment, to avoid extra database queries. :FacebookCustomAudience facebook_custom_audience: (Optional) The preloaded FacebookCustomAudience for the segment, to avoid extra database queries.
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

Schema as JSON:

{
  "conversion_value": 0.0,
  "display_name": "string",
  "duration": 0,
  "eid": "string",
  "group": 0,
  "match_method": "string",
  "mobile": {},
  "name": "string",
  "pattern": "string",
  "product": "string",
  "threshold": 0,
  "type": "string"
}

Schema

Type

object

eid

The EID of the segment.

Type

string

display_name

Optional name of the segment used for display purposes.

Type

string

name

The name of the segment, for use internally and for JS segment matching.

Type

string

type

The type of the segment. One of [s, u, c, p, b, e, g, x, l, q] (s = Segment, u = Single product, c = Conversion, p = Low-intent, b = Shopping cart, e = Email, g = Prospecting, x = External, l = Product list, q = Coop).

Type

string

match_method

The match method used for the segment.

Type

string

pattern

The URL pattern used for matching users.

Type

string

threshold

The threshold used for match methods with a numerical limit.

Type

integer

duration

The duration of the segment, in days.

Type

integer

conversion_value

The value of a conversion from this segment (in USD).

Type

number

group

The group that the segment belongs to.

Type

integer

mobile

The mobile extension data as in the mobile_rule “get” representation

Type

object

product

The product that the segment belongs to.

Type

string

POST /api/v1/user/edit

Edit an existing User with given parameters.

{'u' : user.id,
 'username' : "deliboard",
 'first_name': 'Deli',
 'last_name': 'Board',
 'email_preference_general': 'true',
 'email_preference_payment': 'false',
 'email_preference_campaign_notifications': 'true',
 'email_preference_help_and_suggestions': 'true'}

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

Form Parameters

Name	Required	Type	Description
u	True	string	The ID of the user you want to modify
username	True	string	The arbitrary username of the user.
first_name	True	string	The arbitrary first name of the user.
last_name	True	string	The arbitrary last name of the user.
email_preference_general	True	string	The general email preference as key value pair with boolean designating desired emails to receive.
email_preference_payment	True	string	The payment email preference as key value pair with boolean designating desired emails to receive.
email_preference_campaign_notifications	True	string	The general email preference as key value pair with boolean designating desired emails to receive.

Responses:

200

Schema as JSON:

{
  "results": {}
}

Schema

Type

object

results

The get representation of the user object.

Type

object

GET /api/v1/user/get

Fetch the currently logged in user

Parameters:

Query Parameters

Name	Required	Type	Description
load_advertisables	True	boolean	Should we fetch advertisables from db?
active_advertisables	True	array	List of active advertisables for this user, will be used if load_advertisables is false.
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

Schema as JSON:

{
  "advertisables": [],
  "created_date": "string",
  "default_profile": "string",
  "default_timezone": "string",
  "eid": "string",
  "email": "string",
  "email_verified": true,
  "first_name": "string",
  "id": "string",
  "last_name": "string",
  "locale": "string",
  "name": "string",
  "organization": "string",
  "organization_role": "string",
  "role": "string",
  "username": "string"
}

Schema

Type

object

eid

The user’s EID

Type

string

id

The user’s ID (deprecated: use EID instead)

Type

string

username

The user’s username

Type

string

email

The user’s email address

Type

string

email_verified

Whether the user’s email address is verified or not

Type

boolean

name

The user’s name

Type

string

first_name

The user’s first name

Type

string

last_name

The user’s first name

Type

string

organization_role

The user’s role within their organization (admin or user)

Type

string

locale

Language/locale preference

Type

string

default_timezone

The user’s specified timezone for reporting and billing use

Type

string

role

Exact user type, as known to AdRoll (typically “user”)

Type

string

organization

The EID of the Organization to which the user belongs

Type

string

default_profile

The EID of the user’s default advertisable

Type

string

created_date

Date that the user was created

Type

string

advertisables

List of advertisable EIDs that this user has access to

Type

array of items

POST /api/v1/user/grant

Grant a user in your organization additional privileges. This action may not be conducted by any non-admin user and may not be performed on one’s own user.

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

Form Parameters

Name	Required	Type	Description
u	True	string	ID of the user to deactivate.
advertisables	True	string	comma-separated string of EIDs for the advertisables you wish to grant a non-admin user access to (admin users have implicit access to every advertisables in an organization. Optional.
organization_role	True	string	pass either ‘user’ or ‘admin’ to designate a role within your organization for the specified user. Optional

Responses:

200

Schema as JSON:

{}

Schema

Type

object

GET /api/v1/xdevice_opt_in/retrieve

Retrieve cross-device opt-in setting

Parameters:

Query Parameters

Name	Required	Type	Description
advertisable	True	string	EID of advertisable
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

Schema as JSON:

{
  "accepted": true
}

Schema

Type

object

accepted

True if the advertisable is opted-into the cross-device graph

Type

boolean

POST /api/v1/xdevice_opt_in/update

Update the cross-device opt-in setting

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

Form Parameters

Name	Required	Type	Description
advertisable	True	string	EID of advertisable
value	True	boolean	True if the advertisable should be opted-into the cross-device graph

Responses:

200

Schema as JSON:

{
  "accepted": true
}

Schema

Type

object

accepted

True if the advertisable is opted-into the cross-device graph

Type

boolean