AdRoll CRUD API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use

Description

AdRoll CRUD API v1 by AdRoll

Manage AdRoll with the AdRoll CRUD API

External documentation

List of Operations

Operations

PUT /api/v1/rule/edit

Edit an existing Rule with given parameters.

Parameters:

Query Parameters
Name Required Type Description
rule True string The EID of the rule you want to modify
order True integer The priority order in which this rule needs to be applied among the others.
name True string The arbitrary name of the rule (optional).
display_name True string The display name of the rule (optional).
pattern True string The regexp-like expression that matches a URL. “*” matches everything.
source True string one of [c, d, m] (c=cookie, d=crm_data, m=mobile)

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-0
Type:object
results

The edited rule object

Type:object
GET /api/v1/campaign/get_ip_range_exclusions

Fetches the IP range exclusions associated with a campaign.

Parameters:

Query Parameters
Name Required Type Description
campaign True string The EID of the campaign whose IP range exclusions are to be fetched

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-1
Type:object
results

A list containing each IP address or IP address range that is excluded

Type:array of items
PUT /api/v1/adgroup/add_platform_target

Add platform targets to an adgroup.

Parameters:

Query Parameters
Name Required Type Description
adgroup True string The EID of the adgroup to add the geo targets to.
type True string The type of target to add. One of: [ mobile, desktop ]
os True string The OS to target. One of: [ ios, android ]
os_version True string The OS version to target.
device True string The device to target. One of [ android_tablet, android_smartphone, ipod, ipad, iphone ]

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-2
Type:object
results

Whether or not it was added

Type:boolean
PUT /api/v1/adgroup/add_demographic_target

Add demographic targets to an adgroup.

Parameters:

Query Parameters
Name Required Type Description
adgroup True string The EID of the adgroup to add the geo targets to.
min_age True integer An integer value of the minimum age to be targeted [ cannot be less than 13 and defaults to 18 ]
max_age True integer An integer value of the maximum age to be targeted [ cannot be greater than 65 ]

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-3
Type:object
results

Whether or not it was added

Type:boolean
GET /api/v1/user/get

Fetch a user object by ID

Parameters:

Query Parameters
Name Required Type Description
user True string The ID of the user.

Responses:

200 OK

Sample response:

{
  "default_profile": "string", 
  "default_timezone": "string", 
  "eid": "string", 
  "email": "string", 
  "first_name": "string", 
  "id": "string", 
  "last_name": "string", 
  "locale": "string", 
  "organization": "string", 
  "organization_role": "string", 
  "role": "string", 
  "username": "string"
}

Response schema:

Schema-4
Type:object
username

The user’s username

Type:string
organization_role

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

Type:string
first_name

The user’s first name

Type:string
last_name

The user’s first name

Type:string
locale

Language/locale preference

Type:string
default_timezone

The user’s specified timezone for reporting and billing use

Type:string
email

The user’s email address

Type:string
role

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

Type:string
eid

The user’s EID

Type:string
default_profile

The EID of the user’s default advertisable

Type:string
organization

The EID of the Organization to which the user belongs

Type:string
id

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

Type:string
POST /api/v1/user/grant

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

Parameters:

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 OK

Sample response:

{}

Response schema:

Schema-5
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

Responses:

200 OK

Sample response:

{
  "approval_state": "string", 
  "attached_users": [], 
  "blacklisted_sites": [], 
  "click_through_conversion_window": 0, 
  "cm_networks": "string", 
  "created_date": "string", 
  "eid": "string", 
  "enable_customer_multi_dur_segs": 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"
}

Response schema:

Schema-6
Type:object
iab1_category_name

IAB1 Category Name

Type:integer
liquidads

The EID of this advertisable’s liquidads

Type:string
has_privacy_policy

site has privacy policy

Type:boolean
attached_users

The IDs of additional users allowed to access the advertisable

Type:array of items
approval_state

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

Type:string
product_name

The advertisable’s specified product or brand

Type:string
updated_date

The date this advertisable was last updated

Type:string
saleser

The EID of this advertisable’s saleser

Type:string
optimizer

The EID of this advertisable’s optimizer

Type:string
zvelo_category_name

3rd party service category name

Type:string
ops

The EID of this advertisable’s ops

Type:string
iab_content_id

IAB Content Category

Type:integer
click_through_conversion_window

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

Type:integer
is_active

Whether or not the advertisable is currently active

Type:boolean
view_through_conversion_window

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

Type:integer
cm_networks

The set of networks for which cookiematching is enabled for the advertisable

