Manage Audience Restrictions

When serving Sponsored Content off network, LinkedIn offers a way for advertisers to opt out of serving certain sites and mobile applications. You can manage mobile application restrictions using mobile IAB (Interactive Advertising Bureau) categories and desktop and mobile web restrictions by domains.

Permissions

Permission Description
rw_ads Manage and read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
r_ads Read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER

See Account Access Controls for more information on ad account roles.

Manage IAB Categories

Request Body Fields

Field Name Type Description
offsitePreferences optional iabCategories The set of IAB categories that this campaign may be excluded from based on where the ad request is from. Mobile Apps, Mobile Web, and Desktop inventory are all classified into one or more of these categories.
offsitePreferences.iabCategories.exclude optional IABCategoryUrn[] Excluded list of IAB categories.
offsiteDeliveryEnabled boolean Allow this campaign access to be served on the LinkedIn Advertising Network

Create a Campaign with IAB Category Exclusions

To exclude a campaign from certain websites or applications, enter an IAB category URN in the exclusion list of offsitePreferences. Generate an IAB category URN using the iabCategory API, and append it to urn:li:iabCategory:.

As these categories don't change often, we recommend that you call the iabCategory discovery API, cache the data, and do occasional refreshes.

To add the URN to the excluded list in offsitePreferences, the offsiteDeliveryEnabled flag must be set to true.

POST https://api.linkedin.com/v2/adCampaignsV2
{
   //Standard request to create a campaign. See campaign documentation for full samples.
   "offsiteDeliveryEnabled":true,
   "offsitePreferences":{
      "iabCategories":{
         "exclude":[
            "urn:li:iabCategory:IAB5-3",
            "urn:li:iabCategory:IAB1-1"
         ]
      }
   }
}

Update IAB Category Exclusions

You can add IAB category exclusions through a partial update to an existing campaign.

To add the URN to the excluded list in offsitePreferences, the offsiteDeliveryEnabled flag must be set to true.

POST https://api.linkedin.com/v2/adCampaignsV2/{campaignId}
{
    "patch": {
        "$set": {
            "offsiteDeliveryEnabled": true,
            "offsitePreferences": {
                "iabCategories": {
                    "exclude": [
                        "urn:li:iabCategory:IAB5-3",
                        "urn:li:iabCategory:IAB1-1"
                    ]
                }
            }
        }
    }
}

Delete IAB Exclusions

To remove any exclusions, clear the exclude object.

POST https://api.linkedin.com/v2/adCampaignsV2/{campaignId}
{
    "patch": {
        "$set": {
            "offsitePreferences": {
                "iabCategories": {
                    "exclude": []
                }
            }
        }
    }
}

Disable Offsite Sponsored Content Delivery

If you don't want LinkedIn to serve your content off network, set the offsiteDeliveryEnabled flag on your campaign to false.

Viewing Domain Block Lists

By using domain block lists, advertisers ensure that their ads are only served to their target audience and excluded from certain specific websites. Learn more about uploading a block list within Campaign Manager.

Domain block lists can be uploaded through the Campaign Manager UI as documented here or through the API as documented below in Creating Domain Block Lists.

Request Body Fields

Field Name Type Description
offsitePreferences.publisherRestrictionFiles.exclude optional AdPublisherFileUrn[] Excluded list of domains
offsiteDeliveryEnabled boolean Allow this campaign access to be served on the LinkedIn Advertising Network

Get a Campaign with Excluded Domains

The following example fetches a Sponsored Update campaign that has offsite serving enabled. The offsite audience excludes some domains. For brevity, the campaign response has been limited to the relevant fields using projection.

Note

A block list is named adPublisherFile in the API and is listed under publisherRestrictionFiles.

GET https://api.linkedin.com/v2/adCampaignsV2/{campaignId}?projection=(offsitePreferences,offsiteDeliveryEnabled,type)

Sample Response

{
    "offsiteDeliveryEnabled": true,
    "offsitePreferences": {
        "iabCategories": {
            "exclude": []
        },
        "publisherRestrictionFiles": {
            "exclude": [
                "urn:li:adPublisherFile:1603"
            ]
        }
    },
    "type": "SPONSORED_UPDATES"
}

Get Block List File Details

To get more details on the adPublisherFile URN in the previous sample response, make an additional request.

Sample Request

GET https://api.linkedin.com/v2/adPublisherRestrictions/1603

Sample Response

