Facebook API Reference

Warning

The Facebook API will be retired at the end of February 2023.

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 short_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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Schema for request body: AdParams

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

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Status

Returns AdStatus

application/json example:

{
  "status": "active"
}
403

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

204

Ad Deleted

403

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

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: exclude_audiences, target_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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Success

400

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Paginated list of AdSets

application/json example:

{
  "count": 36,
  "page": 1,
  "page_size": 2,
  "results": [
    {
      "ads": [],
      "audiences": [],
      "bid_amount": null,
      "budget": 300.0,
      "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
      "status": "draft",
      "targeting": {
        "page_types": [
          "desktopfeed",
          "mobilefeed"
        ]
      },
      "ui_period": "daily",
      "updated_date": "2024-10-01T16:45: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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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,
  "end_date": "string",
  "max_age": 0,
  "min_age": 0,
  "name": "string",
  "optimization_goal": "string",
  "pacing_type": "string",
  "promoted_object": {},
  "start_date": "string",
  "status": "string",
  "targeting": {
    "page_types": [
      "string"
    ],
    "placements": {
      "audience_network_positions": [
        "string"
      ],
      "automatic": true,
      "facebook_positions": [
        "string"
      ],
      "instagram_positions": [
        "string"
      ],
      "messenger_positions": [
        "string"
      ]
    }
  }
}

Responses:

200

An AdSet

Returns AdSet

application/json example:

{
  "ads": [],
  "audiences": [],
  "bid_amount": null,
  "budget": 300.0,
  "campaign_eid": "CAMPAIGNEID123",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "status": "draft",
  "targeting": {
    "page_types": [
      "desktopfeed",
      "mobilefeed"
    ]
  },
  "ui_period": "daily",
  "updated_date": "2024-10-01T16:45:26"
}
403

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

An AdSet

Returns AdSet

application/json example:

{
  "ads": [],
  "audiences": [],
  "bid_amount": null,
  "budget": 300.0,
  "campaign_eid": "CAMPAIGNEID123",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "status": "draft",
  "targeting": {
    "page_types": [
      "desktopfeed",
      "mobilefeed"
    ]
  },
  "ui_period": "daily",
  "updated_date": "2024-10-01T16:45:26"
}
403

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Schema for request body:

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

object

geolocation_eid

The EID of the Geolocation to add to the AdSet

Required

True

Type

string

included

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

Required

True

Type

boolean

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

An AdSet

Returns AdSet

application/json example:

{
  "ads": [],
  "audiences": [],
  "bid_amount": null,
  "budget": 300.0,
  "campaign_eid": "CAMPAIGNEID123",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "status": "draft",
  "targeting": {
    "page_types": [
      "desktopfeed",
      "mobilefeed"
    ]
  },
  "ui_period": "daily",
  "updated_date": "2024-10-01T16:45:26"
}
403

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

An AdSet

Returns AdSet

application/json example:

{
  "ads": [],
  "audiences": [],
  "bid_amount": null,
  "budget": 300.0,
  "campaign_eid": "CAMPAIGNEID123",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "status": "draft",
  "targeting": {
    "page_types": [
      "desktopfeed",
      "mobilefeed"
    ]
  },
  "ui_period": "daily",
  "updated_date": "2024-10-01T16:45:26"
}
403

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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,
  "end_date": "string",
  "max_age": 0,
  "min_age": 0,
  "name": "string",
  "optimization_goal": "string",
  "pacing_type": "string",
  "promoted_object": {},
  "start_date": "string",
  "status": "string",
  "targeting": {
    "page_types": [
      "string"
    ],
    "placements": {
      "audience_network_positions": [
        "string"
      ],
      "automatic": true,
      "facebook_positions": [
        "string"
      ],
      "instagram_positions": [
        "string"
      ],
      "messenger_positions": [
        "string"
      ]
    }
  }
}

Responses:

200

An AdSet

Returns AdSet

application/json example:

{
  "ads": [],
  "audiences": [],
  "bid_amount": null,
  "budget": 300.0,
  "campaign_eid": "CAMPAIGNEID123",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "status": "draft",
  "targeting": {
    "page_types": [
      "desktopfeed",
      "mobilefeed"
    ]
  },
  "ui_period": "daily",
  "updated_date": "2024-10-01T16:45:26"
}
403

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

204

AdSet Deleted

403

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

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: resume, pause.

Query Parameters

Name

Required

Type

Description

apikey

False

string

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

Responses:

200

An AdSet

Returns AdSet

application/json example:

{
  "ads": [],
  "audiences": [],
  "bid_amount": null,
  "budget": 300.0,
  "campaign_eid": "CAMPAIGNEID123",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "status": "draft",
  "targeting": {
    "page_types": [
      "desktopfeed",
      "mobilefeed"
    ]
  },
  "ui_period": "daily",
  "updated_date": "2024-10-01T16:45:26"
}
403

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID",
  "account_is_autobilled": false,
  "account_is_prepaid": true,
  "created_date": "2024-10-01T16:45: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,
  "sac_override": null,
  "show_dpa": true,
  "tos_accepted": true,
  "updated_date": "2024-10-01T16:45: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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID",
  "account_is_autobilled": false,
  "account_is_prepaid": true,
  "created_date": "2024-10-01T16:45: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,
  "sac_override": null,
  "show_dpa": true,
  "tos_accepted": true,
  "updated_date": "2024-10-01T16:45:26",
  "url": "https://legitadvertiser.website"
}
403

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID",
  "account_is_autobilled": false,
  "account_is_prepaid": true,
  "created_date": "2024-10-01T16:45: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,
  "sac_override": null,
  "show_dpa": true,
  "tos_accepted": true,
  "updated_date": "2024-10-01T16:45: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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID",
  "account_is_autobilled": false,
  "account_is_prepaid": true,
  "created_date": "2024-10-01T16:45: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,
  "sac_override": null,
  "show_dpa": true,
  "tos_accepted": true,
  "updated_date": "2024-10-01T16:45:26",
  "url": "https://legitadvertiser.website"
}
403

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
          "status": "draft",
          "targeting": {
            "page_types": [
              "desktopfeed",
              "mobilefeed"
            ]
          },
          "ui_period": "daily",
          "updated_date": "2024-10-01T16:45:26"
        }
      ],
      "advertisable": {
        "eid": "LEGIADVERTISEREID"
      },
      "bid_strategy": "automatic",
      "created_date": "2024-10-01T16:45:26",
      "eid": "LEGICAMPAIGNID1",
      "goal": "retarget",
      "is_billable": true,
      "name": "Legit Campaign name 1",
      "objective": "LINK_CLICKS",
      "performance_target": null,
      "performance_target_value": null,
      "source": null,
      "status": "active",
      "updated_date": "2024-10-01T16:45:26"
    },
    {
      "adsets": [
        {
          "ads": [],
          "audiences": [],
          "bid_amount": null,
          "budget": 357.15,
          "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
          "status": "draft",
          "targeting": {
            "page_types": [
              "desktopfeed",
              "mobilefeed",
              "rightcolumn",
              "mobileexternal",
              "instagramstream"
            ]
          },
          "ui_period": "daily",
          "updated_date": "2024-10-01T16:45:26"
        }
      ],
      "advertisable": {
        "eid": "LEGIADVERTISEREID"
      },
      "bid_strategy": "automatic",
      "created_date": "2024-10-01T16:45:26",
      "eid": "LEGICAMPAIGNID2",
      "goal": "retarget",
      "is_billable": true,
      "name": "Legit Campaign name 2",
      "objective": "LINK_CLICKS",
      "performance_target": null,
      "performance_target_value": null,
      "status": "draft",
      "updated_date": "2024-10-01T16:45: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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Schema for request body: CampaignParams

{
  "advertisable_eid": "string",
  "bid_strategy": "string",
  "budget": 0.0,
  "goal": "string",
  "is_autobid": true,
  "name": "string",
  "objective": "string",
  "performance_target": "string",
  "pricing_model": "string",
  "should_launch": true,
  "source": "string",
  "special_ad_category": "string",
  "status": "string"
}

Responses:

200

A Campaign

Returns Campaign

application/json example:

{
  "adsets": [
    {
      "ads": [],
      "audiences": [],
      "bid_amount": null,
      "budget": 300.0,
      "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
      "status": "draft",
      "targeting": {
        "page_types": [
          "desktopfeed",
          "mobilefeed",
          "rightcolumn",
          "mobileexternal",
          "instagramstream"
        ]
      },
      "ui_period": "daily",
      "updated_date": "2024-10-01T16:45:26"
    }
  ],
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  },
  "bid_strategy": "manual",
  "created_date": "2024-10-01T16:45:26",
  "eid": "LEGITEID",
  "goal": "prospect",
  "is_billable": true,
  "name": "Legit Campaign name",
  "objective": "LINK_CLICKS",
  "performance_target": null,
  "performance_target_value": null,
  "source": null,
  "special_ad_category": null,
  "status": "draft",
  "updated_date": "2024-10-01T16:45:26"
}
403

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

