Marketing API Version

Publisher Block List

Use block lists to prevent your ads from appearing in specific places on Facebook and Audience Network. You can include specific publishers of Instant Articles and in-stream videos, as well as websites and apps for Audience Network.

Steps:

  1. Create a publisher block list
  2. Create a draft of the block list
  3. Add publisher to the draft
  4. Save the draft
  5. Use the publisher block list ID in your ad set's targeting spec under excluded_publisher_list_ids

Reading

Custom publisher block list. The list contains publishers the advertisers do not want their ads to be delivered to. The list contains two types of publishers in two separated lists: one is app publishers represented by app store urls, the other is web publishers represented by host urls.

Examples

Graph API Explorer
GET /v2.10/{publisher-block-list-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{publisher-block-list-id}'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{publisher-block-list-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{publisher-block-list-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{publisher-block-list-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

NameDescription
draft_id
numeric string or integer

If draft_id is provided, app_publishers and web_publishers are from the draft. If draft_id is not provided, app_publishers and web_publishers are from the last committed list.

Fields

FieldDescription

id

numeric string

ID

app_publishers

list<AppPublisher>

A list of app store urls

business_owner_id

numeric string

ID of the business owner if the blocklist is shared to a business

is_auto_blocking_on

bool

Auto blocking field for this blocklist

is_eligible_at_campaign_level

bool

Bool field to state if the block list adheres to campaign level maximum block list thresholds

last_update_time

datetime

ID of the user who last update the list

last_update_user

string

ID of the user who last update the list

name

string

Name

owner_ad_account_id

numeric string

ID of the ad account who owners this blocklist

web_publishers

list<WebPublisher>

A list of web domain or Facebook page urls

Edges

EdgeDescription

paged_app_publishers

A paged list of app store urls

paged_web_publishers

A paged list of web domain or Facebook page urls

Validation Rules

ErrorDescription
100Invalid parameter

Creating

Example

Create a new empty publisher block list

curl \
-F "name=My Publisher Block List" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/publisher_block_lists

The response will be the ID of the publisher block list.

{"id":"<PUBLISHER_BLOCK_LIST_ID>"}

Once the publisher block list is created, you can add publishers using update method calls.

You can make a POST request to publisher_block_lists edge from the following paths:
When posting to this edge, a PublisherBlockList will be created.

Parameters

NameDescription
name
UTF-8 encoded string

Name of the list

Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

Example

To add publishers to the publisher block list, first create a draft, then update the draft to add publisher URLs, and finally commit the draft.

Create a draft:

curl \
-F "spec={'update_type': 'create_draft'}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PUBLISHER_BLOCK_LIST_ID>

The response will contain the draft_id:

{"result":{"success":true},"data":{"draft_id":"<DRAFT_ID>"}}

Then, add publishers by updating the publisher block list with draft ID and publisher URLs. Publisher URLs can be either desktop URLs or URLs to iTunes or Google Play store.

curl \
-F "spec={'update_type':'add_publishers', 'draft_id':<DRAFT_ID>, 'publisher_urls':['<URL1>','<URL2>', '<URL3>','<URL4>']}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PUBLISHER_BLOCK_LIST_ID>

The result will contain a count of successful URLs passed through

{"result":{"success":true},"data":{"draft_id":"<DRAFT_ID>","success_url_count":4}}

If you add malformed URLs, the response will contain a warning and the URLs will not be added to the block list.

curl \
-F "spec={'update_type':'add_publishers', 'draft_id':<DRAFT_ID>, 'publisher_urls':['inva lid.com']}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PUBLISHER_BLOCK_LIST_ID>
{"result":{"success":true},"data":{"draft_id":"<DRAFT_ID>","success_url_count":0,"warning":"1 urls are not updated","invalid_urls":[{"url":"inva lid.com"}]}}

Finally when you are ready to save the draft, update the publisher block list ID and with 'update_type': 'commit_draft':

curl \
-F "spec={'update_type': 'commit_draft', 'draft_id': <DRAFT_ID>}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PUBLISHER_BLOCK_LIST_ID>

{"result":{"success":true}}
You can update a PublisherBlockList by making a POST request to /{publisher_block_list_id}.

Parameters

NameDescription
spec
Object

Specifies the update params: update_type and name|publisher_urls

Required
update_type
enum{SET_NAME, ADD_PUBLISHERS, COPY_TO_DRAFT, COMMIT_DRAFT, CREATE_DRAFT, REMOVE_PUBLISHERS, REPLACE_FROM_FILE, ASYNC_ADD_PUBLISHERS, ASYNC_REMOVE_PUBLISHERS, ASYNC_REPLACE_FROM_FILE, ASYNC_GET_STATUS}
Required
draft_id
int64
name
string
publisher_urls
list<string>

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
result: Struct {
success: bool,
},
data: Struct {
app_publishers: List [
Struct {
url: string,
}
],
async_status: string,
draft_id: numeric string,
invalid_urls: List [
Struct {
url: string,
}
],
percentage: int32,
success_url_count: int32,
warning: string,
web_publishers: List [
Struct {
url: string,
}
],
visible_url_count: int32,
},
}

Validation Rules

ErrorDescription
100Invalid parameter

Deleting

You can delete a PublisherBlockList by making a DELETE request to /{publisher_block_list_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter