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

Dynamic Template Capability Description

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

eid

EID of the ad.

Type

string

ad_format_id

The id of the corresponding ad format in the AdRoll system

Type

integer

ad_format

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

Type

string

ad_format_name

Format string. i.e. ‘300x250’

Type

string

advertisable

The EID of the advertisable to which this ad belongs

Type

string

adgroups

The list of adgroup EIDs that this ad belongs to

Type

array of items

has_future_campaigns

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

Type

boolean

destination_url

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

Type

string

headline

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

Type

string

body

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

Type

string

message

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

Type

string

is_active

Whether or not this ad is currently active

Type

boolean

name

The name of this ad

Type

string

src

This ad’s creative’s source URL

Type

string

status

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

Type

string

type

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

Type

string

height

The height in pixels of this ad’s creative

Type

integer

width

The width in pixels of this ad’s creative

Type

integer

created_date

The date this ad was created

Type

string

updated_date

The date this ad was last updated

Type

string

has_edits

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

Type

boolean

has_pending_edits

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

Type

boolean

original_ad

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

Type

string

is_outlined

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

Type

boolean

outline_color

Hexadecimal color code corresponding to the outline of an ad

Type

string

valid_clicktag

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

Type

boolean

display_url_override

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

Type

string

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

ad_optimization

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

Type

string

campaign

The EID of the campaign that this adgroup is associated with

Type

string

eid

The EID of the adgroup

Type

string

name

The name of this adgroup

Type

string

status

This adgroup’s current status

Type

string

created_date

The date this adgroup was created

Type

string

updated_date

The date this adgroup was last updated

Type

string

geo_targets

Deprecated. See geo_targets field on AdGroups.

Type

array of items

ads

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

Type

array of items

segments

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

Type

array of items

site_exclusions

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

Type

array of items

platform_targets

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

Type

array of items

placement_targets

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

Type

array of items

flight_timezone

The timezone preference of all flights of this adgroup

Type

string

product_set

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

Type

object

GET /api/v1/adgroup/get_ads

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

Parameters:

Query Parameters

Name

Required

Type

Description

adgroup

True

string

The EID of the advertisable whose ads are to be fetched

is_active

False

boolean

If True, only active ads will be returned, and vice versa (Optional; default: True)

statuses

False

array

Only ads that match one of these statuses will be returned (Optional; default: None)

types

False

array

Only ads that match one of these types will be returned (Optional; default: None)

width

False

integer

Only ads having one of the specified widths will be returned (Optional; default: None)

height

False

integer

Only ads having one of the specified heights will be returned (Optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each ad’s “get” representation

Type

array of items

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)

is_coop_approved

False

boolean

True if the advertisable should be opted-into prospecting (Optional; default: False)

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The advertisable’s “get” representation after being edited

Type

object

POST /api/v1/advertisable/enable_rollcrawl

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable.

url

True

string

The URL of the product feed. Must point to an XML, JSON or CSV resource or a zipped or gzipped version of such a resource.

crawl_interval_seconds

False

integer

The interval to run the crawl. Must be between 720 and 43200. (Optional; default: 2880)

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/advertisable/get

Fetches an advertisable by its EID.

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable to fetch

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

eid

The EID of the advertisable

Type

string

is_active

Whether or not the advertisable is currently active

Type

boolean

name

The name of the advertisable

Type

string

organization

The EID of this advertisable’s organization

Type

string

status

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

Type

string

url

The advertisable’s URL

Type

string

product_name

The advertisable’s specified product or brand

Type

string

click_through_conversion_window

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

Type

integer

view_through_conversion_window

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

Type

integer

created_date

The date this advertisable was created (UTC).

Type

string

updated_date

The date this advertisable was last updated (UTC).

Type

string

attached_users

The IDs of additional users allowed to access the advertisable

Type

array of items

blacklisted_sites

The list of blacklisted domains for the advertisable

Type

array of items

enable_customer_multi_dur_segs

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

Type

boolean

is_coop_approved

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

Type

boolean

is_publisher

Whether or not this advertisable is a publisher

Type

boolean

iab1_category_id

IAB1 Category

Type

integer

iab1_category_name

IAB1 Category Name

Type

integer

iab2_category_id

IAB2 Category

Type

integer

iab2_category_name

IAB2 Category Name

Type

integer

iab_content_id

IAB Content Category

Type

integer

zvelo_category_id

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

Type

integer

zvelo_category_name

3rd party service category name

Type

string

approval_state

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

Type

string

has_privacy_policy

site has privacy policy

Type

boolean

ops

The EID of this advertisable’s ops

Type

string

optimizer

The EID of this advertisable’s optimizer

Type

string

saleser

The EID of this advertisable’s saleser

Type

string

liquidads

The EID of this advertisable’s liquidads

Type

string

has_approved_consent_solution