A Campaign

Returns Campaign

application/json example:

{
  "adsets": [
    {
      "ads": [],
      "audiences": [],
      "bid_amount": null,
      "budget": 300.0,
      "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
      "status": "draft",
      "targeting": {
        "page_types": [
          "desktopfeed",
          "mobilefeed",
          "rightcolumn",
          "mobileexternal",
          "instagramstream"
        ]
      },
      "ui_period": "daily",
      "updated_date": "2024-10-01T16:45:26"
    }
  ],
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  },
  "bid_strategy": "manual",
  "created_date": "2024-10-01T16:45:26",
  "eid": "LEGITEID",
  "goal": "prospect",
  "is_billable": true,
  "name": "Legit Campaign name",
  "objective": "LINK_CLICKS",
  "performance_target": null,
  "performance_target_value": null,
  "source": null,
  "special_ad_category": null,
  "status": "draft",
  "updated_date": "2024-10-01T16:45:26"
}
403

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

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)

Updates a Campaign

Parameters:

Path Parameters

Name

Required

Type

Description

eid

True

string

EID of the Campaign to update

Query Parameters

Name

Required

Type

Description

apikey

False

string

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

Schema for request body: CampaignParams

{
  "advertisable_eid": "string",
  "bid_strategy": "string",
  "budget": 0.0,
  "goal": "string",
  "is_autobid": true,
  "name": "string",
  "objective": "string",
  "performance_target": "string",
  "pricing_model": "string",
  "should_launch": true,
  "source": "string",
  "special_ad_category": "string",
  "status": "string"
}

