Universal Campaigns API Reference

Warning

The Universal Campaigns API is in beta and may change. If you have questions or feedback, please contact the API team.

Note

If you use the APIs provided here, you are subject to the API Terms of Use, and AdRoll Services Privacy Note

Note

We’ve introduced API keys, please read Migrating to API Keys

Description

AdRoll Universal Campaigns API (v2) 2.0 by AdRoll

Create and edit AdRoll strategies with the AdRoll Universal Campaigns API

Operations

GET /activate/api/v2/adgroup

Fetch adgroup

Parameters:

Query Parameters
Name Required Type Description
eid False string EID of requested adgroup
campaign_eid False string Campaign EID of underlying adgroups
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

A list of adgroups

Schema as JSON:

{
  "data": [
    {
      "ad_type": "string", 
      "ads": [
        {
          "eid": "string", 
          "status": "string"
        }
      ], 
      "campaign_eid": "string", 
      "created_at": "string", 
      "eid": "string", 
      "email": {
        "emails": [
          {
            "body": "string", 
            "cta_destination": "string", 
            "cta_label": "string", 
            "email_subject": "string", 
            "headline": "string", 
            "hero_image_url": "string"
          }
        ], 
        "footer_postal_address": "string", 
        "optin": true, 
        "optin_country": "string", 
        "sender_address": "string", 
        "sender_name": "string"
      }, 
      "end_date": "string", 
      "kpi_goal": 0.0, 
      "kpi_metric": "string", 
      "name": "string", 
      "start_date": "string", 
      "status": "string", 
      "targeting_features": {
        "geotargets": [
          {
            "country_code": "string", 
            "display_name": "string", 
            "facebook_geo_eid": "string", 
            "geo_type": "country", 
            "magellan_geo_eid": "string", 
            "targeted": true
          }
        ], 
        "negative_segment_eids": [
          "string"
        ], 
        "positive_segment_eids": [
          "string"
        ]
      }
    }
  ]
}
Schema
Type:object
data
Type:array of AdGroupResponse
POST /activate/api/v2/adgroup

Create a new adgroup

Parameters:

Query Parameters
Name Required Type Description
campaign_eid True string EID of campaign to attach adgroup to
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: AdGroupCreate

{
  "ad_type": "string", 
  "ads": [
    {
      "eid": "string", 
      "status": "string"
    }
  ], 
  "campaign_eid": "string", 
  "created_at": "string", 
  "eid": "string", 
  "email": {
    "emails": [
      {
        "body": "string", 
        "cta_destination": "string", 
        "cta_label": "string", 
        "email_subject": "string", 
        "headline": "string", 
        "hero_image_url": "string"
      }
    ], 
    "footer_postal_address": "string", 
    "optin": true, 
    "optin_country": "string", 
    "sender_address": "string", 
    "sender_name": "string"
  }, 
  "end_date": "string", 
  "kpi_goal": 0.0, 
  "kpi_metric": "string", 
  "name": "string", 
  "start_date": "string", 
  "targeting_features": {
    "geotargets": [
      {
        "country_code": "string", 
        "display_name": "string", 
        "facebook_geo_eid": "string", 
        "geo_type": "country", 
        "magellan_geo_eid": "string", 
        "targeted": true
      }
    ], 
    "negative_segment_eids": [
      "string"
    ], 
    "positive_segment_eids": [
      "string"
    ]
  }
}

Responses:

200 OK

The newly created adgroup

Schema as JSON:

{
  "data": {
    "ad_type": "string", 
    "ads": [
      {
        "eid": "string", 
        "status": "string"
      }
    ], 
    "campaign_eid": "string", 
    "created_at": "string", 
    "eid": "string", 
    "email": {
      "emails": [
        {
          "body": "string", 
          "cta_destination": "string", 
          "cta_label": "string", 
          "email_subject": "string", 
          "headline": "string", 
          "hero_image_url": "string"
        }
      ], 
      "footer_postal_address": "string", 
      "optin": true, 
      "optin_country": "string", 
      "sender_address": "string", 
      "sender_name": "string"
    }, 
    "end_date": "string", 
    "kpi_goal": 0.0, 
    "kpi_metric": "string", 
    "name": "string", 
    "start_date": "string", 
    "status": "string", 
    "targeting_features": {
      "geotargets": [
        {
          "country_code": "string", 
          "display_name": "string", 
          "facebook_geo_eid": "string", 
          "geo_type": "country", 
          "magellan_geo_eid": "string", 
          "targeted": true
        }
      ], 
      "negative_segment_eids": [
        "string"
      ], 
      "positive_segment_eids": [
        "string"
      ]
    }
  }
}
Schema
Type:object
data
Type:AdGroupResponse
PUT /activate/api/v2/adgroup

Edit an existing adgroup

Parameters:

Query Parameters
Name Required Type Description
eid True string EID of adgroup to edit
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: AdGroupEdit

{
  "ads": [
    {
      "eid": "string", 
      "status": "string"
    }
  ], 
  "campaign_eid": "string", 
  "created_at": "string", 
  "eid": "string", 
  "email": {
    "emails": [
      {
        "body": "string", 
        "cta_destination": "string", 
        "cta_label": "string", 
        "email_subject": "string", 
        "headline": "string", 
        "hero_image_url": "string"
      }
    ], 
    "footer_postal_address": "string", 
    "optin": true, 
    "optin_country": "string", 
    "sender_address": "string", 
    "sender_name": "string"
  }, 
  "end_date": "string", 
  "kpi_goal": 0.0, 
  "kpi_metric": "string", 
  "name": "string", 
  "start_date": "string", 
  "status": "string", 
  "targeting_features": {
    "geotargets": [
      {
        "country_code": "string", 
        "display_name": "string", 
        "facebook_geo_eid": "string", 
        "geo_type": "country", 
        "magellan_geo_eid": "string", 
        "targeted": true
      }
    ], 
    "negative_segment_eids": [
      "string"
    ], 
    "positive_segment_eids": [
      "string"
    ]
  }
}

Responses:

200 OK

The edited adgroup

Schema as JSON:

{
  "data": {
    "ad_type": "string", 
    "ads": [
      {
        "eid": "string", 
        "status": "string"
      }
    ], 
    "campaign_eid": "string", 
    "created_at": "string", 
    "eid": "string", 
    "email": {
      "emails": [
        {
          "body": "string", 
          "cta_destination": "string", 
          "cta_label": "string", 
          "email_subject": "string", 
          "headline": "string", 
          "hero_image_url": "string"
        }
      ], 
      "footer_postal_address": "string", 
      "optin": true, 
      "optin_country": "string", 
      "sender_address": "string", 
      "sender_name": "string"
    }, 
    "end_date": "string", 
    "kpi_goal": 0.0, 
    "kpi_metric": "string", 
    "name": "string", 
    "start_date": "string", 
    "status": "string", 
    "targeting_features": {
      "geotargets": [
        {
          "country_code": "string", 
          "display_name": "string", 
          "facebook_geo_eid": "string", 
          "geo_type": "country", 
          "magellan_geo_eid": "string", 
          "targeted": true
        }
      ], 
      "negative_segment_eids": [
        "string"
      ], 
      "positive_segment_eids": [
        "string"
      ]
    }
  }
}
Schema
Type:object
data
Type:AdGroupResponse
PUT /activate/api/v2/adgroup_ad

Edit an adgroup ad

Parameters:

Query Parameters
Name Required Type Description
adgroup_eid True string EID of adgroup
ad_eid True string EID of the ad to pause
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: AdgroupAd

{
  "eid": "string", 
  "status": "string"
}

Responses:

200 OK

The edited adgroup ad

Schema as JSON:

{
  "data": {
    "eid": "string", 
    "status": "string"
  }
}
Schema
Type:object
data
Type:AdgroupAd
GET /activate/api/v2/campaign

Fetch campaign

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid False string Advertisable EID of requested campaign
eid False string EID of requested campaign
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

A list of Campaign objects

Schema as JSON:

{
  "data": [
    {
      "advertisable_eid": "string", 
      "budget": 0.0, 
      "created_at": "string", 
      "currency": "string", 
      "eid": "string", 
      "end_date": "string", 
      "name": "string", 
      "start_date": "string", 
      "status": "string"
    }
  ]
}
Schema
Type:object
data
Type:array of CampaignResponse
POST /activate/api/v2/campaign

Create a new campaign.

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string Advertisable EID to create campaign under
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: CampaignCreate

{
  "advertisable_eid": "string", 
  "budget": 0.0, 
  "created_at": "string", 
  "currency": "string", 
  "eid": "string", 
  "name": "string"
}

Responses:

200 OK

The newly created campaign

Schema as JSON:

{
  "data": {
    "advertisable_eid": "string", 
    "budget": 0.0, 
    "created_at": "string", 
    "currency": "string", 
    "eid": "string", 
    "end_date": "string", 
    "name": "string", 
    "start_date": "string", 
    "status": "string"
  }
}
Schema
Type:object
data
Type:CampaignResponse
PUT /activate/api/v2/campaign

Edit an existing campaign.

Parameters:

Query Parameters
Name Required Type Description
eid True string Campaign EID
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: CampaignEdit

{
  "advertisable_eid": "string", 
  "budget": 0.0, 
  "created_at": "string", 
  "eid": "string", 
  "name": "string", 
  "status": "string"
}

Responses:

200 OK

The edited campaign

Schema as JSON:

{
  "data": {
    "advertisable_eid": "string", 
    "budget": 0.0, 
    "created_at": "string", 
    "currency": "string", 
    "eid": "string", 
    "end_date": "string", 
    "name": "string", 
    "start_date": "string", 
    "status": "string"
  }
}
Schema
Type:object
data
Type:CampaignResponse

Definitions

AdGroupEdit
Type:object
status

Status of adgroup

Type:string
Enum:live, paused, deleted
name

Name of adgroup.

Type:string
end_date

End date of adgroup in ISO-8601 format in UTC.

Type:string
campaign_eid

EID of campaign this adgroup is in.

Type:string
MaxLength:22
MinLength:22
created_at

Datetime of adgroup creation in ISO-8601 in UTC.

Type:string
kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by campaign’s currency parameter).This must be number greater than 0 or NULL to set an automatic goal.

Type:number
Format:float
email
Type:Email
eid

EID of adgroup.

Type:string
MaxLength:22
MinLength:22
targeting_features
Type:object
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM
start_date

Start date/time of adgroup in ISO-8601 format in UTC.

Type:string
ads
Type:array of AdgroupAd
CampaignCreate
Type:object
advertisable_eid

EID of advertisable campaign is attached to. 22 Characters long.

Type:string
name

Campaign Name

Type:string
MaxLength:100
created_at

Datetime of campaign creation in ISO-8601 in UTC.

Type:string
budget

Daily budget of campaign in the currency specified by the currency field.

Required:True
Type:number
Format:float
currency

ISO-4217 currency code

Required:True
Type:string
Enum:USD, EUR, AUD, GBP, NZD, JPY
eid

EID of campaign. 22 characters long.

Type:string
AdGroupCreate
Type:object
campaign_eid

EID of campaign this adgroup is in.

Type:string
MaxLength:22
MinLength:22
name

Name of adgroup.

Type:string
end_date

End date of adgroup in ISO-8601 format in UTC.

Type:string
created_at

Datetime of adgroup creation in ISO-8601 in UTC.

Type:string
kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by campaign’s currency parameter).This must be number greater than 0 or NULL to set an automatic goal.

Type:number
Format:float
ad_type