Whether or not advertisable has an approved Consent Banner solution

Type

boolean

business_unit

The Business Unit of the advertisable.

Type

string

company_phone

The Phone Number of the advertisable’s company.

Type

string

ecomm_platform_plan

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

Type

string

GET /api/v1/advertisable/get_adgroups

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable whose adgroups are to be fetched

camp_active

False

boolean

If True, only active campaigns will be returned, and vice versa (Optional; default: True)

camp_statuses

False

array

Only campaigns that match one of these statuses will be returned (Optional; default: None)

camp_blacklist_statuses

False

array

Only campaigns whose status is not one of these will be returned (Optional; default: None)

camp_types

False

array

Only campaigns that match one of these types will be returned (Optional; default: None)

statuses

False

array

Only adgroups that match one of these statuses will be returned (Optional; default: [‘approved’, ‘admin_review’, ‘paused’, ‘admin_paused’])

blacklist_statuses

False

array

Only adgroups whose status is not one of these will be returned (Optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each adgroup’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_adgroups_fast

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable whose adgroups are to be fetched

camp_active

False

boolean

If True, only active campaigns will be returned, and vice versa (Optional; default: True)

camp_eids

False

array

Only campaigns that match one of these EIDs will be returned (Optional; default: None)

camp_statuses

False

array

Only campaigns that match one of these statuses will be returned (Optional; default: None)

camp_blacklist_statuses

False

array

Only campaigns whose status is not one of these will be returned (Optional; default: None)

camp_types

False

array

Only campaigns that match one of these types will be returned (Optional; default: None)

statuses

False

array

Only adgroups that match one of these statuses will be returned (Optional; default: [‘approved’, ‘admin_review’, ‘paused’, ‘admin_paused’])

blacklist_statuses

False

array

Only adgroups whose status is not one of these will be returned (Optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each adgroup’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_ads

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable whose ads are to be fetched

is_active

False

boolean

If True, only active ads will be returned, and vice versa (Optional; default: True)

statuses

False

array

Only ads that match one of these statuses will be returned (Optional; default: None)

types

False

array

Only ads that match one of these types will be returned (Optional; default: None)

width

False

integer

Only ads having the specified width will be returned (Optional; default: None)

height

False

integer

Only ads having the specified height will be returned (Optional; default: None)

include_fb

False

boolean

If True, Facebook ads will be included; if False, Facebook ads will be excluded (Optional; default: True)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each ad’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_ads_fast

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable whose ads are to be fetched

is_active

False

boolean

If True, only active ads will be returned, and vice versa (Optional; default: True)

statuses

False

array

Only ads that match one of these statuses will be returned (Optional; default: None)

types

False

array

Only ads that match one of these types will be returned (Optional; default: None)

width

False

integer

Only ads having the specified width will be returned (Optional; default: None)

height

False

integer

Only ads having the specified height will be returned (Optional; default: None)

include_fb

False

boolean

If True, ads with Facebook ad formats will be included (Optional; default: True)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each ad’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_campaigns

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable whose campaigns are to be fetched

is_active

False

boolean

If True, only active campaigns will be returned, and vice versa (Optional; default: True)

statuses

False

array

Only campaigns that match one of these statuses will be returned (Optional; default: None)

blacklist_statuses

False

array

Only campaigns whose status is not one of these will be returned (Optional; default: None)

types

False

array

Only campaigns that match one of these types will be returned (Optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each campaign’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_campaigns_fast

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable whose campaigns are to be fetched

is_active

False

boolean

If True, only active campaigns will be returned, and vice versa (Optional; default: True)

statuses

False

array

Only campaigns that match one of these statuses will be returned (Optional; default: None)

blacklist_statuses

False

array

Only campaigns whose status is not one of these will be returned (Optional; default: None)

types

False

array

Only campaigns that match one of these types will be returned (Optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each campaign’s “get” representation

Type

array of items

GET /api/v1/advertisable/get_pixel

Fetches the active pixel for a given advertisable

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the advertisable. :number pixel_version: pixel version requested, default to 2

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The pixel’s “get” representation

Type

object

GET /api/v1/advertisable/get_segments

Fetches the segments from the active pixel for a given advertisable

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the advertisable. :number page: Current page, defaults to 0. :number per_page: Number of results in each page, do not fill if you don’t want pagination.

sort

True

string

Column to sort the data (rules.created_date, rules.duration_sec).

type

True

string

Filter by the type. :number duration: Filter by the duration in days.

created_start

True

string

Filter by segments created before this date.

created_end

True

string

Filter by segments created after this date.

include_migration_data

True

boolean

Wether to include CDP+ migration related data in the response.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

results

The list of segments in their “get” representation

Type

array of items

pagination

Pagination data with `count` and `pages`

Type

object

GET /api/v1/advertisable/get_suggested_country

Recommends a country for an advertiser based on other known data

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{}
Schema
Type

object

POST /api/v1/advertisable_logo/create

Upload a logo for an advertisable.

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable to which this logo will belong

logo_file

True

string

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

Responses:

200

Schema as JSON:

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

object

id

The ID of the advertisable that uses this logo

Type

string

s3_logo_path

Path to the file

Type

string

width

Width of the logo file in pixels

Type

integer

height

Height of the logo file in pixels

Type

integer

POST /api/v1/campaign/create

Creates a new campaign

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the advertisable to which this campaign will belong

budget

True

number

The WEEKLY budget for the campaign

ui_budget_daily

False

boolean

Whether or not this campaign should show a daily budget in the UI. (Optional; default: true)

is_retargeting

False

boolean

Is this a retargeting campaign? Otherwise, false == geo campaign. (Optional; default: false)

is_fbx_newsfeed

False

boolean

Is this a Facebook newsfeed campaign? Otherwise, false (Optional; default: false)

adgroups

False

array

List of EIDs of adgroups to attach to this campaign (Optional; default: None)

cpc

False

number

The CPC goal for the campaign (Optional; default: None)

cpm

False

number

The CPM limit of the campaign, used in pricing model (Optional; default: None)

start_date

False

string

The day the campaign will start (Optional; default: tomorrow)

end_date

False

string

The day the campaign will end, exclusive. If None, then will run without end. (Optional; default: None)

name

False

string

The name of the campaign (Optional; default: None)

status

False

string

The status of the campaign. One of [‘admin_review’, ‘draft’] (Optional; default: admin_review)

max_cpm

False

number

The CPM limit for the networks, used in bidding (Optional; default: None)

networks

False

string

A string of letters representing which networks to set up initially. Currently only supports ‘f’ (Facebook). (Optional; default: None)

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The new campaign’s “get” representation

Type

object

POST /api/v1/campaign/edit

Edits an existing campaign.

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

campaign

True

string

The EID of the campaign to edit

budget

False

number

The new WEEKLY budget for the campaign (Optional; default: None)

ui_budget_daily

True

boolean

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

cpc

False

number

The new CPC goal for the campaign (Optional; default: None)

cpm

False

number

The new CPM limit of the campaign, to be used in bidding (Optional; default: None)

end_date

False

string

The new end date of the campaign, exclusive (Optional; default: None)

is_retargeting

False

boolean

Whether or not the campaign is a retargeting campaign (Optional; default: None)

name

False

string

The new name of the campaign (Optional; default: None)

start_date

False

string

The new start date of the campaign (Optional; default: None)

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The campaign’s “get” representation after being edited

Type

object

GET /api/v1/campaign/get

Fetches a campaign by its EID.

Parameters:

Query Parameters

Name

Required

Type

Description

campaign

True

string

The EID of the campaign to fetch

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "adgroups": [],
  "advertisable": "string",
  "bid_strategy": "string",
  "bid_strategy_target": "string",
  "billing_auth_status": "string",
  "budget": 0.0,
  "cpc": 0.0,
  "cpm": 0.0,
  "created_date": "string",
  "eid": "string",
  "end_date": "string",
  "is_active": true,
  "is_apple": true,
  "is_coop": true,
  "is_ctv": 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

adgroups

List of EIDs of the adgroups attached to this campaign

Type

array of items

advertisable

EID of the advertisable to which this campaign belongs

Type

string

budget

The WEEKLY budget of the campaign

Type

number

ui_budget_daily

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

Type

boolean

created_date

The date this campaign was created (UTC).

Type

string

cpc

The CPC for this campaign

Type

number

cpm

The CPM for this campaign

Type

number

eid

EID of the campaign

Type

string

end_date

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

Type

string

is_active

Whether or not this campaign is currently active

Type

boolean

is_facebook

Whether or not this campaign is configured for the Facebook network

Type

boolean

is_fbx_newsfeed

Whether or not this campaign is configured for the Facebook Newsfeed

Type

boolean

is_retargeting

Whether or not this campaign is a retargeting campaign

Type

boolean

is_fb_wca

Whether or not this campaign is a Facebook WCA campaign

Type

boolean

is_apple

Whether or not this campaign is an Apple iAd campaign

Type

boolean

is_ctv

Whether or not this campaign is a Connected TV campaign

Type

boolean

max_cpm

The maximum CPM for this campaign

Type

number

name

The name of this campaign

Type

string

pricing_strategies

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

Type

array of items

start_date

The date the campaign will start (UTC).

Type

string

status

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

Type

string

billing_auth_status

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

Type

string

updated_date

The date this campaign was last updated (UTC).

Type

string

is_coop

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

Type

boolean

is_pubgraph

Whether or not this is a publisher graph campaign.

Type

boolean

spend_limit_until

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

Type

string

bid_strategy

The Bid Strategy of the campaign.

Type

string

bid_strategy_target

The Bid Strategy target of the campaign.

Type

string

GET /api/v1/campaign/get_adgroups

Fetches the adgroups associated with a campaign.

Parameters:

Query Parameters

Name

Required

Type

Description

campaign

True

string

The EID of the campaign whose adgroups are to be fetched

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list containing each adgroup’s “get” representation

Type

array of items

PUT /api/v1/campaign/pause

Pauses a campaign.

Parameters:

Query Parameters

Name

Required

Type

Description

campaign

True

string

The EID of the campaign to pause

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": "string"
}
Schema
Type

object

results

The status of the campaign after being paused

Type

string

PUT /api/v1/campaign/pause_ads

Pauses a list of ads in a campaign.

Parameters:

Query Parameters

Name

Required

Type

Description

campaign

True

string

The EID of the campaign

ads

True

string

The EIDs of the ads to pause

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The statuses of the ads after being paused

Type

array of items

PUT /api/v1/campaign/unpause

Unpauses a campaign.

Parameters:

Query Parameters

Name

Required

Type

Description

campaign

True

string

The EID of the campaign to unpause

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": "string"
}
Schema
Type

object

results

The status of the campaign after being unpaused

Type

string

PUT /api/v1/campaign/unpause_ads

Unpauses a list of ads in a campaign.

Parameters:

Query Parameters

Name

Required

Type

Description

campaign

True

string

The EID of the campaign

ads

True

string

The EIDs of the ads to unpause

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The statuses of the ads after being unpaused

Type

array of items

GET /api/v1/consent_banner/get

DEPRECATED Fetch the consent banner configuration by Advertisable EID.

consent_banner_state will be one of:

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

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

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

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

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

  • null: no selection has been made by the advertisable

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of advertisable

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

consent_banner_state

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

Type

string

config_state_change_date

Time current configuration was set.

Type

string

GET /api/v1/consent_banner/retrieve

Fetch the consent banner configuration by Advertisable EID.

consent_banner_state will be one of:

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

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

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

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

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

  • null: no selection has been made by the advertisable

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of advertisable

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

consent_banner_state

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

Type

string

config_state_change_date

Time current configuration was set.

Type

string

POST /api/v1/consent_banner/update

Update or create banner configuration for given advertisable

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

EID of advertisable

state

True

string

new state for banner config. One of ‘adroll’, ‘custom_pending’, ‘banner_declined’

feedback

True

string

(optional) some context about a resubmission update (custom_rejected -> custom_pending transition only).

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The consent banner config’s “get” representation

Type

object

PUT /api/v1/dynamic_configuration/edit

Edit the Dynamic configuration.

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the advertisable.

key

True

string

Name of property being edited

value

True

string

Value of property to set

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The Dynamic configuration’s “get” representation

Type

object

POST /api/v1/dynamic_configuration/enable

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

The EID of the advertisable.

url

True

string

The URL of the product feed. Must point to an XML, JSON or CSV resource or a zipped or gzipped version of such a resource.

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/dynamic_configuration/get

Get the Dynamic configuration.

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the advertisable.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The Dynamic configuration’s “get” representation

Type

object

GET /api/v1/dynamic_template/get_all_for_advertisable

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the *advertisable*

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The list of Dynamic Templates allowed_methods = [GET]

Type

array of items

GET /api/v1/dynamic_template_capability_description/get_all

Retrieve a list of all the available template capabilities

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The list of Dynamic template capabilities

Type

array of items

POST /api/v1/feed/autoconfigure

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the Advertisable

url

True

string

URL of the product feed. Must point to an XML, JSON or CSV resource. The resource can be compressed using zip or gzip.

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/invoice/get

Fetch an invoice by ID

Parameters:

Query Parameters

Name

Required

Type

Description

invoice

True

string

The ID of the invoice.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

id

The invoice ID

Type

string

start_date

The start date of the requested invoice(s)

Type

string

end_date

The end date of the requested invoice(s)

Type

string

organization

The organization of the requested invoice(s)

Type

string

amount

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

Type

integer

transactions

The list of account transactions associated with the invoice.

Type

array of items

GET /api/v1/invoice/get_details

Fetch an invoice by ID

Parameters:

Query Parameters

Name

Required

Type

Description

invoice

True

string

The ID of the invoice.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

id

The invoice ID

Type

string

start_date

The start date of the requested invoice(s)

Type

string

end_date

The end date of the requested invoice(s)

Type

string

organization

The organization of the requested invoice(s)

Type

string

amount

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

Type

integer

transactions

The list of account transactions associated with the invoice.

Type

array of items

POST /api/v1/marketplace/create

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

source_advertisable

True

string

EID of the *marketplace* (parent) Advertisable

dest_advertisable

True

string

EID of the *merchant* (child) Advertisable

shop_id

True

string

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

external_shop_id

False

string

An identifier for the merchant that is used by the merchant. Must be unique within entries with the same source_advertisable (Optional; default: None)

Responses:

200

Schema as JSON:

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

object

id

ID of the marketplace mapping

Type

string

source_advertisable_id

ID of the *marketplace* (parent) Advertisable

Type

string

dest_advertisable_id

ID of the *merchant* (child) Advertisable

Type

string

shop_id

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

Type

string

GET /api/v1/marketplace/get

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

Parameters:

Query Parameters

Name

Required

Type

Description

source_advertisable

True

string

EID of the *marketplace* (parent) Advertisable

dest_advertisable

True

string

EID of the *merchant* (child) Advertisable

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

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

Type

array of items

GET /api/v1/organization/get

Fetch the details about a given organization.

Parameters:

Query Parameters

Name

Required

Type

Description

organization

False

string

The EID of the organization to retrieve (optional; default: your organization).

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

eid

EID of the organization

Type

string

name

The name of this organization

Type

string

created_date

The date this organization was created

Type

string

GET /api/v1/organization/get_accounts

Fetch the accounts associated with an organization.

Parameters:

Query Parameters

Name

Required

Type

Description

organization

False

string

The EID of the organization (optional; default: your organization).

exclude_statuses

False

string

Comma-separated account statuses to exclude (optional; default: no statuses excluded).

include_balances

False

boolean

Whether to include balance information for the accounts (optional; default: True).

include_advertisables

False

boolean

Whether to include a list of advertisables associated to each account (optional; default: False).

include_advertisables_count

False

boolean

Whether to include a count of advertisables associated to each account (optional; default: False).

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The get responses for each of the organization accounts.

Type

array of items

GET /api/v1/organization/get_advertisables

Fetch the advertisables associated with an organization.

Parameters:

Query Parameters

Name

Required

Type

Description

organization

False

string

The EID of the organization (optional; default: your organization).

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The get responses for each of your advertisables.

Type

array of items

GET /api/v1/organization/get_advertisables_paginated

Fetch the advertisables associated with an organization.

Parameters:

Query Parameters

Name

Required

Type

Description

organization

False

string

The EID of the organization (optional; default: your organization). :number page: Current page (optional; default: 1)

per_page

False

integer

How many advertisables to return (optional; default: 10)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

results

The get responses for each of your advertisables.

Type

array of items

meta

The current page and per_page attributes.

Type

object

GET /api/v1/organization/get_billing_methods

Fetch the billing methods associated with an organization.

Parameters:

Query Parameters

Name

Required

Type

Description

organization

False

string

The EID of the organization (optional; default: your organization).

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

A list of your billing methods.

Type

array of items

GET /api/v1/organization/get_users

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

Parameters:

Query Parameters

Name

Required

Type

Description

organization

True

string

The EID of the organization (optional; default: your organization). :number page: Current page, defaults to 0. :number per_page: Number of results in each page, do not fill if you don’t want pagination.

email

True

string

Filter by email.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

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

Type

array of items

GET /api/v1/pixel/get

Fetch the pixel by EID.

Parameters:

Query Parameters

Name

Required

Type

Description

pixel

True

string

EID of the pixel

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

eid

EID of the pixel.

Type

string

status

The status of the pixel.

Type

string

code

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

Type

string

is_consistent

Whether or not the pixel is consistent.

Type

boolean

placed_code_date

Time the pixel was last placed.

Type

string

dropped_code_date

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

Type

string

GET /api/v1/pixel/get_rules

Fetch all the rules associated with a pixel.

Parameters:

Query Parameters

Name

Required

Type

Description

pixel

True

string

The EID of the pixel in question.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

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

Type

array of items

GET /api/v1/pixel/get_segments

Fetch all the segments associated with a pixel.

Parameters:

Query Parameters

Name

Required

Type

Description

pixel

True

string

The EID of the pixel in question. :number page: Current page, defaults to 0. :number per_page: Number of results in each page, do not fill if you don’t want pagination.

sort

True

string

Column to sort the data (rules.created_date, rules.duration_sec).

type

True

string

Filter by the type. :number duration: Filter by the duration in days.

created_start

True

string

Filter by segments created before this date.

created_end

True

string

Filter by segments created after this date.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

results

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

Type

array of items

pagination

Pagination data with `count` and `pages`

Type

object

PUT /api/v1/product_feeds/add_feed_config

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the Advertisable that the feed belongs to

feed_url

True

string

URL of the feed

feedtype

True

string

Data format used in the feed: auto, csv, xml, json

skipfirstrow

True

boolean

True if the CSV contains a header row that should be skipped

delimiter

True

string

Field delimiter used for CSV feeds

escapechar

True

string

Escape character used for CSV feeds

quotechar

True

string

Quote character used for CSV feeds

skipinitialspace

True

boolean

True if the parser should ignore whitespace after the delimiter character in CSV feeds

encoding

True

string

File encoding used by the feed

tag_name

True

string

XML element containing product info

locale

True

string

Cultural locale of the data defaults to en_US

prices_in_locale_format

True

boolean

True if the price field contains a locale character (i.e. $)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The feed configuration’s “get” representation

Type

object

POST /api/v1/product_feeds/autoconfigure

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the Advertisable

url

True

string

URL of the product feed. Must point to an XML, JSON or CSV resource. The resource can be compressed using zip or gzip.

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/product_feeds/delete_feed_config

Delete a feed configuration

Parameters:

Query Parameters

Name

Required

Type

Description

feed_config

True

string

EID of the feed configuration to delete

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/product_feeds/delete_parser_config

Delete a parser configuration.

Parameters:

Query Parameters

Name

Required

Type

Description

feed_config

True

string

EID of the parent feed configuration

key

True

string

Name of the field configuration to remove

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": true
}
Schema
Type

object

results

Whether the delete operation succeeded

Type

boolean

PUT /api/v1/product_feeds/edit_feed_config

Edit a feed configuration

Parameters:

Query Parameters

Name

Required

Type

Description

feed_config

True

string

EID of the feed configuration to edit

key

True

string

Name of property being edited

value

True

string

Value of property to set

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The feed configuration’s “get” representation

Type

object

GET /api/v1/product_feeds/feed_downloadable

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

Parameters:

Query Parameters

Name

Required

Type

Description

feed_url

True

string

URL to verify

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

results

with the following fields

Type

object

downloadable

Whether or not feed is downloadable

Type

boolean

errorCode

Error code in case of failure

Type

integer

errorMessage

Error message

Type

string

GET /api/v1/product_feeds/feed_status

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

Advertisable EID to check the parse status for

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

results

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

Type

array of items

feed_config_eid

EID of the feed configuration

Type

string

errors

Number of parse errors

Type

integer

items

Number of parsed items

Type

integer

skips

Number of skipped items

Type

integer

removed_items

Number of items removed

Type

integer

total_products

Total number of products in feed

Type

integer

timestamp

Time when parse task ran

Type

string

state

State of parse task

Type

string

GET /api/v1/product_feeds/get_feed_config

Fetch the feed configuration that matches the specified EID

Parameters:

Query Parameters

Name

Required

Type

Description

feed_config

True

string

EID of the feed configuration

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The feed configuration’s “get” representation

Type

object

GET /api/v1/product_feeds/get_parser_config

Get all parser configurations for the given feed configuration.

Parameters:

Query Parameters

Name

Required

Type

Description

feed_config

True

string

EID of the feed configuration to retrieve

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

Contains all parser configurations.

Type

object

GET /api/v1/product_feeds/get_products

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the Advertisable

query

True

string

search string

size

True

integer

number of records to fetch

page

True

integer

chunk position by size

feed_selected

True

string

EID of feed to fetch products from

any_word

True

string

search for any word of query

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The products fetched

Type

array of items

GET /api/v1/product_feeds/get_troubled_products

Get the top 5 troubled products for an advertisable

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the Advertisable

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": []
}
Schema
Type

object

results

The 5 troubled products

Type

array of items

GET /api/v1/product_feeds/match_rate

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

Advertisable EID to get match rate statistics for

date

False

string

If specified, match rate for this date (PST) will also be retrieved. Recommended format `YYYY-MM-DD`. (Optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

results

Contains the following attributes:

Type

object

high_match_rate

All time high match rate

Type

integer

high_match_rate_date

Date on which the all time high match rate happened

Type

string

low_match_rate

All time low match rate

Type

integer

low_match_rate_date

Date on which the all time low match rate happened

Type

string

match_rate

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

Type

integer

GET /api/v1/product_feeds/parse_preview

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

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of the Advertisable

parse_prices_in_locale_format

True

boolean

Whether to parse prices based on the locale

language_tag

True

string

Language tag

parser_configs

True

string

Stringified JSON object defining configuration for each field

product_data

True

string

Raw product data to be parsed as string

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

Parse preview output

Type

object

GET /api/v1/product_feeds/set_parser_config

Set parser configuration for the specified key.

Parameters:

Query Parameters

Name

Required

Type

Description

feed_config

True

string

EID of the feed configuration

key

True

string

Name of the field The following parameters set the parser configuration attributes:

is_required

True

boolean

True if this field is required for the parsed product to be valid

path

True

string

Column number (CSV), field name (JSON), or tag name (XML) for the field

attribute

True

string

Attribute on the tag to use (i.e. text)

type

True

string

Field type (either text, image, price)

regular_expression

True

string

Regular expression to search the field

regular_expression_replace

True

string

Replacement string to apply to the field

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": true
}
Schema
Type