Responses:

200

A Campaign

Returns Campaign

application/json example:

{
  "adsets": [
    {
      "ads": [],
      "audiences": [],
      "bid_amount": null,
      "budget": 300.0,
      "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
      "status": "draft",
      "targeting": {
        "page_types": [
          "desktopfeed",
          "mobilefeed",
          "rightcolumn",
          "mobileexternal",
          "instagramstream"
        ]
      },
      "ui_period": "daily",
      "updated_date": "2024-10-01T16:45:26"
    }
  ],
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  },
  "bid_strategy": "manual",
  "created_date": "2024-10-01T16:45:26",
  "eid": "LEGITEID",
  "goal": "prospect",
  "is_billable": true,
  "name": "Legit Campaign name",
  "objective": "LINK_CLICKS",
  "performance_target": null,
  "performance_target_value": null,
  "source": null,
  "special_ad_category": null,
  "status": "draft",
  "updated_date": "2024-10-01T16:45:26"
}
400

Invalid Campaign Status

Returns Error

application/json example:

{
  "code": "ERROR_INVALID_CAMPAIGN_STATUS",
  "error": "Status [deleted, archived] is invalid.",
  "subcode": null
}
403

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

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/campaigns/(eid)

Deletes a campaign

Parameters:

Path Parameters

Name

Required

Type

Description

eid

True

string

Campaign EID to delete

Query Parameters

Name

Required

Type

Description

apikey

False

string

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

Responses:

204

Campaign deleted successfully

403

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

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: resume, pause, admin_pause.

Query Parameters

Name

Required

Type

Description

apikey

False

string

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

Responses:

200

A Campaign

Returns Campaign

application/json example:

{
  "adsets": [
    {
      "ads": [],
      "audiences": [],
      "bid_amount": null,
      "budget": 300.0,
      "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
      "status": "draft",
      "targeting": {
        "page_types": [
          "desktopfeed",
          "mobilefeed",
          "rightcolumn",
          "mobileexternal",
          "instagramstream"
        ]
      },
      "ui_period": "daily",
      "updated_date": "2024-10-01T16:45:26"
    }
  ],
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  },
  "bid_strategy": "manual",
  "created_date": "2024-10-01T16:45:26",
  "eid": "LEGITEID",
  "goal": "prospect",
  "is_billable": true,
  "name": "Legit Campaign name",
  "objective": "LINK_CLICKS",
  "performance_target": null,
  "performance_target_value": null,
  "source": null,
  "special_ad_category": null,
  "status": "draft",
  "updated_date": "2024-10-01T16:45:26"
}
400

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

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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": "2024-10-01T16:45: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": "2024-10-01T16:45: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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

