Campaign Recommendations

The adCampaignRecommendations and adCampaignInsightsV2 APIs let advertisers quickly determine if active LinkedIn campaigns are achieving the desired reach and impact.

  • The Recommendations API offers recommendations for underperforming campaigns and suggests ways to improve performance; including adjusting the creative, bid, audience size, or number of creatives.
  • The Insights API offers analysis of a campaign's budget utilization, and identifies modifications that can be made to a bid, daily budget, or total budget to maximize utilization or impressions.

Results for each API are generated daily, and are available after the campaign has been active for 7 days.

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.

Campaign Recommendations

The adCampaignRecommendations API requires the q=campaigns parameter and at least one campaigns={campaignUrn} parameter. Multiple campaigns can be provided by chaining multiple campaigns parameters that each have their own campaign URN.

Paging is not supported for this API. All results are returned on the first page.

GET https://api.linkedin.com/v2/adCampaignRecommendations?q=campaigns&campaigns={campaign URN 1}&campaigns={campaign URN 2}

Parameters

Field Name Required Description
campaigns Yes SponsoredCampaign URNs for which recommendations should be returned. Specify multiple campaigns parameters with additional campaign URNs to request recommendations for multiple campaigns

Schema

Field Name Type Description
campaign SponsoredCampaign URN The campaign to which this recommendation belongs.
createdAt long The epoch timestamp in milliseconds of when this recommendation was generated.
dailyBudget optional MoneyAmount The recommended daily budget of a campaign.
expandAudience boolean If true, the recommendation is to expand the audience of this campaign.
improveCreativeQuality boolean If true, the recommendation is to improve the quality of this campaign's creatives.
numOfCreatives optional int The recommended number of creatives in the campaign.
priority int The priority of the recommendation, 0 indexed, with 0 being the highest priority. This value is set by the job that generated this recommendation and is used by the API to sort a list of recommendations to return to the caller. The lowest priority possible is MAX_INT.
totalBudget optional MoneyAmount The recommended total budget of a campaign.
type optional String The type of recommendation. Valid values are:
  • UNDER_DELIVERY_BID
  • UNDER_DELIVERY_MORE_CREATIVES
  • UNDER_DELIVERY_AUDIENCE_EXPANSION
  • OVER_DELIVERY_BUDGET
  • LOW_CREATIVE_QUALITY
See the following Campaign Recommendation Types table for descriptions of these values.
unitCost optional MoneyAmount The recommended unit cost or the bid of a campaign.

Campaign Recommendation Types

Recommendation Type Description
UNDER_DELIVERY_BID This campaign is underdelivering and we suggest changing the bid.
UNDER_DELIVERY_MORE_CREATIVES This campaign is underdelivering and we suggest adding more creatives.
UNDER_DELIVERY_AUDIENCE_EXPANSION This campaign is underdelivering and we suggest enabling audience expansion.
OVER_DELIVERY_BUDGET This campaign is overdelivering and we suggest raising the daily/total budget.
LOW_CREATIVE_QUALITY This campaign has low quality creatives and we suggest improving them before doing anything else.

Sample Request

The following example requests recommendations for campaigns urn:li:sponsoredCampaign:12244313 and urn:li:sponsoredCampaign:5466312.

GET https://api.linkedin.com/v2/adCampaignRecommendations?q=campaigns&campaigns=urn:li:sponsoredCampaign:12244313&campaigns=urn:li:sponsoredCampaign:5466312

Sample Response

{
    "elements": [
        {
            "campaign": "urn:li:sponsoredCampaign:12244313",
            "createdAt": 1496602782973,
            "expandAudience": false,
            "improveCreativeQuality": false,
            "numOfCreatives": 4,
            "priority": 0,
            "type": "UNDER_DELIVERY_MORE_CREATIVES"
        },
        {
            "campaign": "urn:li:sponsoredCampaign:5466312",
            "createdAt": 1496602782973,
            "expandAudience": false,
            "improveCreativeQuality": true,
            "priority": 1,
            "type": "LOW_CREATIVE_QUALITY"
        }
    ],
    "paging": {
        "count": 2147483647,
        "links": [],
        "start": 0
    }
}

Campaign Insights

The adCampaignInsightsV2 API requires the q=entities parameter and at least one entities={campaignUrn} parameter with a campaign URN. Multiple campaigns can be provided by chaining multiple entities parameters that each have their own campaign URN.

Paging is not supported for this API. All results are returned on the first page.

GET https://api.linkedin.com/v2/adCampaignInsightsV2?q=entities&entities={campaign URN 1}&entities={campaign URN 2}

Parameters

Field Name Required Description
entities Yes SponsoredCampaign URNs for which insights should be returned. Specify multiple entities parameters with additional campaign URNs to request insights for multiple campaigns.

Schema

Field Name Type Description
averageSpend optional MoneyAmount The average spend of the entity (such as SponsoredCampaign and SponsoredCampaignGroup) in the past 7 days in UTC time. Currency code must match that of the parent account.
bidInsight optional BidInsight A prediction of how much additional impressions could be generated from a different bid.
budgetExhaustedAt optional long Date at which the ad entity's TotalBudget will be exhausted, in Unix Epoch time.
campaignRelevanceScore optional int A score between 0 and 10 (inclusive) indicating how relevant this campaign is compared to its competitors. A score of 10 indicates the most relevant content.
dailyBudgetUtilization optional double The average daily budget utilization. Ranges between 0.0 to about 1.2 if there is over delivery.
entity URN The URN of the entity for which these insights apply (sponsoredCampaign URN).
shareOfVoice optional double The fraction of eligible audience this ad entity has reached. Ranges between 0.0 to 1.0.
totalBudgetUtilization optional double The fraction of the total budget this ad entity has spent so far. Ranges between 0.0 to about 1.2 if there is over delivery. Not provided if totalBudget is not set by the advertiser.

Sample Request

The following example shows insights for campaigns urn:li:sponsoredCampaign:12244313 and urn:li:sponsoredCampaign:5466312.

GET https://api.linkedin.com/v2/adCampaignInsightsV2?q=entities&entities=urn:li:sponsoredCampaign:12244313&entities=urn:li:sponsoredCampaign:5466312

Sample Response

{
    "elements": [
        {
            "averageSpend": {
                "amount": "6",
                "currencyCode": "USD"
            },
            "bidInsight": {
                "newBid": {
                    "amount": "10",
                    "currencyCode": "USD"
                },
                "relativeImpressions": 1.2
            },
            "budgetExhaustedAt": 1507238596599,
            "campaignRelevanceScore": 4,
            "dailyBudgetUtilization": 0.1,
            "entity": "urn:li:sponsoredCampaign:12244313",
            "totalBudgetUtilization": 0.1
        },
        {
            "averageSpend": {
                "amount": "14",
                "currencyCode": "USD"
            },
            "bidInsight": {
                "newBid": {
                    "amount": "18",
                    "currencyCode": "USD"
                },
                "relativeImpressions": 1.3
            },
            "budgetExhaustedAt": 1507238596599,
            "campaignRelevanceScore": 4,
            "dailyBudgetUtilization": 0.1,
            "entity": "urn:li:sponsoredCampaign:5466312",
            "totalBudgetUtilization": 0.1
        }
    ],
    "paging": {
        "count": 2147483647,
        "links": [],
        "start": 0
    }
}