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¶

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. If the ad type is ‘template_based’ or ‘multi_image’, only the name parameter is required for the ad to be active.

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

updated_date

The date this ad was last updated

Type

string

ad_format

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

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

height

The height in pixels of this ad’s creative

Type

integer

message

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

Type

string

has_pending_edits

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

Type

boolean

headline

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

Type

string

width

The width in pixels of this ad’s creative

Type

integer

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

type

The ad type: ‘liquid’, ‘image’, ‘flash’ or ‘ad_network’

Type

string

body

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

Type

string

is_outlined

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

Type

boolean

original_ad

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

Type

string

ad_format_name

Format string. i.e. ‘300x250’

Type

string

adgroups

The list of adgroup EIDs that this ad belongs to

Type

array of items

is_active

Whether or not this ad is currently active

Type

boolean

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

ad_format_id

The id of the corresponding ad format in the AdRoll system

Type

integer

destination_url

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

Type

string

src

This ad’s creative’s source URL

Type

string

advertisable

The EID of the advertisable to which this ad belongs

Type

string

outline_color

Hexadecimal color code corresponding to the outline of an ad

Type

string

name

The name of this ad

Type

string

status

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

Type

string

eid

EID of the ad.

Type

string

created_date

The date this ad was created

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

PUT /api/v1/adgroup/add_segments¶

Adds (associates) segments to an adgroup.

Parameters:

Query 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)
`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 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

PUT /api/v1/adgroup/deselect_ads¶

Detaches ads from an adgroup.

Parameters:

Query 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
`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 compliancy dictionaries in the following format: {ad: ad_eid, sites: [DEPRECATED], errors: [DEPRECATED]}.

Type

array of items

PUT /api/v1/adgroup/edit¶

Edits an adgroup.

Parameters:

Query 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)
`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 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

status

This adgroup’s current status

Type

string

updated_date

The date this adgroup was last updated

Type

string

product_set

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

Type

object

name

The name of this adgroup

Type

string

campaign

The EID of the campaign that this adgroup is associated with

Type

string

platform_targets

A list of dictionaries for the adgroup’s platform targets.

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

geo_targets

Deprecated. See geo_targets field on AdGroups.

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

eid

The EID of the adgroup

Type

string

ad_optimization

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

Type

string

created_date

The date this adgroup was created

Type

string

flight_timezone

The timezone preference of all flights of this adgroup

Type

string

site_exclusions

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

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

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

PUT /api/v1/adgroup/pause¶

Pauses an adgroup.

Parameters:

Query Parameters¶
Name	Required	Type	Description
`adgroup`	True	string	EID of the adgroup 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

results.status is the adgroup’s new status

Type

object

PUT /api/v1/adgroup/pause_ad¶

Pauses a running ad.

Parameters:

Query 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
`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:
{
  "status": "string"
}
Schema

Type

object

status

The new status of the paused ad

Type

string

PUT /api/v1/adgroup/pause_ads¶

Pauses a list of running ads in an adgroup.

Parameters:

Query 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
`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:
{
  "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

PUT /api/v1/adgroup/select_ads¶

Attach ads to an adgroup.

Parameters:

Query 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
`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:
{
  "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

PUT /api/v1/adgroup/unpause¶

Unpauses an adgroup.

Parameters:

Query Parameters¶
Name	Required	Type	Description
`adgroup`	True	string	EID of the adgroup 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

results.status is the adgroup’s new status

Type

object

PUT /api/v1/adgroup/unpause_ad¶

Unpauses a paused ad.

Parameters:

Query 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
`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:
{
  "advertiser_status": "string"
}
Schema

Type

object

advertiser_status

The new status of the unpaused ad

Type

string

PUT /api/v1/adgroup/unpause_ads¶

Unpauses a list of running ads in an adgroup.

Parameters:

Query 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
`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:
{
  "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)
`has_approved_safari_add_on`	False	boolean	True if the advertisable should be opted-into placing a banner on their website asking Safari visitors to accept cookies (Optional; default: False)
`safari_add_on_theme`	False	string	Which banner theme to use when serving ads on Safari. Either `light` or `dark` (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

updated_date

The date this advertisable was last updated (UTC).

Type

string

liquidads

The EID of this advertisable’s liquidads

Type

string

company_phone

The Phone Number of the advertisable’s company.

Type

string

has_privacy_policy

site has privacy policy

Type

boolean

attached_users

The IDs of additional users allowed to access the advertisable

Type

array of items

approval_state

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

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

iab1_category_name

IAB1 Category Name

Type

integer

product_name

The advertisable’s specified product or brand

Type

string

status

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

Type

string

saleser

The EID of this advertisable’s saleser

Type

string

optimizer

The EID of this advertisable’s optimizer

Type

string

zvelo_category_name

3rd party service category name

Type

string

ops

The EID of this advertisable’s ops

Type

string

iab_content_id

IAB Content Category

Type

integer

click_through_conversion_window

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

Type

integer

is_active

Whether or not the advertisable is currently active

Type

boolean

view_through_conversion_window

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

Type

integer

zvelo_category_id

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

Type

integer

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

iab1_category_id

IAB1 Category

Type

integer

name

The name of the advertisable

Type

string

url

The advertisable’s URL

Type

string

is_publisher

Whether or not this advertisable is a publisher

Type

boolean

iab2_category_id

IAB2 Category

Type

integer

iab2_category_name

IAB2 Category Name

Type

integer

ecomm_platform_plan

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

Type

string

eid

The EID of the advertisable

Type

string

blacklisted_sites

The list of blacklisted domains for the advertisable

Type

array of items

created_date

The date this advertisable was created (UTC).

Type

string

organization

The EID of this advertisable’s organization

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

pagination

Pagination data with `count` and `pages`

Type

object

results

The list of segments in their “get” representation

Type

array of items

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

width

Width of the logo file in pixels

Type

integer

s3_logo_path

Path to the file

Type

string

id

The ID of the advertisable that uses this logo

Type

string

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_coop": true,
  "is_facebook": true,
  "is_fb_wca": true,
  "is_fbx_newsfeed": 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

status

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

Type

string

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

is_fbx_newsfeed

Whether or not this campaign is configured for the Facebook Newsfeed

Type

boolean

is_facebook

Whether or not this campaign is configured for the Facebook network

Type

boolean

is_retargeting

Whether or not this campaign is a retargeting campaign

Type

boolean

bid_strategy_target

The Bid Strategy target of the campaign.

Type

string

start_date

The date the campaign will start (UTC).

Type

string

updated_date

The date this campaign was last updated (UTC).

Type

string

pricing_strategies

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

Type

array of items

ui_budget_daily

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

Type

boolean

end_date

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

Type

string

created_date

The date this campaign was created (UTC).

Type

string

is_active

Whether or not this campaign is currently active

Type

boolean

is_fb_wca

Whether or not this campaign is a Facebook WCA campaign

Type

boolean

max_cpm

The maximum CPM for this campaign

Type

number

name

The name of this campaign

Type

string

advertisable

EID of the advertisable to which this campaign belongs

Type

string

cpm

The CPM for this campaign

Type

number

bid_strategy

The Bid Strategy of the campaign.

Type

string

billing_auth_status

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

Type

string

cpc

The CPC for this campaign

Type

number

budget

The WEEKLY budget of the campaign

Type

number

is_coop

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

Type

boolean

eid

EID of the campaign

Type

string

adgroups

List of EIDs of the adgroups attached to this campaign

Type

array of items

is_apple

Whether or not this campaign is an Apple iAd campaign

Type

boolean

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¶

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

end_date

The end date of the requested invoice(s)

Type

string

transactions

The list of account transactions associated with the invoice.

Type

array of items

start_date

The start date of the requested invoice(s)

Type

string

amount

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

Type

integer

organization

The organization of the requested invoice(s)

Type

string

id

The invoice ID

Type

string

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

shop_id

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

Type

string

dest_advertisable_id

ID of the *merchant* (child) Advertisable

Type

string

id

ID of the marketplace mapping

Type

string

source_advertisable_id

ID of the *marketplace* (parent) Advertisable

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

created_date

The date this organization was created

Type

string

eid

EID of the organization

Type

string

name

The name of this organization

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

meta

The current page and per_page attributes.

Type

object

results

The get responses for each of your advertisables.

Type

array of items

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

status

The status of the pixel.

Type

string

dropped_code_date

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

Type

string

code

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

Type

string

placed_code_date

Time the pixel was last placed.

Type

string

eid

EID of the pixel.

Type

string

is_consistent

Whether or not the pixel is consistent.

Type

boolean

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

pagination

Pagination data with `count` and `pages`

Type

object

results

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

Type

array of items

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_configuration¶

Edits an entire feed configuration (FeedConfig and ParserConfigs) in one call.

Parameters:

Query Parameters¶
Name	Required	Type	Description
`feed_config`	True	string	EID of the FeedConfig
`feed_config_edits`	True	string	Stringified JSON object defining edited FeedConfig
`parser_config_edits`	True	string	Stringified JSON object defining all current ParserConfigs
`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

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

errorCode

Error code in case of failure

Type

integer

errorMessage

Error message

Type

string

downloadable

Whether or not feed is downloadable

Type

boolean

results

with the following fields

Type

object

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

errors

Number of parse errors

Type

integer

items

Number of parsed items

Type

integer

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

skips

Number of skipped items

Type

integer

state

State of parse task

Type

string

total_products

Total number of products in feed

Type

integer

removed_items

Number of items removed

Type

integer

timestamp

Time when parse task ran

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

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

match_rate

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

Type

integer

low_match_rate

All time low match rate

Type

integer

results

Contains the following attributes:

Type

object

low_match_rate_date

Date on which the all time low match rate happened

Type

string

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

display_name

The rule’s display name

Type

string

name

The rule’s name

Type

string

pattern

The rule’s url pattern to match

Type

string

segments

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

Type

array of items

source

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

Type

string

eid

The rule’s EID

Type

string

type

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

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

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

match_method

The match method used for the segment.

Type

string

product

The product that the segment belongs to.

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

mobile

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

Type

object

pattern

The URL pattern used for matching users.

Type

string

conversion_value

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

Type

number

duration

The duration of the segment, in days.

Type

integer

eid

The EID of the segment.

Type

string

threshold

The threshold used for match methods with a numerical limit.

Type

integer

group

The group that the segment belongs to.

Type

integer

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

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

username

The user’s username

Type

string

organization_role

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

Type

string

first_name

The user’s first name

Type

string

last_name

The user’s first name

Type

string

name

The user’s name

Type

string

advertisables

List of advertisable EIDs that this user has access to

Type

array of items

locale

Language/locale preference

Type

string

email_verified

Whether the user’s email address is verified or not

Type

boolean

id

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

Type

string

role

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

Type

string

eid

The user’s EID

Type

string

default_profile

The EID of the user’s default advertisable

Type

string

created_date

Date that the user was created

Type

string

organization

The EID of the Organization to which the user belongs

Type

string

default_timezone

The user’s specified timezone for reporting and billing use

Type

string

email

The user’s email address

Type

string

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/get¶

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

CRUD API Reference¶

Description¶

Operations by Tag¶

Ad¶

Adgroup¶

Advertisable¶

Advertisable Logo¶

Campaign¶

Consent Banner¶

Dynamic Configuration¶

Dynamic Template¶

Dynamic Template Capability Description¶

Feed¶

Invoice¶

Marketplace¶

Organization¶

Pixel¶

Product Feeds¶

Report¶

Rule¶

Segment¶

User¶

Xdevice Opt In¶

Operations¶