A Creative

Returns Creative

application/json example:

{
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  },
  "call_to_action": "NO_BUTTON",
  "caption": "legitadvertiser.website",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "width": 600
}
404

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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

A Creative

Returns Creative

application/json example:

{
  "advertisable": {
    "eid": "LEGITADVERTISEREID"
  },
  "call_to_action": "NO_BUTTON",
  "caption": "legitadvertiser.website",
  "created_date": "2024-10-01T16:45: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": "2024-10-01T16:45:26",
  "width": 600
}
400

Request error

Returns Error

application/json example:

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

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

Resource not found

Returns Error

application/json example:

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID",
  "account_is_autobilled": false,
  "account_is_prepaid": true,
  "created_date": "2024-10-01T16:45: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,
  "sac_override": null,
  "show_dpa": true,
  "tos_accepted": true,
  "updated_date": "2024-10-01T16:45:26",
  "url": "https://legitadvertiser.website"
}
400

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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

Advertiser

Returns Advertiser

application/json example:

{
  "account_eid": "LEGITACCOUNTEID",
  "account_is_autobilled": false,
  "account_is_prepaid": true,
  "created_date": "2024-10-01T16:45: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,
  "sac_override": null,
  "show_dpa": true,
  "tos_accepted": true,
  "updated_date": "2024-10-01T16:45:26",
  "url": "https://legitadvertiser.website"
}
400

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Schema for request body:

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

object

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

included

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

Required

True

Type

boolean

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

204

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 Personal Access Tokens (PAT). The value is the Client ID you received when you registered your application on the NextRoll 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

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

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

FacebookPageUrl
Type

object

id

Facebook ID of a page

Type

string

url

Facebook page URL

Type

string

Format

URL

Advertiser
Type

object

eid

Identifier of the Advertisable

Type

string

created_date

Creation date

Type

string

Format

date

updated_date

Last update date

Type

string

Format

date

account_eid

Identifier of the account of the Advertisable

Type

string

account_is_prepaid

Indicates if the account is prepaid

Type

boolean

account_is_autobilled

Indicates if the account is billed automatically

Type

boolean

currency

Currency code of the account

Type

string

is_page_backed

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

Type

boolean

is_suspended

Indicates if the account is suspended

Type

boolean

name

Display name of the Advertisable

Type

string

organization_eid

EID of the Organization that owns the Advertisable

Type

string

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

show_dpa

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

Type

boolean

tos_accepted

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

Type

object

url

URL of the Advertisable’s website

Type

string

fb_page_url

URL of the Advertisable’s Facebook page

Type

string

fb_page_id

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

Type

string

instagram_actor_id

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

Type

integer

Format

int64

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

status

Status of the Advertiser

Type

string

Enum

approved, rejected

sac_override

FB Special Ad Category

Type

string

AdvertisableEid
Type

object

advertsable_eid

EID of an Advertisable

Type

string

Default

Advertisable associated to the logged in user

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

message

Post message of the Creative

Type

string

MinLength

1

link

Link URL of the Creative

Type

string

MaxLength

1024

caption

Link caption of the Creative

Type

string

description

Link description of the Creative

Type

string

call_to_action

Call-to-action of the Creative

Type

string

file

File for the Creative

Type

string

image_url

URL of the Creative image

Type

string

MaxLength

1024

width

Width of the Creative image

Type

integer

height

Height of the Creative image

Type

integer

lead_gen_form_eid

Identifier of the LeadGenForm

Type

string

CustomAudienceParams
Type

object

advertisable_eid

EID of the Advertisable to create this Lookalike Audience for

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

name

Name of this Custom Audience

Required

True

Type

string

retention_days

Number of days that people stay in this Custom Audience for

Required

True

Type

integer

Maximum

180

Minimum

1

rule

Rule that people in this Custom Audience match

Required

True

Type