Type:string
zvelo_category_id

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

Type:integer
enable_customer_multi_dur_segs

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

Type:boolean
is_coop_approved

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

Type:boolean
iab1_category_id

IAB1 Category

Type:integer
name

The name of the advertisable

Type:string
url

The advertisable’s URL

Type:string
is_publisher

Whether or not this advertisable is a publisher

Type:boolean
iab2_category_id

IAB2 Category

Type:integer
iab2_category_name

IAB2 Category Name

Type:integer
status

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

Type:string
eid

The EID of the advertisable

Type:string
blacklisted_sites

The list of blacklisted domains for the advertisable

Type:array of items
created_date

The date this advertisable was created

Type:string
organization

The EID of this advertisable’s organization

Type:string
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 array A comma-separated list of Ad EIDs to attach to the adgroup. Will take the place of existing Ads (Optional; default: None)
positive_segments False array A comma-separated list 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 array A comma-separated list of Segment EIDs to attach to the adgroup as negative segments. Will take the place of existing negative segments. (Optional; default: None)
geo_targets False string JSON string of desired geo targets for the adgroup The parsed JSON should be an array of objects, each object should be like: {“country_id”:19, “eid”:”YD2QNVI2GVH4DP4TIO8GEO”, “is_negative”:false} The first ID should be one of: - “country_id” - “region_id” - “metro_id” - “city_id” - “postal_code_id” - “postal_code” “is_negative” is a boolean, defaulting to False. When is_negative is true, that means the geolocation is excluded. “eid” is the true identifier obtained from magellan about this geo_target. Example of JSON string: ‘[{“country_id”:19,”eid”:”YD2QNVI2GVH4DP4TIO8GEO”,”is_negative”:false}, {“region_id”:”USCA”,”eid”:”FPDT2YVTEZG3LNMQ5Q8GEO”,”is_negative”:false}]’ All existing geo targets will be removed before adding the new ones. (Optional; default: None)
geo_target_worldwide True boolean If passed, all geo targets of the adgroup will be removed. (Optional)

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-7
Type:object
results

The adgroup’s “get” representation after being edited

Type:object
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).

Responses:

200 OK

Sample response:

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

Response schema:

Schema-8
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/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.

Responses:

200 OK

Sample response:

{
  "segments": []
}

Response schema:

Schema-9
Type:object
segments

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

Type:array of items
PUT /api/v1/segment/edit

Edit an existing segment.

Parameters:

Query 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 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-10
Type:object
results

The edited segment’s “get” representation

Type:object
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)

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-11
Type:object
results

A list containing each ad’s “get” representation

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).

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-12
Type:object
results

The get responses for each of your advertisables.

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)

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-13
Type:object
results

A list containing each adgroup’s “get” representation

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

Responses:

200 OK

Sample response:

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

Response schema:

Schema-14
Type:object
status

The status of the pixel.

Type:string
code

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

Type:string
eid

EID of the pixel.

Type:string
is_consistent

Whether or not the pixel is consistent.

Type:boolean
POST /api/v1/adgroup/clone

Clones an adgroup, including connections to sites, geo targets and ads.

Parameters:

Form Parameters
Name Required Type Description
adgroup True string The EID of the adgroup to clone

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-15
Type:object
results

The new adgroup’s “get” representation

Type:object
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 array A list of the EIDs of the segments to add to this adgroup
is_negative False boolean Whether or not this segment is negatively targeted (Optional; default: False)

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-16
Type:object
results

Whether or not the segments were added

Type:boolean
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

Responses:

200 OK

Sample response:

{
  "ad_format": "string", 
  "ad_format_id": 0, 
  "ad_format_name": "string", 
  "adgroups": [], 
  "advertisable": "string", 
  "body": "string", 
  "created_date": "string", 
  "destination_url": "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
}

Response schema:

Schema-17
Type:object
body

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

Type:string
ad_format

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

Type:string
has_edits

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

Type:boolean
height

The height in pixels of this ad’s creative

Type:integer
message

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

Type:string
has_pending_edits

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

Type:boolean
headline

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

Type:string
is_active

Whether or not this ad is currently active

Type:boolean
width

The width in pixels of this ad’s creative

Type:integer
type

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

Type:string
updated_date

The date this ad was last updated

Type:string
is_outlined

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

Type:boolean
ad_format_name

Format string. i.e. ‘300x250’

Type:string
created_date

The date this ad was created

Type:string
original_ad

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

Type:string
has_future_campaigns

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

Type:boolean
ad_format_id