object

results

Whether the set operation succeeded

Type

boolean

POST /api/v1/product_feeds/set_parser_configs

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

feed_config

True

string

EID of the feed configuration

parser_configs

True

string

Stringified JSON object defining configuration for each field The parser_configs parameter consists of an object of fields names as keys and field specification objects consisting of the following attributes:

is_required

True

boolean

True if this field is required for the parsed product to be valid

path

True

string

Column number (CSV), field name (JSON), or tag name (XML) for the field

attribute

True

string

Attribute on the tag to use (i.e. text)

regular_expression

True

string

Regular expression to search the field

regular_expression_replace

True

string

Replacement string to apply to the field

type

True

string

Field type (either text, image, price) Example parser_configs object: :: { “id”: { “path”: “id”, “type”: “text”, “attribute”: “text”, “is_required”: “true” }, “title”: { “path”: “title”, “type”: “text”, “attribute”: “text”, “is_required”: “true” }, “image”: { “path”: “image”, “type”: “image”, “attribute”: “text”, “is_required”: “true” }, “url”: { “path”: “url”, “type”: “text”, “attribute”: “text”, “is_required”: “true” }, “price”: { “path”: “price”, “type”: “price”, “attribute”: “text”, “is_required”: “true” } }

Responses:

200

Schema as JSON:

{
  "results": true
}
Schema
Type

object

results

Whether the set operation succeeded

Type

boolean

GET /api/v1/report/ad

Pull reports for your ads. The entity data_format returns:

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

Parameters:

Query Parameters

Name

Required

Type

Description

campaigns

False

array

List of campaign EIDs (optional; default: None)

adgroups

False

array

List of ad group EIDs (optional; default: None)

ads

False

array

List of ad EIDs (optional; default: None)

advertisables

False

array

List of advertisable EIDs (optional; default: None)

data_format

True

string

‘summary’, ‘date’, or ‘entity’ (required)

currency

False

string

the currency code to use for the report (optional; default: ‘USD’)

past_days

False

integer

Run the report for the last n days (optional; default: None)

start_date

False

string

start date of report (optional; default: None)

end_date

False

string

end date of report (optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/report/advertisable

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

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

Parameters:

Query Parameters

Name

Required

Type

Description

campaigns

True

array

List of campaign EIDs (optional; default: None). If campaign EIDs are passed, only data from these campaigns will be returned.

adgroups

True

array

List of ad group EIDs (optional; default: None). If adgroup EIDs are passed, only data from these adgroups will be returned.

ads

True

array

List of ad EIDs (optional; default: None). If ad EIDs are passed, only data from these ads will be returned.

advertisables

True

array

List of advertisable EIDs (at least one is required)

data_format

True

string

‘summary’, ‘date’, or ‘entity’ (required)

currency

False

string

the currency code to use for the report (optional; default: ‘USD’)

past_days

False

integer

Run the report for the last n days (optional; default: None)

start_date

False

string

start date of report (optional; default: None)

end_date

False

string

end date of report (optional; default: None)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/report/campaign

Pull reports for campaigns.

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

The entity data_format returns:

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

Parameters:

Query Parameters

Name

Required

Type

Description

campaigns

False

array

List of campaign EIDs (optional; default: None)

adgroups

False

array

List of ad group EIDs (optional; default: None)

ads

False

array

List of ad EIDs (optional; default: None)

advertisables

False

array

List of advertisable EIDs (optional; default: None)

data_format

True

string

‘summary’, ‘date’, or ‘entity’ (required)

currency

False

string

the currency code to use for the report (optional; default: ‘USD’)

past_days

False

integer

Run the report for the last n days (optional; default: None)

start_date

False

string

start date of report (optional; default: None)

end_date

False

string

end date of report (optional; default: None)

attributions

False

boolean

include attribution data (optional; default: False)

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{}
Schema
Type

object

POST /api/v1/rule/create

Create a new rule on a given pixel.

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

pixel

True

string

The EID of the pixel in which we want to create a new rule

type

True

string

The type of the rule being created. One of [c, s, p, b] (c=Conversion, s=Segment, p=Prospect, b=Cart). You can’t change this later.

order

True

integer

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

name

False

string

The arbitrary name of the rule (Optional; default: None).

display_name

False

string

The display name of the rule (Optional; default: None).

pattern

True

string

The regexp-like expression that matches a URL, if creating a URL rule.

duration

True

integer

The duration of inactivity that can elapse before a user is dropped from this rule.

source

True

string

one of [c, d, m] (c=cookie, d=crm_data, m=mobile)

csv_file

True

string

A CSV file with the emails to generate the rule from, if creating a CRM rule. Use a multi-part form request. Must contain at least 100 emails.

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The new rule’s “get” representation

Type

object

GET /api/v1/rule/get

Fetch a rule object by EID.

Parameters:

Query Parameters

Name

Required

Type

Description

rule

True

string

The EID of the rule.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

eid

The rule’s EID

Type

string

name

The rule’s name

Type

string

display_name

The rule’s display name

Type

string

pattern

The rule’s url pattern to match

Type

string

type

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

Type

string

source

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

Type

string

order

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

Type

integer

segments

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

Type

array of items

GET /api/v1/rule/get_segments

Fetch the segments on a specific rule.

Parameters:

Query Parameters

Name

Required

Type

Description

rule

True

string

The EID of the rule.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "segments": []
}
Schema
Type