string

subtype

Subtype of the Custom Audience

Required

True

Type

string

Enum

CLAIM, CUSTOM, LOOKALIKE, WEBSITE, arbitrary_data, pages_viewed, products_viewed, lookalike, lead_generation

CustomAudienceApproximateCount
Type

object

approximate_count

Approximate number of people in this audience

Type

integer

CustomAudienceApproximateCountList
Type

array

CampaignParams
Type

object

name

Display name of the Campaign

Type

string

objective

Objective of the Campaign

Type

string

Enum

CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, PRODUCT_CATALOG_SALES

status

Status of the Campaign

Type

string

Enum

draft, active, paused, deleted, archived, admin_paused

bid_strategy

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

Type

string

Enum

automatic, manual, LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS

performance_target

Indicates the performance target when bid strategy is manual

Type

string

Enum

None, cpc, cpm, cpl, cpa, cprl

pricing_model

Pricing model to use for this Campaign

Type

string

Enum

dynamic

budget

Daily budget of the Campaign

Type

number

Format

float

is_autobid

Whether the Advertisable expresses the intent to bid automatically

Type

boolean

goal

Goal of the Campaign

Type

string

Enum

retarget, prospect

advertisable_eid

Identifier of the Advertisable

Type

string

source

Source 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

special_ad_category

The special ad category for ads in this campaign

Type

string

Enum

None, HOUSING, CREDIT, EMPLOYMENT, ISSUES_ELECTIONS_POLITICS, NONE

AdSetParams
Type

object

bid_amount

Bid amount of the AdSet

Type

number

Format

float

pacing_type

Defines the pacing type, standard or using ad scheduling

Type

string

Enum

standard, no_pacing

min_age

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

Type

integer

Maximum

65

Minimum

16

max_age

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

Type

integer

Maximum

65

Minimum

16

name

Name of the AdSet

Type

string

optimization_goal

Which optimization goal this ad set is using

Type

string

Enum

IMPRESSIONS, OFFSITE_CONVERSIONS, ONSITE_CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, LANDING_PAGE_VIEWS, POST_ENGAGEMENT, REACH, AD_RECALL_LIFT, APP_INSTALLS, ENGAGED_USERS, EVENT_RESPONSES, QUALITY_LEAD, PAGE_LIKES, QUALITY_CALL, VISIT_INSTAGRAM_PROFILE, VALUE, THRUPLAY, DERIVED_EVENTS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, CONVERSATIONS, IN_APP_VALUE

promoted_object

Object this ad set is promoting across all its ads

Type

object

start_date

Start date for the AdSet

Type

string

Format

date

end_date

End date for the AdSet

Type

string

Format

date

status

Status of the AdSet

Type

string

Enum

active, paused, deleted, archived, draft

targeting

AdSet attributes that define who sees an ad. Must include one of page_types or placements, but not both

Type

object

ads
Type

array of Ad

audiences
Type

array of Audience

AdParams
Type

object

name

Name of the Ad

Type

string

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

AdStatus
Type

object

status

Indicates the status of the Ad

Type

string

Enum

draft, paused, active, deleted, completed, kicked

AudienceShare
Type

array

UserPermissionChange
Type

object

Creative
Type

object

eid

Unique identifier

Type

string

created_date

Creation date

Type

string

Format

date

updated_date

Last update date

Type

string

Format

date

name

Display name of the Creative

Type

string

external_id

Facebook Creative ID, usable in the Facebook API

Type

string

title

Title of the Creative

Type

string

message

Post message of the Creative

Type

string

call_to_action

Call-to-action of the Creative

Type

string

image_url

URL of the Creative image

Type

string

instagram_permalink_url

Permalink URL to the Creative on Instagram

Type

string

link

Link URL of the Creative

Type

string

caption

Link caption of the Creative

Type

string

description

Link description of the Creative

Type

string

read_only

Indicates whether the Creative is read-only or not

Type

boolean

width

Width of the Creative image

Type

integer

height

Height of the Creative image

Type

integer

status

Indicates the status of the Creative

Type

string

Enum

active, deleted

advertisable
Type

object

is_dynamic

Indicates whether the Creative is dynamic or not

Type

boolean

is_active

Indicates whether the Creative is active or not

Type

boolean

lead_gen_form
Type

object

Campaign
Type

object

eid

Unique identifier

Type

string

created_date

Creation date

Type

string

Format

date

updated_date

Last updated date

Type

string

Format

date

name

Display name of the Campaign

Type

string

objective

Objective of the Campaign

Type

string

Enum

CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, PRODUCT_CATALOG_SALES

source

Source of the Campaign

Type

string

status

Status of the Campaign

Type

string

Enum

draft, active, paused, deleted, archived, admin_paused

bid_strategy

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

Type

string

Enum

automatic, manual, LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS

performance_target_value

Indicates the performance target value when bid strategy is manual

Type

number

Format

float

performance_target

Indicates the performance target when bid strategy is manual

Type

string

Enum

None, cpc, cpm, cpl, cpa, cprl

goal

Goal of the Campaign

Type

string

Enum

retarget, prospect

pricing_model

Pricing model that this Campaign is using

Type

string

Enum

dynamic

budget

Daily budget of the Campaign

Type

number

Format

float

is_autobid

True if the Advertisable is set to bid automatically

Type

boolean

is_billable

True if the Campaign will be billed

Type

boolean

advertisable
Type

object

adsets
Type

array of AdSet

special_ad_category

The special ad category for ads in this campaign

Type

string

Enum

None, HOUSING, CREDIT, EMPLOYMENT, ISSUES_ELECTIONS_POLITICS, NONE

CampaignBulk
Type

object

eid

Unique identifier

Type

string

advertisable_eid

Identifier of the Advertisable

Type

string

name

Display name of the Campaign

Type

string

status

Status of the Campaign

Type

string

Enum

draft, active, paused, deleted, archived, admin_paused

is_active

Whether the Campaign is active or not

Type

boolean

is_retargeting

Whether the Campaign is retargeting or not

Type

boolean

is_prospecting

Whether the Campaign is prospecting or not

Type

boolean

spend_limit_until

Date limit for spending on the campaign

Type

string

Format

date

budget

Budget of the Campaign

Type

number

Format

float

is_autobid

True if the Advertisable is set to bid automatically

Type

boolean

currency

Currency code of the account

Type

string

start_date

Start date for the Campaign

Type

string

Format

date

end_date

End date for the Campaign

Type

string

Format

date

created_date

Creation date

Type

string

Format

date

updated_date

Last updated date

Type

string

Format

date

adsets
Type

array of items

kpi_metric

Metric that this campaign’s KPI represents

Type

string

kpi_goal

Value associated with this campaign’s KPI

Type

string

kpi_currency

Currency of this campaign’s KPI goal

Type

string

source

Source of the Campaign

Type

string

special_ad_category

The special ad category for ads in this campaign

Type

string

Enum

None, HOUSING, CREDIT, EMPLOYMENT, ISSUES_ELECTIONS_POLITICS, NONE

funnel_stage

Bucket

Type

string

Enum

awareness, consideration, conversion, other

Type

object

eid

Unique identifier

Type

string

created_date

Creation date

Type

string

Format

date

updated_date

Last update date

Type

string

Format

date

name

Name of the Ad

Type

string

creative_eid

EID of the Creative to create this Ad for

Type

string

status

Indicates the status of the Ad

Type

string

Enum

draft, paused, active, deleted, completed, kicked

is_active

Whether or not this Ad is active

Type

boolean

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

disapproval_reason

Reason why the Ad was disapproved by Facebook

Type

string

AdSet
Type

object

eid

Unique identifier

Type

string

bid_amount

Bid amount of the AdSet

Type

number

Format

float

created_date

Creation date

Type

string

Format

date

updated_date

Last update date

Type

string

Format

date

min_age

Minimum age for the AdSet to target

Type

integer

Maximum

65

Minimum

16

max_age

Maximum age for the AdSet to target

Type

integer

Maximum

65

Minimum

16

pacing_type

Defines the pacing type, standard or using ad scheduling

Type

string

Enum

standard, no_pacing

name

Name of the AdSet

Type

string

optimization_goal

Which optimization goal this ad set is using

Type

string

Enum

IMPRESSIONS, OFFSITE_CONVERSIONS, ONSITE_CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, LANDING_PAGE_VIEWS, POST_ENGAGEMENT, REACH, AD_RECALL_LIFT, APP_INSTALLS, ENGAGED_USERS, EVENT_RESPONSES, QUALITY_LEAD, PAGE_LIKES, QUALITY_CALL, VISIT_INSTAGRAM_PROFILE, VALUE, THRUPLAY, DERIVED_EVENTS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, CONVERSATIONS, IN_APP_VALUE

promoted_object

Object this ad set is promoting across all its ads

Type

object

start_date

Start date for the AdSet

Type

string

Format

date

end_date

End date for the AdSet

Type

string

Format

date

status

Status of the AdSet

Type

string

Enum

active, paused, deleted, archived, draft

targeting

AdSet attributes that define who sees an ad. Must include one of page_types or placements, but not both

Type

object

ads
Type

array of Ad

audiences
Type

array of Audience

AdSetBulk
Type

object

eid

Unique identifier

Type

string

advertisable_eid

Identifier of the Advertisable

Type

string

campaign_eid

Identifier of the Campaign

Type

string

bid_amount

Bid amount of the AdSet

Type

number

Format

float

created_date

Creation date

Type

string

Format

date

updated_date

Last update date

Type

string

Format

date

pacing_type

Defines the pacing type, standard or using ad scheduling

Type

string

Enum

standard, no_pacing

name

Name of the AdSet

Type

string

optimization_goal

Which optimization goal this ad set is using

Type

string

Enum

IMPRESSIONS, OFFSITE_CONVERSIONS, ONSITE_CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, LANDING_PAGE_VIEWS, POST_ENGAGEMENT, REACH, AD_RECALL_LIFT, APP_INSTALLS, ENGAGED_USERS, EVENT_RESPONSES, QUALITY_LEAD, PAGE_LIKES, QUALITY_CALL, VISIT_INSTAGRAM_PROFILE, VALUE, THRUPLAY, DERIVED_EVENTS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, CONVERSATIONS, IN_APP_VALUE

promoted_object

Object this ad set is promoting across all its ads

Type

object

start_date

Start date for the AdSet

Type

string

Format

date

end_date

End date for the AdSet

Type

string

Format

date

flight_timezone

Just UTC at the moment

Type

string

flight_start_date

Alias of start_date, in ISO 8601 format

Type

string

Format

date

flight_end_date

Alias of end_date, in ISO 8601 format

Type

string

Format

date

status

Status of the AdSet

Type

string

Enum

active, paused, deleted, archived, draft

targeting

AdSet attributes that define who sees an ad

Type

object

ads
Type

array of Ad

audiences
Type

array of Audience

Audience
Type

object

eid

Unique identifier

Type

string

created_date

Creation date

Type

string

Format

date

updated_date

Last update date

Type

string

Format

date

custom_audience_eid

EID of the Custom Audience to create this Audience for

Type

string

targeted

Whether the target is targeted or not

Type

boolean

Error
Type

object

code
Type

string

error
Type

string

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

is_page_backed

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

Type

boolean

instagram_profile_pic

Link to the Instagram account’s profile picture

Type

string

Format

URL

instagram_username

Instagram account’s username

Type

string

FacebookPage
Type

object

fb_page_id

Facebook ID for the page

Type

string

fb_page_url

Facebook page URL

Type

string

Format

URL

is_published

True if the Facebook page is published

Type

boolean

fb_page_name

Name of the Facebook page

Type

string

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_img

Link to the Facebook Page’s profile picture

Type

string

Format

URL

no_profile_picture

Indicates if the Facebook Page does not have a profile picture

Type

boolean

AdSetGeolocation

A Geolocation attached to an AdSet

Type

object

country_code

Two-letter ISO country code for this AdSetGeolocation

Type

string

country_name

Country associated with this AdSetGeolocation

Type

string

eid

EID for this AdSetGeolocation

Type

string

error

Error message 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

name

Name of this AdSetGeolocation

Type

string

primary_city

City associated with this AdSetGeolocation

Type

string

region

Region associated with this AdSetGeolocation

Type

string

selected_children

AdSetGeolocations that are children of this AdSetGeolocation

Type

array of AdSetGeolocation

type

Type of this AdSetGeolocation

Type

string

Enum

country, region, city, zip

Geolocation

A location that can be used to target or exclude users

Type

object

country_code

Two-letter ISO country code for this Geolocation

Type

string

country_name

Country associated with this Geolocation

Type

string

eid

EID for this Geolocation

Type

string