{
    "fileName": "Test Block List",
    "changeAuditStamps": {
        "created": {
            "actor": "urn:li:unknown:0",
            "time": 1501619504000
        },
        "lastModified": {
            "actor": "urn:li:unknown:0",
            "time": 1501619504000
        }
    },
    "dataId": "urn:li:media:/AAMB_wDxAAUAAQAAAAAAAAydAAAAJDc4MzJkMDk4LThkNTMtNDkzZC05NmY0LTk0MDc5YzA3ODJhNQ.csv",
    "compressionFormat": "NONE",
    "id": 1603,
    "entity": "urn:li:sponsoredAccount:506106200",
    "status": "SUCCESS"
}

Sample Request

Alternatively when you fetch the campaign, you can resolve the adPublisherFile by decorating the URN.

GET https://api.linkedin.com/v2/adCampaignsV2/133066184?projection=(offsitePreferences(publisherRestrictionFiles(exclude*~)),offsiteDeliveryEnabled,type)

Sample Response

{
    "offsitePreferences": {
        "publisherRestrictionFiles": {
            "exclude": [
                "urn:li:adPublisherFile:1603"
            ],
            "exclude~": [
                {
                    "fileName": "Test Block List",
                    "changeAuditStamps": {
                        "created": {
                            "actor": "urn:li:unknown:0",
                            "time": 1501619504000
                        },
                        "lastModified": {
                            "actor": "urn:li:unknown:0",
                            "time": 1501619504000
                        }
                    },
                    "dataId": "urn:li:media:/AAMB_wDxAAUAAQAAAAAAAAydAAAAJDc4MzJkMDk4LThkNTMtNDkzZC05NmY0LTk0MDc5YzA3ODJhNQ.csv",
                    "compressionFormat": "NONE",
                    "id": 1603,
                    "entity": "urn:li:sponsoredAccount:506106200",
                    "status": "SUCCESS"
                }
            ]
        }
    },
    "offsiteDeliveryEnabled": true,
    "type": "SPONSORED_UPDATES"
}

Get All Block List File Details by Advertiser Account

You can fetch block lists by Ad Account.

Sample Request

GET https://api.linkedin.com/v2/adPublisherRestrictions?q=entity&entity=urn:li:sponsoredAccount:506106200

Sample Response

{
    "elements": [
        {
            "fileName": "Test Block List",
            "dataId": "urn:li:media:/AAMB_wDxAAUAAQAAAAAAAAydAAAAJDc4MzJkMDk4LThkNTMtNDkzZC05NmY0LTk0MDc5YzA3ODJhNQ.csv",
            "changeAuditStamps": {
                "created": {
                    "actor": "urn:li:unknown:0",
                    "time": 1501619504000
                },
                "lastModified": {
                    "actor": "urn:li:unknown:0",
                    "time": 1501619504000
                }
            },
            "compressionFormat": "NONE",
            "id": 1603,
            "entity": "urn:li:sponsoredAccount:506106200",
            "status": "SUCCESS"
        }
    ],
    "paging": {
        "total": 1,
        "count": 10,
        "start": 0,
        "links": []
    }
}

Download Content of Block List File

The contents of a block list file can be download through the following API.

Get Block List File Download URL

The following API returns a URL where the block list file content can be downloaded.

POST https://api.linkedin.com/v2/adPublisherRestrictions?action=generateRestrictionsDownloadUrl

Request Body

Name Description Format Optional
publisherRestrictionId Id of the publisher restriction record Numeric NO

Request Header

Name Description Format Optional
Content-Type Content type for the request, must be: application/json String NO

Sample Request

POST https://api.linkedin.com/v2/adPublisherRestrictions?action=generateRestrictionsDownloadUrl
{
  "publisherRestrictionId": {id}
}

Sample Response

{
  "value": {
    "downloadSignedUrl": "https://www.linkedin.com/ambry/?x-li-ambry-ep=AQE_0g8A8UiOFgAAAWaEbHjizKrQZ4dPxDltpmPEHS-wdlXITXHYJp7SHZkbeCdS_Tqo077_EpEB1IO-i-m_LZzmIfHXhtGAJj1f1JZ4HOozhzfjZ_U3U7U-jkRm3nt5VXQp2tiDm2GsQbspN4MKhSRjF_zsmPF_XPU4kT5m09_2qSPlMTT40ICFfInn4H8rCygOlxLEX7kuMbjPjRQoogc-VBZuYIHv8q6r2yzjWqoBLzjKYyN79PpJ18DBu08xYnrNufHcuBX9QPCK8lTX_1bt1Rgl-Ml2Fwi13aslsvvBg9dERu0I0TBboKmSx-O4s_V_AwTGz4FDhyjDwvpftCF1D2uSjtkk-4BV6tdaLpn3nupuRY9sl9MleWd08fJ2UR0EOxHz_PbC5e_iPgw3XXpyDvhjreMofoqQ0DFtLZS-T922Y_m-Jv28Uv1C0x4OOKRmTOvcBQgfRy0So2UnwSl1JMaKa9L-WFlQGPCuksnnc81hoh3zUGjW9D01NxJZ2v7RwJOQtCjeEug1Ktb8AGTE7Purpidh_0P867MtAaCQ0YV-h0o61K2sOx_VK4mcPzdF1GikN2m3prO_b8LHjhNtxxEg"
  }
}

Response Body Fields

Field Name Description Format Guaranteed in Response?
value Collection for the response data collection YES
downloadSignedUrl URL to download block list content URL YES

Download Content Of The Block List File

To download the content of the block list file, simply invoke downloadSignedUrl obtained from the previous GET call. The URL is fully qualified including www.linkedin.com part.

GET {downloadSignedUrl}

Creating Domain Block Lists

The Block List APIs provide higher control to advertisers by giving them the ability to define where their ads should not appear. Partners have the ability to disable serving their campaigns from certain apps and websites by creating block lists through the API.

Schema

Field Name Type Description
uploadSignUrl URL URL to upload block list csv file
data-binary file File details with location that has block list to upload
location string Location of the uploaded file
dataId media URN Media URN with details of uploaded file location
entity URN Sponsored Account URN of the Campaign
fileName string Description of the uploaded file
publisherRestrictionId numeric Id of the newly created adPublisherRestrictions record
downloadSignedUrl URL URL to download the content of uploaded block list file

Upload Domain Block Lists And Create Restriction

Uploading of a list with blocked domains and creating a campaign restriction to use it is a multi-step process.

Obtain a URL To Upload The Content

Use the following API to get the URL where you can upload your block list file.

POST https://api.linkedin.com/v2/adPublisherRestrictions?action=generateRestrictionsUploadUrl

Sample Response

{
  "value": {
    "uploadSignUrl": "https://www.linkedin.com/ambry/?x-li-ambry-ep=AQFFC-Geqr_KYwAAAWZpL87yDFipgwXwWnG72OKIeDoTKqBzpXK_xMYgWYJu_A3dnSqPFUjBY9xhhx3z8FVVzKbwyg6A-ZuMkKJs4cUCnbMZJ4Qz3xug9FwVTGnnqWgB5_BLKr-HP-90a6P2drsm459tSOeuOgNqrsL1P2Cpj7MDuHgV9qqnxbEaxbHeMLHrzk8zVJx4yZTzkEUguBX6PPCOss3uSbzntZt7wk9B5ZtVSdwUd4eOe9hkuKEt78dN9u3KAyoJ3oonnt8sl2Gyvq_X2et6PW5GpHGcnM4Zy16iJIjzffTn5Xp1Im1vp7JSYw5J_eDtJE98-6mgYeOIF0oX8m0-BJF1H0u1j0rIt01t3y-DrGR9EyyDtArc9mMrllrR7SyuuYz0T106yjyxd8mrJVJqWDavo-1kpRTLUGKrQjusTfcIDbbkTWQaW13NSUiZkZsEzJuP1-GBbWuebj1GlZLUaijePOvni3lS8DO9SNqBtF4AUK4KwhuqYvJCrCBkZ5JmktEoPsAq6RJBPlFiFgS1VvXPZ2Xb4KjlnyxdM98NQTdfZcs_1kTo68YDZF-1CwTofXdBJtwXH-R_gGMq0Z74Imh7QwAns5osgp96Tm3qXuvYUF9R0ndXtPrd3DGIOgapJ7XYQZtIlEt9DXkEtwTqFiSvq3USYmQSBHDDaCP-Usfik-ILKgQ8UNWQ2lund8tQeO3yqj-hH2ObI7vRANkH4Q1i-25tVAYjEgmV20tqrRSxZZJfiOy6FxzEhmgxw3xLhkAiSmFDT_2Z9PUZ7HXQDguBcsBqguvvjQW56-ud2S9CEk9cfos3zFcuLr2llHFN6pOW5tgkFxY8nHydcJnNkrSvh_DUvqPcuV2vFi7F5kzRoDDNJ2CkUqCEbyJ0C5AnFvTQm9LgndlJjpvdxyIhIRjPzWjhcLRkiifKpwywQID3WQ0mUOieSypKkUflOPY5Ah7_Gvr38uX6F8kqLQAUd7mDnDrvaVKzTNIuMLaEoJLp5Rs"
  }
}

Response Body Fields

Field Name Description Format Guaranteed in Response?
value Collection for the response data collection YES
uploadSignUrl URL to upload block list file URL YES

Upload The Block List File

Using the uploadSignUrl from the above request, you can upload the block list file stored in your local computer.

  • Find the full file path and name for your block list file.
  • Use the following API call to upload the block list csv file
