Media Planning

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Try in Postman

Overview

Media Planning API can help Media Planners understand the reach and ROI that LinkedIn can offer to their client. It allows them to make budget allocation recommendations with confidence and know how to improve the results, even before spending the first dollar. Media Planning API helps Media Planners make that decision by giving the forecasted reach, impressions (and more in future, like clicks, leads) curve over the budget, based on inputs provided like targeted audience, campaign start/end date and more.

Note

This is a private API that is available to qualified developers who meet additional criteria for access. To learn more about eligibility qualifications and how to request access, please see the FAQ. If you wish to apply for access, submit a Zendesk support ticket.

Permissions

Media Planning API requires a 3-legged OAuth member token, and your developer application needs to be provisioned with the Media Planning API product. Once you have been approved to access, you can use any valid member access token associated with the authenticated user with any valid scope permissions for member authentication. If there is no valid member token for the relevant user from any previous integration, we recommend using the bare minimum scope permissions like r_ads which will be required to fetch authenticated user's ad accounts.

Note

This API is application-specific; hence, explicit member consent is not required. Any valid member access token associated with the authenticated user can be used, and you do not need to add any additional permission in the scope of your Oauth2 flow for authorization.

Request Schema

Field Type Description Required
request request Object request Object that wraps the entire request body. See details below. Yes

request Object

Field Type Description Required
sponsoredAccountUrn URN The sponsored ad account URN where the authenticated user has a valid ad account user role. Yes
targetingCriteria targetingCriteria Object targetingCriteria Object defines the audience that the desired insights are for. This is a boolean expression of ad targeting facets and entities that identifies the member attributes to be included/excluded in the audience. See details below. Yes
currencyCode string The currency units for the forecasting curve. Optional(default=USD)
objectiveType string (Enum) The objective of your marketing campaign. Refer objectivetype. Yes
optimizationType string (Enum) The marketing results that you’re optimizing for. Optional (default=MAX_REACH for BRAND_AWARENESS objectiveType and deafult=MAX_VIDEO_VIEW for VIDEO VIEW objective type)
startDate date The start date of the media plan. Optional (default=today’s date in UTC)
endDate date The end date of the media plan. Optional (default=90 days since today’s date in UTC)
targetBudgetMicros long A specific budget that the caller is interested in. More metrics will be returned about this point. Note that this budget is represented in micros for precision ($1 USD = 1000000 micros) Optional (default=none)
enableAudienceNetwork boolean The LinkedIn Audience Network status. (It’s enabled if true and disabled if false.) Optional (default=true)
enableAudienceExpansion boolean The Audience Expansion status. (It’s enabled if true and disabled if false.) Optional (default=true)

Ad Account User Roles:

  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER

To make a request on behalf of a given user, you should fetch that authenticated user’s ad accounts and select one of their ad accounts. Refer Find Ad Accounts By Authenticated User to find and select an ad account.

For more information on Ad Account roles and permissions:

targetingCriteria Object

targetingCriteria provides a generic AND / OR construct to include and exclude different adTargetingFacets when defining the audience. The targeting criteria can be composed of LinkedIn Audience Attributes and/or existing matched audience Ad Segments (Contact/Company lists). See Ad Segments to fetch existing matched audience ad segment URNs that can be passed to urn:li:adTargetingFacet:audienceMatchingSegments.

The basic structure for a targetingCriteria object is as follows:

{
    "targetingCriteria":{
        "include":{
            "and":[
                {
                    "or":{
                        "urn:li:adTargetingFacet:{facet1}":[
                            "{facet1_value1}",
                            "{facet1_value2}"
                        ],
                        "urn:li:adTargetingFacet:{facet2}":[
                            "{facet2_value1}"
                        ]
                    }
                },
                {
                    "or":{
                        "urn:li:adTargetingFacet:{facet3}":[
                            "{facet3_value1}",
                            "{facet3_value2}"
                        ]
                    }
                }
            ]
        },
        "exclude":{
            "or":{
                "urn:li:adTargetingFacet:{facet4}":[
                    "{facet4_value1}"
                ]
            }
        }
    }
}

Refer the below links for additional details:

Validations and Minimum Requirements

  • A sponsored ad account ID must be provided in the request. Authenticated members must have access to that sponsored ad account (any role VIEWER or above).
  • For the MVP version of the API, the only currency supported as input is USD (default).
  • An objectiveType must always be present as input in the API request. Current supported values are “BRAND_AWARENESS” and “VIDEO_VIEW”.
  • The optimizationType values supported are “MAX_REACH”, “MAX_IMPRESSION” and “MAX_VIDEO_VIEW”. This is an optional input in the API request and defaults to “MAX_REACH” for the objectiveType “BRAND_AWARENESS” and “MAX_VIDEO_VIEW” for the objectiveType “VIDEO_VIEW”.
  • The minimum target budget to be input for a single point metric corresponding to that budget is $100 USD. The upper bound of the metric curve is dynamic instead of fixed, any request with budget value exceeding the upper bound will not be served.
  • The total audience counts for the Targeting Criteria provided should be at least 300 for the API to predict reach metrics.
  • The targeting criteria provided in the request doesn’t support negative targeting (exclude section) and should always have a geo or profileGeo criteria in the input.
  • The start date and end date are optional inputs and defaults to today’s date in UTC and 90 days after respectively. If set explicitly, both the dates must be in the future and the duration between them should not exceed 90 days.

Note

