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", 
      "end_date": "string", 
      "kpi_goal": 0.0, 
      "kpi_metric": "string", 
      "name": "string", 
      "start_date": "string", 
      "status": "string", 
      "targeting_features": {
        "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", 
  "end_date": "string", 
  "kpi_goal": 0.0, 
  "kpi_metric": "string", 
  "name": "string", 
  "start_date": "string", 
  "targeting_features": {
    "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", 
    "end_date": "string", 
    "kpi_goal": 0.0, 
    "kpi_metric": "string", 
    "name": "string", 
    "start_date": "string", 
    "status": "string", 
    "targeting_features": {
      "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", 
  "end_date": "string", 
  "kpi_goal": 0.0, 
  "kpi_metric": "string", 
  "name": "string", 
  "start_date": "string", 
  "status": "string", 
  "targeting_features": {
    "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", 
    "end_date": "string", 
    "kpi_goal": 0.0, 
    "kpi_metric": "string", 
    "name": "string", 
    "start_date": "string", 
    "status": "string", 
    "targeting_features": {
      "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, 
      "budget_settings": {
        "budget_type": "string", 
        "goal": 0.0, 
        "spend": 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, 
  "budget_settings": {
    "budget_type": "string", 
    "goal": 0.0, 
    "spend": 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, 
    "budget_settings": {
      "budget_type": "string", 
      "goal": 0.0, 
      "spend": 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, 
  "budget_settings": {
    "budget_type": "string", 
    "goal": 0.0, 
    "spend": 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, 
    "budget_settings": {
      "budget_type": "string", 
      "goal": 0.0, 
      "spend": 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
ads
Type:array of AdgroupAd
end_date

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

Type:string
name

Name of adgroup.

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
campaign_eid

EID of campaign this adgroup is in.

Type:string
MaxLength:22
MinLength:22
eid

EID of adgroup.

Type:string
MaxLength:22
MinLength:22
targeting_features
Type:AdgroupTargeting
start_date

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

Type:string
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM
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.

Type:number
Format:float
currency

ISO-4217 currency code for budget. This value must match the currency set on the Advertisable’s billing account.

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

EID of campaign. 22 characters long.

Type:string
budget_settings
Type:BudgetSettings
AdGroupCreate
Type:object
ads
Type:array of AdgroupAd
end_date

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

Type:string
name

Name of adgroup.

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
campaign_eid

EID of campaign this adgroup is in.

Type:string
MaxLength:22
MinLength:22
eid

EID of adgroup.

Type:string
MaxLength:22
MinLength:22
targeting_features
Type:AdgroupTargeting
start_date

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

Type:string
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM
BudgetSettings
Type:object
spend

Amount spent by this campaign till now, if a lifetime budget is used.

Type:number
Format:float
budget_type

Type of budget

Required:True
Type:string
Enum:daily, monthly, lifetime
goal

Budget of campaign in the currency specified by the currency field.

Required:True
Type:number
Format:float
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
budget_settings
Type:BudgetSettings
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.

Type:number
Format:float
currency

ISO-4217 currency code for budget. This value must match the currency set on the Advertisable’s billing account.

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

EID of campaign. 22 characters long.

Type:string
budget_settings
Type:BudgetSettings
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
ads
Type:array of AdgroupAd
end_date

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

Type:string
name

Name of adgroup.

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
campaign_eid

EID of campaign this adgroup is in.

Type:string
MaxLength:22
MinLength:22
eid

EID of adgroup.

Type:string
MaxLength:22
MinLength:22
targeting_features
Type:AdgroupTargeting
start_date

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

Type:string
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM
AdgroupTargeting
Type:object
positive_segment_eids

List of segment EIDs being positively targeted by this adgroup.

Type:array of items
negative_segment_eids

List of segment EIDs being negatively targeted by this adgroup.

Type:array of items
AdgroupAd
Type:object
status

Adgroup ad status

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

Ad eid.

Required:True
Type:string