curl -i {uploadSignUrl} --data-binary @{csv file name}

Sample Request

curl -i "https://www.linkedin.com/ambry/?x-li-ambry-ep=AQFVRiTireeDqQAAAWcaXRMl2JPZd5aIs9gs70cBHxBxCa_Hg6wMRJEf7BuAtu_Xd_JFxrlqay3cGNxqif64gXA4NvTrDhCluxjDaaKkUG066nGIJm-wglQS2a8JzMdwrvJ7el5ATTjbONRv0xVT-dXF0zbej5RblSnuRmpk66Ar8s_dA9EPOhkX0rQiPnUZ967iFutSX0aBINoXE_fOLx1LHKZtx6AfpYZuQ7CnMxDBS-UDnRrJma--O2-vx1MfGN4GRXikFR37EhRFc4z-OiOPSw2z3M6Qv8XfaBrx7J8bS2fVhy2tS4OhfR5jusDm02e_Byhipn_Zm-iiGF9GUkT3CZXOplI83NLr0Tmy6Lb1M4tegVZGIuAe4EBrYCPEhParwe16GQ0J6TDR430M0HRh0KSOJhNQFwI_jQCRFulK0VNXtIXzPGcL90B3SPrk1xzeT5XXKU264BENYBcqJhAJ38rUc4Z75xaJhBR29QMGWYp4QAX9f15W_F7AKdKRUrZ1HkCH1ssCLiOaffSNt0WpOOqfdDR_tUsXGhbqNszEPpLPhHyOT9G-9iEWDvnfWO6KCgjNiZMX46vBl_Ypm53ScwQBoc9UOeGd_dmqLIzMrUSF69ciQW0U91yqficNcWCMZpexEyIiK1PkfvQn4kI0ig2b3YSKswNJuLbezExB2WKh2U9Yamqqf3t46-XP3YBLnmBS_hBLQJOJIbyDAqpYuTxOonHqOOmjHZWkwmso4mQls8Kxh5eMLIyHyMbIScWwHb7T1ZUaBR91P-SDJww3bXalThbDU1RXThKPtgKwPlUqhSrVtGQx0ccsbfzlRtPkSPnnPx6V9RIRLsrFLe_NcELEBXWjDv0VNEkjriExmxKpSPwp5P8DZXlmEg8KN0CTmFUQi4NETUcZ1LkF9PeT5WAKvhdR_XxmOJ7qnrm3rw" -H 'Authorization: Bearer AQW8ysj2IxGNn_imaWMQazugeb4bhwvTqQ7m1jIeI2Sk1Iop8qz65Ns4-0QgMGuqM9zlV21tP3sbHkLLiiz3DEQoNbxK5XeXdQ69Nzd4aK7qwbNt99T49-bBSrGDFqCAeqXNYP2SXCYsMb1-xDumJCfh1UAtsg5qYwzwlVyIcPmz7yEJq9FQ0rDwHMFB3ls8rg7TXIZCPfxXqpE0abX4A3uPu2ozvMOLP3Dmz-TTOfdTlJv5CzLCyffrHdG57-Xq5Wjq_d_NMi2tM5AB_zOpiZkfKFBh0YiDaG7Ek7Ey9CR1LowFE9SekT74f_K6IhOrYvP1M009iRrs4yKf0OzTsVwFxZeS_A' --data-binary @BlockList.csv

Sample Response

From the API response, find the value of the location header. This value is used for the media URN while creating the publisher restrictions in the next step.

location: /AAUQBADxAAQAAQAAAAAAABB7AAAAJDBjOTY0ODk5LTMyMTMsfdsBkNS1iMjkyLThmNDJlYjVkNmI4ZQ.csv

Create The Publisher Restriction

Now that the block list file has been uploaded, you can create an adPublisherRestriction to be used in an Ad Campaign.

POST https://api.linkedin.com/v2/adPublisherRestrictions

Request Body Fields

Name Description Format Optional
dataId Media URN of the location URN NO
entity SponsoredAccount URN URN NO
fileName File name String NO

Request Header

Name Description Format Optional
Content-Type Content type for the request, must be: application/json String NO

Sample Request

POST https://api.linkedin.com/v2/adPublisherRestrictions
{
  "dataId": "urn:li:media:/AAUQAQCwAAQAAQAAAAAAAADPAAAAJDIxYTllNzllLTQ0Y2EtNDgdfgfd4i05NTcyLTEwYWVmYTgxNWY4Yg.csv",
  "entity": "urn:li:sponsoredAccount:518306371",
  "fileName": "BlockList.csv"
}

Sample Response

The ID of the newly created record can be parsed out of the location header.

location: /adPublisherRestrictions/28424