Facebook API Reference

Note

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

Note

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

Description

AdRoll Facebook Standalone API v1 by apihelp@adroll.com

Manage your Facebook campaigns with AdRoll

Operations by Tag

Operations

GET /facebook/ads/

Retrieves a list of all Ads for the specified AdSet

Parameters:

Query Parameters
Name Required Type Description
all False boolean If true, all records are returned. If false, only the selected page is returned
page False integer Page number of records to return
page_size False integer Number of records on each page
sort False string Name of the field to sort by
adset_eid True string EID of the AdSet to retrieve
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

Paginated list of Ads

application/json example:

{
  "count": 36, 
  "page": 1, 
  "page_size": 2, 
  "results": [
    {
      "adset_eid": "LEGITADSETEID", 
      "created_date": "2016-05-03T22:05:45.865251", 
      "creative_eid": "LEGITCREATIVEEID", 
      "disapproval_reason": null, 
      "eid": "LEGITADEID", 
      "is_active": null, 
      "name": "My Ad", 
      "remote_status": null, 
      "status": "paused", 
      "updated_date": "2016-06-06T18:58:45.757349"
    }, 
    {
      "adset_eid": "LEGITADSETEID", 
      "created_date": "2016-05-03T22:05:45.865251", 
      "creative_eid": "LEGITCREATIVEEID2", 
      "disapproval_reason": null, 
      "eid": "LEGITADEID2", 
      "is_active": null, 
      "name": "My Ad", 
      "remote_status": null, 
      "status": "active", 
      "updated_date": "2016-10-06T18:58:45.757349"
    }
  ]
}
Schema
Type:object
count

The total number of records

Type:integer
page

The current page

Type:integer
page_size

The number of records on each page

Type:integer
results
Type:array of Ad
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
POST /facebook/ads/

Creates an Ad

Parameters:

Query Parameters
Name Required Type Description
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: AdParams

{
  "adset_eid": "string", 
  "creative_eid": "string", 
  "name": "string", 
  "status": "string"
}

Responses:

200 OK

An Ad

Returns Ad

application/json example:

{
  "adset_eid": "LEGITADSETEID", 
  "created_date": "2016-05-03T22:05:45.865251", 
  "creative_eid": "LEGITCREATIVEEID", 
  "disapproval_reason": null, 
  "eid": "LEGITADEID", 
  "is_active": null, 
  "name": "My Ad", 
  "remote_status": null, 
  "status": "paused", 
  "updated_date": "2016-06-06T18:58:45.757349"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
PUT /facebook/ads/(action)

Update the state of a set of ads

Parameters:

Path Parameters
Name Required Type Description
action True string How to change the ads
Query Parameters
Name Required Type Description
adset_eid False string EID of the AdSet to update
campaign_eid False string EID of the campaign to update
creative_eids False array EIDs of the creatives to update
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

Status

Returns AdStatus

application/json example:

{
  "status": "active"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
GET /facebook/ads/(eid)

Retrieves Ad information

Parameters:

Path Parameters
Name Required Type Description
eid True string Ad EID to get
Query Parameters
Name Required Type Description
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

An Ad

Returns Ad

application/json example:

{
  "adset_eid": "LEGITADSETEID", 
  "created_date": "2016-05-03T22:05:45.865251", 
  "creative_eid": "LEGITCREATIVEEID", 
  "disapproval_reason": null, 
  "eid": "LEGITADEID", 
  "is_active": null, 
  "name": "My Ad", 
  "remote_status": null, 
  "status": "paused", 
  "updated_date": "2016-06-06T18:58:45.757349"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
DELETE /facebook/ads/(eid)

Deletes an Ad

Parameters:

Path Parameters
Name Required Type Description
eid True string Ad EID to delete
Query Parameters
Name Required Type Description
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:

204 No Content
Ad Deleted
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
PUT /facebook/adsetaudiences/(action)

Sets the targeting of AdSetAudiences

Parameters:

Path Parameters
Name Required Type Description
action True string Indicates whether the AdSetAudience should be targeted or excluded One of: target_audiences, exclude_audiences.
Query Parameters
Name Required Type Description
adset_eid True string The EID of the AdGroup to update
audience_eids True array A list of EIDs of audiences to update
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
Success
400 Bad Request

Bad Request

Returns Error

application/json example:

{
  "code": "ERROR_NO_AUDIENCE_FOR_ADSET", 
  "error": "No AdSetAudience found with given adset_eid=ADSET_EID and audience_eids=[AUDIENCE_EID_1,AUDIENCE_EID_2].", 
  "subcode": null
}
GET /facebook/adsets/

Retrieves a list of all AdSets for the current user

Parameters:

Query Parameters
Name Required Type Description
all False boolean If true, all records are returned. If false, only the selected page is returned
page False integer Page number of records to return
page_size False integer Number of records on each page
sort False string Name of the field to sort by
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

Paginated list of AdSets

application/json example:

{
  "count": 36, 
  "page": 1, 
  "page_size": 2, 
  "results": [
    {
      "ads": [], 
      "audiences": [], 
      "bid_amount": null, 
      "budget": 300.0, 
      "cpc": null, 
      "created_date": "2018-11-02T01:41:26", 
      "eid": "LEGITADSETEID1", 
      "end_date": null, 
      "is_autobid": true, 
      "max_age": null, 
      "min_age": null, 
      "name": "AdGroup 1", 
      "optimization_goal": "LINK_CLICKS", 
      "pacing_type": "standard", 
      "pricing_model": "dynamic", 
      "promoted_object": {
        "segment_eid": "LEGITSEGMENTEID"
      }, 
      "start_date": "2018-11-02T01:41:26", 
      "status": "draft", 
      "targeting": {
        "page_types": [
          "desktopfeed", 
          "mobilefeed"
        ]
      }, 
      "ui_period": "daily", 
      "updated_date": "2018-11-02T01:41:26"
    }, 
    {
      "ads": [], 
      "audiences": [], 
      "bid_amount": null, 
      "budget": 600.0, 
      "cpc": 2.0, 
      "created_date": "2018-11-02T01:41:26", 
      "eid": "LEGITADSETEID1", 
      "end_date": null, 
      "is_autobid": true, 
      "max_age": 50, 
      "min_age": 21, 
      "name": "AdGroup 2", 
      "optimization_goal": "LEAD_GENERATION", 
      "pacing_type": "standard", 
      "pricing_model": "fixed_cpc", 
      "promoted_object": {
        "segment_eid": "LEGITSEGMENTEID"
      }, 
      "start_date": "2018-11-02T01:41:26", 
      "status": "draft", 
      "targeting": {
        "page_types": [
          "desktopfeed", 
          "mobilefeed"
        ]
      }, 
      "ui_period": "daily", 
      "updated_date": "2018-11-02T01:41:26"
    }
  ]
}
Schema
Type:object
count

The total number of records

Type:integer
page

The current page

Type:integer
page_size

The number of records on each page

Type:integer
results
Type:array of AdSet
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
POST /facebook/adsets/

Creates an AdSet

Parameters:

Query Parameters
Name Required Type Description
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: AdSetParams

{
  "ads": [
    {
      "created_date": "string", 
      "creative_eid": "string", 
      "disapproval_reason": "string", 
      "eid": "string", 
      "is_active": true, 
      "name": "string", 
      "remote_status": "string", 
      "status": "string", 
      "updated_date": "string"
    }
  ], 
  "audiences": [
    {
      "created_date": "string", 
      "custom_audience_eid": "string", 
      "eid": "string", 
      "targeted": true, 
      "updated_date": "string"
    }
  ], 
  "bid_amount": 0.0, 
  "budget": 0.0, 
  "cpc": 0.0, 
  "end_date": "string", 
  "is_autobid": true, 
  "max_age": 0, 
  "min_age": 0, 
  "name": "string", 
  "optimization_goal": "string", 
  "pacing_type": "string", 
  "pricing_model": "string", 
  "promoted_object": {}, 
  "start_date": "string", 
  "status": "string", 
  "targeting": {
    "page_types": [
      "string"
    ]
  }
}

Responses:

200 OK

An AdSet

Returns AdSet

application/json example:

{
  "ads": [], 
  "audiences": [], 
  "bid_amount": null, 
  "budget": 300.0, 
  "campaign_eid": "CAMPAIGNEID123", 
  "cpc": null, 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITADSETEID1", 
  "end_date": null, 
  "is_autobid": true, 
  "max_age": null, 
  "min_age": null, 
  "name": "AdGroup 1", 
  "optimization_goal": "LINK_CLICKS", 
  "pacing_type": "standard", 
  "pricing_model": "dynamic", 
  "promoted_object": {
    "segment_eid": "LEGITSEGMENTEID"
  }, 
  "start_date": "2018-11-02T01:41:26", 
  "status": "draft", 
  "targeting": {
    "page_types": [
      "desktopfeed", 
      "mobilefeed"
    ]
  }, 
  "ui_period": "daily", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
POST /facebook/adsets/create_default/(campaign_eid)

Creates an AdSet

Parameters:

Path Parameters
Name Required Type Description
campaign_eid True string EID of the Campaign to create the AdSet for
Query Parameters
Name Required Type Description
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

An AdSet

Returns AdSet

application/json example:

{
  "ads": [], 
  "audiences": [], 
  "bid_amount": null, 
  "budget": 300.0, 
  "campaign_eid": "CAMPAIGNEID123", 
  "cpc": null, 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITADSETEID1", 
  "end_date": null, 
  "is_autobid": true, 
  "max_age": null, 
  "min_age": null, 
  "name": "AdGroup 1", 
  "optimization_goal": "LINK_CLICKS", 
  "pacing_type": "standard", 
  "pricing_model": "dynamic", 
  "promoted_object": {
    "segment_eid": "LEGITSEGMENTEID"
  }, 
  "start_date": "2018-11-02T01:41:26", 
  "status": "draft", 
  "targeting": {
    "page_types": [
      "desktopfeed", 
      "mobilefeed"
    ]
  }, 
  "ui_period": "daily", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
GET /facebook/adsets/(adset_eid)/geotargeting

Retrieves AdSetGeolocations by AdSet

Parameters:

Path Parameters
Name Required Type Description
adset_eid True string The EID of the AdSet to retrieve AdSetGeolocations for
Query Parameters
Name Required Type Description
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

An array of AdSetGeolocations

application/json example:

[
  {
    "country_code": "CA", 
    "country_name": "Canada", 
    "eid": "VQJXBJC5Z5GV3JXYEF8C4G", 
    "error": null, 
    "included": true, 
    "name": "Toronto", 
    "primary_city": null, 
    "region": "Ontario", 
    "selected_children": [], 
    "type": "city"
  }
]
Schema
Type:array
400 Bad Request

Missing parameter

Returns Error

application/json example:

{
  "code": "ERROR_MISSING_PARAMETER", 
  "error": "The parameter adset_eid is missing.", 
  "subcode": null
}
POST /facebook/adsets/(adset_eid)/geotargeting

Adds a Geolocation to an AdSet

Parameters:

Path Parameters
Name Required Type Description
adset_eid True string The EID of the AdSet to retrieve AdSetGeolocations for
Query Parameters
Name Required Type Description
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:

{
  "geolocation_eid": "string", 
  "included": true
}
Schema
Type:object
included

If true, users in this Geolocation will be targeted. If false, users in this geolocation will be excluded.

Required:True
Type:boolean
geolocation_eid

The EID of the Geolocation to add to the AdSet

Required:True
Type:string

Responses:

200 OK

An array of AdSetGeolocations

application/json example:

[
  {
    "country_code": "CA", 
    "country_name": "Canada", 
    "eid": "VQJXBJC5Z5GV3JXYEF8C4G", 
    "error": null, 
    "included": true, 
    "name": "Toronto", 
    "primary_city": null, 
    "region": "Ontario", 
    "selected_children": [], 
    "type": "city"
  }
]
Schema
Type:array
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
GET /facebook/adsets/(eid)

Retrieves AdSet information

Parameters:

Path Parameters
Name Required Type Description
eid True string AdSet EID to get
Query Parameters
Name Required Type Description
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

An AdSet

Returns AdSet

application/json example:

{
  "ads": [], 
  "audiences": [], 
  "bid_amount": null, 
  "budget": 300.0, 
  "campaign_eid": "CAMPAIGNEID123", 
  "cpc": null, 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITADSETEID1", 
  "end_date": null, 
  "is_autobid": true, 
  "max_age": null, 
  "min_age": null, 
  "name": "AdGroup 1", 
  "optimization_goal": "LINK_CLICKS", 
  "pacing_type": "standard", 
  "pricing_model": "dynamic", 
  "promoted_object": {
    "segment_eid": "LEGITSEGMENTEID"
  }, 
  "start_date": "2018-11-02T01:41:26", 
  "status": "draft", 
  "targeting": {
    "page_types": [
      "desktopfeed", 
      "mobilefeed"
    ]
  }, 
  "ui_period": "daily", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
POST /facebook/adsets/(eid)

Clones an AdSet

Parameters:

Path Parameters
Name Required Type Description
eid True string AdSet EID to clone
Query Parameters
Name Required Type Description
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

An AdSet

Returns AdSet

application/json example:

{
  "ads": [], 
  "audiences": [], 
  "bid_amount": null, 
  "budget": 300.0, 
  "campaign_eid": "CAMPAIGNEID123", 
  "cpc": null, 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITADSETEID1", 
  "end_date": null, 
  "is_autobid": true, 
  "max_age": null, 
  "min_age": null, 
  "name": "AdGroup 1", 
  "optimization_goal": "LINK_CLICKS", 
  "pacing_type": "standard", 
  "pricing_model": "dynamic", 
  "promoted_object": {
    "segment_eid": "LEGITSEGMENTEID"
  }, 
  "start_date": "2018-11-02T01:41:26", 
  "status": "draft", 
  "targeting": {
    "page_types": [
      "desktopfeed", 
      "mobilefeed"
    ]
  }, 
  "ui_period": "daily", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
PUT /facebook/adsets/(eid)

Updates AdSet information

Parameters:

Path Parameters
Name Required Type Description
eid True string AdSet EID to update
Query Parameters
Name Required Type Description
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: AdSetParams

{
  "ads": [
    {
      "created_date": "string", 
      "creative_eid": "string", 
      "disapproval_reason": "string", 
      "eid": "string", 
      "is_active": true, 
      "name": "string", 
      "remote_status": "string", 
      "status": "string", 
      "updated_date": "string"
    }
  ], 
  "audiences": [
    {
      "created_date": "string", 
      "custom_audience_eid": "string", 
      "eid": "string", 
      "targeted": true, 
      "updated_date": "string"
    }
  ], 
  "bid_amount": 0.0, 
  "budget": 0.0, 
  "cpc": 0.0, 
  "end_date": "string", 
  "is_autobid": true, 
  "max_age": 0, 
  "min_age": 0, 
  "name": "string", 
  "optimization_goal": "string", 
  "pacing_type": "string", 
  "pricing_model": "string", 
  "promoted_object": {}, 
  "start_date": "string", 
  "status": "string", 
  "targeting": {
    "page_types": [
      "string"
    ]
  }
}

Responses:

200 OK

An AdSet

Returns AdSet

application/json example:

{
  "ads": [], 
  "audiences": [], 
  "bid_amount": null, 
  "budget": 300.0, 
  "campaign_eid": "CAMPAIGNEID123", 
  "cpc": null, 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITADSETEID1", 
  "end_date": null, 
  "is_autobid": true, 
  "max_age": null, 
  "min_age": null, 
  "name": "AdGroup 1", 
  "optimization_goal": "LINK_CLICKS", 
  "pacing_type": "standard", 
  "pricing_model": "dynamic", 
  "promoted_object": {
    "segment_eid": "LEGITSEGMENTEID"
  }, 
  "start_date": "2018-11-02T01:41:26", 
  "status": "draft", 
  "targeting": {
    "page_types": [
      "desktopfeed", 
      "mobilefeed"
    ]
  }, 
  "ui_period": "daily", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
DELETE /facebook/adsets/(eid)

Deletes an AdSet

Parameters:

Path Parameters
Name Required Type Description
eid True string AdSet EID to delete
Query Parameters
Name Required Type Description
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:

204 No Content
AdSet Deleted
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
PUT /facebook/adsets/(eid)/(action)

Update the state of a single AdSet

Parameters:

Path Parameters
Name Required Type Description
eid True string EID of the AdSet to update
action True string How to change the AdSet One of: pause, resume.
Query Parameters
Name Required Type Description
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

An AdSet

Returns AdSet

application/json example:

{
  "ads": [], 
  "audiences": [], 
  "bid_amount": null, 
  "budget": 300.0, 
  "campaign_eid": "CAMPAIGNEID123", 
  "cpc": null, 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITADSETEID1", 
  "end_date": null, 
  "is_autobid": true, 
  "max_age": null, 
  "min_age": null, 
  "name": "AdGroup 1", 
  "optimization_goal": "LINK_CLICKS", 
  "pacing_type": "standard", 
  "pricing_model": "dynamic", 
  "promoted_object": {
    "segment_eid": "LEGITSEGMENTEID"
  }, 
  "start_date": "2018-11-02T01:41:26", 
  "status": "draft", 
  "targeting": {
    "page_types": [
      "desktopfeed", 
      "mobilefeed"
    ]
  }, 
  "ui_period": "daily", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
GET /facebook/advertisable

Retrieves basic information for the current Advertisable

Parameters:

Query Parameters
Name Required Type Description
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

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID", 
  "account_is_autobilled": false, 
  "account_is_prepaid": true, 
  "created_date": "2018-11-02T01:41:26", 
  "currency": "USD", 
  "eid": "LEGITEID", 
  "external_id": "6543210987", 
  "fb_page_id": "5432109876", 
  "fb_page_url": "https://facebook.com/yourlegitadvertiser", 
  "instagram_actor_id": 123456789, 
  "is_page_backed": false, 
  "is_suspended": false, 
  "name": "Legit Advertisable Name", 
  "organization_eid": "LEGITORGANIZATIONEID", 
  "page_access": true, 
  "page_admin_access": true, 
  "page_backed_instagram_actor_id": 1213123123123, 
  "show_dpa": true, 
  "tos_accepted": true, 
  "updated_date": "2018-11-02T01:41:26", 
  "url": "https://legitadvertiser.website"
}
GET /facebook/advertisable/(eid)

Retrieves basic information for an Advertisable by EID

Parameters:

Path Parameters
Name Required Type Description
eid True string EID of the Advertisable to retrieve
Query Parameters
Name Required Type Description
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

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID", 
  "account_is_autobilled": false, 
  "account_is_prepaid": true, 
  "created_date": "2018-11-02T01:41:26", 
  "currency": "USD", 
  "eid": "LEGITEID", 
  "external_id": "6543210987", 
  "fb_page_id": "5432109876", 
  "fb_page_url": "https://facebook.com/yourlegitadvertiser", 
  "instagram_actor_id": 123456789, 
  "is_page_backed": false, 
  "is_suspended": false, 
  "name": "Legit Advertisable Name", 
  "organization_eid": "LEGITORGANIZATIONEID", 
  "page_access": true, 
  "page_admin_access": true, 
  "page_backed_instagram_actor_id": 1213123123123, 
  "show_dpa": true, 
  "tos_accepted": true, 
  "updated_date": "2018-11-02T01:41:26", 
  "url": "https://legitadvertiser.website"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
GET /facebook/advertiser

Retrieves basic information for the current Advertisable

Parameters:

Query Parameters
Name Required Type Description
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

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID", 
  "account_is_autobilled": false, 
  "account_is_prepaid": true, 
  "created_date": "2018-11-02T01:41:26", 
  "currency": "USD", 
  "eid": "LEGITEID", 
  "external_id": "6543210987", 
  "fb_page_id": "5432109876", 
  "fb_page_url": "https://facebook.com/yourlegitadvertiser", 
  "instagram_actor_id": 123456789, 
  "is_page_backed": false, 
  "is_suspended": false, 
  "name": "Legit Advertisable Name", 
  "organization_eid": "LEGITORGANIZATIONEID", 
  "page_access": true, 
  "page_admin_access": true, 
  "page_backed_instagram_actor_id": 1213123123123, 
  "show_dpa": true, 
  "tos_accepted": true, 
  "updated_date": "2018-11-02T01:41:26", 
  "url": "https://legitadvertiser.website"
}
GET /facebook/advertiser/(eid)

Retrieves basic information for an Advertisable by EID

Parameters:

Path Parameters
Name Required Type Description
eid True string EID of the Advertisable to retrieve
Query Parameters
Name Required Type Description
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

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID", 
  "account_is_autobilled": false, 
  "account_is_prepaid": true, 
  "created_date": "2018-11-02T01:41:26", 
  "currency": "USD", 
  "eid": "LEGITEID", 
  "external_id": "6543210987", 
  "fb_page_id": "5432109876", 
  "fb_page_url": "https://facebook.com/yourlegitadvertiser", 
  "instagram_actor_id": 123456789, 
  "is_page_backed": false, 
  "is_suspended": false, 
  "name": "Legit Advertisable Name", 
  "organization_eid": "LEGITORGANIZATIONEID", 
  "page_access": true, 
  "page_admin_access": true, 
  "page_backed_instagram_actor_id": 1213123123123, 
  "show_dpa": true, 
  "tos_accepted": true, 
  "updated_date": "2018-11-02T01:41:26", 
  "url": "https://legitadvertiser.website"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
GET /facebook/audiences/

Retrieves Custom Audiences by Advertisable EID

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string EID of the Advertisable to retrieve records for
all False boolean If true, all records are returned. If false, only the selected page is returned
page False integer Page number of records to return
page_size False integer Number of records on each page
sort False string Name of the field to sort by
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

An array of Custom Audiences

application/json example:

{
  "count": 115, 
  "page": 1, 
  "page_size": 115, 
  "results": [
    {
      "advertisable": {
        "eid": "2BQEPPOCDNEZRCCIVULFDY"
      }, 
      "approximate_count": 999, 
      "created_date": "2016-01-12T00:21:24", 
      "eid": "B3HYG53NAJFVDD336ZMXGO", 
      "is_conversion": null, 
      "lookalike_audience": {
        "allow_international_seeds": null, 
        "country_code": null, 
        "country_name": null, 
        "eid": null, 
        "origin_audience_eid": null, 
        "ratio": null, 
        "type": null
      }, 
      "match_method": "url_match", 
      "name": "USE THIS ONE!", 
      "retention_days": 90, 
      "rule": "code-ninja.org", 
      "subtype": "WEBSITE", 
      "updated_date": "2017-07-07T16:38:31.656100"
    }
  ]
}
Schema
Type:object
count

The total number of records

Type:integer
page

The current page

Type:integer
page_size

The number of records on each page

Type:integer
results
Type:array of CustomAudience
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
POST /facebook/audiences/

Creates a Custom Audience

Parameters:

Query Parameters
Name Required Type Description
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: CustomAudienceParams

{
  "advertisable_eid": "string", 
  "conversion_value": 0.0, 
  "is_conversion": true, 
  "name": "string", 
  "retention_days": 0, 
  "rule": "string", 
  "subtype": "string"
}

Responses:

200 OK

A Custom Audience

Returns CustomAudience

application/json example:

{
  "advertisable": {
    "eid": "2BQEPPOCDNEZRCCIVULFDY"
  }, 
  "approximate_count": 999, 
  "created_date": "2016-01-12T00:21:24", 
  "eid": "B3HYG53NAJFVDD336ZMXGO", 
  "is_conversion": null, 
  "lookalike_audience": {
    "allow_international_seeds": null, 
    "country_code": null, 
    "country_name": null, 
    "eid": null, 
    "origin_audience_eid": null, 
    "ratio": null, 
    "type": null
  }, 
  "match_method": "url_match", 
  "name": "USE THIS ONE!", 
  "retention_days": 90, 
  "rule": "code-ninja.org", 
  "subtype": "WEBSITE", 
  "threshold": 1, 
  "updated_date": "2017-07-07T16:38:31.656100"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
GET /facebook/audiences/(eid)

Retrieves a Custom Audience

Parameters:

Path Parameters
Name Required Type Description
eid True string EID of the Custom Audience to retrieve
Query Parameters
Name Required Type Description
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 Custom Audience

Returns CustomAudience

application/json example:

{
  "advertisable": {
    "eid": "2BQEPPOCDNEZRCCIVULFDY"
  }, 
  "approximate_count": 999, 
  "created_date": "2016-01-12T00:21:24", 
  "eid": "B3HYG53NAJFVDD336ZMXGO", 
  "is_conversion": null, 
  "lookalike_audience": {
    "allow_international_seeds": null, 
    "country_code": null, 
    "country_name": null, 
    "eid": null, 
    "origin_audience_eid": null, 
    "ratio": null, 
    "type": null
  }, 
  "match_method": "url_match", 
  "name": "USE THIS ONE!", 
  "retention_days": 90, 
  "rule": "code-ninja.org", 
  "subtype": "WEBSITE", 
  "threshold": 1, 
  "updated_date": "2017-07-07T16:38:31.656100"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
GET /facebook/campaigns/

Retrieves a list of all Campaigns for the current user or the Advertisable specified by advertisable_eid

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string EID of the Advertisable to retrieve records for
all False boolean If true, all records are returned. If false, only the selected page is returned
page False integer Page number of records to return
page_size False integer Number of records on each page
sort False string Name of the field to sort by
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

Paginated list of Campaigns

application/json example:

{
  "count": 36, 
  "page": 1, 
  "page_size": 2, 
  "results": [
    {
      "adsets": [
        {
          "ads": [], 
          "audiences": [], 
          "bid_amount": null, 
          "budget": 300.0, 
          "created_date": "2018-11-02T01:41:26", 
          "eid": "LEGITADSETEID1", 
          "end_date": null, 
          "is_autobid": true, 
          "max_age": null, 
          "min_age": null, 
          "name": "AdGroup 1", 
          "optimization_goal": "LINK_CLICKS", 
          "pacing_type": "standard", 
          "promoted_object": {
            "segment_eid": "LEGITSEGMENTEID"
          }, 
          "start_date": "2018-11-02T01:41:26", 
          "status": "draft", 
          "targeting": {
            "page_types": [
              "desktopfeed", 
              "mobilefeed"
            ]
          }, 
          "ui_period": "daily", 
          "updated_date": "2018-11-02T01:41:26"
        }
      ], 
      "advertisable": {
        "eid": "LEGIADVERTISEREID"
      }, 
      "bid_strategy": "automatic", 
      "created_date": "2018-11-02T01:41:26", 
      "eid": "LEGICAMPAIGNID1", 
      "goal": "retarget", 
      "name": "Legit Campaign name 1", 
      "objective": "LINK_CLICKS", 
      "performance_target": null, 
      "performance_target_value": null, 
      "source": null, 
      "status": "active", 
      "updated_date": "2018-11-02T01:41:26"
    }, 
    {
      "adsets": [
        {
          "ads": [], 
          "audiences": [], 
          "bid_amount": null, 
          "budget": 357.15, 
          "created_date": "2018-11-02T01:41:26", 
          "eid": "LEGITADSETID2", 
          "end_date": null, 
          "is_autobid": true, 
          "max_age": null, 
          "min_age": null, 
          "name": "AdGroup 1", 
          "optimization_goal": "LINK_CLICKS", 
          "pacing_type": "standard", 
          "promoted_object": null, 
          "start_date": "2018-11-02T01:41:26", 
          "status": "draft", 
          "targeting": {
            "page_types": [
              "desktopfeed", 
              "mobilefeed", 
              "rightcolumn", 
              "mobileexternal", 
              "instagramstream"
            ]
          }, 
          "ui_period": "daily", 
          "updated_date": "2018-11-02T01:41:26"
        }
      ], 
      "advertisable": {
        "eid": "LEGIADVERTISEREID"
      }, 
      "bid_strategy": "automatic", 
      "created_date": "2018-11-02T01:41:26", 
      "eid": "LEGICAMPAIGNID2", 
      "goal": "retarget", 
      "name": "Legit Campaign name 2", 
      "objective": "LINK_CLICKS", 
      "performance_target": null, 
      "performance_target_value": null, 
      "status": "draft", 
      "updated_date": "2018-11-02T01:41:26"
    }
  ]
}
Schema
Type:object
count

The total number of records

Type:integer
page

The current page

Type:integer
page_size

The number of records on each page

Type:integer
results
Type:array of Campaign
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
POST /facebook/campaigns/

Creates a Campaign

Parameters:

Query Parameters
Name Required Type Description
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: CampaignParams

{
  "advertisable_eid": "string", 
  "bid_strategy": "string", 
  "goal": "string", 
  "name": "string", 
  "objective": "string", 
  "performance_target": "string", 
  "should_launch": true, 
  "source": "string", 
  "status": "string"
}

Responses:

200 OK

A Campaign

Returns Campaign

application/json example:

{
  "adsets": [
    {
      "ads": [], 
      "audiences": [], 
      "bid_amount": null, 
      "budget": 300.0, 
      "created_date": "2018-11-02T01:41:26", 
      "eid": "MMWLFRGRHBD4XL26ZC8C4G", 
      "end_date": null, 
      "is_autobid": true, 
      "max_age": null, 
      "min_age": null, 
      "name": "AdGroup 1", 
      "optimization_goal": "LINK_CLICKS", 
      "pacing_type": "standard", 
      "promoted_object": null, 
      "start_date": "2018-11-02T01:41:26", 
      "status": "draft", 
      "targeting": {
        "page_types": [
          "desktopfeed", 
          "mobilefeed", 
          "rightcolumn", 
          "mobileexternal", 
          "instagramstream"
        ]
      }, 
      "ui_period": "daily", 
      "updated_date": "2018-11-02T01:41:26"
    }
  ], 
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  }, 
  "bid_strategy": "manual", 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITEID", 
  "goal": "prospect", 
  "name": "Legit Campaign name", 
  "objective": "LINK_CLICKS", 
  "performance_target": null, 
  "performance_target_value": null, 
  "source": null, 
  "status": "draft", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
GET /facebook/campaigns/(eid)

Retrieves Campaign information

Parameters:

Path Parameters
Name Required Type Description
eid True string Campaign EID to get
Query Parameters
Name Required Type Description
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 Campaign

Returns Campaign

application/json example:

{
  "adsets": [
    {
      "ads": [], 
      "audiences": [], 
      "bid_amount": null, 
      "budget": 300.0, 
      "created_date": "2018-11-02T01:41:26", 
      "eid": "MMWLFRGRHBD4XL26ZC8C4G", 
      "end_date": null, 
      "is_autobid": true, 
      "max_age": null, 
      "min_age": null, 
      "name": "AdGroup 1", 
      "optimization_goal": "LINK_CLICKS", 
      "pacing_type": "standard", 
      "promoted_object": null, 
      "start_date": "2018-11-02T01:41:26", 
      "status": "draft", 
      "targeting": {
        "page_types": [
          "desktopfeed", 
          "mobilefeed", 
          "rightcolumn", 
          "mobileexternal", 
          "instagramstream"
        ]
      }, 
      "ui_period": "daily", 
      "updated_date": "2018-11-02T01:41:26"
    }
  ], 
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  }, 
  "bid_strategy": "manual", 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITEID", 
  "goal": "prospect", 
  "name": "Legit Campaign name", 
  "objective": "LINK_CLICKS", 
  "performance_target": null, 
  "performance_target_value": null, 
  "source": null, 
  "status": "draft", 
  "updated_date": "2018-11-02T01:41:26"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
PUT /facebook/campaigns/(eid)/(action)

Update the status of a single Campaign

Parameters:

Path Parameters
Name Required Type Description
eid True string EID of the Campaign to update
action True string How to change the campaign One of: pause, admin_pause, resume.
Query Parameters
Name Required Type Description
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 Campaign

Returns Campaign

application/json example:

{
  "adsets": [
    {
      "ads": [], 
      "audiences": [], 
      "bid_amount": null, 
      "budget": 300.0, 
      "created_date": "2018-11-02T01:41:26", 
      "eid": "MMWLFRGRHBD4XL26ZC8C4G", 
      "end_date": null, 
      "is_autobid": true, 
      "max_age": null, 
      "min_age": null, 
      "name": "AdGroup 1", 
      "optimization_goal": "LINK_CLICKS", 
      "pacing_type": "standard", 
      "promoted_object": null, 
      "start_date": "2018-11-02T01:41:26", 
      "status": "draft", 
      "targeting": {
        "page_types": [
          "desktopfeed", 
          "mobilefeed", 
          "rightcolumn", 
          "mobileexternal", 
          "instagramstream"
        ]
      }, 
      "ui_period": "daily", 
      "updated_date": "2018-11-02T01:41:26"
    }
  ], 
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  }, 
  "bid_strategy": "manual", 
  "created_date": "2018-11-02T01:41:26", 
  "eid": "LEGITEID", 
  "goal": "prospect", 
  "name": "Legit Campaign name", 
  "objective": "LINK_CLICKS", 
  "performance_target": null, 
  "performance_target_value": null, 
  "source": null, 
  "status": "draft", 
  "updated_date": "2018-11-02T01:41:26"
}
400 Bad Request

Request format error

Returns Error

application/json example:

{
  "code": "ERROR_CANNOT_CHANGE_DRAFT_CAMPAIGN_STATUS", 
  "error": "You cannot change the status of a draft campaign", 
  "subcode": null
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
GET /facebook/creatives/

Retrieves a set of Creatives by Advertisable EID

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string EID of the Advertisable to retrieve records for
all False boolean If true, all records are returned. If false, only the selected page is returned
page False integer Page number of records to return
page_size False integer Number of records on each page
sort False string Name of the field to sort by
lead_gen_only False string If true, only Creatives with a Lead Gen Form will be included
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

Creatives

application/json example:

{
  "count": 1, 
  "page": 1, 
  "page_size": 10, 
  "results": [
    {
      "advertisable": {
        "eid": "LEGITADVERTISEREID"
      }, 
      "call_to_action": "NO_BUTTON", 
      "caption": "legitadvertiser.website", 
      "created_date": "2018-11-02T01:41:26", 
      "description": "This is a legit description for a creative", 
      "eid": "LEGITEID", 
      "external_id": 1029384756, 
      "height": 315, 
      "image_url": "https://legitadvertiser.website/logo2x.jpg", 
      "instagram_permalink_url": "https://www.instagram.com/p/LeGiTuId/", 
      "is_active": true, 
      "is_dynamic": false, 
      "lead_gen_form": {
        "eid": "LEGITLEADGENFORMEID", 
        "name": "Lead Gen Form"
      }, 
      "link": "https://legitadvertiser.website", 
      "message": "This is a legit creative message", 
      "name": "Legit Creative Name", 
      "read_only": false, 
      "status": "active", 
      "title": "Legit Creative Title", 
      "updated_date": "2018-11-02T01:41:26", 
      "width": 600
    }
  ]
}
Schema
Type:object
count

The total number of records

Type:integer
page

The current page

Type:integer
page_size

The number of records on each page

Type:integer
results
Type:array of Creative
400 Bad Request

Request format error

Returns Error

application/json example:

{
  "code": "ERROR_INVALID_REQUEST_FORMAT", 
  "error": "The request does not match the expected format: invalidRequestFormat.", 
  "subcode": null
}
GET /facebook/creatives/(eid)

Retrieves a Creative by EID

Parameters:

Path Parameters
Name Required Type Description
eid True string The EID of the Creative to retrieve
Query Parameters
Name Required Type Description
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 Creative

Returns Creative

application/json example:

{
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  }, 
  "call_to_action": "NO_BUTTON", 
  "caption": "legitadvertiser.website", 
  "created_date": "2018-11-02T01:41:26", 
  "description": "This is a legit description for a creative", 
  "eid": "LEGITEID", 
  "external_id": 1029384756, 
  "height": 315, 
  "image_url": "https://legitadvertiser.website/logo2x.jpg", 
  "instagram_permalink_url": "https://www.instagram.com/p/LeGiTuId/", 
  "is_active": true, 
  "is_dynamic": false, 
  "lead_gen_form": {
    "eid": "LEGITLEADGENFORMEID", 
    "name": "Lead Gen Form"
  }, 
  "link": "https://legitadvertiser.website", 
  "message": "This is a legit creative message", 
  "name": "Legit Creative Name", 
  "read_only": false, 
  "status": "active", 
  "title": "Legit Creative Title", 
  "updated_date": "2018-11-02T01:41:26", 
  "width": 600
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
PUT /facebook/creatives/(eid)

Updates a Creative and calls AdRoll API to update Ad on AdRoll

Parameters:

Path Parameters
Name Required Type Description
eid True string The EID of the Creative to update
Query Parameters
Name Required Type Description
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: CreativeParams

{
  "advertisable_eid": "Unknown type", 
  "call_to_action": "string", 
  "caption": "string", 
  "description": "string", 
  "file": "string", 
  "height": 0, 
  "image_url": "string", 
  "lead_gen_form_eid": "string", 
  "link": "string", 
  "message": "string", 
  "name": "string", 
  "title": "string", 
  "width": 0
}

Responses:

200 OK

A Creative

Returns Creative

application/json example:

{
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  }, 
  "call_to_action": "NO_BUTTON", 
  "caption": "legitadvertiser.website", 
  "created_date": "2018-11-02T01:41:26", 
  "description": "This is a legit description for a creative", 
  "eid": "LEGITEID", 
  "external_id": 1029384756, 
  "height": 315, 
  "image_url": "https://legitadvertiser.website/logo2x.jpg", 
  "instagram_permalink_url": "https://www.instagram.com/p/LeGiTuId/", 
  "is_active": true, 
  "is_dynamic": false, 
  "lead_gen_form": {
    "eid": "LEGITLEADGENFORMEID", 
    "name": "Lead Gen Form"
  }, 
  "link": "https://legitadvertiser.website", 
  "message": "This is a legit creative message", 
  "name": "Legit Creative Name", 
  "read_only": false, 
  "status": "active", 
  "title": "Legit Creative Title", 
  "updated_date": "2018-11-02T01:41:26", 
  "width": 600
}
400 Bad Request

Request error

Returns Error

application/json example:

{
  "code": "ERROR_LEAD_GEN_FORM_NOT_FOUND", 
  "error": "Lead gen form FORMEID not found.", 
  "subcode": null
}
403 Forbidden

Error trying to access resource

Returns Error

application/json example:

{
  "code": "ERROR_INVALID_OWNERSHIP", 
  "error": "For this operation this lead gen form with id 1 should be owned by the advertisable 1.", 
  "subcode": null
}
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
405 Method Not Allowed

Creative is read-only

Returns Error

application/json example:

{
  "code": "ERROR_CREATIVE_IS_READ_ONLY", 
  "error": "Creative CREATIVEEID has been synced to Facebook and is read only.", 
  "subcode": null
}
POST /facebook/fb_page_id

Connects and stores a Facebook page ID for an advertisable

Parameters:

Query Parameters
Name Required Type Description
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:

{
  "advertisable_eid": "string", 
  "page_id": 0
}
Schema
Type:object
advertisable_eid

EID of an Advertisable

Type:string
page_id

ID of the Facebook Page to be integrated with

Required:True
Type:integer

Responses:

200 OK

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID", 
  "account_is_autobilled": false, 
  "account_is_prepaid": true, 
  "created_date": "2018-11-02T01:41:26", 
  "currency": "USD", 
  "eid": "LEGITEID", 
  "external_id": "6543210987", 
  "fb_page_id": "5432109876", 
  "fb_page_url": "https://facebook.com/yourlegitadvertiser", 
  "instagram_actor_id": 123456789, 
  "is_page_backed": false, 
  "is_suspended": false, 
  "name": "Legit Advertisable Name", 
  "organization_eid": "LEGITORGANIZATIONEID", 
  "page_access": true, 
  "page_admin_access": true, 
  "page_backed_instagram_actor_id": 1213123123123, 
  "show_dpa": true, 
  "tos_accepted": true, 
  "updated_date": "2018-11-02T01:41:26", 
  "url": "https://legitadvertiser.website"
}
400 Bad Request

Page back instagram account failed to create

Returns Error

application/json example:

{
  "code": "ERROR_FACEBOOK_PBIA_CREATION_FAILED", 
  "error": "Failed to create PBIA for <advertisable_eid>: <page_id>.", 
  "subcode": null
}
GET /facebook/fb_page_url

Returns the advertiser’s Facebook page

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string EID of the Advertisable to retrieve records for
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

Facebook Page metadata

Returns FacebookPage

application/json example:

{
  "fb_page_id": "123456789", 
  "fb_page_img": "<url_to_image>", 
  "fb_page_name": "Fake Page", 
  "fb_page_url": "https://www.facebook.com/FakePage-123456789", 
  "is_published": false, 
  "no_profile_picture": false, 
  "page_access": true, 
  "page_admin_access": true
}
POST /facebook/fb_page_url

Connects and stores a Facebook page URL for an Advertisable

Parameters:

Query Parameters
Name Required Type Description
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:

{
  "advertisable_eid": "string", 
  "page_url": "string"
}
Schema
Type:object
advertisable_eid

EID of an Advertisable

Type:string
page_url

URL of the Facebook Page to be integrated with

Required:True
Type:string

Responses:

200 OK

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID", 
  "account_is_autobilled": false, 
  "account_is_prepaid": true, 
  "created_date": "2018-11-02T01:41:26", 
  "currency": "USD", 
  "eid": "LEGITEID", 
  "external_id": "6543210987", 
  "fb_page_id": "5432109876", 
  "fb_page_url": "https://facebook.com/yourlegitadvertiser", 
  "instagram_actor_id": 123456789, 
  "is_page_backed": false, 
  "is_suspended": false, 
  "name": "Legit Advertisable Name", 
  "organization_eid": "LEGITORGANIZATIONEID", 
  "page_access": true, 
  "page_admin_access": true, 
  "page_backed_instagram_actor_id": 1213123123123, 
  "show_dpa": true, 
  "tos_accepted": true, 
  "updated_date": "2018-11-02T01:41:26", 
  "url": "https://legitadvertiser.website"
}
400 Bad Request

Missing parameter

Returns Error

application/json example:

{
  "code": "ERROR_MISSING_PARAMETER", 
  "error": "The parameter page_url is missing.", 
  "subcode": null
}
GET /facebook/geolocation/(partial_name)

Searches for Geolocations by name

Parameters:

Path Parameters
Name Required Type Description
partial_name True string The partial location name to search for
Query Parameters
Name Required Type Description
location_types False array The types of locations to search for
country_code False string The two-letter ISO country code to limit the results 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

Responses:

200 OK

Paginated list of GeoLocations

application/json example:

{
  "count": 200, 
  "page": 1, 
  "page_size": 2, 
  "results": [
    {
      "country_code": "CA", 
      "country_name": "Canada", 
      "eid": "VCYHV7ZDFFCS3KKK348C4G", 
      "name": "Vancouver", 
      "primary_city": null, 
      "region": "British Columbia", 
      "type": "city"
    }
  ]
}
Schema
Type:object
count

The total number of records

Type:integer
page

The current page

Type:integer
page_size

The number of records on each page

Type:integer
results
Type:array of Geolocation
PUT /facebook/geotargeting/(adset_geo_eid)

Updates an AdSetGeolocation

Parameters:

Path Parameters
Name Required Type Description
adset_geo_eid True string The EID of the AdSetGeolocation to update
Query Parameters
Name Required Type Description
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:

{
  "adset_eid": "string", 
  "eid": "string", 
  "included": true
}
Schema
Type:object
included

If true, users in this AdSetGeolocation will be targeted. If false, users in this AdSetGeolocation will be excluded.

Required:True
Type:boolean
adset_eid

The EID of the AdSet to update

Required:True
Type:string
eid

The EID of the AdSetGeolocation to update

Required:True
Type:string

Responses:

200 OK

An array of AdSetGeolocations

application/json example:

[
  {
    "country_code": "CA", 
    "country_name": "Canada", 
    "eid": "VQJXBJC5Z5GV3JXYEF8C4G", 
    "error": null, 
    "included": true, 
    "name": "Toronto", 
    "primary_city": null, 
    "region": "Ontario", 
    "selected_children": [], 
    "type": "city"
  }
]
Schema
Type:array
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
DELETE /facebook/geotargeting/(adset_geo_eid)

Deletes an AdSetGeolocation

Parameters:

Path Parameters
Name Required Type Description
adset_geo_eid True string The EID of the AdSetGeolocation to remove
Query Parameters
Name Required Type Description
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

An array of AdSetGeolocations

application/json example:

[
  {
    "country_code": "CA", 
    "country_name": "Canada", 
    "eid": "VQJXBJC5Z5GV3JXYEF8C4G", 
    "error": null, 
    "included": true, 
    "name": "Toronto", 
    "primary_city": null, 
    "region": "Ontario", 
    "selected_children": [], 
    "type": "city"
  }
]
Schema
Type:array
404 Not Found

Resource not found

Returns Error

application/json example:

{
  "code": "ERROR_RESOURCE_NOT_FOUND", 
  "error": "The specified resource could not be found.", 
  "subcode": null
}
GET /facebook/instagram_account

Fetches an advertisable’s instagram account

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string EID of the Advertisable to retrieve records for
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

Instagram Account metadata

Returns InstagramAccount

application/json example:

{
  "instagram_actor_id": 1234, 
  "instagram_profile_pic": "<link_to_pic>", 
  "instagram_username": "niles-nelson"
}
POST /facebook/instagram_account

Connects and stores an Instagram account for an Advertisable

Parameters:

Query Parameters
Name Required Type Description
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:

{
  "account_id": 0, 
  "advertisable_eid": "string"
}
Schema
Type:object
advertisable_eid

EID of an Advertisable

Type:string
account_id

The Instagram account ID to be connected to the Advertisable

Required:True
Type:integer
Format:int64

Responses:

200 OK

Instagram account ID

application/json example:

{
  "instagram_actor_id": 1234
}
Schema
Type:integer
Format:int64
DELETE /facebook/instagram_account

Removes the current Instagram Integration from an Advertisable

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string EID of the Advertisable to retrieve records for
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:

204 No Content
Deleted Instagram integration
POST /facebook/lookalike_audiences/

Creates a Lookalike Audience from a Custom Audience

Parameters:

Query Parameters
Name Required Type Description
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: LookalikeAudience

{
  "advertisable_eid": "string", 
  "allow_international_seeds": true, 
  "country_code": "string", 
  "country_name": "string", 
  "origin_audience_eid": "string", 
  "ratio": 0, 
  "type": "string"
}

Responses:

200 OK

Successful response

Returns CustomAudience

application/json example:

{
  "advertiser": {
    "eid": "2BQEPPOCDNEZRCCIVULFDY"
  }, 
  "approximate_count": 0, 
  "created_date": "2017-07-06T21:51:01", 
  "eid": "T2BIS4PE3JDOZAVCUBZNTL", 
  "is_conversion": false, 
  "lookalike_audience": {
    "allow_international_seeds": false, 
    "country_code": "NI", 
    "country_name": "Nicaragua", 
    "eid": "MQ3USVX4TFDSRGMFDJ8C4G", 
    "origin_audience_eid": "B3HYG53NAJFVDD336ZMXGO", 
    "ratio": null, 
    "type": "similarity"
  }, 
  "match_method": "lookalike", 
  "name": "52f1e170 - fb prospecting similarity ni", 
  "retention_days": 90, 
  "rule": "test-rule", 
  "subtype": "LOOKALIKE", 
  "updated_date": "2017-07-06T21:51:02"
}
403 Forbidden

Permission error

Returns Error

application/json example:

{
  "code": "ERROR_NO_PERMISSION_FOR_ACTION", 
  "error": "You do not have permission to perform this action.", 
  "subcode": null
}

Definitions

AdvertisableEid
Type:object
advertsable_eid

EID of an Advertisable

Type:string
Default:Advertisable associated to the logged in user
AdSetParams
Type:object
status

Status of the AdSet

Type:string
Enum:active, paused, deleted, archived
is_autobid

Whether the Advertisable express the intent to bid automatically

Type:boolean
targeting

AdSet attributes that define who sees an ad

Type:object
pricing_model

Pricing model to use for this AdSet

Type:string
Enum:dynamic, fixed_cpc
end_date

End date for the AdSet

Type:string
Format:date
max_age

Maximum age for the AdSet to target. Cannot be less than min_age

Type:integer
Maximum:65
Minimum:13
promoted_object

Object this ad set is promoting across all its ads

Type:object
bid_amount

Bid amount of the AdSet

Type:number
Format:float
cpc

CPC value to use with fixed_cpc pricing model

Type:number
Format:float
budget

Daily budget of the AdSet

Type:number
Format:float
min_age

Minimum age for the AdSet to target. Cannot be greater than max_age

Type:integer
Maximum:65
Minimum:13
optimization_goal

Which optimization goal this ad set is using

Type:string
Enum:IMPRESSIONS, OFFSITE_CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, LANDING_PAGE_VIEWS
pacing_type

Defines the pacing type, standard or using ad scheduling

Type:string
Enum:standard, no_pacing
audiences
Type:array of Audience
ads
Type:array of Ad
start_date

Start date for the AdSet

Type:string
Format:date
name

Name of the AdSet

Type:string
LeadGenForm
Type:object
updated_date

Last updated date

Type:string
Format:date
advertisable

Advertisable that owns the Lead Gen Form

Type:object
name

Name of the Lead Gen Form

Type:string
eid

Unique identifier

Type:string
created_date

Creation date

Type:string
Format:date
external_id

Facebook ID of the Lead Gen Form

Type:string
Creative
Type:object
updated_date

Last update date

Type:string
Format:date
read_only

Indicates whether the Creative is read-only or not

Type:boolean
advertisable
Type:object
name

Display name of the Creative

Type:string
call_to_action

Call-to-action of the Creative

Type:string
description

Link description of the Creative

Type:string
title

Title of the Creative

Type:string
is_active

Indicates whether the Creative is active or not

Type:boolean
height

Height of the Creative image

Type:integer
is_dynamic

Indicates whether the Creative is dynamic or not

Type:boolean
caption

Link caption of the Creative

Type:string
status

Indicates the status of the Creative

Type:string
Enum:active, deleted
eid

Unique identifier

Type:string
lead_gen_form
Type:object
link

Link URL of the Creative

Type:string
image_url

URL of the Creative image

Type:string
message

Post message of the Creative

Type:string
instagram_permalink_url

Permalink URL to the Creative on Instagram

Type:string
external_id

Facebook Creative ID, usable in the Facebook API

Type:string
width

Width of the Creative image

Type:integer
created_date

Creation date

Type:string
Format:date
HoldoutAudience
Type:object
advertisable_eid

EID of the Advertisable that owns this Holdout Audience

Type:string
start_cohort_id

ID of the start of this Holdout Audience’s cohort

Type:integer
end_cohort_id

ID of the end of this Holdout Audience’s cohort

Type:integer
is_active

Whether or not this Holdout Audience is active

Type:boolean
eid

EID of the Holdout Audience

Type:string
group_id

Group ID of the Holdout Audience

Type:integer
external_id

Facebook ID of this Holdout Audience

Type:integer
Format:int64
AdSetBulk
Type:object
updated_date

Last update date

Type:string
Format:date
advertisable_eid

Identifier of the Advertisable

Type:string
flight_start_date

Alias of start_date, in ISO 8601 format

Type:string
Format:date
targeting

AdSet attributes that define who sees an ad

Type:object
name

Name of the AdSet

Type:string
end_date

End date for the AdSet

Type:string
Format:date
is_autobid

True if the Advertisable is set to bid automatically

Type:boolean
promoted_object

Object this ad set is promoting across all its ads

Type:object
bid_amount

Bid amount of the AdSet

Type:number
Format:float
flight_end_date

Alias of end_date, in ISO 8601 format

Type:string
Format:date
budget

Daily budget of the AdSet

Type:number
Format:float
start_date

Start date for the AdSet

Type:string
Format:date
status

Status of the AdSet

Type:string
Enum:active, paused, deleted, archived
optimization_goal

Which optimization goal this ad set is using

Type:string
Enum:IMPRESSIONS, OFFSITE_CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, LANDING_PAGE_VIEWS
audiences
Type:array of Audience
eid

Unique identifier

Type:string
created_date

Creation date

Type:string
Format:date
pacing_type

Defines the pacing type, standard or using ad scheduling

Type:string
Enum:standard, no_pacing
flight_timezone

Just UTC at the moment

Type:string
campaign_eid

Identifier of the Campaign

Type:string
ads
Type:array of Ad
Audience
Type:object
updated_date

Last update date

Type:string
Format:date
targeted

Whether the target is targeted or not

Type:boolean
custom_audience_eid

EID of the Custom Audience to create this Audience for

Type:string
eid

Unique identifier

Type:string
created_date

Creation date

Type:string
Format:date
CampaignParams
Type:object
status

Status of the Campaign

Type:string
Enum:active, paused, deleted, archived
advertisable_eid

Identifier of the Advertisable

Type:string
goal

Goal of the Campaign

Type:string
Enum:retarget, prospect
bid_strategy

Indicates if the bid strategy of the Campaign is automatic or manual

Type:string
Enum:automatic, manual
name

Display name of the Campaign

Type:string
should_launch

Indicates whether the Campaign should be launched. Campaigns will not serve until they have been launched

Type:boolean
source

Source of the Campaign

Type:string
objective

Objective of the Campaign

Type:string
Enum:CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, PRODUCT_CATALOG_SALES
performance_target

Indicates the performance target when bid strategy is manual

Type:string
Enum:None, cpc, cpm, cpl, cpa
Error
Type:object
code
Type:string
error
Type:string
LookalikeAudience
Type:object
advertisable_eid

EID of the Advertisable to create this Lookalike Audience for

Required:True
Type:string
allow_international_seeds

If true, other countries will automatically be included if your audience size is too small

Required:True
Type:boolean
origin_audience_eid

EID of the Custom Audience to create this Lookalike Audience from

Required:True
Type:string
country_code

Two-letter ISO country code to create this Lookalike Audience for

Required:True
Type:string
country_name

Name of the country to create this Lookalike Audience for

Required:True
Type:string
ratio

Ratio of similarity to audience size. 1 is the smallest but most similar. 10 is the largest but least similar

Required:True
Type:integer
Maximum:10
Minimum:1
type

Whether this Lookalike Audience is optimized for similarity, reach, or a ratio

Required:True
Type:string
Enum:similarity, reach, None
AdSetGeolocation

A Geolocation attached to an AdSet

Type:object
name

Name of this AdSetGeolocation

Type:string
region

Region associated with this AdSetGeolocation

Type:string
primary_city

City associated with this AdSetGeolocation

Type:string
included

If true, users in this geolocation will be targeted. If false, users in this geolocation will be excluded

Type:boolean
eid

EID for this AdSetGeolocation

Type:string
country_code

Two-letter ISO country code for this AdSetGeolocation

Type:string
error

Error message associated with this AdSetGeolocation

Type:string
country_name

Country associated with this AdSetGeolocation

Type:string
type

Type of this AdSetGeolocation

Type:string
Enum:country, region, city, zip
selected_children

AdSetGeolocations that are children of this AdSetGeolocation

Type:array of AdSetGeolocation
AudienceShare
Type:array
Advertiser
Type:object
updated_date

Last update date

Type:string
Format:date
status

Status of the Advertiser

Type:string
Enum:approved, rejected
is_page_backed

Indicates if the Advertisable publishes to Instagram through a page backed account

Type:boolean
name

Display name of the Advertisable

Type:string
organization_eid

EID of the Organization that owns the Advertisable

Type:string
url

URL of the Advertisable’s website

Type:string
page_access

Indicates if AdRoll has access to the Advertisable’s page

Type:boolean
is_suspended

Indicates if the account is suspended

Type:boolean
page_admin_access

Indicates if AdRoll has admin access to the Advertisable’s page

Type:boolean
account_eid

Identifier of the account of the Advertisable

Type:string
tos_accepted

An object that contains the terms of service accepted by the Advertisable

Type:object
show_dpa

Indicates if we should show DPA-related content to the Advertisable

Type:boolean
fb_page_id

Identifier of the Advertisable’s Facebook page, usable in the Facebook API

Type:string
currency

Currency code of the account

Type:string
eid

Identifier of the Advertisable

Type:string
account_is_prepaid

Indicates if the account is prepaid

Type:boolean
fb_page_url

URL of the Advertisable’s Facebook page

Type:string
created_date

Creation date

Type:string
Format:date
page_backed_instagram_actor_id

Identifier of the Advertisable’s Page backed Instagram account, created automatically and usable in the Facebook API

Type:integer
Format:int64
instagram_actor_id

Identifier of the Advertisable’s Instagram account, usable in the Facebook API

Type:integer
Format:int64
account_is_autobilled

Indicates if the account is billed automatically

Type:boolean
CreativeParams
Type:object
advertisable_eid

Identifier of the Advertisable

Required:True
name

Display name of the Creative

Required:True
Type:string
title

Title of the Creative

Type:string
MinLength:1
call_to_action

Call-to-action of the Creative

Type:string
image_url

URL of the Creative image

Type:string
MaxLength:1024
height

Height of the Creative image

Type:integer
caption

Link caption of the Creative

Type:string
lead_gen_form_eid

Identifier of the LeadGenForm

Type:string
file

File for the Creative

Type:string
link

Link URL of the Creative

Type:string
MaxLength:1024
message

Post message of the Creative

Type:string
MinLength:1
width

Width of the Creative image

Type:integer
description

Link description of the Creative

Type:string
Geolocation

A location that can be used to target or exclude users

Type:object
name

Name of this Geolocation

Type:string
region

Region associated with this Geolocation

Type:string
primary_city

City associated with this Geolocation

Type:string
eid

EID for this Geolocation

Type:string
country_code

Two-letter ISO country code for this Geolocation

Type:string
country_name

Country associated with this Geolocation

Type:string
type

Type of this Geolocation

Type:string
Enum:country, region, city, zip
InstagramAccount
Type:object
instagram_actor_id

Instagram ID for the account

Type:integer
Format:int64
page_backed_instagram_actor_id

Instagram ID of the page backed Instagram account

Type:integer
Format:int64
instagram_profile_pic

Link to the Instagram account’s profile picture

Type:string
Format:URL
instagram_username

Instagram account’s username

Type:string
is_page_backed

Indicates if the Advertisable publishes to Instagram through a page backed account

Type:boolean
Type:object
updated_date

Last update date

Type:string
Format:date
creative_eid

EID of the Creative to create this Ad for

Type:string
remote_status

Effective Facebook status for the Ad

Type:string
Enum:ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED
name

Name of the Ad

Type:string
is_active

Whether or not this Ad is active

Type:boolean
status

Indicates the status of the Ad

Type:string
Enum:draft, paused, active, deleted, completed, kicked
eid

Unique identifier

Type:string
disapproval_reason

Reason why the Ad was disapproved by Facebook

Type:string
created_date

Creation date

Type:string
Format:date
CampaignBulk
Type:object
status

Status of the Campaign

Type:string
Enum:active, paused, deleted, archived
advertisable_eid

Identifier of the Advertisable

Type:string
kpi_metric

Metric that this campaign’s KPI represents

Type:string
updated_date

Last updated date

Type:string
Format:date
name

Display name of the Campaign

Type:string
end_date

End date for the Campaign

Type:string
Format:date
is_prospecting

Whether the Campaign is prospecting or not

Type:boolean
kpi_goal

Value associated with this campaign’s KPI

Type:string
kpi_currency

Currency of this campaign’s KPI goal

Type:string
budget

Budget of the Campaign

Type:number
Format:float
is_active

Whether the Campaign is active or not

Type:boolean
source

Source of the Campaign

Type:string
is_retargeting

Whether the Campaign is retargeting or not

Type:boolean
eid

Unique identifier

Type:string
created_date

Creation date

Type:string
Format:date
spend_limit_until

Date limit for spending on the campaign

Type:string
Format:date
adsets
Type:array of items
start_date

Start date for the Campaign

Type:string
Format:date
currency

Currency code of the account

Type:string
CustomAudienceParams
Type:object
advertisable_eid

EID of the Advertisable to create this Lookalike Audience for

Required:True
Type:string
name

Name of this Custom Audience

Required:True
Type:string
conversion_value

Value to attribute to conversions for this Custom Audience

Type:number
Format:float
is_conversion

Whether or not members of this Custom Audience have converted

Required:True
Type:boolean
retention_days

Number of days that people stay in this Custom Audience for

Required:True
Type:integer
Maximum:180
Minimum:1
subtype

Subtype of the Custom Audience

Required:True
Type:string
Enum:CLAIM, CUSTOM, LOOKALIKE, WEBSITE, arbitrary_data, pages_viewed, products_viewed, lookalike, lead_generation
rule

Rule that people in this Custom Audience match

Required:True
Type:string
UserPermissionChange
Type:object
FacebookPage
Type:object
page_access

Indicates if AdRoll has access to the Advertisable’s page

Type:boolean
page_admin_access

Indicates if AdRoll has admin access to the Advertisable’s page

Type:boolean
fb_page_id

Facebook ID for the page

Type:string
fb_page_name

Name of the Facebook page

Type:string
fb_page_img

Link to the Facebook Page’s profile picture

Type:string
Format:URL
fb_page_url

Facebook page URL

Type:string
Format:URL
no_profile_picture

Indicates if the Facebook Page does not have a profile picture

Type:boolean
is_published

True if the Facebook page is published

Type:boolean
Campaign
Type:object
updated_date

Last updated date

Type:string
Format:date
status

Status of the Campaign

Type:string
Enum:active, paused, deleted, archived
advertisable
Type:object
name

Display name of the Campaign

Type:string
adsets
Type:array of AdSet
bid_strategy

Indicates if the bid strategy of the Campaign is automatic or manual

Type:string
Enum:automatic, manual
performance_target

Indicates the performance target when bid strategy is manual

Type:string
Enum:None, cpc, cpm, cpl, cpa
source

Source of the Campaign

Type:string
objective

Objective of the Campaign

Type:string
Enum:CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, PRODUCT_CATALOG_SALES
eid

Unique identifier

Type:string
created_date

Creation date

Type:string
Format:date
performance_target_value

Indicates the performance target value when bid strategy is manual

Type:number
Format:float
goal

Goal of the Campaign

Type:string
Enum:retarget, prospect
AdStatus
Type:object
status

Indicates the status of the Ad

Type:string
Enum:draft, paused, active, deleted, completed, kicked
CustomAudienceApproximateCountList
Type:array
Event
Type:object
object_eid

EID of the related object to the event

Type:string
event_type

Type of the event

Type:string
error_string

Message if an error happens

Type:string
object_type

Type of the related object to the event

Type:string
eid

Unique identifier

Type:string
created_date

Creation date

Type:string
Format:date
error_reason

Reason of why the error happened

Type:string
response_json

Full JSON response from remote events

Type:string
event_data

Information associated with the event

Type:string
LeadGenFormParams
Type:object
follow_up_action_url

URL to redirect users to after they fill in the Lead Gen Form

Required:True
Type:string
privacy_policy_url

URL containing a privacy policy that describes how the Lead Gen Form’s data is handled

Required:True
Type:string
name

Name of the Lead Gen Form

Required:True
Type:string
AdSet
Type:object
updated_date

Last update date

Type:string
Format:date
is_autobid

True if the Advertisable is set to bid automatically

Type:boolean
pacing_type

Defines the pacing type, standard or using ad scheduling

Type:string
Enum:standard, no_pacing
targeting

AdSet attributes that define who sees an ad

Type:object
pricing_model

Pricing model that this AdSet is using

Type:string
Enum:dynamic, fixed_cpc
end_date

End date for the AdSet

Type:string
Format:date
max_age

Maximum age for the AdSet to target

Type:integer
Maximum:65
Minimum:13
promoted_object

Object this ad set is promoting across all its ads

Type:object
bid_amount

Bid amount of the AdSet

Type:number
Format:float
cpc

CPC value that this AdSet is using if the pricing model is fixed_cpc

Type:number
Format:float
budget

Daily budget of the AdSet

Type:number
Format:float
min_age

Minimum age for the AdSet to target

Type:integer
Maximum:65
Minimum:13
optimization_goal

Which optimization goal this ad set is using

Type:string
Enum:IMPRESSIONS, OFFSITE_CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, LANDING_PAGE_VIEWS
status

Status of the AdSet

Type:string
Enum:active, paused, deleted, archived
eid

Unique identifier

Type:string
created_date

Creation date

Type:string
Format:date
audiences
Type:array of Audience
ads
Type:array of Ad
start_date

Start date for the AdSet

Type:string
Format:date
name

Name of the AdSet

Type:string
FacebookPageUrl
Type:object
url

Facebook page URL

Type:string
Format:URL
id

Facebook ID of a page

Type:string
AdParams
Type:object
status

Status of the Ad

Type:string
Enum:draft, paused, active, deleted, completed, kicked
creative_eid

EID of the Creative to create this Ad for

Type:string
adset_eid

EID of the AdSet to create this Ad for

Type:string
name

Name of the Ad

Type:string
CustomAudienceApproximateCount
Type:object
approximate_count

Approximate number of people in this audience

Type:integer
CustomAudience
Type:object
updated_date

Last updated date

Type:string
Format:date
match_method

Type of the Custom Audience

Type:string
Enum:url_match, crm_data, arbitrary_data, pages_viewed, lookalike, lead_generation, products_viewed
advertisable
Type:object
name

Name of this Custom Audience

Type:string
is_conversion

Whether or not members of this Custom Audience have converted

Type:boolean
approximate_count

Approximate number of people in this audience

Type:integer
rule

Rule that people in this Custom Audience match

Type:string
subtype

Subtype of the Custom Audience

Type:string
Enum:CLAIM, CUSTOM, LOOKALIKE, WEBSITE, arbitrary_data, pages_viewed, products_viewed, lookalike, lead_generation
operation_status

Status of the last operation performed on the audience

Type:object
retention_days

Number of days that people stay in this Custom Audience for

Type:integer
Maximum:180
Minimum:1
created_date

Creation date

Type:string
Format:date
threshold

The threshold used for match methods with a numerical limit.

Type:integer
delivery_status

Indicates whether or not the audience can be used in ads

Type:object
lookalike_audience
Type:LookalikeAudience
eid

Unique identifier

Type:string