object

segments

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

Type

array of items

POST /api/v1/segment/edit

Edit an existing segment.

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

conversion_value

True

number

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

duration

True

integer

The duration of inactivity that can elapse before a user is dropped from this segment.

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The edited segment’s “get” representation

Type

object

GET /api/v1/segment/get

Get an existing segment by its EID.

Parameters:

Query Parameters

Name

Required

Type

Description

segment

True

string

The EID of the segment.

include_int_id

True

boolean

whether the response should include segment integer id or not.

include_lookalike

True

boolean

Whether to include lookalike data.

include_migration_data

True

boolean

Wether to include CDP+ migration related data in the response. :LookalikeSegment lookalike_parent: (Optional) The preloaded LookalikeSegment for the segment, to avoid extra database queries. :FacebookCustomAudience facebook_custom_audience: (Optional) The preloaded FacebookCustomAudience for the segment, to avoid extra database queries.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

eid

The EID of the segment.

Type

string

display_name

Optional name of the segment used for display purposes.

Type

string

name

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

Type

string

type

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

Type

string

match_method

The match method used for the segment.

Type

string

pattern

The URL pattern used for matching users.

Type

string

threshold

The threshold used for match methods with a numerical limit.

Type

integer

duration

The duration of the segment, in days.

Type

integer

conversion_value

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

Type

number

group

The group that the segment belongs to.

Type

integer

mobile

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

Type

object

product

The product that the segment belongs to.

Type

string

POST /api/v1/user/edit

Edit an existing User with given parameters.

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

u

True

string

The ID of the user you want to modify

username

True

string

The arbitrary username of the user.

first_name

True

string

The arbitrary first name of the user.

last_name

True

string

The arbitrary last name of the user.

email_preference_general

True

string

The general email preference as key value pair with boolean designating desired emails to receive.

email_preference_payment

True

string

The payment email preference as key value pair with boolean designating desired emails to receive.

email_preference_campaign_notifications

True

string

The general email preference as key value pair with boolean designating desired emails to receive.

Responses:

200

Schema as JSON:

{
  "results": {}
}
Schema
Type

object

results

The get representation of the user object.

Type

object

GET /api/v1/user/get

Fetch the currently logged in user

Parameters:

Query Parameters

Name

Required

Type

Description

load_advertisables

True

boolean

Should we fetch advertisables from db?

active_advertisables

True

array

List of active advertisables for this user, will be used if load_advertisables is false.

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

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

object

eid

The user’s EID

Type

string

id

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

Type

string

username

The user’s username

Type

string

email

The user’s email address

Type

string

email_verified

