Graph 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. To read or write to the blocklist, the same business must own the app and the ad account.

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

Example

Graph API Explorer
GET /v3.3/{publisher-block-list-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{publisher-block-list-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* 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

ParameterDescription
draft_id
numeric string or integer

ID of the draft list used to create the block list. If provided, app_publishers and web_publishers are from the draft. If 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

Deprecated
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

Deprecated

Edges

EdgeDescription

A paged list of app store urls

A paged list of web domain or Facebook page urls

Validation Rules

ErrorDescription
278Reading advertisements requires an access token with the extended permission ads_read

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

ParameterDescription
name
string

Name of the block list

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

ParameterDescription
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