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

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

Ad¶

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

Facebook API Reference¶

Description¶

Operations by Tag¶

Ads¶

Adsets¶

Advertisers¶

Audiences¶

Campaigns¶

Creatives¶

Geotargeting¶

Instagram¶

Oauth¶

Page Integration¶

Operations¶

Definitions¶