Whether the user’s email address is verified or not

Type

boolean

name

The user’s name

Type

string

first_name

The user’s first name

Type

string

last_name

The user’s first name

Type

string

organization_role

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

Type

string

locale

Language/locale preference

Type

string

default_timezone

The user’s specified timezone for reporting and billing use

Type

string

role

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

Type

string

organization

The EID of the Organization to which the user belongs

Type

string

default_profile

The EID of the user’s default advertisable

Type

string

created_date

Date that the user was created

Type

string

advertisables

List of advertisable EIDs that this user has access to

Type

array of items

POST /api/v1/user/grant

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

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

u

True

string

ID of the user to deactivate.

advertisables

True

string

comma-separated string of EIDs for the advertisables you wish to grant a non-admin user access to (admin users have implicit access to every advertisables in an organization. Optional.

organization_role

True

string

pass either ‘user’ or ‘admin’ to designate a role within your organization for the specified user. Optional

Responses:

200

Schema as JSON:

{}
Schema
Type

object

GET /api/v1/xdevice_opt_in/get

DEPRECATED: use retrieve() instead. 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

GET /api/v1/xdevice_opt_in/retrieve

Retrieve cross-device opt-in setting

Parameters:

Query Parameters

Name

Required

Type

Description

advertisable

True

string

EID of advertisable

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "accepted": true
}
Schema
Type

object

accepted

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

Type

boolean

POST /api/v1/xdevice_opt_in/update

Update the cross-device opt-in setting

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site
Form Parameters

Name

Required

Type

Description

advertisable

True

string

EID of advertisable

value

True

boolean

True if the advertisable should be opted-into the cross-device graph

Responses:

200

Schema as JSON:

{
  "accepted": true
}
Schema
Type

object

accepted

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

Type

boolean