The id of the corresponding ad format in the AdRoll system

Type:integer
destination_url

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

Type:string
src

This ad’s creative’s source URL

Type:string
advertisable

The EID of the advertisable to which this ad belongs

Type:string
outline_color

Hexadecimal color code corresponding to the outline of an ad

Type:string
name

The name of this ad

Type:string
status

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

Type:string
eid

EID of the ad.

Type:string
adgroups

The list of adgroup EIDs that this ad belongs to

Type:array of items
valid_clicktag

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

Type:boolean
POST /api/v1/advertisable/create

Creates a new advertisable.

Parameters:

Form Parameters
Name Required Type Description
name False string The name of the advertisable (Optional; default: None)
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)

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-18
Type:object
results

The new advertisable’s “get” representation

Type:object
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)

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-19
Type:object
results

A list containing each campaign’s “get” representation

Type:array of items
PUT /api/v1/campaign/edit

Edits an existing campaign.

Parameters:

Query 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 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-20
Type:object
results

The campaign’s “get” representation after being edited

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.

Responses:

200 OK

Sample response:

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

Response schema:

Schema-21
Type:object
display_name

The rule’s display name

Type:string
name

The rule’s name

Type:string
pattern

The rule’s url pattern to match

Type:string
segments

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

Type:array of items
source

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

Type:string
eid

The rule’s EID

Type:string
type

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

Type:string
order

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

Type:integer
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

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-22
Type:object
results

The statuses of the ads after being paused

Type:array of items
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)
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)

Responses:

200 OK

Sample response:

{}

Response schema:

Schema-23
Type:object
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)

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-24
Type:object
results

A list containing each adgroup’s “get” representation

Type:array of items
GET /api/v1/pixel/reorder_rules

Reorder the rules in a pixel.

Parameters:

Query Parameters
Name Required Type Description
pixel True string The EID of the pixel in question.
rules True array A list of the rules eids, in their new order.

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-25
Type:object
results

Whether or not the request succeeded

Type:boolean
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

Responses:

200 OK

Sample response:

{
  "advertiser_status": "string"
}

Response schema:

Schema-26
Type:object
advertiser_status

The new status of the unpaused ad

Type:string
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)

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-27
Type:object
results

A list containing each ad’s “get” representation

Type:array of items
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:

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 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-28
Type:object
results

The get representation of the user object.

Type:object
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.

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-29
Type:object
results

The pixel’s “get” representation

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

Responses:

200 OK

Sample response:

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

Response schema:

Schema-30
Type:object
status

This adgroup’s current status

Type:string
updated_date

The date this adgroup was last updated

Type:string
name

The name of this adgroup

Type:string
campaign

The EID of the campaign that this adgroup is associated with

Type:string
platform_targets

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

Type:array of items
segments

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

Type:array of items
is_active

Whether or not this adgroup is currently active

Type:boolean
geo_targets

Deprecated. See fetch geotargets for adgroup documentation for an alternative.

Type:array of items
placement_targets

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

Type:array of items
eid

The EID of the adgroup

Type:string
ad_optimization

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

Type:string
created_date

The date this adgroup was created

Type:string
flight_timezone

The timezone preference of all flights of this adgroup

Type:string
site_exclusions

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

Type:array of items
ads

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

Type:array of items
PUT /api/v1/adgroup/exclude_site

Exclude a specific ad_format for a site if not already excluded

Parameters:

Query Parameters
Name Required Type Description
adgroup True string The EID of the adgroup to add the site exclusion to.
ad_format True integer ID of ad_format to exclude
site True string domain name of site to exclude

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-31
Type:object
results

The adgroup’s “get” representation after being edited

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

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-32
Type:object
results

A list of compliancy dictionaries in the following format: {ad: ad_eid, sites: [site_eids], errors: [compliancy_errors]}. ‘site_eids’ is a list of EIDs for the sites the ad will run on.

Type:array of items
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)
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)

Responses:

200 OK

Sample response:

{}

Response schema:

Schema-33
Type:object
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.

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-34
Type:object
results

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

Type:array of items
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

Responses:

200 OK

Sample response:

{
  "statuses": []
}

Response schema:

Schema-35
Type:object
statuses

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

Type:array of items
PUT /api/v1/adgroup/add_placement_target

Add placement targets to an adgroup.

Parameters:

Query Parameters
Name Required Type Description
adgroup True string The EID of the adgroup to add the placements to.
placement True string The placement to add. ex. ‘newsfeed’.

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-36
Type:object
results

Whether or not it was added

Type:boolean
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: ‘’)