Applications utilizing LinkedIn's targeting capabilities are required to clearly and prominently display a notice in their user interface notifying advertisers that they cannot use LinkedIn to discriminate against members based on personal characteristics. The notice should include the following text: LinkedIn tools may not be used to discriminate based on personal characteristics like gender, age, race, or ethnicity. Learn more. Applications utilizing the Media Planning API need to clearly and prominently display notice in their user interface notifying advertisers the forecasted results are directional estimates and do not guarantee performance. The notice should include the following text: The forecasted results are directional estimates and don't guarantee the actual performance of campaigns. Learn more

Sample Request

Note

All API requests are represented in Rest.li Protocol 2.0.0 and require the header: X-Restli-Protocol-Version: 2.0.0. Read the Protocol Versions document to learn about using Rest.li Protocol 2.0.0. To generate Reach/Reach Percentage curve use action=forecastReaches and to generate Impression/Average Lifetime Frequency curve action=forecastImpressions

POST https://api.linkedin.com/rest/mediaPlanning?action=forecastReaches

{ 
 "request": {
      "sponsoredAccountUrn": "urn:li:sponsoredAccount:123"
      "targetingCriteria":{
         "include":{
            "and":[
               {
                  "or":{
                     "urn:li:adTargetingFacet:locations":[
                        "urn:li:geo:105080838"
                     ]
                  }
               },
               {
                  "or":{
                     "urn:li:adTargetingFacet:interfaceLocales":[
                        "urn:li:locale:en_US"
                     ]
                  }
               },
               {
                  "or":{
                     "urn:li:adTargetingFacet:skills":[
                        "urn:li:skill:236",
                        "urn:li:skill:242",
                        "urn:li:skill:252"
                     ]
                  }
               }
            ]
         }
      },
    "targetBudgetMicros": 300000000, 
    "optimizationType": "MAX_IMPRESSION",
    "objectiveType": "VIDEO_VIEWS",
    "startDateOn": {"day":20, "month":1, "year":2024}, 
    "endDateOn": {"day":25, "month":2, "year":2024},
    "enableAudienceNetwork": true,
    "enableAudienceExpansion": true,
 }
}

Response Schema

Field Name Type Description
reachCurve ForecastMetrics The array of points along the reach curve. Will currently return 100 points and an additional point if an input targetBudget was provided. If we were illustrating the curve, budget would be on the x-axis and reach would be on the y-axis. Optional(returned only when action= forecastReaches)
reachPercentageCurve ForecastMetrics object The array of points along the reach percentage curve. Will currently return 100 points and an additional point if an input targetBudget was provided. If we were illustrating the curve, budget would be on the x-axis and reach would be on the y-axis. Optional(returned only when action= forecastReaches and enableAudienceExpansion=false)
impressionCurve ForecastMetrics object The array of points along the impressions curve. Will currently return 100 points and an additional point if an input targetBudget was provided. If we were illustrating the curve, budget would be on the x-axis and reach would be on the y-axis. Optional(returned only when action= forecastImpressions)
averageFrequency ForecastMetrics object Average Frequency is a single point value calculated by impression/reach assuming the single point budget in the request was used to forecast impression and reach results. It would be returned together with the impression curve if the forecasted impression is requested. Optional (returned when action=forecastImpressions and targetBudgetMicros is set in the input)

ForecastMetrics Object

Field Name Type Description
metricCurve array [MediaPlanningForecastDataPoint] The array of points along the reach, impressions, reachPercentage or averageFrequency curve.
singlePointMetric array [MediaPlanningForecastDataPoint]] Optional metrics on a specific point (only returned when targetBudget in the request is populated).

MediaPlanningForecastDatapoint Object

Field Name Type Description
budgetMicros long The position on the budget axis of the curve. That is, how much budget is required to reach this point on the curve.
metricValue double The metric number on the curve.
metricUpper double Optional, the upper bound of the metric.
metricLower double Optional, the lower bound of the metric.

Sample Response

{
    "value": {
        "reachCurve": {
            "metricCurve": [
                {
                    "metricValue": 21137.181640625,
                    "budgetMicros": 100000000
                },
                {
                    "metricValue": 22540.12109375,
                    "budgetMicros": 109020202
                },
                {
                    "metricValue": 23913.630859375,
                    "budgetMicros": 118040405
                },
                {
                    "metricValue": 25260.513671875,
                    "budgetMicros": 127060607
                } 
                ... 96 other points
            ],
            "singlePointMetric": {
                "metricValue": 21137.181640625,
                "budgetMicros": 100000000
            }
        }
    }
}

After fetcing the required forecasts,, you can save the targeting criteria used to plan for the campaigns with the Saved Audience Templates API so that you can activate them through the campaign API or from the Campaign Manager User Interface.

API Error Details

HTTP Status Code ERROR MESSAGE DESCRIPTION ERROR RESOLUTION
401 EMPTY_ACCESS_TOKEN Empty or expired oauth2 access token Use a valid member access token.
403 ACCESS_DENIED Not enough permissions to access: targetingAudienceInsights Make sure your developer application is provisioned with the (Private) Media Planning API.
403 USER_NOT_AUTHORIZED Caller should have access to the Ad Account provided in the request Make sure the member associated with access token has a user role on the provided Ad Account.
422 FAILED_VALIDATION_CONDITION Request fails structure validation. / Missing required fields in the request. Make sure all required fields are passed and follow valid structure.
500 sINTERNAL_SERVER_ERROR Internal server side error N/A