The type of ads supported by this adgroup. The ad_eids passed in should be of this type.

Required:True
Type:string
Enum:dynamic, static
email
Type:Email
eid

EID of adgroup.

Type:string
MaxLength:22
MinLength:22
targeting_features
Type:object
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM
start_date

Start date/time of adgroup in ISO-8601 format in UTC.

Type:string
ads
Type:array of AdgroupAd
AdgroupAd
Type:object
status

Adgroup ad status

Required:True
Type:string
Enum:live, paused, deleted
eid

Ad eid.

Required:True
Type:string
CampaignEdit
Type:object
status

Status of campaign

Type:string
Enum:live, paused, deleted
advertisable_eid

EID of advertisable campaign is attached to. 22 Characters long.

Type:string
name

Campaign Name

Type:string
MaxLength:100
created_at

Datetime of campaign creation in ISO-8601 in UTC.

Type:string
budget

Daily budget of campaign in the currency specified by the currency field.

Type:number
Format:float
eid

EID of campaign. 22 characters long.

Type:string
CampaignResponse
Type:object
status

Status of campaign

Type:string
Enum:live, paused, deleted
advertisable_eid

EID of advertisable campaign is attached to. 22 Characters long.

Type:string
name

Campaign Name

Type:string
MaxLength:100
end_date

End date of campaign in ISO-8601 format in UTC.

Type:string
created_at

Datetime of campaign creation in ISO-8601 in UTC.

Type:string
budget

Daily budget of campaign in the currency specified by the currency field.

Required:True
Type:number
Format:float
currency

ISO-4217 currency code

Required:True
Type:string
Enum:USD, EUR, AUD, GBP, NZD, JPY
eid

EID of campaign. 22 characters long.

Type:string
start_date

Start date/time of campaign in ISO-8601 format in UTC.

Type:string
AdGroupResponse
Type:object
status

Status of adgroup

Type:string
Enum:live, paused, deleted
name

Name of adgroup.

Type:string
end_date

End date of adgroup in ISO-8601 format in UTC.

Type:string
campaign_eid

EID of campaign this adgroup is in.

Type:string
MaxLength:22
MinLength:22
created_at

Datetime of adgroup creation in ISO-8601 in UTC.

Type:string
kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by campaign’s currency parameter).This must be number greater than 0 or NULL to set an automatic goal.

Type:number
Format:float
ad_type

The type of ads supported by this adgroup. The ad_eids passed in should be of this type.

Required:True
Type:string
Enum:dynamic, static
email
Type:Email
eid

EID of adgroup.

Type:string
MaxLength:22
MinLength:22
targeting_features
Type:object
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM
start_date

Start date/time of adgroup in ISO-8601 format in UTC.

Type:string
ads
Type:array of AdgroupAd
GeoTargets
Type:object
display_name

Human readable text that represents the target. Will be used in the web UI.

Required:True
Type:string
facebook_geo_eid

Facebook eid for the given geo target.

Required:True
Type:string
MaxLength:22
MinLength:22
targeted

Boolean indication whether we want to target or exclude this geo.

Required:True
Type:boolean
country_code

Country code in ISO-3166 format.

Required:True
Type:string
MaxLength:2
MinLength:2
magellan_geo_eid

Magellan eid for the given geo target.

Required:True
Type:string
MaxLength:22
MinLength:22
geo_type

Geo type as returned by targma

Required:True
Type:string
Default:country
Email
Type:object
sender_name

Name of sender for emails sent by AdRoll Email.

Type:string
optin

Boolean indicating whether or not the user has opted in to use AdRoll Email.

Type:boolean
sender_address

Email address to use as the sender email for emails sent by AdRoll Email.

Type:string
Format:email
optin_country

ISO-3166 country code for advertisable.

Type:string
MaxLength:2
MinLength:2
footer_postal_address

Postal address of business to place in the footer of emails sent by AdRoll Email.

Type:string
emails
Type:array of items