Responses:

200 OK

Sample response:

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

Response schema:

Schema-37
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/report/campaign

Pull reports for campaigns. 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)
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)

Responses:

200 OK

Sample response:

{}

Response schema:

Schema-38
Type:object
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

Responses:

200 OK

Sample response:

{
  "status": "string"
}

Response schema:

Schema-39
Type:object
status

The new status of the paused ad(s)

Type:string
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)

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-40
Type:object
results

A list containing each ad’s “get” representation

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

Responses:

200 OK

Sample response:

{
  "results": "string"
}

Response schema:

Schema-41
Type:object
results

The status of the campaign after being unpaused

Type:string
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)

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-42
Type:object
results

A list containing each campaign’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

Responses:

200 OK

Sample response:

{
  "results": "string"
}

Response schema:

Schema-43
Type:object
results

The status of the campaign after being paused

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

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-44
Type:object
results

A list containing each adgroup’s “get” representation

Type:array of items
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

Responses:

200 OK

Sample response:

{
  "status": "string"
}

Response schema:

Schema-45
Type:object
status

The new status of the paused ad

Type:string
GET /api/v1/adgroup/allow_site

Allow ad_format for site if it was previously excluded

Parameters:

Query Parameters
Name Required Type Description
adgroup True string The EID of the adgroup for which to allow the ad_format on the site.
ad_format True integer ID of ad_format to allow
site True string domain name of site to allow

Responses:

200 OK

Sample response:

{}

Response schema:

Schema-46
Type:object
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:

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 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-47
Type:object
results

The new ad’s “get” representation

Type:object
POST /api/v1/rule/create

Create a new rule on a given pixel.

Parameters:

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 True string The arbitrary name of the rule (Optional; default None).
display_name True 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.
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 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-48
Type:object
results

The new rule’s “get” representation

Type:object
POST /api/v1/advertisable/edit

Edits an advertisable.

Parameters:

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 True boolean Whether this advertisable is actively syncing its cookie data to Twitter
twitter_handle True string Twitter handle used by the advertisable

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-49
Type:object
results

The advertisable’s “get” representation after being edited

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

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-50
Type:object
results

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

Type:array of items
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.

Responses:

200 OK

Sample response:

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

Response schema:

Schema-51
Type:object
end_date

The end date of the requested invoice(s)

Type:string
transactions

The list of account transactions associated with the time period referenced by this invoice

Type:array of items
start_date

The start date of the requested invoice(s)

Type:string
amount

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

Type:integer
organization

The organization of the requested invoice(s)

Type:string
id

The invoice ID

Type:string
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.

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-52
Type:object
results

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

Type:array of items
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.

Responses:

200 OK

Sample response:

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

Response schema:

Schema-53
Type:object
match_method

The match method used for 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
mobile

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

Type:object
pattern

The URL pattern used for matching users.

Type:string
conversion_value

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

Type:number
threshold

The threshold used for match methods with a numerical limit.

Type:integer
eid

The EID of the segment.

Type:string
duration

The duration of the segment, in days.

Type:integer
group

The group that the segment belongs to.

Type:integer
type

The type of the segment. One of [c,s] (c=Conversion, s=Segment).

Type:string
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

Responses:

200 OK

Sample response:

{
  "comps": []
}

Response schema:

Schema-54
Type:object
comps

A list of compliancy dictionaries in the following format: {ad: ad_eid, sites: [site_eids], errors: [compliancy_errors]}. ‘site_eids’ is a list of EIDs for the sites the ad will run on.

Type:array of items
POST /api/v1/advertisable_logo/create

Upload a logo for an advertisable.

Parameters:

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.

Responses:

200 OK

Sample response:

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

Response schema:

Schema-55
Type:object
width

Width of the logo file in pixels

Type:integer
s3_logo_path

Path to the file

Type:string
id

The ID of the advertisable that uses this logo

Type:string
height

Height of the logo file in pixels

Type:integer
PUT /api/v1/adgroup/pause

Pauses an adgroup.

Parameters:

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

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-56
Type:object
results

results.status is the adgroup’s new status

Type:object
POST /api/v1/ad/create

Creates a new ad.

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

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:

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 Display this URL instead of destination_url (Optional; default: ‘’)
type False string Ad type (Optional; default: ‘image’)

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-57
Type:object
results

The new ad’s “get” representation

Type:object
PUT /api/v1/adgroup/unpause

Unpauses an adgroup.

Parameters:

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

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-58
Type:object
results

results.status is the adgroup’s new status