name

Name of this Geolocation

Type

string

primary_city

City associated with this Geolocation

Type

string

region

Region associated with this Geolocation

Type

string

type

Type of this Geolocation

Type

string

Enum

country, region, city, zip

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

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

origin_audience_eid

EID of the Custom Audience to create this Lookalike Audience from

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

CustomAudience
Type

object

advertisable
Type

object

approximate_count

Approximate number of people in this audience

Type

integer

created_date

Creation date

Type

string

Format

date

eid

Unique identifier

Type

string

is_conversion

Whether or not members of this Custom Audience have converted

Type

boolean

lookalike_audience
Type

LookalikeAudience

match_method

Type of the Custom Audience

Type

string

Enum

url_match, crm_data, arbitrary_data, pages_viewed, lookalike, lead_generation, products_viewed, user_attributes, crosschannel_lal, device_id

threshold

The threshold used for match methods with a numerical limit.

Type

integer

name

Name of this Custom Audience

Type

string

retention_days

Number of days that people stay in this Custom Audience for

Type

integer

Maximum

180

Minimum

1

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

updated_date

Last updated date

Type

string

Format

date

operation_status

Status of the last operation performed on the audience

Type

object

delivery_status

Indicates whether or not the audience can be used in ads

Type

object

LeadGenForm
Type

object

advertisable

Advertisable that owns the Lead Gen Form

Type

object

created_date

Creation date

Type

string

Format

date

updated_date

Last updated date

Type

string

Format

date

eid

Unique identifier

Type

string

name

Name of the Lead Gen Form

Type

string

external_id

Facebook ID of the Lead Gen Form

Type

string

LeadGenFormParams
Type

object

name

Name of the Lead Gen Form

Required

True

Type

string

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

Event
Type

object

eid

Unique identifier

Type

string

created_date

Creation date

Type

string

Format

date

error_string

Message if an error happens

Type

string

event_data

Information associated with the event

Type

string

event_type

Type of the event

Type

string

object_eid

EID of the related object to the event

Type

string

object_type

Type of the related object to the event

Type

string

error_reason

Reason of why the error happened

Type

string

response_json

Full JSON response from remote events

Type

string

ProductSet
Type

object

eid

Unique identifier

Type

string

created_date
Type

string

Format

date

updated_date
Type

string

Format

date

product_count

How many products were validated by Facebook

Type

integer

adroll_product_set_eid

The EID in AdRoll’s database

Type

string

product_group
Type

string

is_unfiltered
Type

boolean

is_dummy
Type

boolean

product_catalog_eid

The ProductCatalog it belongs to

Type

string

AudienceEstimationFacebookAttributeSchema
Type

object

key

Key of the attribute

Required

True

Type

integer

Format

int32

type

Type of the attribute

Required

True

Type

string

AudienceEstimationGeolocationSchema
Type

object

included

Is geolocation included

Required

True

Type

boolean

geolocation_eid

Geolocation identifier

Required

True

Type

string

MaxLength

100

MinLength

1

AudienceEstimationAudiencesSchema
Type

object

custom_audience_eid

Audience unique identifier

Required

True

Type

string

MaxLength

100

MinLength

1

targeted

If defined audience is target

Required

True

Type

boolean

AudienceEstimationSchema
Type

object

optimization_goal

Goal to optimize for

Type

string

Enum

IMPRESSIONS, OFFSITE_CONVERSIONS, ONSITE_CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, LANDING_PAGE_VIEWS, POST_ENGAGEMENT, REACH, AD_RECALL_LIFT, APP_INSTALLS, ENGAGED_USERS, EVENT_RESPONSES, QUALITY_LEAD, PAGE_LIKES, QUALITY_CALL, VISIT_INSTAGRAM_PROFILE, VALUE, THRUPLAY, DERIVED_EVENTS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, CONVERSATIONS, IN_APP_VALUE

promoted_object

FB Object to target in campaign

Type

object

campaign_objective

Campaign objective

Type

string

Enum

CONVERSIONS, LINK_CLICKS, LEAD_GENERATION, PRODUCT_CATALOG_SALES

audiences
Type

array of AudienceEstimationAudiencesSchema

facebook_attributes
Type

array of AudienceEstimationFacebookAttributeSchema

geolocations
Type

array of AudienceEstimationGeolocationSchema