Type:object
POST /api/v1/campaign/create

Creates a new campaign

Parameters:

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 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-59
Type:object
results

The new campaign’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.

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-60
Type:object
results

The list of segments in their “get” representation

Type:array of items
DELETE /api/v1/adgroup/remove_segments

Removes (dissociates) segments from an adgroup.

Parameters:

Form Parameters
Name Required Type Description
adgroup True string The EID of the adgroup from which to remove the segments
segments True array A list of the EIDs of the segments to remove from this adgroup

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-61
Type:object
results

Whether or not the segments were removed

Type:boolean
POST /api/v1/campaign/clone

Clones a campaign.

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-62
Type:object
results

The new campaign’s “get” representation

Type:object
DELETE /api/v1/adgroup/remove_platform_target

Remove platform targets to an adgroup.

Parameters:

Form Parameters
Name Required Type Description
adgroup True string The EID of the adgroup to add the geo targets to.
type True string The type of target to add. One of: [ mobile, desktop ]
os True string The OS to target. One of: [ ios, android ]
os_version True string The OS version to target.
device True string The device to target. One of [ android_tablet, android_smartphone, ipod, ipad, iphone ]

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-63
Type:object
results

Whether or not it was removed

Type:boolean
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:

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 OK

Sample response:

{}

Response schema:

Schema-64
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:

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.
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_name True string The id of the template to be created
text_promo True string The call to action text shown on the cta box
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: ‘’)

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-65
Type:object
results

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

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

Responses:

200 OK

Sample response:

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

Response schema:

Schema-66
Type:object
updated_date

The date this campaign was last updated

Type:string
is_pubgraph

Whether or not this is a publisher graph campaign.

Type:boolean
spend_limit_until

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

Type:string
is_fbx_newsfeed

Whether or not this campaign is configured for the Facebook Newsfeed

Type:boolean
is_facebook

Whether or not this campaign is configured for the Facebook network

Type:boolean
is_retargeting

Whether or not this campaign is a retargeting campaign

Type:boolean
start_date

The day the campaign will start

Type:string
status

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

Type:string
pricing_strategies

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

Type:array of items
ui_budget_daily

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

Type:boolean
end_date

The day the campaign will end, exclusive

Type:string
adgroups

List of EIDs of the adgroups attached to this campaign

Type:array of items
is_active

Whether or not this campaign is currently active

Type:boolean
is_fb_wca

Whether or not this campaign is a Facebook WCA campaign

Type:boolean
max_cpm

The maximum CPM for this campaign

Type:number
cpm

The CPM for this campaign

Type:number
advertisable

EID of the advertisable to which this campaign belongs

Type:string
name

The name of this campaign

Type:string
cpc

The CPC for this campaign

Type:number
budget

The WEEKLY budget of the campaign

Type:number
is_coop

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

Type:boolean
eid

EID of the campaign

Type:string
created_date

The date this campaign was created

Type:string
promotion

Information about the promotion used with this campaign. Only exists if a promo was used.

Type:object
is_apple

Whether or not this campaign is an Apple iAd campaign

Type:boolean
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).

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-67
Type:object
results

The get representation for each of your billing methods.

Type:array of items
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

Responses:

200 OK

Sample response:

{
  "results": []
}

Response schema:

Schema-68
Type:object
results

The statuses of the ads after being unpaused

Type:array of items
POST /api/v1/adgroup/create

Creates a new adgroup on a campaign.

Parameters:

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)
ads False array A comma-separated list of Ad EIDs to attach to the adgroup (Optional; default: None)
positive_segments False array A comma-separated list of Segment EIDs to attach to the adgroup as positive segments (Optional; default: None)
negative_segments False array A comma-separated list of Segment EIDs to attach to the adgroup as negative segments (Optional; default: None)
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 False array A comma-separated list of placements targets for Facebook ads. One of: all, rightcolumn, desktopfeed, mobilefeed, FAN, instagramstream (Optional; default: None)

Responses:

200 OK

Sample response:

{
  "results": {}
}

Response schema:

Schema-69
Type:object
results

The new adgroup’s “get” representation

Type:object
DELETE /api/v1/adgroup/remove_placement_target

Remove placement targets to an adgroup.

Parameters:

Form Parameters
Name Required Type Description
adgroup True string The EID of the adgroup to add the placements to.
placement True string The placement to add. ex. ‘newsfeed’.

Responses:

200 OK

Sample response:

{
  "results": true
}

Response schema:

Schema-70
Type:object
results

Whether or not it was removed.

Type:boolean